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 new-line 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{new-line-value}
1561 The string written to the output to cause a new-line (carriage return
1562 plus linefeed). The default, which can be specified explicitly with
1563 @code{newline-string=default}, is to use the system-dependent new-line
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:
2163 @item -a @{compatible|enhanced@}
2164 @itemx --algorithm=@{compatible|enhanced@}
2166 If you chose @code{compatible}, then PSPP will use the same algorithms
2167 as used by some proprietary statistical analysis packages.
2168 This is not recommended, as these algorithms are inferior and in some cases
2170 The default setting is @code{enhanced}.
2171 Certain commands have subcommands which allow you to override this setting on
2172 a per command basis.
2175 @itemx --config-dir=@var{dir}
2177 Sets the configuration directory to @var{dir}. @xref{File locations}.
2179 @item -o @var{device}
2180 @itemx --device=@var{device}
2182 Selects the output device with name @var{device}. If this option is
2183 given more than once, then all devices mentioned are selected. This
2184 option disables all devices besides those mentioned on the command line.
2186 @item -d @var{var}[=@var{value}]
2187 @itemx --define=@var{var}[=@var{value}]
2189 Defines an `environment variable' named @var{var} having the optional
2190 value @var{value} specified. @xref{Variable values}.
2193 @itemx --undef=@var{var}
2195 Undefines the `environment variable' named @var{var}. @xref{Variable
2199 @node Input and output options, Language control options, Configuration Options, Invocation
2200 @section Input and output options
2202 Input and output options affect how PSPP reads input and writes
2203 output. These are the input and output options:
2207 @itemx --out-file=@var{file}
2209 This overrides the output file name for devices designated as listing
2210 devices. If a file named @var{file} already exists, it is overwritten.
2215 Allows PSPP to be used as a filter by causing the syntax file to be
2216 read from stdin and output to be written to stdout. Conflicts with the
2217 @code{-f @var{file}} and @code{--file=@var{file}} options.
2222 Clears all directories from the include path. This includes all
2223 directories put in the include path by default. @xref{Miscellaneous
2227 @itemx --include=@var{dir}
2229 Appends directory @var{dir} to the path that is searched for include
2230 files in PSPP syntax files.
2232 @item -c @var{command}
2233 @itemx --command=@var{command}
2235 Execute literal command @var{command}. The command is executed before
2236 startup syntax files, if any.
2238 @item --testing-mode
2240 Invoke heuristics to assist with testing PSPP. For use by @code{make
2241 check} and similar scripts.
2244 @node Language control options, Informational options, Input and output options, Invocation
2245 @section Language control options
2247 Language control options control how PSPP syntax files are parsed and
2248 interpreted. The available language control options are:
2252 @itemx --interactive
2254 When a syntax file is specified on the command line, PSPP normally
2255 terminates after processing it. Giving this option will cause PSPP to
2256 bring up a command prompt after processing the syntax file.
2258 In addition, this forces syntax files to be interpreted in interactive
2259 mode, rather than the default batch mode. @xref{Tokenizing lines}, for
2260 information on the differences between batch mode and interactive mode
2261 command interpretation.
2269 Only the syntax of any syntax file specified or of commands entered at
2270 the command line is checked. Transformations are not performed and
2271 procedures are not executed. Not yet implemented.
2276 Prevents the execution of the PSPP startup syntax file. Not yet
2277 implemented, as startup syntax files aren't, either.
2282 Disables certain unsafe operations. This includes the ERASE and
2283 HOST commands, as well as use of pipes as input and output files.
2286 @node Informational options, , Language control options, Invocation
2287 @section Informational options
2289 Informational options cause information about PSPP to be written to
2290 the terminal. Here are the available options:
2296 Prints a message describing PSPP command-line syntax and the available
2297 device driver classes, then terminates.
2302 Lists the available device driver classes, then terminates.
2304 @item -x @{compatible|enhanced@}
2305 @itemx --syntax=@{compatible|enhanced@}
2307 If you chose @code{compatible}, then PSPP will only accept command syntax that
2308 is compatible with the proprietary program SPSS.
2309 If you choose @code{enhanced} then additional syntax will be available.
2310 The default is @code{enhanced}.
2316 Prints a brief message listing PSPP's version, warranties you don't
2317 have, copying conditions and copyright, and e-mail address for bug
2318 reports, then terminates.
2323 Increments PSPP's verbosity level. Higher verbosity levels cause
2324 PSPP to display greater amounts of information about what it is
2325 doing. Often useful for debugging PSPP's configuration.
2327 This option can be given multiple times to set the verbosity level to
2328 that value. The default verbosity level is 0, in which no informational
2329 messages will be displayed.
2331 Higher verbosity levels cause messages to be displayed when the
2332 corresponding events take place.
2337 Driver and subsystem initializations.
2341 Completion of driver initializations. Beginning of driver closings.
2345 Completion of driver closings.
2349 Files searched for; success of searches.
2353 Individual directories included in file searches.
2356 Each verbosity level also includes messages from lower verbosity levels.
2360 @node Language, Expressions, Invocation, Top
2361 @chapter The PSPP language
2362 @cindex language, PSPP
2363 @cindex PSPP, language
2366 @strong{Please note:} PSPP is not even close to completion.
2367 Only a few actual statistical procedures are implemented. PSPP
2368 is a work in progress.
2371 This chapter discusses elements common to many PSPP commands.
2372 Later chapters will describe individual commands in detail.
2375 * Tokens:: Characters combine to form tokens.
2376 * Commands:: Tokens combine to form commands.
2377 * Types of Commands:: Commands come in several flavors.
2378 * Order of Commands:: Commands combine to form syntax files.
2379 * Missing Observations:: Handling missing observations.
2380 * Variables:: The unit of data storage.
2381 * Files:: Files used by PSPP.
2382 * BNF:: How command syntax is described.
2385 @node Tokens, Commands, Language, Language
2387 @cindex language, lexical analysis
2388 @cindex language, tokens
2390 @cindex lexical analysis
2393 PSPP divides most syntax file lines into series of short chunks
2394 called @dfn{tokens}, @dfn{lexical elements}, or @dfn{lexemes}. These
2395 tokens are then grouped to form commands, each of which tells
2396 PSPP to take some action---read in data, write out data, perform
2397 a statistical procedure, etc. The process of dividing input into tokens
2398 is @dfn{tokenization}, or @dfn{lexical analysis}. Each type of token is
2403 Tokens must be separated from each other by @dfn{delimiters}.
2404 Delimiters include whitespace (spaces, tabs, carriage returns, line
2405 feeds, vertical tabs), punctuation (commas, forward slashes, etc.), and
2406 operators (plus, minus, times, divide, etc.) Note that while whitespace
2407 only separates tokens, other delimiters are tokens in themselves.
2412 Identifiers are names that specify variable names, commands, or command
2417 The first character in an identifier must be a letter, @samp{#}, or
2418 @samp{@@}. Some system identifiers begin with @samp{$}, but
2419 user-defined variables' names may not begin with @samp{$}.
2422 The remaining characters in the identifier must be letters, digits, or
2423 one of the following special characters:
2430 @cindex variable names
2431 @cindex names, variable
2432 Variable names may be any length, but only the first 8 characters are
2436 @cindex case-sensitivity
2437 Identifiers are not case-sensitive: @code{foobar}, @code{Foobar},
2438 @code{FooBar}, @code{FOOBAR}, and @code{FoObaR} are different
2439 representations of the same identifier.
2443 Identifiers other than variable names may be abbreviated to their first
2444 3 characters if this abbreviation is unambiguous. These identifiers are
2445 often called @dfn{keywords}. (Unique abbreviations of 3 or more
2446 characters are also accepted: @samp{FRE}, @samp{FREQ}, and
2447 @samp{FREQUENCIES} are equivalent when the last is a keyword.)
2450 Whether an identifier is a keyword depends on the context.
2453 @cindex keywords, reserved
2454 @cindex reserved keywords
2455 Some keywords are reserved. These keywords may not be used in any
2456 context besides those explicitly described in this manual. The reserved
2460 ALL AND BY EQ GE GT LE LT NE NOT OR TO WITH
2464 Since keywords are identifiers, all the rules for identifiers apply.
2465 Specifically, they must be delimited as are other identifiers:
2466 @code{WITH} is a reserved keyword, but @code{WITHOUT} is a valid
2472 @cindex variable names, ending with period
2473 @strong{Caution:} It is legal to end a variable name with a period, but
2474 @emph{don't do it!} The variable name will be misinterpreted when it is
2475 the final token on a line: @code{FOO.} will be divided into two separate
2476 tokens, @samp{FOO} and @samp{.}, the @dfn{terminal dot}.
2477 @xref{Commands, , Forming commands of tokens}.
2483 Numbers may be specified as integers or reals. Integers are internally
2484 converted into reals. Scientific notation is not supported. Here are
2485 some examples of valid numbers:
2488 1234 3.14159265359 .707106781185 8945.
2491 @strong{Caution:} The last example will be interpreted as two tokens,
2492 @samp{8945} and @samp{.}, if it is the last token on a line.
2498 @cindex case-sensitivity
2499 Strings are literal sequences of characters enclosed in pairs of single
2500 quotes (@samp{'}) or double quotes (@samp{"}).
2504 Whitespace and case of letters @emph{are} significant inside strings.
2506 Whitespace characters inside a string are not delimiters.
2508 To include single-quote characters in a string, enclose the string in
2511 To include double-quote characters in a string, enclose the string in
2514 It is not possible to put both single- and double-quote characters
2520 Hexstrings are string variants that use hex digits to specify
2525 A hexstring may be used anywhere that an ordinary string is allowed.
2530 A hexstring begins with @samp{X'} or @samp{x'}, and ends with @samp{'}.
2534 No whitespace is allowed between the initial @samp{X} and @samp{'}.
2537 Double quotes @samp{"} may be used in place of single quotes @samp{'} if
2538 done in both places.
2541 Each pair of hex digits is internally changed into a single character
2542 with the given value.
2545 If there is an odd number of hex digits, the missing last digit is
2546 assumed to be @samp{0}.
2550 @strong{Please note:} Use of hexstrings is nonportable because the same
2551 numeric values are associated with different glyphs by different
2552 operating systems. Therefore, their use should be confined to syntax
2553 files that will not be widely distributed.
2556 @cindex characters, reserved
2559 @strong{Please note also:} The character with value 00 is reserved for
2560 internal use by PSPP. Its use in strings causes an error and
2561 replacement with a blank space (in ASCII, hex 20, decimal 32).
2566 Punctuation separates tokens; punctuators are delimiters. These are the
2567 punctuation characters:
2575 Operators describe mathematical operations. Some operators are delimiters:
2581 Many of the above operators are also punctuators. Punctuators are
2582 distinguished from operators by context.
2584 The other operators are all reserved keywords. None of these are
2588 AND EQ GE GT LE LT NE OR
2592 @cindex terminal dot
2593 @cindex dot, terminal
2596 A period (@samp{.}) at the end of a line (except for whitespace) is one
2597 type of a @dfn{terminal dot}, although not every terminal dot is a
2598 period at the end of a line. @xref{Commands, , Forming commands of
2599 tokens}. A period is a terminal dot @emph{only}
2600 when it is at the end of a line; otherwise it is part of a
2601 floating-point number. (A period outside a number in the middle of a
2605 @cindex terminal dot, changing
2606 @cindex dot, terminal, changing
2607 @strong{Please note:} The character used for the @dfn{terminal dot}
2608 can be changed with @cmd{SET}'s ENDCMD subcommand (@pxref{SET}). This
2609 is strongly discouraged, and throughout all the remainder of this
2610 manual it will be assumed that the default setting is in effect.
2615 @node Commands, Types of Commands, Tokens, Language
2616 @section Forming commands of tokens
2618 @cindex PSPP, command structure
2619 @cindex language, command structure
2620 @cindex commands, structure
2622 Most PSPP commands share a common structure, diagrammed below:
2625 @var{cmd}@dots{} [@var{sbc}[=][@var{spec} [[,]@var{spec}]@dots{}]] [[/[=][@var{spec} [[,]@var{spec}]@dots{}]]@dots{}].
2629 In the above, rather daunting, expression, pairs of square brackets
2630 (@samp{[ ]}) indicate optional elements, and names such as @var{cmd}
2631 indicate parts of the syntax that vary from command to command.
2632 Ellipses (@samp{...}) indicate that the preceding part may be repeated
2633 an arbitrary number of times. Let's pick apart what it says above:
2636 @cindex commands, names
2638 A command begins with a command name of one or more keywords, such as
2639 @cmd{FREQUENCIES}, @cmd{DATA LIST}, or @cmd{N OF CASES}. @var{cmd}
2640 may be abbreviated to its first word if that is unambiguous; each word
2641 in @var{cmd} may be abbreviated to a unique prefix of three or more
2642 characters as described above.
2646 The command name may be followed by one or more @dfn{subcommands}:
2650 Each subcommand begins with a unique keyword, indicated by @var{sbc}
2651 above. This is analogous to the command name.
2654 The subcommand name is optionally followed by an equals sign (@samp{=}).
2657 Some subcommands accept a series of one or more specifications
2658 (@var{spec}), optionally separated by commas.
2661 Each subcommand must be separated from the next (if any) by a forward
2665 @cindex dot, terminal
2666 @cindex terminal dot
2668 Each command must be terminated with a @dfn{terminal dot}.
2669 The terminal dot may be given one of three ways:
2673 (most commonly) A period character at the very end of a line, as
2677 (only if NULLINE is on: @xref{SET, , Setting user preferences}, for more
2678 details.) A completely blank line.
2681 (in batch mode only) Any line that is not indented from the left side of
2682 the page causes a terminal dot to be inserted before that line.
2683 Therefore, each command begins with a line that is flush left, followed
2684 by zero or more lines that are indented one or more characters from the
2687 In batch mode, PSPP will ignore a plus sign, minus sign, or period
2688 (@samp{+}, @samp{@minus{}}, or @samp{.}) as the first character in a
2689 line. Any of these characters as the first character on a line will
2690 begin a new command. This allows for visual indentation of a command
2691 without that command being considered part of the previous command.
2693 PSPP is in batch mode when it is reading input from a file, rather
2694 than from an interactive user. Note that the other forms of the
2695 terminal dot may also be used in batch mode.
2697 Sometimes, one encounters syntax files that are intended to be
2698 interpreted in interactive mode rather than batch mode (for instance,
2699 this can happen if a session log file is used directly as a syntax
2700 file). When this occurs, use the @samp{-i} command line option to force
2701 interpretation in interactive mode (@pxref{Language control options}).
2705 PSPP ignores empty commands when they are generated by the above
2706 rules. Note that, as a consequence of these rules, each command must
2707 begin on a new line.
2709 @node Types of Commands, Order of Commands, Commands, Language
2710 @section Types of Commands
2712 Commands in PSPP are divided roughly into six categories:
2715 @item Utility commands
2716 @cindex utility commands
2717 Set or display various global options that affect PSPP operations.
2718 May appear anywhere in a syntax file. @xref{Utilities, , Utility
2721 @item File definition commands
2722 @cindex file definition commands
2723 Give instructions for reading data from text files or from special
2724 binary ``system files''. Most of these commands discard any previous
2725 data or variables to replace it with the new data and
2726 variables. At least one must appear before the first command in any of
2727 the categories below. @xref{Data Input and Output}.
2729 @item Input program commands
2730 @cindex input program commands
2731 Though rarely used, these provide powerful tools for reading data files
2732 in arbitrary textual or binary formats. @xref{INPUT PROGRAM}.
2734 @item Transformations
2735 @cindex transformations
2736 Perform operations on data and write data to output files. Transformations
2737 are not carried out until a procedure is executed.
2739 @item Restricted transformations
2740 @cindex restricted transformations
2741 Same as transformations for most purposes. @xref{Order of Commands}, for a
2742 detailed description of the differences.
2746 Analyze data, writing results of analyses to the listing file. Cause
2747 transformations specified earlier in the file to be performed. In a
2748 more general sense, a @dfn{procedure} is any command that causes the
2749 active file (the data) to be read.
2752 @node Order of Commands, Missing Observations, Types of Commands, Language
2753 @section Order of Commands
2754 @cindex commands, ordering
2755 @cindex order of commands
2757 PSPP does not place many restrictions on ordering of commands.
2758 The main restriction is that variables must be defined with one of the
2759 file-definition commands before they are otherwise referred to.
2761 Of course, there are specific rules, for those who are interested.
2762 PSPP possesses five internal states, called initial, INPUT PROGRAM,
2763 FILE TYPE, transformation, and procedure states. (Please note the
2764 distinction between the @cmd{INPUT PROGRAM} and @cmd{FILE TYPE}
2765 @emph{commands} and the INPUT PROGRAM and FILE TYPE @emph{states}.)
2767 PSPP starts up in the initial state. Each successful completion
2768 of a command may cause a state transition. Each type of command has its
2769 own rules for state transitions:
2772 @item Utility commands
2775 Legal in all states.
2777 Do not cause state transitions. Exception: when @cmd{N OF CASES}
2778 is executed in the procedure state, it causes a transition to the
2779 transformation state.
2782 @item @cmd{DATA LIST}
2785 Legal in all states.
2787 When executed in the initial or procedure state, causes a transition to
2788 the transformation state.
2790 Clears the active file if executed in the procedure or transformation
2794 @item @cmd{INPUT PROGRAM}
2797 Invalid in INPUT PROGRAM and FILE TYPE states.
2799 Causes a transition to the INPUT PROGRAM state.
2801 Clears the active file.
2804 @item @cmd{FILE TYPE}
2807 Invalid in INPUT PROGRAM and FILE TYPE states.
2809 Causes a transition to the FILE TYPE state.
2811 Clears the active file.
2814 @item Other file definition commands
2817 Invalid in INPUT PROGRAM and FILE TYPE states.
2819 Cause a transition to the transformation state.
2821 Clear the active file, except for @cmd{ADD FILES}, @cmd{MATCH FILES},
2825 @item Transformations
2828 Invalid in initial and FILE TYPE states.
2830 Cause a transition to the transformation state.
2833 @item Restricted transformations
2836 Invalid in initial, INPUT PROGRAM, and FILE TYPE states.
2838 Cause a transition to the transformation state.
2844 Invalid in initial, INPUT PROGRAM, and FILE TYPE states.
2846 Cause a transition to the procedure state.
2850 @node Missing Observations, Variables, Order of Commands, Language
2851 @section Handling missing observations
2852 @cindex missing values
2853 @cindex values, missing
2855 PSPP includes special support for unknown numeric data values.
2856 Missing observations are assigned a special value, called the
2857 @dfn{system-missing value}. This ``value'' actually indicates the
2858 absence of value; it means that the actual value is unknown. Procedures
2859 automatically exclude from analyses those observations or cases that
2860 have missing values. Whether single observations or entire cases are
2861 excluded depends on the procedure.
2863 The system-missing value exists only for numeric variables. String
2864 variables always have a defined value, even if it is only a string of
2867 Variables, whether numeric or string, can have designated
2868 @dfn{user-missing values}. Every user-missing value is an actual value
2869 for that variable. However, most of the time user-missing values are
2870 treated in the same way as the system-missing value. String variables
2871 that are wider than a certain width, usually 8 characters (depending on
2872 computer architecture), cannot have user-missing values.
2874 For more information on missing values, see the following sections:
2875 @ref{Variables}, @ref{MISSING VALUES}, @ref{Expressions}. See also the
2876 documentation on individual procedures for information on how they
2877 handle missing values.
2879 @node Variables, Files, Missing Observations, Language
2884 Variables are the basic unit of data storage in PSPP. All the
2885 variables in a file taken together, apart from any associated data, are
2886 said to form a @dfn{dictionary}.
2887 Some details of variables are described in the sections below.
2890 * Attributes:: Attributes of variables.
2891 * System Variables:: Variables automatically defined by PSPP.
2892 * Sets of Variables:: Lists of variable names.
2893 * Input/Output Formats:: Input and output formats.
2894 * Scratch Variables:: Variables deleted by procedures.
2897 @node Attributes, System Variables, Variables, Variables
2898 @subsection Attributes of Variables
2899 @cindex variables, attributes of
2900 @cindex attributes of variables
2901 Each variable has a number of attributes, including:
2905 This is an identifier. Each variable must have a different name.
2908 @cindex variables, type
2909 @cindex type of variables
2913 @cindex variables, width
2914 @cindex width of variables
2916 (string variables only) String variables with a width of 8 characters or
2917 fewer are called @dfn{short string variables}. Short string variables
2918 can be used in many procedures where @dfn{long string variables} (those
2919 with widths greater than 8) are not allowed.
2922 @strong{Please note:} Certain systems may consider strings longer than 8
2923 characters to be short strings. Eight characters represents a minimum
2924 figure for the maximum length of a short string.
2928 Variables in the dictionary are arranged in a specific order.
2929 @cmd{DISPLAY} can be used to show this order: see @ref{DISPLAY}.
2931 @item Initialization
2932 Either reinitialized to 0 or spaces for each case, or left at its
2933 existing value. @xref{LEAVE}.
2935 @cindex missing values
2936 @cindex values, missing
2937 @item Missing values
2938 Optionally, up to three values, or a range of values, or a specific
2939 value plus a range, can be specified as @dfn{user-missing values}.
2940 There is also a @dfn{system-missing value} that is assigned to an
2941 observation when there is no other obvious value for that observation.
2942 Observations with missing values are automatically excluded from
2943 analyses. User-missing values are actual data values, while the
2944 system-missing value is not a value at all. @xref{Missing Observations}.
2946 @cindex variable labels
2947 @cindex labels, variable
2948 @item Variable label
2949 A string that describes the variable. @xref{VARIABLE LABELS}.
2951 @cindex value labels
2952 @cindex labels, value
2954 Optionally, these associate each possible value of the variable with a
2955 string. @xref{VALUE LABELS}.
2957 @cindex print format
2959 Display width, format, and (for numeric variables) number of decimal
2960 places. This attribute does not affect how data are stored, just how
2961 they are displayed. Example: a width of 8, with 2 decimal places.
2962 @xref{PRINT FORMATS}.
2964 @cindex write format
2966 Similar to print format, but used by certain commands that are
2967 designed to write to binary files. @xref{WRITE FORMATS}.
2970 @node System Variables, Sets of Variables, Attributes, Variables
2971 @subsection Variables Automatically Defined by PSPP
2972 @cindex system variables
2973 @cindex variables, system
2975 There are seven system variables. These are not like ordinary
2976 variables, as they are not stored in each case. They can only be used
2977 in expressions. These system variables, whose values and output formats
2978 cannot be modified, are described below.
2981 @cindex @code{$CASENUM}
2983 Case number of the case at the moment. This changes as cases are
2986 @cindex @code{$DATE}
2988 Date the PSPP process was started, in format A9, following the
2989 pattern @code{DD MMM YY}.
2991 @cindex @code{$JDATE}
2993 Number of days between 15 Oct 1582 and the time the PSPP process
2996 @cindex @code{$LENGTH}
2998 Page length, in lines, in format F11.
3000 @cindex @code{$SYSMIS}
3002 System missing value, in format F1.
3004 @cindex @code{$TIME}
3006 Number of seconds between midnight 14 Oct 1582 and the time the active file
3007 was read, in format F20.
3009 @cindex @code{$WIDTH}
3011 Page width, in characters, in format F3.
3014 @node Sets of Variables, Input/Output Formats, System Variables, Variables
3015 @subsection Lists of variable names
3016 @cindex TO convention
3017 @cindex convention, TO
3019 There are several ways to specify a set of variables:
3023 (Most commonly.) List the variable names one after another, optionally
3024 separating them by commas.
3028 (This method cannot be used on commands that define the dictionary, such
3029 as @cmd{DATA LIST}.) The syntax is the names of two existing variables,
3030 separated by the reserved keyword @code{TO}. The meaning is to include
3031 every variable in the dictionary between and including the variables
3032 specified. For instance, if the dictionary contains six variables with
3033 the names @code{ID}, @code{X1}, @code{X2}, @code{GOAL}, @code{MET}, and
3034 @code{NEXTGOAL}, in that order, then @code{X2 TO MET} would include
3035 variables @code{X2}, @code{GOAL}, and @code{MET}.
3038 (This method can be used only on commands that define the dictionary,
3039 such as @cmd{DATA LIST}.) It is used to define sequences of variables
3040 that end in consecutive integers. The syntax is two identifiers that
3041 end in numbers. This method is best illustrated with examples:
3045 The syntax @code{X1 TO X5} defines 5 variables:
3061 The syntax @code{ITEM0008 TO ITEM0013} defines 6 variables:
3079 Each of the syntaxes @code{QUES001 TO QUES9} and @code{QUES6 TO QUES3}
3080 are invalid, although for different reasons, which should be evident.
3083 Note that after a set of variables has been defined with @cmd{DATA LIST}
3084 or another command with this method, the same set can be referenced on
3085 later commands using the same syntax.
3088 The above methods can be combined, either one after another or delimited
3089 by commas. For instance, the combined syntax @code{A Q5 TO Q8 X TO Z}
3090 is legal as long as each part @code{A}, @code{Q5 TO Q8}, @code{X TO Z}
3091 is individually legal.
3094 @node Input/Output Formats, Scratch Variables, Sets of Variables, Variables
3095 @subsection Input and Output Formats
3097 Data that PSPP inputs and outputs must have one of a number of formats.
3098 These formats are described, in general, by a format specification of
3099 the form @code{NAMEw.d}, where @var{name} is the
3100 format name and @var{w} is a field width. @var{d} is the optional
3101 desired number of decimal places, if appropriate. If @var{d} is not
3102 included then it is assumed to be 0. Some formats do not allow @var{d}
3105 When an input format is specified on @cmd{DATA LIST} or another
3107 it is converted to an output format for the purposes of @cmd{PRINT}
3109 data output commands. For most purposes, input and output formats are
3110 the same; the salient differences are described below.
3112 Below are listed the input and output formats supported by PSPP. If an
3113 input format is mapped to a different output format by default, then
3114 that mapping is indicated with @result{}. Each format has the listed
3115 bounds on input width (iw) and output width (ow).
3117 The standard numeric input and output formats are given in the following
3121 @item Fw.d: 1 <= iw,ow <= 40
3122 Standard decimal format with @var{d} decimal places. If the number is
3123 too large to fit within the field width, it is expressed in scientific
3124 notation (@code{1.2+34}) if w >= 6, with always at least two digits in
3125 the exponent. When used as an input format, scientific notation is
3126 allowed but an E or an F must be used to introduce the exponent.
3128 The default output format is the same as the input format, except if
3129 @var{d} > 1. In that case the output @var{w} is always made to be at
3132 @item Ew.d: 1 <= iw <= 40; 6 <= ow <= 40
3133 For input this is equivalent to F format except that no E or F is
3134 require to introduce the exponent. For output, produces scientific
3135 notation in the form @code{1.2+34}. There are always at least two
3136 digits given in the exponent.
3138 The default output @var{w} is the largest of the input @var{w}, the
3139 input @var{d} + 7, and 10. The default output @var{d} is the input
3140 @var{d}, but at least 3.
3142 @item COMMAw.d: 1 <= iw,ow <= 40
3143 Equivalent to F format, except that groups of three digits are
3144 comma-separated on output. If the number is too large to express in the
3145 field width, then first commas are eliminated, then if there is still
3146 not enough space the number is expressed in scientific notation given
3147 that w >= 6. Commas are allowed and ignored when this is used as an
3150 @item DOTw.d: 1 <= iw,ow <= 40
3151 Equivalent to COMMA format except that the roles of comma and decimal
3152 point are interchanged. However: If SET /DECIMAL=DOT is in effect, then
3153 COMMA uses @samp{,} for a decimal point and DOT uses @samp{.} for a
3156 @item DOLLARw.d: 1 <= iw <= 40; 2 <= ow <= 40
3157 Equivalent to COMMA format, except that the number is prefixed by a
3158 dollar sign (@samp{$}) if there is room. On input the value is allowed
3159 to be prefixed by a dollar sign, which is ignored.
3161 The default output @var{w} is the input @var{w}, but at least 2.
3163 @item PCTw.d: 2 <= iw,ow <= 40
3164 Equivalent to F format, except that the number is suffixed by a percent
3165 sign (@samp{%}) if there is room. On input the value is allowed to be
3166 suffixed by a percent sign, which is ignored.
3168 The default output @var{w} is the input @var{w}, but at least 2.
3170 @item Nw.d: 1 <= iw,ow <= 40
3171 Only digits are allowed within the field width. The decimal point is
3172 assumed to be @var{d} digits from the right margin.
3174 The default output format is F with the same @var{w} and @var{d}, except
3175 if @var{d} > 1. In that case the output @var{w} is always made to be at
3178 @item Zw.d @result{} F: 1 <= iw,ow <= 40
3179 Zoned decimal input. If you need to use this then you know how.
3181 @item IBw.d @result{} F: 1 <= iw,ow <= 8
3182 Integer binary format. The field is interpreted as a fixed-point
3183 positive or negative binary number in two's-complement notation. The
3184 location of the decimal point is implied. Endianness is the same as the
3187 The default output format is F8.2 if @var{d} is 0. Otherwise it is F,
3188 with output @var{w} as 9 + input @var{d} and output @var{d} as input
3191 @item PIB @result{} F: 1 <= iw,ow <= 8
3192 Positive integer binary format. The field is interpreted as a
3193 fixed-point positive binary number. The location of the decimal point
3194 is implied. Endianness is teh same as the host machine.
3196 The default output format follows the rules for IB format.
3198 @item Pw.d @result{} F: 1 <= iw,ow <= 16
3199 Binary coded decimal format. Each byte from left to right, except the
3200 rightmost, represents two digits. The upper nibble of each byte is more
3201 significant. The upper nibble of the final byte is the least
3202 significant digit. The lower nibble of the final byte is the sign; a
3203 value of D represents a negative sign and all other values are
3204 considered positive. The decimal point is implied.
3206 The default output format follows the rules for IB format.
3208 @item PKw.d @result{} F: 1 <= iw,ow <= 16
3209 Positive binary code decimal format. Same as P but the last byte is the
3212 The default output format follows the rules for IB format.
3214 @item RBw @result{} F: 2 <= iw,ow <= 8
3216 Binary C architecture-dependent ``double'' format. For a standard
3217 IEEE754 implementation @var{w} should be 8.
3219 The default output format follows the rules for IB format.
3221 @item PIBHEXw.d @result{} F: 2 <= iw,ow <= 16
3222 PIB format encoded as textual hex digit pairs. @var{w} must be even.
3224 The input width is mapped to a default output width as follows:
3225 2@result{}4, 4@result{}6, 6@result{}9, 8@result{}11, 10@result{}14,
3226 12@result{}16, 14@result{}18, 16@result{}21. No allowances are made for
3229 @item RBHEXw @result{} F: 4 <= iw,ow <= 16
3231 RB format encoded as textual hex digits pairs. @var{w} must be even.
3233 The default output format is F8.2.
3235 @item CCAw.d: 1 <= ow <= 40
3236 @itemx CCBw.d: 1 <= ow <= 40
3237 @itemx CCCw.d: 1 <= ow <= 40
3238 @itemx CCDw.d: 1 <= ow <= 40
3239 @itemx CCEw.d: 1 <= ow <= 40
3241 User-defined custom currency formats. May not be used as an input
3242 format. @xref{SET}, for more details.
3245 The date and time numeric input and output formats accept a number of
3246 possible formats. Before describing the formats themselves, some
3247 definitions of the elements that make up their formats will be helpful:
3251 All formats accept an optional whitespace leader.
3254 An integer between 1 and 31 representing the day of month.
3257 An integer representing a number of days.
3259 @item date-delimiter
3260 One or more characters of whitespace or the following characters:
3264 A month name in one of the following forms:
3267 An integer between 1 and 12.
3269 Roman numerals representing an integer between 1 and 12.
3271 At least the first three characters of an English month name (January,
3276 An integer year number between 1582 and 19999, or between 1 and 199.
3277 Years between 1 and 199 will have 1900 added.
3280 A single number with a year number in the first 2, 3, or 4 digits (as
3281 above) and the day number within the year in the last 3 digits.
3284 An integer between 1 and 4 representing a quarter.
3287 The letter @samp{Q} or @samp{q}.
3290 An integer between 1 and 53 representing a week within a year.
3293 The letters @samp{wk} in any case.
3295 @item time-delimiter
3296 At least one characters of whitespace or @samp{:} or @samp{.}.
3299 An integer greater than 0 representing an hour.
3302 An integer between 0 and 59 representing a minute within an hour.
3305 Optionally, a time-delimiter followed by a real number representing a
3309 An integer between 0 and 23 representing an hour within a day.
3312 At least the first two characters of an English day word.
3315 Any amount or no amount of whitespace.
3318 An optional positive or negative sign.
3321 All formats accept an optional whitespace trailer.
3324 The date input formats are strung together from the above pieces. On
3325 output, the date formats are always printed in a single canonical
3326 manner, based on field width. The date input and output formats are
3330 @item DATEw: 9 <= iw,ow <= 40
3331 Date format. Input format: leader + day + date-delimiter +
3332 month + date-delimiter + year + trailer. Output format: DD-MMM-YY for
3333 @var{w} < 11, DD-MMM-YYYY otherwise.
3335 @item EDATEw: 8 <= iw,ow <= 40
3336 European date format. Input format same as DATE. Output format:
3337 DD.MM.YY for @var{w} < 10, DD.MM.YYYY otherwise.
3339 @item SDATEw: 8 <= iw,ow <= 40
3340 Standard date format. Input format: leader + year + date-delimiter +
3341 month + date-delimiter + day + trailer. Output format: YY/MM/DD for
3342 @var{w} < 10, YYYY/MM/DD otherwise.
3344 @item ADATEw: 8 <= iw,ow <= 40
3345 American date format. Input format: leader + month + date-delimiter +
3346 day + date-delimiter + year + trailer. Output format: MM/DD/YY for
3347 @var{w} < 10, MM/DD/YYYY otherwise.
3349 @item JDATEw: 5 <= iw,ow <= 40
3350 Julian date format. Input format: leader + julian + trailer. Output
3351 format: YYDDD for @var{w} < 7, YYYYDDD otherwise.
3353 @item QYRw: 4 <= iw <= 40, 6 <= ow <= 40
3354 Quarter/year format. Input format: leader + quarter + q-delimiter +
3355 year + trailer. Output format: @samp{Q Q YY}, where the first
3356 @samp{Q} is one of the digits 1, 2, 3, 4, if @var{w} < 8, @code{Q Q
3359 @item MOYRw: 6 <= iw,ow <= 40
3360 Month/year format. Input format: leader + month + date-delimiter + year
3361 + trailer. Output format: @samp{MMM YY} for @var{w} < 8, @samp{MMM
3364 @item WKYRw: 6 <= iw <= 40, 8 <= ow <= 40
3365 Week/year format. Input format: leader + week + wk-delimiter + year +
3366 trailer. Output format: @samp{WW WK YY} for @var{w} < 10, @samp{WW WK
3369 @item DATETIMEw.d: 17 <= iw,ow <= 40
3370 Date and time format. Input format: leader + day + date-delimiter +
3371 month + date-delimiter + yaer + time-delimiter + hour24 + time-delimiter
3372 + minute + opt-second. Output format: @samp{DD-MMM-YYYY HH:MM}. If
3373 @var{w} > 19 then seconds @samp{:SS} is added. If @var{w} > 22 and
3374 @var{d} > 0 then fractional seconds @samp{.SS} are added.
3376 @item TIMEw.d: 5 <= iw,ow <= 40
3377 Time format. Input format: leader + sign + spaces + hour +
3378 time-delimiter + minute + opt-second. Output format: @samp{HH:MM}.
3379 Seconds and fractional seconds are available with @var{w} of at least 8
3380 and 10, respectively.
3382 @item DTIMEw.d: 1 <= iw <= 40, 8 <= ow <= 40
3383 Time format with day count. Input format: leader + sign + spaces +
3384 day-count + time-delimiter + hour + time-delimiter + minute +
3385 opt-second. Output format: @samp{DD HH:MM}. Seconds and fractional
3386 seconds are available with @var{w} of at least 8 and 10, respectively.
3388 @item WKDAYw: 2 <= iw,ow <= 40
3389 A weekday as a number between 1 and 7, where 1 is Sunday. Input format:
3390 leader + weekday + trailer. Output format: as many characters, in all
3391 capital letters, of the English name of the weekday as will fit in the
3394 @item MONTHw: 3 <= iw,ow <= 40
3395 A month as a number between 1 and 12, where 1 is January. Input format:
3396 leader + month + trailer. Output format: as many character, in all
3397 capital letters, of the English name of the month as will fit in the
3401 There are only two formats that may be used with string variables:
3404 @item Aw: 1 <= iw <= 255, 1 <= ow <= 254
3405 The entire field is treated as a string value.
3407 @item AHEXw @result{} A: 2 <= iw <= 254; 2 <= ow <= 510
3408 The field is composed of characters in a string encoded as textual hex
3411 The default output @var{w} is half the input @var{w}.
3414 @node Scratch Variables, , Input/Output Formats, Variables
3415 @subsection Scratch Variables
3417 Most of the time, variables don't retain their values between cases.
3418 Instead, either they're being read from a data file or the active file,
3419 in which case they assume the value read, or, if created with
3421 another transformation, they're initialized to the system-missing value
3422 or to blanks, depending on type.
3424 However, sometimes it's useful to have a variable that keeps its value
3425 between cases. You can do this with @cmd{LEAVE} (@pxref{LEAVE}), or you can
3426 use a @dfn{scratch variable}. Scratch variables are variables whose
3427 names begin with an octothorpe (@samp{#}).
3429 Scratch variables have the same properties as variables left with
3431 they retain their values between cases, and for the first case they are
3432 initialized to 0 or blanks. They have the additional property that they
3433 are deleted before the execution of any procedure. For this reason,
3434 scratch variables can't be used for analysis. To obtain the same
3435 effect, use @cmd{COMPUTE} (@pxref{COMPUTE}) to copy the scratch variable's
3436 value into an ordinary variable, then analysis that variable.
3438 @node Files, BNF, Variables, Language
3439 @section Files Used by PSPP
3441 PSPP makes use of many files each time it runs. Some of these it
3442 reads, some it writes, some it creates. Here is a table listing the
3443 most important of these files:
3446 @cindex file, command
3447 @cindex file, syntax file
3448 @cindex command file
3452 These names (synonyms) refer to the file that contains instructions to
3453 PSPP that tell it what to do. The syntax file's name is specified on
3454 the PSPP command line. Syntax files can also be pulled in with
3455 @cmd{INCLUDE} (@pxref{INCLUDE}).
3460 Data files contain raw data in ASCII format suitable for being read in
3461 by @cmd{DATA LIST}. Data can be embedded in the syntax
3462 file with @cmd{BEGIN DATA} and @cmd{END DATA}: this makes the
3463 syntax file a data file too.
3465 @cindex file, output
3468 One or more output files are created by PSPP each time it is
3469 run. The output files receive the tables and charts produced by
3470 statistical procedures. The output files may be in any number of formats,
3471 depending on how PSPP is configured.
3474 @cindex file, active
3476 The active file is the ``file'' on which all PSPP procedures
3477 are performed. The active file contains variable definitions and
3478 cases. The active file is not necessarily a disk file: it is stored
3479 in memory if there is room.
3482 @node BNF, , Files, Language
3483 @section Backus-Naur Form
3485 @cindex Backus-Naur Form
3486 @cindex command syntax, description of
3487 @cindex description of command syntax
3489 The syntax of some parts of the PSPP language is presented in this
3490 manual using the formalism known as @dfn{Backus-Naur Form}, or BNF. The
3491 following table describes BNF:
3497 Words in all-uppercase are PSPP keyword tokens. In BNF, these are
3498 often called @dfn{terminals}. There are some special terminals, which
3499 are actually written in lowercase for clarity:
3502 @cindex @code{number}
3506 @cindex @code{integer}
3507 @item @code{integer}
3510 @cindex @code{string}
3514 @cindex @code{var-name}
3515 @item @code{var-name}
3516 A single variable name.
3520 @item @code{=}, @code{/}, @code{+}, @code{-}, etc.
3521 Operators and punctuators.
3524 @cindex terminal dot
3525 @cindex dot, terminal
3527 The terminal dot. This is not necessarily an actual dot in the syntax
3528 file: @xref{Commands}, for more details.
3533 @cindex nonterminals
3534 Other words in all lowercase refer to BNF definitions, called
3535 @dfn{productions}. These productions are also known as
3536 @dfn{nonterminals}. Some nonterminals are very common, so they are
3537 defined here in English for clarity:
3540 @cindex @code{var-list}
3542 A list of one or more variable names or the keyword @code{ALL}.
3544 @cindex @code{expression}
3546 An expression. @xref{Expressions}, for details.
3551 @cindex ``is defined as''
3553 @samp{::=} means ``is defined as''. The left side of @samp{::=} gives
3554 the name of the nonterminal being defined. The right side of @samp{::=}
3555 gives the definition of that nonterminal. If the right side is empty,
3556 then one possible expansion of that nonterminal is nothing. A BNF
3557 definition is called a @dfn{production}.
3560 @cindex terminals and nonterminals, differences
3561 So, the key difference between a terminal and a nonterminal is that a
3562 terminal cannot be broken into smaller parts---in fact, every terminal
3563 is a single token (@pxref{Tokens}). On the other hand, nonterminals are
3564 composed of a (possibly empty) sequence of terminals and nonterminals.
3565 Thus, terminals indicate the deepest level of syntax description. (In
3566 parsing theory, terminals are the leaves of the parse tree; nonterminals
3570 @cindex start symbol
3571 @cindex symbol, start
3572 The first nonterminal defined in a set of productions is called the
3573 @dfn{start symbol}. The start symbol defines the entire syntax for
3577 @node Expressions, Data Input and Output, Language, Top
3578 @chapter Mathematical Expressions
3579 @cindex expressions, mathematical
3580 @cindex mathematical expressions
3582 Some PSPP commands use expressions, which share a common syntax
3583 among all PSPP commands. Expressions are made up of
3584 @dfn{operands}, which can be numbers, strings, or variable names,
3585 separated by @dfn{operators}. There are five types of operators:
3586 grouping, arithmetic, logical, relational, and functions.
3588 Every operator takes one or more @dfn{arguments} as input and produces
3589 or @dfn{returns} exactly one result as output. Both strings and numeric
3590 values can be used as arguments and are produced as results, but each
3591 operator accepts only specific combinations of numeric and string values
3592 as arguments. With few exceptions, operator arguments may be
3593 full-fledged expressions in themselves.
3596 * Boolean Values:: Boolean values.
3597 * Missing Values in Expressions:: Using missing values in expressions.
3598 * Grouping Operators:: parentheses
3599 * Arithmetic Operators:: add sub mul div pow
3600 * Logical Operators:: AND NOT OR
3601 * Relational Operators:: EQ GE GT LE LT NE
3602 * Functions:: More-sophisticated operators.
3603 * Order of Operations:: Operator precedence.
3606 @node Boolean Values, Missing Values in Expressions, Expressions, Expressions
3607 @section Boolean Values
3609 @cindex values, Boolean
3611 Some PSPP operators and expressions work with Boolean values, which
3612 represent true/false conditions. Booleans have only three possible
3613 values: 0 (false), 1 (true), and system-missing (unknown).
3614 System-missing is neither true nor false and indicates that the true
3617 Boolean-typed operands or function arguments must take on one of these
3618 three values. Other values are considered false, but cause an error
3619 when the expression is evaluated.
3621 Strings and Booleans are not compatible, and neither may be used in
3624 @node Missing Values in Expressions, Grouping Operators, Boolean Values, Expressions
3625 @section Missing Values in Expressions
3627 String missing values are not treated specially in expressions. Most
3628 numeric operators return system-missing when given system-missing
3629 arguments. Exceptions are listed under particular operator
3632 User-missing values for numeric variables are always transformed into
3633 the system-missing value, except inside the arguments to the
3634 @code{VALUE} and @code{SYSMIS} functions.
3636 The missing-value functions can be used to precisely control how missing
3637 values are treated in expressions. @xref{Missing Value Functions}, for
3640 @node Grouping Operators, Arithmetic Operators, Missing Values in Expressions, Expressions
3641 @section Grouping Operators
3644 @cindex grouping operators
3645 @cindex operators, grouping
3647 Parentheses (@samp{()}) are the grouping operators. Surround an
3648 expression with parentheses to force early evaluation.
3650 Parentheses also surround the arguments to functions, but in that
3651 situation they act as punctuators, not as operators.
3653 @node Arithmetic Operators, Logical Operators, Grouping Operators, Expressions
3654 @section Arithmetic Operators
3655 @cindex operators, arithmetic
3656 @cindex arithmetic operators
3658 The arithmetic operators take numeric arguments and produce numeric
3664 @item @var{a} + @var{b}
3665 Adds @var{a} and @var{b}, returning the sum.
3669 @item @var{a} - @var{b}
3670 Subtracts @var{b} from @var{a}, returning the difference.
3673 @cindex multiplication
3674 @item @var{a} * @var{b}
3675 Multiplies @var{a} and @var{b}, returning the product.
3679 @item @var{a} / @var{b}
3680 Divides @var{a} by @var{b}, returning the quotient. If @var{b} is
3681 zero, the result is system-missing.
3684 @cindex exponentiation
3685 @item @var{a} ** @var{b}
3686 Returns the result of raising @var{a} to the power @var{b}. If
3687 @var{a} is negative and @var{b} is not an integer, the result is
3688 system-missing. The result of @code{0**0} is system-missing as well.
3693 Reverses the sign of @var{a}.
3696 @node Logical Operators, Relational Operators, Arithmetic Operators, Expressions
3697 @section Logical Operators
3698 @cindex logical operators
3699 @cindex operators, logical
3704 @cindex values, system-missing
3705 @cindex system-missing
3706 The logical operators take logical arguments and produce logical
3707 results, meaning ``true or false''. PSPP logical operators are
3708 not true Boolean operators because they may also result in a
3709 system-missing value.
3714 @cindex intersection, logical
3715 @cindex logical intersection
3716 @item @var{a} AND @var{b}
3717 @itemx @var{a} & @var{b}
3718 True if both @var{a} and @var{b} are true, false otherwise. If one
3719 argument is false, the result is false even if the other is missing. If
3720 both arguments are missing, the result is missing.
3724 @cindex union, logical
3725 @cindex logical union
3726 @item @var{a} OR @var{b}
3727 @itemx @var{a} | @var{b}
3728 True if at least one of @var{a} and @var{b} is true. If one argument is
3729 true, the result is true even if the other argument is missing. If both
3730 arguments are missing, the result is missing.
3734 @cindex inversion, logical
3735 @cindex logical inversion
3738 True if @var{a} is false. If the argument is missing, then the result
3742 @node Relational Operators, Functions, Logical Operators, Expressions
3743 @section Relational Operators
3745 The relational operators take numeric or string arguments and produce Boolean
3748 Strings cannot be compared to numbers. When strings of different
3749 lengths are compared, the shorter string is right-padded with spaces
3750 to match the length of the longer string.
3752 The results of string comparisons, other than tests for equality or
3753 inequality, are dependent on the character set in use. String
3754 comparisons are case-sensitive.
3757 @cindex equality, testing
3758 @cindex testing for equality
3761 @item @var{a} EQ @var{b}
3762 @itemx @var{a} = @var{b}
3763 True if @var{a} is equal to @var{b}.
3765 @cindex less than or equal to
3768 @item @var{a} LE @var{b}
3769 @itemx @var{a} <= @var{b}
3770 True if @var{a} is less than or equal to @var{b}.
3775 @item @var{a} LT @var{b}
3776 @itemx @var{a} < @var{b}
3777 True if @var{a} is less than @var{b}.
3779 @cindex greater than or equal to
3782 @item @var{a} GE @var{b}
3783 @itemx @var{a} >= @var{b}
3784 True if @var{a} is greater than or equal to @var{b}.
3786 @cindex greater than
3789 @item @var{a} GT @var{b}
3790 @itemx @var{a} > @var{b}
3791 True if @var{a} is greater than @var{b}.
3793 @cindex inequality, testing
3794 @cindex testing for inequality
3798 @item @var{a} NE @var{b}
3799 @itemx @var{a} ~= @var{b}
3800 @itemx @var{a} <> @var{b}
3801 True is @var{a} is not equal to @var{b}.
3804 @node Functions, Order of Operations, Relational Operators, Expressions
3813 @cindex names, of functions
3814 PSPP functions provide mathematical abilities above and beyond
3815 those possible using simple operators. Functions have a common
3816 syntax: each is composed of a function name followed by a left
3817 parenthesis, one or more arguments, and a right parenthesis. Function
3818 names are @strong{not} reserved; their names are specially treated
3819 only when followed by a left parenthesis: @code{EXP(10)} refers to the
3820 constant value @code{e} raised to the 10th power, but @code{EXP} by
3821 itself refers to the value of variable EXP.
3823 The sections below describe each function in detail.
3826 * Advanced Mathematics:: EXP LG10 LN SQRT
3827 * Miscellaneous Mathematics:: ABS MOD MOD10 RND TRUNC
3828 * Trigonometry:: ACOS ARCOS ARSIN ARTAN ASIN ATAN COS SIN TAN
3829 * Missing Value Functions:: MISSING NMISS NVALID SYSMIS VALUE
3830 * Pseudo-Random Numbers:: NORMAL UNIFORM
3831 * Set Membership:: ANY RANGE
3832 * Statistical Functions:: CFVAR MAX MEAN MIN SD SUM VARIANCE
3833 * String Functions:: CONCAT INDEX LENGTH LOWER LPAD LTRIM NUMBER
3834 RINDEX RPAD RTRIM STRING SUBSTR UPCASE
3835 * Time & Date:: CTIME.xxx DATE.xxx TIME.xxx XDATE.xxx
3836 * Miscellaneous Functions:: LAG YRMODA
3837 * Functions Not Implemented:: CDF.xxx CDFNORM IDF.xxx NCDF.xxx PROBIT RV.xxx
3840 @node Advanced Mathematics, Miscellaneous Mathematics, Functions, Functions
3841 @subsection Advanced Mathematical Functions
3842 @cindex mathematics, advanced
3844 Advanced mathematical functions take numeric arguments and produce
3847 @deftypefn {Function} {} EXP (@var{exponent})
3848 Returns @i{e} (approximately 2.71828) raised to power @var{exponent}.
3852 @deftypefn {Function} {} LG10 (@var{number})
3853 Takes the base-10 logarithm of @var{number}. If @var{number} is
3854 not positive, the result is system-missing.
3857 @deftypefn {Function} {} LN (@var{number})
3858 Takes the base-@i{e} logarithm of @var{number}. If @var{number} is
3859 not positive, the result is system-missing.
3862 @cindex square roots
3863 @deftypefn {Function} {} SQRT (@var{number})
3864 Takes the square root of @var{number}. If @var{number} is negative,
3865 the result is system-missing.
3868 @node Miscellaneous Mathematics, Trigonometry, Advanced Mathematics, Functions
3869 @subsection Miscellaneous Mathematical Functions
3870 @cindex mathematics, miscellaneous
3872 Miscellaneous mathematical functions take numeric arguments and produce
3875 @cindex absolute value
3876 @deftypefn {Function} {} ABS (@var{number})
3877 Results in the absolute value of @var{number}.
3881 @deftypefn {Function} {} MOD (@var{numerator}, @var{denominator})
3882 Returns the remainder (modulus) of @var{numerator} divided by
3883 @var{denominator}. If @var{denominator} is 0, the result is
3884 system-missing. However, if @var{numerator} is 0 and
3885 @var{denominator} is system-missing, the result is 0.
3888 @cindex modulus, by 10
3889 @deftypefn {Function} {} MOD10 (@var{number})
3890 Returns the remainder when @var{number} is divided by 10. If
3891 @var{number} is negative, MOD10(@var{number}) is negative or zero.
3895 @deftypefn {Function} {} RND (@var{number})
3896 Takes the absolute value of @var{number} and rounds it to an integer.
3897 Then, if @var{number} was negative originally, negates the result.
3901 @deftypefn {Function} {} TRUNC (@var{number})
3902 Discards the fractional part of @var{number}; that is, rounds
3903 @var{number} towards zero.
3906 @node Trigonometry, Missing Value Functions, Miscellaneous Mathematics, Functions
3907 @subsection Trigonometric Functions
3908 @cindex trigonometry
3910 Trigonometric functions take numeric arguments and produce numeric
3914 @cindex inverse cosine
3915 @deftypefn {Function} {} ARCOS (@var{number})
3916 Takes the arccosine, in radians, of @var{number}. Results in
3917 system-missing if @var{number} is not between -1 and 1.
3921 @cindex inverse sine
3922 @deftypefn {Function} {} ARSIN (@var{number})
3923 Takes the arcsine, in radians, of @var{number}. Results in
3924 system-missing if @var{number} is not between -1 and 1 inclusive.
3928 @cindex inverse tangent
3929 @deftypefn {Function} {} ARTAN (@var{number})
3930 Takes the arctangent, in radians, of @var{number}.
3934 @deftypefn {Function} {} COS (@var{angle})
3935 Takes the cosine of @var{angle} which should be in radians.
3939 @deftypefn {Function} {} SIN (@var{angle})
3940 Takes the sine of @var{angle} which should be in radians.
3944 @deftypefn {Function} {} TAN (@var{angle})
3945 Takes the tangent of @var{angle} which should be in radians.
3946 Results in system-missing at values
3947 of @var{angle} that are too close to odd multiples of pi/2.
3951 @node Missing Value Functions, Pseudo-Random Numbers, Trigonometry, Functions
3952 @subsection Missing-Value Functions
3953 @cindex missing values
3954 @cindex values, missing
3955 @cindex functions, missing-value
3957 Missing-value functions take various numeric arguments and yield
3958 various types of results. Note that the normal rules of evaluation
3959 apply within expression arguments to these functions. In particular,
3960 user-missing values for numeric variables are converted to
3961 system-missing values.
3963 @deftypefn {Function} {} MISSING (@var{expr})
3964 Returns 1 if @var{expr} has the system-missing value, 0 otherwise.
3967 @deftypefn {Function} {} NMISS (@var{expr} [, @var{expr}]@dots{})
3968 Each argument must be a numeric expression. Returns the number of
3969 system-missing values in the list. As a special extension,
3970 the syntax @code{@var{var1} TO @var{var2}} may be used to refer to a
3971 range of variables; see @ref{Sets of Variables}, for more details.
3974 @deftypefn {Function} {} NVALID (@var{expr} [, @var{expr}]@dots{})
3975 Each argument must be a numeric expression. Returns the number of
3976 values in the list that are not system-missing. As a special extension,
3977 the syntax @code{@var{var1} TO @var{var2}} may be used to refer to a
3978 range of variables; see @ref{Sets of Variables}, for more details.
3981 @deftypefn {Function} {} SYSMIS (@var{expr})
3982 When @var{expr} is simply the name of a numeric variable, returns 1 if
3983 the variable has the system-missing value, 0 if it is user-missing or
3984 not missing. If given @var{expr} takes another form, results in 1 if
3985 the value is system-missing, 0 otherwise.
3988 @deftypefn {Function} {} VALUE (@var{variable})
3989 Prevents the user-missing values of @var{variable} from being
3990 transformed into system-missing values, and always results in the
3991 actual value of @var{variable}, whether it is user-missing,
3992 system-missing or not missing at all.
3995 @node Pseudo-Random Numbers, Set Membership, Missing Value Functions, Functions
3996 @subsection Pseudo-Random Number Generation Functions
3997 @cindex random numbers
3998 @cindex pseudo-random numbers (see random numbers)
4000 Pseudo-random number generation functions take numeric arguments and
4001 produce numeric results.
4003 PSPP uses the alleged RC4 cipher as a pseudo-random number generator
4004 (PRNG). The bytes output by this PRNG are system-independent for a
4005 given random seed, but differences in endianness and floating-point
4006 formats will make PRNG results differ from system to system. RC4
4007 should produce high-quality random numbers for simulation purposes.
4008 (If you're concerned about the quality of the random number generator,
4009 well, you're using a statistical processing package---analyze it!)
4011 PSPP's implementation of RC4 has not undergone any security auditing.
4012 Furthermore, various precautions that would be necessary for secure
4013 operation, such as secure seeding and discarding the first several
4014 bytes of output, have not been taken. Therefore, PSPP's
4015 implementation of RC4 should not be used for security purposes.
4017 @cindex random numbers, normally-distributed
4018 @deftypefn {Function} {} NORMAL (@var{number})
4019 Results in a random number. Results from @code{NORMAL} are normally
4020 distributed with a mean of 0 and a standard deviation of @var{number}.
4023 @cindex random numbers, uniformly-distributed
4024 @deftypefn {Function} {} UNIFORM (@var{number})
4025 Results in a random number between 0 and @var{number}. Results from
4026 @code{UNIFORM} are evenly distributed across its entire range. There
4027 may be a maximum on the largest random number ever generated---this is
4035 (2,147,483,647), but it may be orders of magnitude
4039 @node Set Membership, Statistical Functions, Pseudo-Random Numbers, Functions
4040 @subsection Set-Membership Functions
4041 @cindex set membership
4042 @cindex membership, of set
4044 Set membership functions determine whether a value is a member of a set.
4045 They take a set of numeric arguments or a set of string arguments, and
4046 produce Boolean results.
4048 String comparisons are performed according to the rules given in
4049 @ref{Relational Operators}.
4051 @deftypefn {Function} {} ANY (@var{value}, @var{set} [, @var{set}]@dots{})
4052 Results in true if @var{value} is equal to any of the @var{set}
4053 values. Otherwise, results in false. If @var{value} is
4054 system-missing, returns system-missing. System-missing values in
4055 @var{set} do not cause ANY to return system-missing.
4058 @deftypefn {Function} {} RANGE (@var{value}, @var{low}, @var{high} [, @var{low}, @var{high}]@dots{})
4059 Results in true if @var{value} is in any of the intervals bounded by
4060 @var{low} and @var{high} inclusive. Otherwise, results in false.
4061 Each @var{low} must be less than or equal to its corresponding
4062 @var{high} value. @var{low} and @var{high} must be given in pairs.
4063 If @var{value} is system-missing, returns system-missing.
4064 System-missing values in @var{set} do not cause RANGE to return
4068 @node Statistical Functions, String Functions, Set Membership, Functions
4069 @subsection Statistical Functions
4070 @cindex functions, statistical
4073 Statistical functions compute descriptive statistics on a list of
4074 values. Some statistics can be computed on numeric or string values;
4075 other can only be computed on numeric values. Their results have the
4076 same type as their arguments. The current case's weighting factor
4077 (@pxref{WEIGHT}) has no effect on statistical functions.
4079 @cindex arguments, minimum valid
4080 @cindex minimum valid number of arguments
4081 With statistical functions it is possible to specify a minimum number of
4082 non-missing arguments for the function to be evaluated. To do so,
4083 append a dot and the number to the function name. For instance, to
4084 specify a minimum of three valid arguments to the MEAN function, use the
4087 @cindex coefficient of variation
4088 @cindex variation, coefficient of
4089 @deftypefn {Function} {} CFVAR (@var{number}, @var{number}[, @dots{}])
4090 Results in the coefficient of variation of the values of @var{number}.
4091 This function requires at least two valid arguments to give a
4092 non-missing result. (The coefficient of variation is the standard
4093 deviation divided by the mean.)
4097 @deftypefn {Function} {} MAX (@var{value}, @var{value}[, @dots{}])
4098 Results in the value of the greatest @var{value}. The @var{value}s may
4099 be numeric or string. Although at least two arguments must be given,
4100 only one need be valid for MAX to give a non-missing result.
4104 @deftypefn {Function} {} MEAN (@var{number}, @var{number}[, @dots{}])
4105 Results in the mean of the values of @var{number}. Although at least
4106 two arguments must be given, only one need be valid for MEAN to give a
4111 @deftypefn {Function} {} MIN (@var{number}, @var{number}[, @dots{}])
4112 Results in the value of the least @var{value}. The @var{value}s may
4113 be numeric or string. Although at least two arguments must be given,
4114 only one need be valid for MAX to give a non-missing result.
4117 @cindex standard deviation
4118 @cindex deviation, standard
4119 @deftypefn {Function} {} SD (@var{number}, @var{number}[, @dots{}])
4120 Results in the standard deviation of the values of @var{number}.
4121 This function requires at least two valid arguments to give a
4126 @deftypefn {Function} {} SUM (@var{number}, @var{number}[, @dots{}])
4127 Results in the sum of the values of @var{number}. Although at least two
4128 arguments must be given, only one need by valid for SUM to give a
4133 @deftypefn {Function} {} VARIANCE (@var{number}, @var{number}[, @dots{}])
4134 Results in the variance of the values of @var{number}. This function
4135 requires at least two valid arguments to give a non-missing result.
4138 @node String Functions, Time & Date, Statistical Functions, Functions
4139 @subsection String Functions
4140 @cindex functions, string
4141 @cindex string functions
4143 String functions take various arguments and return various results.
4145 @cindex concatenation
4146 @cindex strings, concatenation of
4147 @deftypefn {Function} {} CONCAT (@var{string}, @var{string}[, @dots{}])
4148 Returns a string consisting of each @var{string} in sequence.
4149 @code{CONCAT("abc", "def", "ghi")} has a value of @code{"abcdefghi"}.
4150 The resultant string is truncated to a maximum of 255 characters.
4153 @cindex searching strings
4154 @deftypefn {Function} {} INDEX (@var{haystack}, @var{needle})
4155 Returns a positive integer indicating the position of the first
4156 occurrence @var{needle} in @var{haystack}. Returns 0 if @var{haystack}
4157 does not contain @var{needle}. Returns system-missing if @var{needle}
4161 @deftypefn {Function} {} INDEX (@var{haystack}, @var{needle}, @var{divisor})
4162 Divides @var{needle} into parts, each with length @var{divisor}.
4163 Searches @var{haystack} for the first occurrence of each part, and
4164 returns the smallest value. Returns 0 if @var{haystack} does not
4165 contain any part in @var{needle}. It is an error if @var{divisor}
4166 cannot be evenly divided into the length of @var{needle}. Returns
4167 system-missing if @var{needle} is an empty string.
4170 @cindex strings, finding length of
4171 @deftypefn {Function} {} LENGTH (@var{string})
4172 Returns the number of characters in @var{string}.
4175 @cindex strings, case of
4176 @deftypefn {Function} {} LOWER (@var{string})
4177 Returns a string identical to @var{string} except that all uppercase
4178 letters are changed to lowercase letters. The definitions of
4179 ``uppercase'' and ``lowercase'' are system-dependent.
4182 @cindex strings, padding
4183 @deftypefn {Function} {} LPAD (@var{string}, @var{length})
4184 If @var{string} is at least @var{length} characters in length, returns
4185 @var{string} unchanged. Otherwise, returns @var{string} padded with
4186 spaces on the left side to length @var{length}. Returns an empty string
4187 if @var{length} is system-missing, negative, or greater than 255.
4190 @deftypefn {Function} {} LPAD (@var{string}, @var{length}, @var{padding})
4191 If @var{string} is at least @var{length} characters in length, returns
4192 @var{string} unchanged. Otherwise, returns @var{string} padded with
4193 @var{padding} on the left side to length @var{length}. Returns an empty
4194 string if @var{length} is system-missing, negative, or greater than 255, or
4195 if @var{padding} does not contain exactly one character.
4198 @cindex strings, trimming
4199 @cindex whitespace, trimming
4200 @deftypefn {Function} {} LTRIM (@var{string})
4201 Returns @var{string}, after removing leading spaces. Other whitespace,
4202 such as tabs, carriage returns, line feeds, and vertical tabs, is not
4206 @deftypefn {Function} {} LTRIM (@var{string}, @var{padding})
4207 Returns @var{string}, after removing leading @var{padding} characters.
4208 If @var{padding} does not contain exactly one character, returns an
4212 @cindex numbers, converting from strings
4213 @cindex strings, converting to numbers
4214 @deftypefn {Function} {} NUMBER (@var{string}, @var{format})
4215 Returns the number produced when @var{string} is interpreted according
4216 to format specifier @var{format}. If the format width @var{w} is less
4217 than the length of @var{string}, then only the first @var{w}
4218 characters in @var{string} are used, e.g.@: @code{NUMBER("123", F3.0)}
4219 and @code{NUMBER("1234", F3.0)} both have value 123. If @var{w} is
4220 greater than @var{string}'s length, then it is treated as if it were
4221 right-padded with spaces. If @var{string} is not in the correct
4222 format for @var{format}, system-missing is returned.
4225 @cindex strings, searching backwards
4226 @deftypefn {Function} {} RINDEX (@var{string}, @var{format})
4227 Returns a positive integer indicating the position of the last
4228 occurrence of @var{needle} in @var{haystack}. Returns 0 if
4229 @var{haystack} does not contain @var{needle}. Returns system-missing if
4230 @var{needle} is an empty string.
4233 @deftypefn {Function} {} RINDEX (@var{haystack}, @var{needle}, @var{divisor})
4234 Divides @var{needle} into parts, each with length @var{divisor}.
4235 Searches @var{haystack} for the last occurrence of each part, and
4236 returns the largest value. Returns 0 if @var{haystack} does not contain
4237 any part in @var{needle}. It is an error if @var{divisor} cannot be
4238 evenly divided into the length of @var{needle}. Returns system-missing
4239 if @var{needle} is an empty string.
4242 @cindex padding strings
4243 @cindex strings, padding
4244 @deftypefn {Function} {} RPAD (@var{string}, @var{length})
4245 If @var{string} is at least @var{length} characters in length, returns
4246 @var{string} unchanged. Otherwise, returns @var{string} padded with
4247 spaces on the right to length @var{length}. Returns an empty string if
4248 @var{length} is system-missing, negative, or greater than 255.
4251 @deftypefn {Function} {} RPAD (@var{string}, @var{length}, @var{padding})
4252 If @var{string} is at least @var{length} characters in length, returns
4253 @var{string} unchanged. Otherwise, returns @var{string} padded with
4254 @var{padding} on the right to length @var{length}. Returns an empty
4255 string if @var{length} is system-missing, negative, or greater than 255,
4256 or if @var{padding} does not contain exactly one character.
4259 @cindex strings, trimming
4260 @cindex whitespace, trimming
4261 @deftypefn {Function} {} RTRIM (@var{string})
4262 Returns @var{string}, after removing trailing spaces. Other types of
4263 whitespace are not removed.
4266 @deftypefn {Function} {} RTRIM (@var{string}, @var{padding})
4267 Returns @var{string}, after removing trailing @var{padding} characters.
4268 If @var{padding} does not contain exactly one character, returns an
4272 @cindex strings, converting from numbers
4273 @cindex numbers, converting to strings
4274 @deftypefn {Function} {} STRING (@var{number}, @var{format})
4275 Returns a string corresponding to @var{number} in the format given by
4276 format specifier @var{format}. For example, @code{STRING(123.56, F5.1)}
4277 has the value @code{"123.6"}.
4281 @cindex strings, taking substrings of
4282 @deftypefn {Function} {} SUBSTR (@var{string}, @var{start})
4283 Returns a string consisting of the value of @var{string} from position
4284 @var{start} onward. Returns an empty string if @var{start} is system-missing
4285 or has a value less than 1 or greater than the number of characters in
4289 @deftypefn {Function} {} SUBSTR (@var{string}, @var{start}, @var{count})
4290 Returns a string consisting of the first @var{count} characters from
4291 @var{string} beginning at position @var{start}. Returns an empty string
4292 if @var{start} or @var{count} is system-missing, if @var{start} is less
4293 than 1 or greater than the number of characters in @var{string}, or if
4294 @var{count} is less than 1. Returns a string shorter than @var{count}
4295 characters if @var{start} + @var{count} - 1 is greater than the number
4296 of characters in @var{string}. Examples: @code{SUBSTR("abcdefg", 3, 2)}
4297 has value @code{"cd"}; @code{SUBSTR("Ben Pfaff", 5, 10)} has the value
4301 @cindex case conversion
4302 @cindex strings, case of
4303 @deftypefn {Function} {} UPCASE (@var{string})
4304 Returns @var{string}, changing lowercase letters to uppercase letters.
4307 @node Time & Date, Miscellaneous Functions, String Functions, Functions
4308 @subsection Time & Date Functions
4309 @cindex functions, time & date
4313 @cindex dates, legal range of
4314 The legal range of dates for use in PSPP is 15 Oct 1582
4315 through 31 Dec 19999.
4317 @cindex arguments, invalid
4318 @cindex invalid arguments
4320 @strong{Please note:} Most time & date extraction functions will accept
4325 Negative numbers in PSPP time format.
4327 Numbers less than 86,400 in PSPP date format.
4330 However, sensible results are not guaranteed for these invalid values.
4331 The given equivalents for these functions are definitely not guaranteed
4336 @strong{Please note also:} The time & date construction
4337 functions @strong{do} produce reasonable and useful results for
4338 out-of-range values; these are not considered invalid.
4342 * Time & Date Concepts:: How times & dates are defined and represented
4343 * Time Construction:: TIME.@{DAYS HMS@}
4344 * Time Extraction:: CTIME.@{DAYS HOURS MINUTES SECONDS@}
4345 * Date Construction:: DATE.@{DMY MDY MOYR QYR WKYR YRDAY@}
4346 * Date Extraction:: XDATE.@{DATE HOUR JDAY MDAY MINUTE MONTH
4347 QUARTER SECOND TDAY TIME WEEK
4351 @node Time & Date Concepts, Time Construction, Time & Date, Time & Date
4352 @subsubsection How times & dates are defined and represented
4354 @cindex time, concepts
4355 @cindex time, intervals
4356 Times and dates are handled by PSPP as single numbers. A
4357 @dfn{time} is an interval. PSPP measures times in seconds.
4358 Thus, the following intervals correspond with the numeric values given:
4363 1 day, 3 hours, 10 seconds 97,210
4365 10010 d, 14 min, 24 s 864,864,864
4368 @cindex dates, concepts
4369 @cindex time, instants of
4370 A @dfn{date}, on the other hand, is a particular instant in the past or
4371 the future. PSPP represents a date as a number of seconds after the
4372 midnight that separated 8 Oct 1582 and 9 Oct 1582. (Please note that 15
4373 Oct 1582 immediately followed 9 Oct 1582.) Thus, the midnights before
4374 the dates given below correspond with the numeric PSPP dates given:
4378 4 Jul 1776 6,113,318,400
4379 1 Jan 1900 10,010,390,400
4380 1 Oct 1978 12,495,427,200
4381 24 Aug 1995 13,028,601,600
4384 @cindex time, mathematical properties of
4385 @cindex mathematics, applied to times & dates
4386 @cindex dates, mathematical properties of
4392 A time may be added to, or subtracted from, a date, resulting in a date.
4395 The difference of two dates may be taken, resulting in a time.
4398 Two times may be added to, or subtracted from, each other, resulting in
4402 (Adding two dates does not produce a useful result.)
4404 Since times and dates are merely numbers, the ordinary addition and
4405 subtraction operators are employed for these purposes.
4408 @strong{Please note:} Many dates and times have extremely large
4409 values---just look at the values above. Thus, it is not a good idea to
4410 take powers of these values; also, the accuracy of some procedures may
4411 be affected. If necessary, convert times or dates in seconds to some
4412 other unit, like days or years, before performing analysis.
4415 @node Time Construction, Time Extraction, Time & Date Concepts, Time & Date
4416 @subsubsection Functions that Produce Times
4417 @cindex times, constructing
4418 @cindex constructing times
4420 These functions take numeric arguments and produce numeric results in
4424 @cindex time, in days
4425 @deftypefn {Function} {} TIME.DAYS (@var{ndays})
4426 Results in a time value corresponding to @var{ndays} days.
4427 (@code{TIME.DAYS(@var{x})} is equivalent to @code{@var{x} * 60 * 60 *
4431 @cindex hours-minutes-seconds
4432 @cindex time, in hours-minutes-seconds
4433 @deftypefn {Function} {} TIME.HMS (@var{nhours}, @var{nmins}, @var{nsecs})
4434 Results in a time value corresponding to @var{nhours} hours, @var{nmins}
4435 minutes, and @var{nsecs} seconds. (@code{TIME.HMS(@var{h}, @var{m},
4436 @var{s})} is equivalent to @code{@var{h}*60*60 + @var{m}*60 +
4440 @node Time Extraction, Date Construction, Time Construction, Time & Date
4441 @subsubsection Functions that Examine Times
4442 @cindex extraction, of time
4443 @cindex time examination
4444 @cindex examination, of times
4445 @cindex time, lengths of
4447 These functions take numeric arguments in PSPP time format and
4448 give numeric results.
4451 @cindex time, in days
4452 @deftypefn {Function} {} CTIME.DAYS (@var{time})
4453 Results in the number of days and fractional days in @var{time}.
4454 (@code{CTIME.DAYS(@var{x})} is equivalent to @code{@var{x}/60/60/24}.)
4458 @cindex time, in hours
4459 @deftypefn {Function} {} CTIME.HOURS (@var{time})
4460 Results in the number of hours and fractional hours in @var{time}.
4461 (@code{CTIME.HOURS(@var{x})} is equivalent to @code{@var{x}/60/60}.)
4465 @cindex time, in minutes
4466 @deftypefn {Function} {} CTIME.MINUTES (@var{time})
4467 Results in the number of minutes and fractional minutes in @var{time}.
4468 (@code{CTIME.MINUTES(@var{x})} is equivalent to @code{@var{x}/60}.)
4472 @cindex time, in seconds
4473 @deftypefn {Function} {} CTIME.SECONDS (@var{time})
4474 Results in the number of seconds and fractional seconds in @var{time}.
4475 (@code{CTIME.SECONDS} does nothing; @code{CTIME.SECONDS(@var{x})} is
4476 equivalent to @code{@var{x}}.)
4479 @node Date Construction, Date Extraction, Time Extraction, Time & Date
4480 @subsubsection Functions that Produce Dates
4481 @cindex dates, constructing
4482 @cindex constructing dates
4484 @cindex arguments, of date construction functions
4485 These functions take numeric arguments and give numeric results in the
4486 PSPP date format. Arguments taken by these functions are:
4490 Refers to a day of the month between 1 and 31.
4493 Refers to a month of the year between 1 and 12.
4496 Refers to a quarter of the year between 1 and 4. The quarters of the
4497 year begin on the first days of months 1, 4, 7, and 10.
4500 Refers to a week of the year between 1 and 53.
4503 Refers to a day of the year between 1 and 366.
4506 Refers to a year between 1582 and 19999.
4509 @cindex arguments, invalid
4510 If these functions' arguments are out-of-range, they are correctly
4511 normalized before conversion to date format. Non-integers are rounded
4514 @cindex day-month-year
4515 @cindex dates, day-month-year
4516 @deftypefn {Function} {} DATE.DMY (@var{day}, @var{month}, @var{year})
4517 @deftypefnx {Function} {} DATE.MDY (@var{month}, @var{day}, @var{year})
4518 Results in a date value corresponding to the midnight before day
4519 @var{day} of month @var{month} of year @var{year}.
4523 @cindex dates, month-year
4524 @deftypefn {Function} {} DATE.MOYR (@var{month}, @var{year})
4525 Results in a date value corresponding to the midnight before the first
4526 day of month @var{month} of year @var{year}.
4529 @cindex quarter-year
4530 @cindex dates, quarter-year
4531 @deftypefn {Function} {} DATE.QYR (@var{quarter}, @var{year})
4532 Results in a date value corresponding to the midnight before the first
4533 day of quarter @var{quarter} of year @var{year}.
4537 @cindex dates, week-year
4538 @deftypefn {Function} {} DATE.WKYR (@var{week}, @var{year})
4539 Results in a date value corresponding to the midnight before the first
4540 day of week @var{week} of year @var{year}.
4544 @cindex dates, year-day
4545 @deftypefn {Function} {} DATE.YRDAY (@var{year}, @var{yday})
4546 Results in a date value corresponding to the midnight before day
4547 @var{yday} of year @var{year}.
4550 @node Date Extraction, , Date Construction, Time & Date
4551 @subsubsection Functions that Examine Dates
4552 @cindex extraction, of dates
4553 @cindex date examination
4555 @cindex arguments, of date extraction functions
4556 These functions take numeric arguments in PSPP date or time
4557 format and give numeric results. These names are used for arguments:
4561 A numeric value in PSPP date format.
4564 A numeric value in PSPP time format.
4567 A numeric value in PSPP time or date format.
4571 @cindex dates, in days
4572 @cindex time, in days
4573 @deftypefn {Function} {} XDATE.DATE (@var{time-or-date})
4574 For a time, results in the time corresponding to the number of whole
4575 days @var{date-or-time} includes. For a date, results in the date
4576 corresponding to the latest midnight at or before @var{date-or-time};
4577 that is, gives the date that @var{date-or-time} is in.
4578 (XDATE.DATE(@var{x}) is equivalent to TRUNC(@var{x}/86400)*86400.)
4579 Applying this function to a time is a non-portable feature.
4583 @cindex dates, in hours
4584 @cindex time, in hours
4585 @deftypefn {Function} {} XDATE.HOUR (@var{time-or-date})
4586 For a time, results in the number of whole hours beyond the number of
4587 whole days represented by @var{date-or-time}. For a date, results in
4588 the hour (as an integer between 0 and 23) corresponding to
4589 @var{date-or-time}. (XDATE.HOUR(@var{x}) is equivalent to
4590 MOD(TRUNC(@var{x}/3600),24)) Applying this function to a time is a
4591 non-portable feature.
4594 @cindex day of the year
4595 @cindex dates, day of the year
4596 @deftypefn {Function} {} XDATE.JDAY (@var{date})
4597 Results in the day of the year (as an integer between 1 and 366)
4598 corresponding to @var{date}.
4601 @cindex day of the month
4602 @cindex dates, day of the month
4603 @deftypefn {Function} {} XDATE.MDAY (@var{date})
4604 Results in the day of the month (as an integer between 1 and 31)
4605 corresponding to @var{date}.
4609 @cindex dates, in minutes
4610 @cindex time, in minutes
4611 @deftypefn {Function} {} XDATE.MINUTE (@var{time-or-date})
4612 Results in the number of minutes (as an integer between 0 and 59) after
4613 the last hour in @var{time-or-date}. (XDATE.MINUTE(@var{x}) is
4614 equivalent to MOD(TRUNC(@var{x}/60),60)) Applying this function to a
4615 time is a non-portable feature.
4619 @cindex dates, in months
4620 @deftypefn {Function} {} XDATE.MONTH (@var{date})
4621 Results in the month of the year (as an integer between 1 and 12)
4622 corresponding to @var{date}.
4626 @cindex dates, in quarters
4627 @deftypefn {Function} {} XDATE.QUARTER (@var{date})
4628 Results in the quarter of the year (as an integer between 1 and 4)
4629 corresponding to @var{date}.
4633 @cindex dates, in seconds
4634 @cindex time, in seconds
4635 @deftypefn {Function} {} XDATE.SECOND (@var{time-or-date})
4636 Results in the number of whole seconds after the last whole minute (as
4637 an integer between 0 and 59) in @var{time-or-date}.
4638 (XDATE.SECOND(@var{x}) is equivalent to MOD(@var{x}, 60).) Applying
4639 this function to a time is a non-portable feature.
4643 @cindex times, in days
4644 @deftypefn {Function} {} XDATE.TDAY (@var{time})
4645 Results in the number of whole days (as an integer) in @var{time}.
4646 (XDATE.TDAY(@var{x}) is equivalent to TRUNC(@var{x}/86400).)
4650 @cindex dates, time of day
4651 @deftypefn {Function} {} XDATE.TIME (@var{date})
4652 Results in the time of day at the instant corresponding to @var{date},
4653 in PSPP time format. This is the number of seconds since
4654 midnight on the day corresponding to @var{date}. (XDATE.TIME(@var{x}) is
4655 equivalent to TRUNC(@var{x}/86400)*86400.)
4659 @cindex dates, in weeks
4660 @deftypefn {Function} {} XDATE.WEEK (@var{date})
4661 Results in the week of the year (as an integer between 1 and 53)
4662 corresponding to @var{date}.
4665 @cindex day of the week
4667 @cindex dates, day of the week
4668 @cindex dates, in weekdays
4669 @deftypefn {Function} {} XDATE.WKDAY (@var{date})
4670 Results in the day of week (as an integer between 1 and 7) corresponding
4671 to @var{date}. The days of the week are:
4692 @cindex dates, in years
4693 @deftypefn {Function} {} XDATE.YEAR (@var{date})
4694 Returns the year (as an integer between 1582 and 19999) corresponding to
4698 @node Miscellaneous Functions, Functions Not Implemented, Time & Date, Functions
4699 @subsection Miscellaneous Functions
4700 @cindex functions, miscellaneous
4702 Miscellaneous functions take various arguments and produce various
4705 @cindex cross-case function
4706 @cindex function, cross-case
4707 @deftypefn {Function} {} LAG (@var{variable})
4709 @var{variable} must be a numeric or string variable name. @code{LAG}
4710 results in the value of that variable for the case before the current
4711 one. In case-selection procedures, @code{LAG} results in the value of
4712 the variable for the last case selected. Results in system-missing (for
4713 numeric variables) or blanks (for string variables) for the first case
4714 or before any cases are selected.
4717 @deftypefn {Function} {} LAG (@var{variable}, @var{ncases})
4718 @var{variable} must be a numeric or string variable name. @var{ncases}
4719 must be a small positive constant integer, although there is no explicit
4720 limit. (Use of a large value for @var{ncases} will increase memory
4721 consumption, since PSPP must keep @var{ncases} cases in memory.)
4722 @code{LAG (@var{variable}, @var{ncases}} results in the value of
4723 @var{variable} that is @var{ncases} before the case currently being
4724 processed. See @code{LAG (@var{variable})} above for more details.
4727 @cindex date, Julian
4729 @deftypefn {Function} {} YRMODA (@var{year}, @var{month}, @var{day})
4730 @var{year} is a year between 0 and 199 or 1582 and 19999. @var{month} is
4731 a month between 1 and 12. @var{day} is a day between 1 and 31. If
4732 @var{month} or @var{day} is out-of-range, it changes the next higher
4733 unit. For instance, a @var{day} of 0 refers to the last day of the
4734 previous month, and a @var{month} of 13 refers to the first month of the
4735 next year. @var{year} must be in range. If @var{year} is between 0 and
4736 199, 1900 is added. @var{year}, @var{month}, and @var{day} must all be
4739 @code{YRMODA} results in the number of days between 15 Oct 1582 and
4740 the date specified, plus one. The date passed to @code{YRMODA} must be
4741 on or after 15 Oct 1582. 15 Oct 1582 has a value of 1.
4744 @node Functions Not Implemented, , Miscellaneous Functions, Functions
4745 @subsection Functions Not Implemented
4746 @cindex functions, not implemented
4747 @cindex not implemented
4748 @cindex features, not implemented
4750 These functions are not yet implemented and thus not yet documented,
4751 since it's a hassle.
4775 @node Order of Operations, , Functions, Expressions
4776 @section Operator Precedence
4777 @cindex operator precedence
4778 @cindex precedence, operator
4779 @cindex order of operations
4780 @cindex operations, order of
4782 The following table describes operator precedence. Smaller-numbered
4783 levels in the table have higher precedence. Within a level, operations
4784 are performed from left to right, except for level 2 (exponentiation),
4785 where operations are performed from right to left. If an operator
4786 appears in the table in two places (@code{-}), the first occurrence is
4787 unary, the second is binary.
4801 @code{EQ GE GT LE LT NE}
4806 @node Data Input and Output, System and Portable Files, Expressions, Top
4807 @chapter Data Input and Output
4812 @cindex observations
4814 Data are the focus of the PSPP language.
4815 Each datum belongs to a @dfn{case} (also called an @dfn{observation}).
4816 Each case represents an individual or `experimental unit'.
4817 For example, in the results of a survey, the names of the respondents,
4818 their sex, age @i{etc}. and their responses are all data and the data
4819 pertaining to single respondent is a case.
4820 This chapter examines
4821 the PSPP commands for defining variables and reading and writing data.
4824 @strong{Please note:} Data is not actually read until a procedure is
4825 executed. These commands tell PSPP how to read data, but they
4826 do not @emph{cause} PSPP to read data.
4830 * BEGIN DATA:: Embed data within a syntax file.
4831 * CLEAR TRANSFORMATIONS:: Clear pending transformations.
4832 * DATA LIST:: Fundamental data reading command.
4833 * END CASE:: Output the current case.
4834 * END FILE:: Terminate the current input program.
4835 * FILE HANDLE:: Support for fixed-length records.
4836 * INPUT PROGRAM:: Support for complex input programs.
4837 * LIST:: List cases in the active file.
4838 * MATRIX DATA:: Read matrices in text format.
4839 * NEW FILE:: Clear the active file and dictionary.
4840 * PRINT:: Display values in print formats.
4841 * PRINT EJECT:: Eject the current page then print.
4842 * PRINT SPACE:: Print blank lines.
4843 * REREAD:: Take another look at the previous input line.
4844 * REPEATING DATA:: Multiple cases on a single line.
4845 * WRITE:: Display values in write formats.
4848 @node BEGIN DATA, CLEAR TRANSFORMATIONS, Data Input and Output, Data Input and Output
4852 @cindex Embedding data in syntax files
4853 @cindex Data, embedding in syntax files
4861 @cmd{BEGIN DATA} and @cmd{END DATA} can be used to embed raw ASCII
4862 data in a PSPP syntax file. @cmd{DATA LIST} or another input
4863 procedure must be used before @cmd{BEGIN DATA} (@pxref{DATA LIST}).
4864 @cmd{BEGIN DATA} and @cmd{END DATA} must be used together. @cmd{END
4865 DATA} must appear by itself on a single line, with no leading
4866 whitespace and exactly one space between the words @code{END} and
4867 @code{DATA}, followed immediately by the terminal dot, like this:
4873 @node CLEAR TRANSFORMATIONS, DATA LIST, BEGIN DATA, Data Input and Output
4874 @section CLEAR TRANSFORMATIONS
4875 @vindex CLEAR TRANSFORMATIONS
4878 CLEAR TRANSFORMATIONS.
4881 @cmd{CLEAR TRANSFORMATIONS} clears out all pending
4882 transformations. It does not cancel the current input program. It is
4883 valid only when PSPP is interactive, not in syntax files.
4885 @node DATA LIST, END CASE, CLEAR TRANSFORMATIONS, Data Input and Output
4888 @cindex reading data from a file
4889 @cindex data, reading from a file
4890 @cindex data, embedding in syntax files
4891 @cindex embedding data in syntax files
4893 Used to read text or binary data, @cmd{DATA LIST} is the most
4894 fundamental data-reading command. Even the more sophisticated input
4895 methods use @cmd{DATA LIST} commands as a building block.
4896 Understanding @cmd{DATA LIST} is important to understanding how to use
4897 PSPP to read your data files.
4899 There are two major variants of @cmd{DATA LIST}, which are fixed
4900 format and free format. In addition, free format has a minor variant,
4901 list format, which is discussed in terms of its differences from vanilla
4904 Each form of @cmd{DATA LIST} is described in detail below.
4907 * DATA LIST FIXED:: Fixed columnar locations for data.
4908 * DATA LIST FREE:: Any spacing you like.
4909 * DATA LIST LIST:: Each case must be on a single line.
4912 @node DATA LIST FIXED, DATA LIST FREE, DATA LIST, DATA LIST
4913 @subsection DATA LIST FIXED
4914 @vindex DATA LIST FIXED
4915 @cindex reading fixed-format data
4916 @cindex fixed-format data, reading
4917 @cindex data, fixed-format, reading
4918 @cindex embedding fixed-format data
4924 RECORDS=record_count
4926 /[line_no] var_spec@dots{}
4928 where each var_spec takes one of the forms
4929 var_list start-end [type_spec]
4930 var_list (fortran_spec)
4933 @cmd{DATA LIST FIXED} is used to read data files that have values at fixed
4934 positions on each line of single-line or multiline records. The
4935 keyword FIXED is optional.
4937 The FILE subcommand must be used if input is to be taken from an
4938 external file. It may be used to specify a filename as a string or a
4939 file handle (@pxref{FILE HANDLE}). If the FILE subcommand is not used,
4940 then input is assumed to be specified within the command file using
4941 @cmd{BEGIN DATA}@dots{}@cmd{END DATA} (@pxref{BEGIN DATA}).
4943 The optional RECORDS subcommand, which takes a single integer as an
4944 argument, is used to specify the number of lines per record. If RECORDS
4945 is not specified, then the number of lines per record is calculated from
4946 the list of variable specifications later in @cmd{DATA LIST}.
4948 The END subcommand is only useful in conjunction with @cmd{INPUT
4949 PROGRAM}. @xref{INPUT PROGRAM}, for details.
4951 @cmd{DATA LIST} can optionally output a table describing how the data file
4952 will be read. The TABLE subcommand enables this output, and NOTABLE
4953 disables it. The default is to output the table.
4955 The list of variables to be read from the data list must come last.
4956 Each line in the data record is introduced by a slash (@samp{/}).
4957 Optionally, a line number may follow the slash. Following, any number
4958 of variable specifications may be present.
4960 Each variable specification consists of a list of variable names
4961 followed by a description of their location on the input line. Sets of
4962 variables may specified using the @code{DATA LIST} TO convention
4964 Variables}). There are two ways to specify the location of the variable
4965 on the line: PSPP style and FORTRAN style.
4967 With PSPP style, the starting column and ending column for the field
4968 are specified after the variable name, separated by a dash (@samp{-}).
4969 For instance, the third through fifth columns on a line would be
4970 specified @samp{3-5}. By default, variables are considered to be in
4971 @samp{F} format (@pxref{Input/Output Formats}). (This default can be
4972 changed; see @ref{SET} for more information.)
4974 When using PSPP style, to use a variable format other than the default,
4975 specify the format type in parentheses after the column numbers. For
4976 instance, for alphanumeric @samp{A} format, use @samp{(A)}.
4978 In addition, implied decimal places can be specified in parentheses
4979 after the column numbers. As an example, suppose that a data file has a
4980 field in which the characters @samp{1234} should be interpreted as
4981 having the value 12.34. Then this field has two implied decimal places,
4982 and the corresponding specification would be @samp{(2)}. If a field
4983 that has implied decimal places contains a decimal point, then the
4984 implied decimal places are not applied.
4986 Changing the variable format and adding implied decimal places can be
4987 done together; for instance, @samp{(N,5)}.
4989 When using PSPP style, the input and output width of each variable is
4990 computed from the field width. The field width must be evenly divisible
4991 into the number of variables specified.
4993 FORTRAN style is an altogether different approach to specifying field
4994 locations. With this approach, a list of variable input format
4995 specifications, separated by commas, are placed after the variable names
4996 inside parentheses. Each format specifier advances as many characters
4997 into the input line as it uses.
4999 In addition to the standard format specifiers (@pxref{Input/Output
5000 Formats}), FORTRAN style defines some extensions:
5004 Advance the current column on this line by one character position.
5006 @item @code{T}@var{x}
5007 Set the current column on this line to column @var{x}, with column
5008 numbers considered to begin with 1 at the left margin.
5010 @item @code{NEWREC}@var{x}
5011 Skip forward @var{x} lines in the current record, resetting the active
5012 column to the left margin.
5015 Any format specifier may be preceded by a number. This causes the
5016 action of that format specifier to be repeated the specified number of
5019 @item (@var{spec1}, @dots{}, @var{specN})
5020 Group the given specifiers together. This is most useful when preceded
5021 by a repeat count. Groups may be nested arbitrarily.
5024 FORTRAN and PSPP styles may be freely intermixed. PSPP style leaves the
5025 active column immediately after the ending column specified. Record
5026 motion using @code{NEWREC} in FORTRAN style also applies to later
5027 FORTRAN and PSPP specifiers.
5030 * DATA LIST FIXED Examples:: Examples of DATA LIST FIXED.
5033 @node DATA LIST FIXED Examples, , DATA LIST FIXED, DATA LIST FIXED
5034 @unnumberedsubsubsec Examples
5039 DATA LIST TABLE /NAME 1-10 (A) INFO1 TO INFO3 12-17 (1).
5048 Defines the following variables:
5052 @code{NAME}, a 10-character-wide long string variable, in columns 1
5056 @code{INFO1}, a numeric variable, in columns 12 through 13.
5059 @code{INFO2}, a numeric variable, in columns 14 through 15.
5062 @code{INFO3}, a numeric variable, in columns 16 through 17.
5065 The @code{BEGIN DATA}/@code{END DATA} commands cause three cases to be
5069 Case NAME INFO1 INFO2 INFO3
5070 1 John Smith 10 23 11
5071 2 Bob Arnold 12 20 15
5075 The @code{TABLE} keyword causes PSPP to print out a table
5076 describing the four variables defined.
5080 DAT LIS FIL="survey.dat"
5081 /ID 1-5 NAME 7-36 (A) SURNAME 38-67 (A) MINITIAL 69 (A)
5086 Defines the following variables:
5090 @code{ID}, a numeric variable, in columns 1-5 of the first record.
5093 @code{NAME}, a 30-character long string variable, in columns 7-36 of the
5097 @code{SURNAME}, a 30-character long string variable, in columns 38-67 of
5101 @code{MINITIAL}, a 1-character short string variable, in column 69 of
5105 Fifty variables @code{Q01}, @code{Q02}, @code{Q03}, @dots{}, @code{Q49},
5106 @code{Q50}, all numeric, @code{Q01} in column 7, @code{Q02} in column 8,
5107 @dots{}, @code{Q49} in column 55, @code{Q50} in column 56, all in the second
5111 Cases are separated by a blank record.
5113 Data is read from file @file{survey.dat} in the current directory.
5115 This example shows keywords abbreviated to their first 3 letters.
5119 @node DATA LIST FREE, DATA LIST LIST, DATA LIST FIXED, DATA LIST
5120 @subsection DATA LIST FREE
5121 @vindex DATA LIST FREE
5130 where each var_spec takes one of the forms
5131 var_list [(type_spec)]
5135 In free format, the input data is structured as a series of comma- or
5136 whitespace-delimited fields (end of line is one form of whitespace; it
5137 is not treated specially). Field contents may be surrounded by matched
5138 pairs of apostrophes (@samp{'}) or quotes (@samp{"}), or they may be
5139 unenclosed. For any type of field leading white space (up to the
5140 apostrophe or quote, if any) is not included in the field.
5142 Multiple consecutive delimiters are equivalent to a single delimiter.
5143 To specify an empty field, write an empty set of single or double
5144 quotes; for instance, @samp{""}.
5146 The NOTABLE and TABLE subcommands are as in @cmd{DATA LIST FIXED} above.
5147 NOTABLE is the default.
5149 The FILE and END subcommands are as in @cmd{DATA LIST FIXED} above.
5151 The variables to be parsed are given as a single list of variable names.
5152 This list must be introduced by a single slash (@samp{/}). The set of
5153 variable names may contain format specifications in parentheses
5154 (@pxref{Input/Output Formats}). Format specifications apply to all
5155 variables back to the previous parenthesized format specification.
5157 In addition, an asterisk may be used to indicate that all variables
5158 preceding it are to have input/output format @samp{F8.0}.
5160 Specified field widths are ignored on input, although all normal limits
5161 on field width apply, but they are honored on output.
5163 @node DATA LIST LIST, , DATA LIST FREE, DATA LIST
5164 @subsection DATA LIST LIST
5165 @vindex DATA LIST LIST
5174 where each var_spec takes one of the forms
5175 var_list [(type_spec)]
5179 With one exception, @cmd{DATA LIST LIST} is syntactically and
5180 semantically equivalent to @cmd{DATA LIST FREE}. The exception is
5181 that each input line is expected to correspond to exactly one input
5182 record. If more or fewer fields are found on an input line than
5183 expected, an appropriate diagnostic is issued.
5185 @node END CASE, END FILE, DATA LIST, Data Input and Output
5193 @cmd{END CASE} is used only within @cmd{INPUT PROGRAM} to output the
5194 current case. @xref{INPUT PROGRAM}, for details.
5196 @node END FILE, FILE HANDLE, END CASE, Data Input and Output
5204 @cmd{END FILE} is used only within @cmd{INPUT PROGRAM} to terminate
5205 the current input program. @xref{INPUT PROGRAM}.
5207 @node FILE HANDLE, INPUT PROGRAM, END FILE, Data Input and Output
5208 @section FILE HANDLE
5212 FILE HANDLE handle_name
5214 /RECFORM=@{VARIABLE,FIXED,SPANNED@}
5216 /MODE=@{CHARACTER,IMAGE,BINARY,MULTIPUNCH,360@}
5219 Use @cmd{FILE HANDLE} to define the attributes of a file that does
5220 not use conventional variable-length records terminated by new-line
5223 Specify the file handle name as an identifier. Any given identifier may
5224 only appear once in a PSPP run. File handles may not be reassigned to a
5225 different file. The file handle name must immediately follow the @cmd{FILE
5226 HANDLE} command name.
5228 The NAME subcommand specifies the name of the file associated with the
5229 handle. It is the only required subcommand.
5231 The RECFORM subcommand specifies how the file is laid out. VARIABLE
5232 specifies variable-length lines terminated with new-lines, and it is the
5233 default. FIXED specifies fixed-length records. SPANNED is not
5236 LRECL specifies the length of fixed-length records. It is required if
5237 @code{/RECFORM FIXED} is specified.
5239 MODE specifies a file mode. CHARACTER, the default, causes the data
5240 file to be opened in ANSI C text mode. BINARY causes the data file to
5241 be opened in ANSI C binary mode. The other possibilities are not
5244 @node INPUT PROGRAM, LIST, FILE HANDLE, Data Input and Output
5245 @section INPUT PROGRAM
5246 @vindex INPUT PROGRAM
5250 @dots{} input commands @dots{}
5254 @cmd{INPUT PROGRAM}@dots{}@cmd{END INPUT PROGRAM} specifies a
5255 complex input program. By placing data input commands within @cmd{INPUT
5256 PROGRAM}, PSPP programs can take advantage of more complex file
5257 structures than available with only @cmd{DATA LIST}.
5259 The first sort of extended input program is to simply put multiple @cmd{DATA
5260 LIST} commands within the @cmd{INPUT PROGRAM}. This will cause all of
5262 files to be read in parallel. Input will stop when end of file is
5263 reached on any of the data files.
5265 Transformations, such as conditional and looping constructs, can also be
5266 included within @cmd{INPUT PROGRAM}. These can be used to combine input
5267 from several data files in more complex ways. However, input will still
5268 stop when end of file is reached on any of the data files.
5270 To prevent @cmd{INPUT PROGRAM} from terminating at the first end of
5272 the END subcommand on @cmd{DATA LIST}. This subcommand takes a
5274 which should be a numeric scratch variable (@pxref{Scratch Variables}).
5275 (It need not be a scratch variable but otherwise the results can be
5276 surprising.) The value of this variable is set to 0 when reading the
5277 data file, or 1 when end of file is encountered.
5279 Two additional commands are useful in conjunction with @cmd{INPUT PROGRAM}.
5280 @cmd{END CASE} is the first. Normally each loop through the
5282 structure produces one case. @cmd{END CASE} controls exactly
5283 when cases are output. When @cmd{END CASE} is used, looping from the end of
5284 @cmd{INPUT PROGRAM} to the beginning does not cause a case to be output.
5286 @cmd{END FILE} is the second. When the END subcommand is used on @cmd{DATA
5287 LIST}, there is no way for the @cmd{INPUT PROGRAM} construct to stop
5289 so an infinite loop results. @cmd{END FILE}, when executed,
5290 stops the flow of input data and passes out of the @cmd{INPUT PROGRAM}
5293 All this is very confusing. A few examples should help to clarify.
5297 DATA LIST NOTABLE FILE='a.data'/X 1-10.
5298 DATA LIST NOTABLE FILE='b.data'/Y 1-10.
5303 The example above reads variable X from file @file{a.data} and variable
5304 Y from file @file{b.data}. If one file is shorter than the other then
5305 the extra data in the longer file is ignored.
5312 DATA LIST NOTABLE END=#A FILE='a.data'/X 1-10.
5315 DATA LIST NOTABLE END=#B FILE='b.data'/Y 1-10.
5325 The above example reads variable X from @file{a.data} and variable Y from
5326 @file{b.data}. If one file is shorter than the other then the missing
5327 field is set to the system-missing value alongside the present value for
5328 the remaining length of the longer file.
5335 DATA LIST NOTABLE END=#B FILE='b.data'/X 1-10.
5342 DATA LIST NOTABLE END=#A FILE='a.data'/X 1-10.
5351 The above example reads data from file @file{a.data}, then from
5352 @file{b.data}, and concatenates them into a single active file.
5359 DATA LIST NOTABLE END=#EOF FILE='a.data'/X 1-10.
5367 DATA LIST NOTABLE END=#EOF FILE='b.data'/X 1-10.
5378 The above example does the same thing as the previous example, in a
5384 COMPUTE X=UNIFORM(10).
5389 LIST/FORMAT=NUMBERED.
5392 The above example causes an active file to be created consisting of 50
5393 random variates between 0 and 10.
5395 @node LIST, MATRIX DATA, INPUT PROGRAM, Data Input and Output
5402 /CASES=FROM start_index TO end_index BY incr_index
5403 /FORMAT=@{UNNUMBERED,NUMBERED@} @{WRAP,SINGLE@}
5407 The @cmd{LIST} procedure prints the values of specified variables to the
5410 The VARIABLES subcommand specifies the variables whose values are to be
5411 printed. Keyword VARIABLES is optional. If VARIABLES subcommand is not
5412 specified then all variables in the active file are printed.
5414 The CASES subcommand can be used to specify a subset of cases to be
5415 printed. Specify FROM and the case number of the first case to print,
5416 TO and the case number of the last case to print, and BY and the number
5417 of cases to advance between printing cases, or any subset of those
5418 settings. If CASES is not specified then all cases are printed.
5420 The FORMAT subcommand can be used to change the output format. NUMBERED
5421 will print case numbers along with each case; UNNUMBERED, the default,
5422 causes the case numbers to be omitted. The WRAP and SINGLE settings are
5423 currently not used. WEIGHT will cause case weights to be printed along
5424 with variable values; NOWEIGHT, the default, causes case weights to be
5425 omitted from the output.
5427 Case numbers start from 1. They are counted after all transformations
5428 have been considered.
5430 @cmd{LIST} attempts to fit all the values on a single line. If needed
5431 to make them fit, variable names are displayed vertically. If values
5432 cannot fit on a single line, then a multi-line format will be used.
5434 @cmd{LIST} is a procedure. It causes the data to be read.
5436 @node MATRIX DATA, NEW FILE, LIST, Data Input and Output
5437 @section MATRIX DATA
5444 /FORMAT=@{LIST,FREE@} @{LOWER,UPPER,FULL@} @{DIAGONAL,NODIAGONAL@}
5445 /SPLIT=@{new_var,var_list@}
5449 /CONTENTS=@{N_VECTOR,N_SCALAR,N_MATRIX,MEAN,STDDEV,COUNT,MSE,
5450 DFE,MAT,COV,CORR,PROX@}
5453 @cmd{MATRIX DATA} command reads square matrices in one of several textual
5454 formats. @cmd{MATRIX DATA} clears the dictionary and replaces it and
5458 Use VARIABLES to specify the variables that form the rows and columns of
5459 the matrices. You may not specify a variable named @code{VARNAME_}. You
5460 should specify VARIABLES first.
5462 Specify the file to read on FILE, either as a file name string or a file
5463 handle (@pxref{FILE HANDLE}). If FILE is not specified then matrix data
5464 must immediately follow @cmd{MATRIX DATA} with a @cmd{BEGIN
5465 DATA}@dots{}@cmd{END DATA}
5466 construct (@pxref{BEGIN DATA}).
5468 The FORMAT subcommand specifies how the matrices are formatted. LIST,
5469 the default, indicates that there is one line per row of matrix data;
5470 FREE allows single matrix rows to be broken across multiple lines. This
5471 is analogous to the difference between @cmd{DATA LIST FREE} and
5472 @cmd{DATA LIST LIST}
5473 (@pxref{DATA LIST}). LOWER, the default, indicates that the lower
5474 triangle of the matrix is given; UPPER indicates the upper triangle; and
5475 FULL indicates that the entire matrix is given. DIAGONAL, the default,
5476 indicates that the diagonal is part of the data; NODIAGONAL indicates
5477 that it is omitted. DIAGONAL/NODIAGONAL have no effect when FULL is
5480 The SPLIT subcommand is used to specify @cmd{SPLIT FILE} variables for the
5481 input matrices (@pxref{SPLIT FILE}). Specify either a single variable
5482 not specified on VARIABLES, or one or more variables that are specified
5483 on VARIABLES. In the former case, the SPLIT values are not present in
5484 the data and ROWTYPE_ may not be specified on VARIABLES. In the latter
5485 case, the SPLIT values are present in the data.
5487 Specify a list of factor variables on FACTORS. Factor variables must
5488 also be listed on VARIABLES. Factor variables are used when there are
5489 some variables where, for each possible combination of their values,
5490 statistics on the matrix variables are included in the data.
5492 If FACTORS is specified and ROWTYPE_ is not specified on VARIABLES, the
5493 CELLS subcommand is required. Specify the number of factor variable
5494 combinations that are given. For instance, if factor variable A has 2
5495 values and factor variable B has 3 values, specify 6.
5497 The N subcommand specifies a population number of observations. When N
5498 is specified, one N record is output for each @cmd{SPLIT FILE}.
5500 Use CONTENTS to specify what sort of information the matrices include.
5501 Each possible option is described in more detail below. When ROWTYPE_
5502 is specified on VARIABLES, CONTENTS is optional; otherwise, if CONTENTS
5503 is not specified then /CONTENTS=CORR is assumed.
5508 Number of observations as a vector, one value for each variable.
5510 Number of observations as a single value.
5516 Vector of standard deviations.
5520 Vector of mean squared errors.
5522 Vector of degrees of freedom.
5533 The exact semantics of the matrices read by @cmd{MATRIX DATA} are complex.
5534 Right now @cmd{MATRIX DATA} isn't too useful due to a lack of procedures
5535 accepting or producing related data, so these semantics aren't
5536 documented. Later, they'll be described here in detail.
5538 @node NEW FILE, PRINT, MATRIX DATA, Data Input and Output
5546 @cmd{NEW FILE} command clears the current active file.
5548 @node PRINT, PRINT EJECT, NEW FILE, Data Input and Output
5557 /[line_no] arg@dots{}
5559 arg takes one of the following forms:
5560 'string' [start-end]
5561 var_list start-end [type_spec]
5562 var_list (fortran_spec)
5566 The @cmd{PRINT} transformation writes variable data to an output file.
5567 @cmd{PRINT} is executed when a procedure causes the data to be read.
5568 Follow @cmd{PRINT} by @cmd{EXECUTE} to print variable data without
5569 invoking a procedure (@pxref{EXECUTE}).
5571 All @cmd{PRINT} subcommands are optional.
5573 The OUTFILE subcommand specifies the file to receive the output. The
5574 file may be a file name as a string or a file handle (@pxref{FILE
5575 HANDLE}). If OUTFILE is not present then output will be sent to PSPP's
5576 output listing file.
5578 The RECORDS subcommand specifies the number of lines to be output. The
5579 number of lines may optionally be surrounded by parentheses.
5581 TABLE will cause the PRINT command to output a table to the listing file
5582 that describes what it will print to the output file. NOTABLE, the
5583 default, suppresses this output table.
5585 Introduce the strings and variables to be printed with a slash
5586 (@samp{/}). Optionally, the slash may be followed by a number
5587 indicating which output line will be specified. In the absence of this
5588 line number, the next line number will be specified. Multiple lines may
5589 be specified using multiple slashes with the intended output for a line
5590 following its respective slash.
5592 Literal strings may be printed. Specify the string itself. Optionally
5593 the string may be followed by a column number or range of column
5594 numbers, specifying the location on the line for the string to be
5595 printed. Otherwise, the string will be printed at the current position
5598 Variables to be printed can be specified in the same ways as available
5599 for @cmd{DATA LIST FIXED} (@pxref{DATA LIST FIXED}). In addition, a
5601 list may be followed by an asterisk (@samp{*}), which indicates that the
5602 variables should be printed in their dictionary print formats, separated
5603 by spaces. A variable list followed by a slash or the end of command
5604 will be interpreted the same way.
5606 If a FORTRAN type specification is used to move backwards on the current
5607 line, then text is written at that point on the line, the line will be
5608 truncated to that length, although additional text being added will
5609 again extend the line to that length.
5611 @node PRINT EJECT, PRINT SPACE, PRINT, Data Input and Output
5612 @section PRINT EJECT
5620 /[line_no] arg@dots{}
5622 arg takes one of the following forms:
5623 'string' [start-end]
5624 var_list start-end [type_spec]
5625 var_list (fortran_spec)
5629 @cmd{PRINT EJECT} writes data to an output file. Before the data is
5630 written, the current page in the listing file is ejected.
5632 @xref{PRINT}, for more information on syntax and usage.
5634 @node PRINT SPACE, REREAD, PRINT EJECT, Data Input and Output
5635 @section PRINT SPACE
5639 PRINT SPACE OUTFILE='filename' n_lines.
5642 @cmd{PRINT SPACE} prints one or more blank lines to an output file.
5644 The OUTFILE subcommand is optional. It may be used to direct output to
5645 a file specified by file name as a string or file handle (@pxref{FILE
5646 HANDLE}). If OUTFILE is not specified then output will be directed to
5649 n_lines is also optional. If present, it is an expression
5650 (@pxref{Expressions}) specifying the number of blank lines to be
5651 printed. The expression must evaluate to a nonnegative value.
5653 @node REREAD, REPEATING DATA, PRINT SPACE, Data Input and Output
5658 REREAD FILE=handle COLUMN=column.
5661 The @cmd{REREAD} transformation allows the previous input line in a
5663 already processed by @cmd{DATA LIST} or another input command to be re-read
5664 for further processing.
5666 The FILE subcommand, which is optional, is used to specify the file to
5667 have its line re-read. The file must be specified in the form of a file
5668 handle (@pxref{FILE HANDLE}). If FILE is not specified then the last
5669 file specified on @cmd{DATA LIST} will be assumed (last file specified
5670 lexically, not in terms of flow-of-control).
5672 By default, the line re-read is re-read in its entirety. With the
5673 COLUMN subcommand, a prefix of the line can be exempted from
5674 re-reading. Specify an expression (@pxref{Expressions}) evaluating to
5675 the first column that should be included in the re-read line. Columns
5676 are numbered from 1 at the left margin.
5678 Issuing @code{REREAD} multiple times will not back up in the data
5679 file. Instead, it will re-read the same line multiple times.
5681 @node REPEATING DATA, WRITE, REREAD, Data Input and Output
5682 @section REPEATING DATA
5683 @vindex REPEATING DATA
5691 /CONTINUED[=cont_start-cont_end]
5692 /ID=id_start-id_end=id_var
5694 /DATA=var_spec@dots{}
5696 where each var_spec takes one of the forms
5697 var_list start-end [type_spec]
5698 var_list (fortran_spec)
5701 @cmd{REPEATING DATA} parses groups of data repeating in
5702 a uniform format, possibly with several groups on a single line. Each
5703 group of data corresponds with one case. @cmd{REPEATING DATA} may only be
5704 used within an @cmd{INPUT PROGRAM} structure (@pxref{INPUT PROGRAM}).
5705 When used with @cmd{DATA LIST}, it
5706 can be used to parse groups of cases that share a subset of variables
5707 but differ in their other data.
5709 The STARTS subcommand is required. Specify a range of columns, using
5710 literal numbers or numeric variable names. This range specifies the
5711 columns on the first line that are used to contain groups of data. The
5712 ending column is optional. If it is not specified, then the record
5713 width of the input file is used. For the inline file (@pxref{BEGIN
5714 DATA}) this is 80 columns; for a file with fixed record widths it is the
5715 record width; for other files it is 1024 characters by default.
5717 The OCCURS subcommand is required. It must be a number or the name of a
5718 numeric variable. Its value is the number of groups present in the
5721 The DATA subcommand is required. It must be the last subcommand
5722 specified. It is used to specify the data present within each repeating
5723 group. Column numbers are specified relative to the beginning of a
5724 group at column 1. Data is specified in the same way as with @cmd{DATA LIST
5725 FIXED} (@pxref{DATA LIST FIXED}).
5727 All other subcommands are optional.
5729 FILE specifies the file to read, either a file name as a string or a
5730 file handle (@pxref{FILE HANDLE}). If FILE is not present then the
5731 default is the last file handle used on @cmd{DATA LIST} (lexically, not in
5732 terms of flow of control).
5734 By default @cmd{REPEATING DATA} will output a table describing how it will
5735 parse the input data. Specifying NOTABLE will disable this behavior;
5736 specifying TABLE will explicitly enable it.
5738 The LENGTH subcommand specifies the length in characters of each group.
5739 If it is not present then length is inferred from the DATA subcommand.
5740 LENGTH can be a number or a variable name.
5742 Normally all the data groups are expected to be present on a single
5743 line. Use the CONTINUED command to indicate that data can be continued
5744 onto additional lines. If data on continuation lines starts at the left
5745 margin and continues through the entire field width, no column
5746 specifications are necessary on CONTINUED. Otherwise, specify the
5747 possible range of columns in the same way as on STARTS.
5749 When data groups are continued from line to line, it is easy
5750 for cases to get out of sync through careless hand editing. The
5751 ID subcommand allows a case identifier to be present on each line of
5752 repeating data groups. @cmd{REPEATING DATA} will check for the same
5753 identifier on each line and report mismatches. Specify the range of
5754 columns that the identifier will occupy, followed by an equals sign
5755 (@samp{=}) and the identifier variable name. The variable must already
5756 have been declared with @cmd{NUMERIC} or another command.
5758 @cmd{REPEATING DATA} should be the last command given within an
5759 @cmd{INPUT PROGRAM}. It should not be enclosed within a @cmd{LOOP}
5760 structure (@pxref{LOOP}). Use @cmd{DATA LIST} before, not after,
5761 @cmd{REPEATING DATA}.
5763 @node WRITE, , REPEATING DATA, Data Input and Output
5772 /[line_no] arg@dots{}
5774 arg takes one of the following forms:
5775 'string' [start-end]
5776 var_list start-end [type_spec]
5777 var_list (fortran_spec)
5781 @code{WRITE} writes text or binary data to an output file.
5783 @xref{PRINT}, for more information on syntax and usage. The main
5784 difference between @code{PRINT} and @code{WRITE} is that @cmd{WRITE}
5785 uses write formats by default, where PRINT uses print formats.
5787 The sole additional difference is that if @cmd{WRITE} is used to send output
5788 to a binary file, carriage control characters will not be output.
5789 @xref{FILE HANDLE}, for information on how to declare a file as binary.
5791 @node System and Portable Files, Variable Attributes, Data Input and Output, Top
5792 @chapter System Files and Portable Files
5794 The commands in this chapter read, write, and examine system files and
5798 * APPLY DICTIONARY:: Apply system file dictionary to active file.
5799 * EXPORT:: Write to a portable file.
5800 * GET:: Read from a system file.
5801 * IMPORT:: Read from a portable file.
5802 * MATCH FILES:: Merge system files.
5803 * SAVE:: Write to a system file.
5804 * SYSFILE INFO:: Display system file dictionary.
5805 * XSAVE:: Write to a system file, as a transform.
5808 @node APPLY DICTIONARY, EXPORT, System and Portable Files, System and Portable Files
5809 @section APPLY DICTIONARY
5810 @vindex APPLY DICTIONARY
5813 APPLY DICTIONARY FROM='filename'.
5816 @cmd{APPLY DICTIONARY} applies the variable labels, value labels,
5817 and missing values from variables in a system file to corresponding
5818 variables in the active file. In some cases it also updates the
5821 Specify a system file with a file name string or as a file handle
5822 (@pxref{FILE HANDLE}). The dictionary in the system file will be read,
5823 but it will not replace the active file dictionary. The system file's
5824 data will not be read.
5826 Only variables with names that exist in both the active file and the
5827 system file are considered. Variables with the same name but different
5828 types (numeric, string) will cause an error message. Otherwise, the
5829 system file variables' attributes will replace those in their matching
5830 active file variables, as described below.
5832 If a system file variable has a variable label, then it will replace the
5833 active file variable's variable label. If the system file variable does
5834 not have a variable label, then the active file variable's variable
5835 label, if any, will be retained.
5837 If the active file variable is numeric or short string, then value
5838 labels and missing values, if any, will be copied to the active file
5839 variable. If the system file variable does not have value labels or
5840 missing values, then those in the active file variable, if any, will not
5843 Finally, weighting of the active file is updated (@pxref{WEIGHT}). If
5844 the active file has a weighting variable, and the system file does not,
5845 or if the weighting variable in the system file does not exist in the
5846 active file, then the active file weighting variable, if any, is
5847 retained. Otherwise, the weighting variable in the system file becomes
5848 the active file weighting variable.
5850 @cmd{APPLY DICTIONARY} takes effect immediately. It does not read the
5852 file. The system file is not modified.
5854 @node EXPORT, GET, APPLY DICTIONARY, System and Portable Files
5863 /RENAME=(src_names=target_names)@dots{}
5866 The @cmd{EXPORT} procedure writes the active file dictionary and data to a
5867 specified portable file.
5869 The OUTFILE subcommand, which is the only required subcommand, specifies
5870 the portable file to be written as a file name string or a file handle
5871 (@pxref{FILE HANDLE}).
5873 DROP, KEEP, and RENAME follow the same format as the SAVE procedure
5876 @cmd{EXPORT} is a procedure. It causes the active file to be read.
5878 @node GET, IMPORT, EXPORT, System and Portable Files
5887 /RENAME=(src_names=target_names)@dots{}
5890 @cmd{GET} clears the current dictionary and active file and
5891 replaces them with the dictionary and data from a specified system file.
5893 The FILE subcommand is the only required subcommand. Specify the system
5894 file to be read as a string file name or a file handle (@pxref{FILE
5897 By default, all the variables in a system file are read. The DROP
5898 subcommand can be used to specify a list of variables that are not to be
5899 read. By contrast, the KEEP subcommand can be used to specify variable
5900 that are to be read, with all other variables not read.
5902 Normally variables in a system file retain the names that they were
5903 saved under. Use the RENAME subcommand to change these names. Specify,
5904 within parentheses, a list of variable names followed by an equals sign
5905 (@samp{=}) and the names that they should be renamed to. Multiple
5906 parenthesized groups of variable names can be included on a single
5907 RENAME subcommand. Variables' names may be swapped using a RENAME
5908 subcommand of the form @samp{/RENAME=(A B=B A)}.
5910 Alternate syntax for the RENAME subcommand allows the parentheses to be
5911 eliminated. When this is done, only a single variable may be renamed at
5912 once. For instance, @samp{/RENAME=A=B}. This alternate syntax is
5915 DROP, KEEP, and RENAME are performed in left-to-right order. They
5916 each may be present any number of times. @cmd{GET} never modifies a
5917 system file on disk. Only the active file read from the system file
5918 is affected by these subcommands.
5920 @cmd{GET} does not cause the data to be read, only the dictionary. The data
5921 is read later, when a procedure is executed.
5923 @node IMPORT, MATCH FILES, GET, System and Portable Files
5933 /RENAME=(src_names=target_names)@dots{}
5936 The @cmd{IMPORT} transformation clears the active file dictionary and
5938 replaces them with a dictionary and data from a portable file on disk.
5940 The FILE subcommand, which is the only required subcommand, specifies
5941 the portable file to be read as a file name string or a file handle
5942 (@pxref{FILE HANDLE}).
5944 The TYPE subcommand is currently not used.
5946 DROP, KEEP, and RENAME follow the syntax used by @cmd{GET} (@pxref{GET}).
5948 @cmd{IMPORT} does not cause the data to be read, only the dictionary. The
5949 data is read later, when a procedure is executed.
5951 @node MATCH FILES, SAVE, IMPORT, System and Portable Files
5952 @section MATCH FILES
5958 /@{FILE,TABLE@}=@{*,'filename'@}
5961 /RENAME=(src_names=target_names)@dots{}
5968 @cmd{MATCH FILES} merges one or more system files, optionally
5969 including the active file. Records with the same values for BY
5970 variables are combined into a single record. Records with different
5971 values are output in order. Thus, multiple sorted system files are
5972 combined into a single sorted system file based on the value of the BY
5973 variables. The results of the merge become the new active file.
5975 The BY subcommand specifies a list of variables that are used to match
5976 records from each of the system files. Variables specified must exist
5977 in all the files specified on FILE and TABLE. BY should usually be
5978 specified. If TABLE is used then BY is required.
5980 Specify FILE with a system file as a file name string or file handle
5981 (@pxref{FILE HANDLE}), or with an asterisk (@samp{*}) to
5982 indicate the current active file. The files specified on FILE are
5983 merged together based on the BY variables, or combined case-by-case if
5984 BY is not specified. Normally at least two FILE subcommands should be
5987 Specify TABLE with a system file to use it as a @dfn{table
5988 lookup file}. Records in table lookup files are not used up after
5989 they've been used once. This means that data in table lookup files can
5990 correspond to any number of records in FILE files. Table lookup files
5991 correspond to lookup tables in traditional relational database systems.
5992 It is incorrect to have records with duplicate BY values in table lookup
5995 Any number of FILE and TABLE subcommands may be specified. Each
5996 instance of FILE or TABLE can be followed by DROP, KEEP, and/or RENAME
5997 subcommands. These take the same form as the corresponding subcommands
5998 of @cmd{GET} (@pxref{GET}), and perform the same functions.
6000 Variables belonging to files that are not present for the current case
6001 are set to the system-missing value for numeric variables or spaces for
6004 IN, FIRST, LAST, and MAP are currently not used.
6006 @cmd{MATCH FILES} may not be specified following @cmd{TEMPORARY}
6007 (@pxref{TEMPORARY}) if the active file is used as an input source.
6009 @node SAVE, SYSFILE INFO, MATCH FILES, System and Portable Files
6016 /@{COMPRESSED,UNCOMPRESSED@}
6019 /RENAME=(src_names=target_names)@dots{}
6022 The @cmd{SAVE} procedure causes the dictionary and data in the active
6024 be written to a system file.
6026 FILE is the only required subcommand. Specify the system
6027 file to be written as a string file name or a file handle (@pxref{FILE
6030 The COMPRESS and UNCOMPRESS subcommand determine whether the saved
6031 system file is compressed. By default, system files are compressed.
6032 This default can be changed with the SET command (@pxref{SET}).
6034 By default, all the variables in the active file dictionary are written
6035 to the system file. The DROP subcommand can be used to specify a list
6036 of variables not to be written. In contrast, KEEP specifies variables
6037 to be written, with all variables not specified not written.
6039 Normally variables are saved to a system file under the same names they
6040 have in the active file. Use the RENAME subcommand to change these names.
6041 Specify, within parentheses, a list of variable names followed by an
6042 equals sign (@samp{=}) and the names that they should be renamed to.
6043 Multiple parenthesized groups of variable names can be included on a
6044 single RENAME subcommand. Variables' names may be swapped using a
6045 RENAME subcommand of the form @samp{/RENAME=(A B=B A)}.
6047 Alternate syntax for the RENAME subcommand allows the parentheses to be
6048 eliminated. When this is done, only a single variable may be renamed at
6049 once. For instance, @samp{/RENAME=A=B}. This alternate syntax is
6052 DROP, KEEP, and RENAME are performed in left-to-right order. They
6053 each may be present any number of times. @cmd{SAVE} never modifies
6054 the active file. DROP, KEEP, and RENAME only affect the system file
6057 @cmd{SAVE} causes the data to be read. It is a procedure.
6059 @node SYSFILE INFO, XSAVE, SAVE, System and Portable Files
6060 @section SYSFILE INFO
6061 @vindex SYSFILE INFO
6064 SYSFILE INFO FILE='filename'.
6067 @cmd{SYSFILE INFO} reads the dictionary in a system file and
6068 displays the information in its dictionary.
6070 Specify a file name or file handle. @cmd{SYSFILE INFO} reads that file as
6071 a system file and displays information on its dictionary.
6073 @cmd{SYSFILE INFO} does not affect the current active file.
6075 @node XSAVE, , SYSFILE INFO, System and Portable Files
6082 /@{COMPRESSED,UNCOMPRESSED@}
6085 /RENAME=(src_names=target_names)@dots{}
6088 The @cmd{XSAVE} transformation writes the active file dictionary and
6090 system file stored on disk.
6092 @cmd{XSAVE} is a transformation, not a procedure. It is executed when the
6093 data is read by a procedure or procedure-like command. In all other
6094 respects, @cmd{XSAVE} is identical to @cmd{SAVE}. @xref{SAVE}, for
6096 on syntax and usage.
6098 @node Variable Attributes, Data Manipulation, System and Portable Files, Top
6099 @chapter Manipulating variables
6101 The variables in the active file dictionary are important. There are
6102 several utility functions for examining and adjusting them.
6105 * ADD VALUE LABELS:: Add value labels to variables.
6106 * DISPLAY:: Display variable names & descriptions.
6107 * DISPLAY VECTORS:: Display a list of vectors.
6108 * FORMATS:: Set print and write formats.
6109 * LEAVE:: Don't clear variables between cases.
6110 * MISSING VALUES:: Set missing values for variables.
6111 * MODIFY VARS:: Rename, reorder, and drop variables.
6112 * NUMERIC:: Create new numeric variables.
6113 * PRINT FORMATS:: Set variable print formats.
6114 * RENAME VARIABLES:: Rename variables.
6115 * VALUE LABELS:: Set value labels for variables.
6116 * STRING:: Create new string variables.
6117 * VARIABLE LABELS:: Set variable labels for variables.
6118 * VECTOR:: Declare an array of variables.
6119 * WRITE FORMATS:: Set variable write formats.
6122 @node ADD VALUE LABELS, DISPLAY, Variable Attributes, Variable Attributes
6123 @section ADD VALUE LABELS
6124 @vindex ADD VALUE LABELS
6128 /var_list value 'label' [value 'label']@dots{}
6131 @cmd{ADD VALUE LABELS} has the same syntax and purpose as @cmd{VALUE
6132 LABELS} (@pxref{VALUE LABELS}), but it does not clear value
6133 labels from the variables before adding the ones specified.
6135 @node DISPLAY, DISPLAY VECTORS, ADD VALUE LABELS, Variable Attributes
6140 DISPLAY @{NAMES,INDEX,LABELS,VARIABLES,DICTIONARY,SCRATCH@}
6144 @cmd{DISPLAY} displays requested information on variables. Variables can
6145 optionally be sorted alphabetically. The entire dictionary or just
6146 specified variables can be described.
6148 One of the following keywords can be present:
6152 The variables' names are displayed.
6155 The variables' names are displayed along with a value describing their
6156 position within the active file dictionary.
6159 Variable names, positions, and variable labels are displayed.
6162 Variable names, positions, print and write formats, and missing values
6166 Variable names, positions, print and write formats, missing values,
6167 variable labels, and value labels are displayed.
6170 Varible names are displayed, for scratch variables only (@pxref{Scratch
6174 If SORTED is specified, then the variables are displayed in ascending
6175 order based on their names; otherwise, they are displayed in the order
6176 that they occur in the active file dictionary.
6178 @node DISPLAY VECTORS, FORMATS, DISPLAY, Variable Attributes
6179 @section DISPLAY VECTORS
6180 @vindex DISPLAY VECTORS
6186 @cmd{DISPLAY VECTORS} lists all the currently declared vectors.
6188 @node FORMATS, LEAVE, DISPLAY VECTORS, Variable Attributes
6193 FORMATS var_list (fmt_spec).
6196 @cmd{FORMATS} set both print and write formats for the specified
6197 variables to the specified format specification. @xref{Input/Output
6200 Specify a list of variables followed by a format specification in
6201 parentheses. The print and write formats of the specified variables
6204 Additional lists of variables and formats may be included if they are
6205 delimited by a slash (@samp{/}).
6207 @cmd{FORMATS} takes effect immediately. It is not affected by
6208 conditional and looping structures such as @cmd{DO IF} or @cmd{LOOP}.
6210 @node LEAVE, MISSING VALUES, FORMATS, Variable Attributes
6218 @cmd{LEAVE} prevents the specified variables from being
6219 reinitialized whenever a new case is processed.
6221 Normally, when a data file is processed, every variable in the active
6222 file is initialized to the system-missing value or spaces at the
6223 beginning of processing for each case. When a variable has been
6224 specified on @cmd{LEAVE}, this is not the case. Instead, that variable is
6225 initialized to 0 (not system-missing) or spaces for the first case.
6226 After that, it retains its value between cases.
6228 This becomes useful for counters. For instance, in the example below
6229 the variable SUM maintains a running total of the values in the ITEM
6233 DATA LIST /ITEM 1-3.
6234 COMPUTE SUM=SUM+ITEM.
6245 @noindent Partial output from this example:
6254 It is best to use @cmd{LEAVE} command immediately before invoking a
6255 procedure command, because the left status of variables is reset by
6256 certain transformations---for instance, @cmd{COMPUTE} and @cmd{IF}.
6257 Left status is also reset by all procedure invocations.
6259 @node MISSING VALUES, MODIFY VARS, LEAVE, Variable Attributes
6260 @section MISSING VALUES
6261 @vindex MISSING VALUES
6264 MISSING VALUES var_list (missing_values).
6266 missing_values takes one of the following forms:
6271 num1 THRU num2, num3
6274 string1, string2, string3
6275 As part of a range, LO or LOWEST may take the place of num1;
6276 HI or HIGHEST may take the place of num2.
6279 @cmd{MISSING VALUES} sets user-missing values for numeric and
6280 short string variables. Long string variables may not have missing
6283 Specify a list of variables, followed by a list of their user-missing
6284 values in parentheses. Up to three discrete values may be given, or,
6285 for numeric variables only, a range of values optionally accompanied by
6286 a single discrete value. Ranges may be open-ended on one end, indicated
6287 through the use of the keyword LO or LOWEST or HI or HIGHEST.
6289 The @cmd{MISSING VALUES} command takes effect immediately. It is not
6290 affected by conditional and looping constructs such as @cmd{DO IF} or
6293 @node MODIFY VARS, NUMERIC, MISSING VALUES, Variable Attributes
6294 @section MODIFY VARS
6299 /REORDER=@{FORWARD,BACKWARD@} @{POSITIONAL,ALPHA@} (var_list)@dots{}
6300 /RENAME=(old_names=new_names)@dots{}
6301 /@{DROP,KEEP@}=var_list
6305 @cmd{MODIFY VARS} reorders, renames, and deletes variables in the
6308 At least one subcommand must be specified, and no subcommand may be
6309 specified more than once. DROP and KEEP may not both be specified.
6311 The REORDER subcommand changes the order of variables in the active
6312 file. Specify one or more lists of variable names in parentheses. By
6313 default, each list of variables is rearranged into the specified order.
6314 To put the variables into the reverse of the specified order, put
6315 keyword BACKWARD before the parentheses. To put them into alphabetical
6316 order in the dictionary, specify keyword ALPHA before the parentheses.
6317 BACKWARD and ALPHA may also be combined.
6319 To rename variables in the active file, specify RENAME, an equals sign
6320 (@samp{=}), and lists of the old variable names and new variable names
6321 separated by another equals sign within parentheses. There must be the
6322 same number of old and new variable names. Each old variable is renamed to
6323 the corresponding new variable name. Multiple parenthesized groups of
6324 variables may be specified.
6326 The DROP subcommand deletes a specified list of variables from the
6329 The KEEP subcommand keeps the specified list of variables in the active
6330 file. Any unlisted variables are deleted from the active file.
6332 MAP is currently ignored.
6334 If either DROP or KEEP is specified, the data is read; otherwise it is
6337 @cmd{MODIFY VARS} may not be specified following @cmd{TEMPORARY}
6338 (@pxref{TEMPORARY}).
6340 @node NUMERIC, PRINT FORMATS, MODIFY VARS, Variable Attributes
6345 NUMERIC /var_list [(fmt_spec)].
6348 @cmd{NUMERIC} explicitly declares new numeric variables, optionally
6349 setting their output formats.
6351 Specify a slash (@samp{/}), followed by the names of the new numeric
6352 variables. If you wish to set their output formats, follow their names
6353 by an output format specification in parentheses (@pxref{Input/Output
6354 Formats}); otherwise, the default is F8.2.
6356 Variables created with @cmd{NUMERIC} are initialized to the
6357 system-missing value.
6359 @node PRINT FORMATS, RENAME VARIABLES, NUMERIC, Variable Attributes
6360 @section PRINT FORMATS
6361 @vindex PRINT FORMATS
6364 PRINT FORMATS var_list (fmt_spec).
6367 @cmd{PRINT FORMATS} sets the print formats for the specified
6368 variables to the specified format specification.
6370 Its syntax is identical to that of @cmd{FORMATS} (@pxref{FORMATS}),
6371 but @cmd{PRINT FORMATS} sets only print formats, not write formats.
6373 @node RENAME VARIABLES, VALUE LABELS, PRINT FORMATS, Variable Attributes
6374 @section RENAME VARIABLES
6375 @vindex RENAME VARIABLES
6378 RENAME VARIABLES (old_names=new_names)@dots{} .
6381 @cmd{RENAME VARIABLES} changes the names of variables in the active
6382 file. Specify lists of the old variable names and new
6383 variable names, separated by an equals sign (@samp{=}), within
6384 parentheses. There must be the same number of old and new variable
6385 names. Each old variable is renamed to the corresponding new variable
6386 name. Multiple parenthesized groups of variables may be specified.
6388 @cmd{RENAME VARIABLES} takes effect immediately. It does not cause the data
6391 @cmd{RENAME VARIABLES} may not be specified following @cmd{TEMPORARY}
6392 (@pxref{TEMPORARY}).
6394 @node VALUE LABELS, STRING, RENAME VARIABLES, Variable Attributes
6395 @section VALUE LABELS
6396 @vindex VALUE LABELS
6400 /var_list value 'label' [value 'label']@dots{}
6403 @cmd{VALUE LABELS} allows values of numeric and short string
6404 variables to be associated with labels. In this way, a short value can
6405 stand for a long value.
6407 To set up value labels for a set of variables, specify the
6408 variable names after a slash (@samp{/}), followed by a list of values
6409 and their associated labels, separated by spaces. Long string
6410 variables may not be specified.
6412 Before @cmd{VALUE LABELS} is executed, any existing value labels
6413 are cleared from the variables specified. Use @cmd{ADD VALUE LABELS}
6414 (@pxref{ADD VALUE LABELS}) to add value labels without clearing those
6417 @node STRING, VARIABLE LABELS, VALUE LABELS, Variable Attributes
6422 STRING /var_list (fmt_spec).
6425 @cmd{STRING} creates new string variables for use in
6428 Specify a slash (@samp{/}), followed by the names of the string
6429 variables to create and the desired output format specification in
6430 parentheses (@pxref{Input/Output Formats}). Variable widths are
6431 implicitly derived from the specified output formats.
6433 Created variables are initialized to spaces.
6435 @node VARIABLE LABELS, VECTOR, STRING, Variable Attributes
6436 @section VARIABLE LABELS
6437 @vindex VARIABLE LABELS
6441 /var_list 'var_label'.
6444 @cmd{VARIABLE LABELS} associates explanatory names
6445 with variables. This name, called a @dfn{variable label}, is displayed by
6446 statistical procedures.
6448 To assign a variable label to a group of variables, specify a slash
6449 (@samp{/}), followed by the list of variable names and the variable
6452 @node VECTOR, WRITE FORMATS, VARIABLE LABELS, Variable Attributes
6457 Two possible syntaxes:
6458 VECTOR vec_name=var_list.
6459 VECTOR vec_name_list(count).
6462 @cmd{VECTOR} allows a group of variables to be accessed as if they
6463 were consecutive members of an array with a vector(index) notation.
6465 To make a vector out of a set of existing variables, specify a name for
6466 the vector followed by an equals sign (@samp{=}) and the variables that
6467 belong in the vector.
6469 To make a vector and create variables at the same time, specify one or
6470 more vector names followed by a count in parentheses. This will cause
6471 variables named @code{@var{vec}1} through @code{@var{vec}@var{count}}
6472 to be created as numeric variables with print and write format F8.2.
6473 Variable names including numeric suffixes may not exceed 8 characters
6474 in length, and none of the variables may exist prior to @cmd{VECTOR}.
6476 All the variables in a vector must be the same type.
6478 Vectors created with @cmd{VECTOR} disappear after any procedure or
6479 procedure-like command is executed. The variables contained in the
6480 vectors remain, unless they are scratch variables (@pxref{Scratch
6483 Variables within a vector may be references in expressions using
6484 @code{vector(index)} syntax.
6486 @node WRITE FORMATS, , VECTOR, Variable Attributes
6487 @section WRITE FORMATS
6488 @vindex WRITE FORMATS
6491 WRITE FORMATS var_list (fmt_spec).
6494 @cmd{WRITE FORMATS} sets the write formats for the specified variables
6495 to the specified format specification. Its syntax is identical to
6496 that of FORMATS (@pxref{FORMATS}), but @cmd{WRITE FORMATS} sets only
6497 write formats, not print formats.
6499 @node Data Manipulation, Data Selection, Variable Attributes, Top
6500 @chapter Data transformations
6501 @cindex transformations
6503 The PSPP procedures examined in this chapter manipulate data and
6504 prepare the active file for later analyses. They do not produce output,
6508 * AGGREGATE:: Summarize multiple cases into a single case.
6509 * AUTORECODE:: Automatic recoding of variables.
6510 * COMPUTE:: Assigning a variable a calculated value.
6511 * COUNT:: Counting variables with particular values.
6512 * FLIP:: Exchange variables with cases.
6513 * IF:: Conditionally assigning a calculated value.
6514 * RECODE:: Mapping values from one set to another.
6515 * SORT CASES:: Sort the active file.
6518 @node AGGREGATE, AUTORECODE, Data Manipulation, Data Manipulation
6526 /OUTFILE=@{*,'filename'@}
6529 /dest_vars=agr_func(src_vars, args@dots{})@dots{}
6532 @cmd{AGGREGATE} summarizes groups of cases into single cases.
6533 Cases are divided into groups that have the same values for one or more
6534 variables called @dfn{break variables}. Several functions are available
6535 for summarizing case contents.
6537 At least one break variable must be specified on BREAK, the only
6538 required subcommand. The values of these variables are used to divide
6539 the active file into groups to be summarized. In addition, at least
6540 one @var{dest_var} must be specified.
6542 By default, the active file is sorted based on the break variables
6543 before aggregation takes place. If the active file is already sorted
6544 or otherwise grouped in terms of the break variables, specify
6545 PRESORTED to save time.
6547 The OUTFILE subcommand specifies a system file by file name string or
6548 file handle (@pxref{FILE HANDLE}). The aggregated cases are written to
6549 this file. If OUTFILE is not specified, or if @samp{*} is specified,
6550 then the aggregated cases replace the active file.
6552 Specify DOCUMENT to copy the documents from the active file into the
6553 aggregate file (@pxref{DOCUMENT}). Otherwise, the aggregate file will
6554 not contain any documents, even if the aggregate file replaces the
6557 One or more sets of aggregation variables must be specified. Each set
6558 comprises a list of aggregation variables, an equals sign (@samp{=}),
6559 the name of an aggregation function (see the list below), and a list
6560 of source variables in parentheses. Some aggregation functions expect
6561 additional arguments following the source variable names.
6563 Each set must have exactly as many source variables as aggregation
6564 variables. Each aggregation variable receives the results of applying
6565 the specified aggregation function to the corresponding source
6566 variable. Most aggregation functions may be applied to numeric and
6567 short and long string variables. Others, marked below, are restricted
6570 The available aggregation functions are as follows:
6574 Sum. Limited to numeric values.
6575 @item MEAN(var_name)
6576 Arithmetic mean. Limited to numeric values.
6578 Standard deviation of the mean. Limited to numeric values.
6583 @item FGT(var_name, value)
6584 @itemx PGT(var_name, value)
6585 Fraction between 0 and 1, or percentage between 0 and 100, respectively,
6586 of values greater than the specified constant.
6587 @item FLT(var_name, value)
6588 @itemx PLT(var_name, value)
6589 Fraction or percentage, respectively, of values less than the specified
6591 @item FIN(var_name, low, high)
6592 @itemx PIN(var_name, low, high)
6593 Fraction or percentage, respectively, of values within the specified
6594 inclusive range of constants.
6595 @item FOUT(var_name, low, high)
6596 @itemx POUT(var_name, low, high)
6597 Fraction or percentage, respectively, of values strictly outside the
6598 specified range of constants.
6600 Number of non-missing values.
6602 Number of cases aggregated to form this group. Don't supply a source
6603 variable for this aggregation function.
6605 Number of non-missing values. Each case is considered to have a weight
6606 of 1, regardless of the current weighting variable (@pxref{WEIGHT}).
6608 Number of cases aggregated to form this group. Each case is considered
6609 to have a weight of 1, regardless of the current weighting variable.
6610 @item NMISS(var_name)
6611 Number of missing values.
6612 @item NUMISS(var_name)
6613 Number of missing values. Each case is considered to have a weight of
6614 1, regardless of the current weighting variable.
6615 @item FIRST(var_name)
6616 First value in this group.
6617 @item LAST(var_name)
6618 Last value in this group.
6621 Aggregation functions compare string values in terms of internal
6622 character codes. On most modern computers, this is a form of ASCII.
6624 The aggregation functions listed above exclude all user-missing values
6625 from calculations. To include user-missing values, insert a period
6626 (@samp{.}) between the function name and left parenthesis
6629 Normally, only a single case (for SD and SD., two cases) need be
6630 non-missing in each group for the aggregate variable to be
6631 non-missing. Specifying /MISSING=COLUMNWISE inverts this behavior, so
6632 that the aggregate variable becomes missing if any aggregated value is
6635 @cmd{AGGREGATE} both ignores and cancels the current @cmd{SPLIT FILE}
6636 settings (@pxref{SPLIT FILE}).
6638 @node AUTORECODE, COMPUTE, AGGREGATE, Data Manipulation
6643 AUTORECODE VARIABLES=src_vars INTO dest_vars
6648 The @cmd{AUTORECODE} procedure considers the @var{n} values that a variable
6649 takes on and maps them onto values 1@dots{}@var{n} on a new numeric
6652 Subcommand VARIABLES is the only required subcommand and must come
6653 first. Specify VARIABLES, an equals sign (@samp{=}), a list of source
6654 variables, INTO, and a list of target variables. There must the same
6655 number of source and target variables. The target variables must not
6658 By default, increasing values of a source variable (for a string, this
6659 is based on character code comparisons) are recoded to increasing values
6660 of its target variable. To cause increasing values of a source variable
6661 to be recoded to decreasing values of its target variable (@var{n} down
6662 to 1), specify DESCENDING.
6664 PRINT is currently ignored.
6666 @cmd{AUTORECODE} is a procedure. It causes the data to be read.
6668 @node COMPUTE, COUNT, AUTORECODE, Data Manipulation
6673 COMPUTE variable = expression.
6675 COMPUTE vector(index) = expression.
6678 @cmd{COMPUTE} assigns the value of an expression to a target
6679 variable. For each case, the expression is evaluated and its value
6680 assigned to the target variable. Numeric and short and long string
6681 variables may be assigned. When a string expression's width differs
6682 from the target variable's width, the string result of the expression
6683 is truncated or padded with spaces on the right as necessary. The
6684 expression and variable types must match.
6686 For numeric variables only, the target variable need not already
6687 exist. Numeric variables created by @cmd{COMPUTE} are assigned an
6688 @code{F8.2} output format. String variables must be declared before
6689 they can be used as targets for @cmd{COMPUTE}.
6691 The target variable may be specified as an element of a vector
6692 (@pxref{VECTOR}). In this case, a vector index expression must be
6693 specified in parentheses following the vector name. The index
6694 expression must evaluate to a numeric value that, after rounding down
6695 to the nearest integer, is a valid index for the named vector.
6697 Using @cmd{COMPUTE} to assign to a variable specified on @cmd{LEAVE}
6698 (@pxref{LEAVE}) resets the variable's left state. Therefore,
6699 @code{LEAVE} should be specified following @cmd{COMPUTE}, not before.
6701 @cmd{COMPUTE} is a transformation. It does not cause the active file to be
6704 When @cmd{COMPUTE} is specified following @cmd{TEMPORARY}
6705 (@pxref{TEMPORARY}), the @cmd{LAG} function may not be used
6708 @node COUNT, FLIP, COMPUTE, Data Manipulation
6713 COUNT var_name = var@dots{} (value@dots{}).
6715 Each value takes one of the following forms:
6721 In addition, num1 and num2 can be LO or LOWEST, or HI or HIGHEST,
6725 @cmd{COUNT} creates or replaces a numeric @dfn{target} variable that
6726 counts the occurrence of a @dfn{criterion} value or set of values over
6727 one or more @dfn{test} variables for each case.
6729 The target variable values are always nonnegative integers. They are
6730 never missing. The target variable is assigned an F8.2 output format.
6731 @xref{Input/Output Formats}. Any variables, including long and short
6732 string variables, may be test variables.
6734 User-missing values of test variables are treated just like any other
6735 values. They are @strong{not} treated as system-missing values.
6736 User-missing values that are criterion values or inside ranges of
6737 criterion values are counted as any other values. However (for numeric
6738 variables), keyword MISSING may be used to refer to all system-
6739 and user-missing values.
6741 @cmd{COUNT} target variables are assigned values in the order
6742 specified. In the command @code{COUNT A=A B(1) /B=A B(2).}, the
6743 following actions occur:
6747 The number of occurrences of 1 between @code{A} and @code{B} is counted.
6750 @code{A} is assigned this value.
6753 The number of occurrences of 1 between @code{B} and the @strong{new}
6754 value of @code{A} is counted.
6757 @code{B} is assigned this value.
6760 Despite this ordering, all @cmd{COUNT} criterion variables must exist
6761 before the procedure is executed---they may not be created as target
6762 variables earlier in the command! Break such a command into two
6765 The examples below may help to clarify.
6769 Assuming @code{Q0}, @code{Q2}, @dots{}, @code{Q9} are numeric variables,
6770 the following commands:
6774 Count the number of times the value 1 occurs through these variables
6775 for each case and assigns the count to variable @code{QCOUNT}.
6778 Print out the total number of times the value 1 occurs throughout
6779 @emph{all} cases using @cmd{DESCRIPTIVES}. @xref{DESCRIPTIVES}, for
6784 COUNT QCOUNT=Q0 TO Q9(1).
6785 DESCRIPTIVES QCOUNT /STATISTICS=SUM.
6789 Given these same variables, the following commands:
6793 Count the number of valid values of these variables for each case and
6794 assigns the count to variable @code{QVALID}.
6797 Multiplies each value of @code{QVALID} by 10 to obtain a percentage of
6798 valid values, using @cmd{COMPUTE}. @xref{COMPUTE}, for details.
6801 Print out the percentage of valid values across all cases, using
6802 @cmd{DESCRIPTIVES}. @xref{DESCRIPTIVES}, for details.
6806 COUNT QVALID=Q0 TO Q9 (LO THRU HI).
6807 COMPUTE QVALID=QVALID*10.
6808 DESCRIPTIVES QVALID /STATISTICS=MEAN.
6812 @node FLIP, IF, COUNT, Data Manipulation
6817 FLIP /VARIABLES=var_list /NEWNAMES=var_name.
6820 @cmd{FLIP} transposes rows and columns in the active file. It
6821 causes cases to be swapped with variables, and vice versa.
6823 All variables in the transposed active file are numeric. String
6824 variables take on the system-missing value in the transposed file.
6826 No subcommands are required. The VARIABLES subcommand specifies
6827 variables that will be transformed into cases. Variables not specified
6828 are discarded. By default, all variables are selected for
6831 The variables specified by NEWNAMES, which must be a string variable, is
6832 used to give names to the variables created by @cmd{FLIP}. If
6834 specified then the default is a variable named CASE_LBL, if it exists.
6835 If it does not then the variables created by FLIP are named VAR000
6836 through VAR999, then VAR1000, VAR1001, and so on.
6838 When a NEWNAMES variable is available, the names must be canonicalized
6839 before becoming variable names. Invalid characters are replaced by
6840 letter @samp{V} in the first position, or by @samp{_} in subsequent
6841 positions. If the name thus generated is not unique, then numeric
6842 extensions are added, starting with 1, until a unique name is found or
6843 there are no remaining possibilities. If the latter occurs then the
6844 FLIP operation aborts.
6846 The resultant dictionary contains a CASE_LBL variable, which stores the
6847 names of the variables in the dictionary before the transposition. If
6848 the active file is subsequently transposed using @cmd{FLIP}, this
6850 be used to recreate the original variable names.
6852 FLIP honors N OF CASES. It ignores TEMPORARY, so that ``temporary''
6853 transformations become permanent.
6855 @node IF, RECODE, FLIP, Data Manipulation
6860 IF condition variable=expression.
6862 IF condition vector(index)=expression.
6865 The @cmd{IF} transformation conditionally assigns the value of a target
6866 expression to a target variable, based on the truth of a test
6869 Specify a boolean-valued expression (@pxref{Expressions}) to be tested
6870 following the IF keyword. This expression is evaluated for each case.
6871 If the value is true, then the value of the expression is computed and
6872 assigned to the specified variable. If the value is false or missing,
6873 nothing is done. Numeric and short and long string variables may be
6874 assigned. When a string expression's width differs from the target
6875 variable's width, the string result of the expression is truncated or
6876 padded with spaces on the right as necessary. The expression and
6877 variable types must match.
6879 The target variable may be specified as an element of a vector
6880 (@pxref{VECTOR}). In this case, a vector index expression must be
6881 specified in parentheses following the vector name. The index
6882 expression must evaluate to a numeric value that, after rounding down
6883 to the nearest integer, is a valid index for the named vector.
6885 Using @cmd{IF} to assign to a variable specified on @cmd{LEAVE}
6886 (@pxref{LEAVE}) resets the variable's left state. Therefore,
6887 @code{LEAVE} should be specified following @cmd{IF}, not before.
6889 When @cmd{IF} is specified following @cmd{TEMPORARY}
6890 (@pxref{TEMPORARY}), the @cmd{LAG} function may not be used
6893 @node RECODE, SORT CASES, IF, Data Manipulation
6898 RECODE var_list (src_value@dots{}=dest_value)@dots{} [INTO var_list].
6900 src_value may take the following forms:
6907 Open-ended ranges may be specified using LO or LOWEST for num1
6908 or HI or HIGHEST for num2.
6910 dest_value may take the following forms:
6917 @cmd{RECODE} translates data from one range of values to
6918 another, via flexible user-specified mappings. Data may be remapped
6919 in-place or copied to new variables. Numeric, short string, and long
6920 string data can be recoded.
6922 Specify the list of source variables, followed by one or more mapping
6923 specifications each enclosed in parentheses. If the data is to be
6924 copied to new variables, specify INTO, then the list of target
6925 variables. String target variables must already have been declared
6926 using @cmd{STRING} or another transformation, but numeric target
6928 be created on the fly. There must be exactly as many target variables
6929 as source variables. Each source variable is remapped into its
6930 corresponding target variable.
6932 When INTO is not used, the input and output variables must be of the
6933 same type. Otherwise, string values can be recoded into numeric values,
6934 and vice versa. When this is done and there is no mapping for a
6935 particular value, either a value consisting of all spaces or the
6936 system-missing value is assigned, depending on variable type.
6938 Mappings are considered from left to right. The first src_value that
6939 matches the value of the source variable causes the target variable to
6940 receive the value indicated by the dest_value. Literal number, string,
6941 and range src_value's should be self-explanatory. MISSING as a
6942 src_value matches any user- or system-missing value. SYSMIS matches the
6943 system missing value only. ELSE is a catch-all that matches anything.
6944 It should be the last src_value specified.
6946 Numeric and string dest_value's should also be self-explanatory. COPY
6947 causes the input values to be copied to the output. This is only value
6948 if the source and target variables are of the same type. SYSMIS
6949 indicates the system-missing value.
6951 If the source variables are strings and the target variables are
6952 numeric, then there is one additional mapping available: (CONVERT),
6953 which must be the last specified mapping. CONVERT causes a number
6954 specified as a string to be converted to a numeric value. If the string
6955 cannot be parsed as a number, then the system-missing value is assigned.
6957 Multiple recodings can be specified on a single @cmd{RECODE} invocation.
6958 Introduce additional recodings with a slash (@samp{/}) to
6959 separate them from the previous recodings.
6961 @node SORT CASES, , RECODE, Data Manipulation
6966 SORT CASES BY var_list.
6969 @cmd{SORT CASES} sorts the active file by the values of one or more
6972 Specify BY and a list of variables to sort by. By default, variables
6973 are sorted in ascending order. To override sort order, specify (D) or
6974 (DOWN) after a list of variables to get descending order, or (A) or (UP)
6975 for ascending order. These apply to the entire list of variables
6978 @cmd{SORT CASES} is a procedure. It causes the data to be read.
6980 @cmd{SORT CASES} attempts to sort the entire active file in main memory.
6981 If main memory is exhausted, it falls back to a merge sort algorithm that
6982 involves writing and reading numerous temporary files.
6984 @cmd{SORT CASES} may not be specified following TEMPORARY.
6986 @node Data Selection, Conditionals and Looping, Data Manipulation, Top
6987 @chapter Selecting data for analysis
6989 This chapter documents PSPP commands that temporarily or permanently
6990 select data records from the active file for analysis.
6993 * FILTER:: Exclude cases based on a variable.
6994 * N OF CASES:: Limit the size of the active file.
6995 * PROCESS IF:: Temporarily excluding cases.
6996 * SAMPLE:: Select a specified proportion of cases.
6997 * SELECT IF:: Permanently delete selected cases.
6998 * SPLIT FILE:: Do multiple analyses with one command.
6999 * TEMPORARY:: Make transformations' effects temporary.
7000 * WEIGHT:: Weight cases by a variable.
7003 @node FILTER, N OF CASES, Data Selection, Data Selection
7012 @cmd{FILTER} allows a boolean-valued variable to be used to select
7013 cases from the data stream for processing.
7015 To set up filtering, specify BY and a variable name. Keyword
7016 BY is optional but recommended. Cases which have a zero or system- or
7017 user-missing value are excluded from analysis, but not deleted from the
7018 data stream. Cases with other values are analyzed.
7019 To filter based on a different condition, use
7020 transformations such as @cmd{COMPUTE} or @cmd{RECODE} to compute a
7021 filter variable of the required form, then specify that variable on
7024 @code{FILTER OFF} turns off case filtering.
7026 Filtering takes place immediately before cases pass to a procedure for
7027 analysis. Only one filter variable may be active at a time. Normally,
7028 case filtering continues until it is explicitly turned off with @code{FILTER
7029 OFF}. However, if @cmd{FILTER} is placed after TEMPORARY, it filters only
7030 the next procedure or procedure-like command.
7032 @node N OF CASES, PROCESS IF, FILTER, Data Selection
7037 N [OF CASES] num_of_cases [ESTIMATED].
7040 Sometimes you may want to disregard cases of your input. @cmd{N} can
7041 do this. @code{N 100} tells PSPP to disregard all cases after the
7044 If the value specified for @cmd{N} is greater than the number of cases
7045 read in, the value is ignored.
7047 @cmd{N} does not discard cases or prevent them from being read. It
7048 just causes cases beyond the last one specified to be ignored by data
7051 A later @cmd{N} command can increase or decrease the number of cases
7052 selected. (To select all the cases without knowing how many there are,
7053 specify a very high number: 100000 or whatever you think is large enough.)
7055 Transformation procedures performed after @cmd{N} is executed
7056 @emph{do} cause cases to be discarded.
7058 @cmd{SAMPLE}, @cmd{PROCESS IF}, and @cmd{SELECT IF} have
7059 precedence over @cmd{N}---the same results are obtained by both of the
7060 following fragments, given the same random number seeds:
7063 @i{@dots{}set up, read in data@dots{}}
7066 @i{@dots{}analyze data@dots{}}
7068 @i{@dots{}set up, read in data@dots{}}
7071 @i{@dots{}analyze data@dots{}}
7074 Both fragments above first randomly sample approximately half of the
7075 cases, then select the first 100 of those sampled.
7077 @cmd{N} with the @code{ESTIMATED} keyword gives an
7078 estimated number of cases before @cmd{DATA LIST} or another command to
7079 read in data. @code{ESTIMATED} never limits the number of cases
7080 processed by procedures. PSPP currently does not make use of
7081 case count estimates.
7083 When @cmd{N} is specified after @cmd{TEMPORARY}, it affects only
7084 the next procedure (@pxref{TEMPORARY}).
7086 @node PROCESS IF, SAMPLE, N OF CASES, Data Selection
7091 PROCESS IF expression.
7094 @cmd{PROCESS IF} temporarily eliminates cases from the
7095 data stream. Its effects are active only through the execution of the
7096 next procedure or procedure-like command.
7098 Specify a boolean expression (@pxref{Expressions}). If the value of the
7099 expression is true for a particular case, the case will be analyzed. If
7100 the expression has a false or missing value, then the case will be
7101 deleted from the data stream for this procedure only.
7103 Regardless of its placement relative to other commands, @cmd{PROCESS IF}
7104 always takes effect immediately before data passes to the procedure.
7105 Only one @cmd{PROCESS IF} command may be in effect at any given time.
7107 The effects of @cmd{PROCESS IF} are similar, but not identical, to the
7108 effects of executing @cmd{TEMPORARY}, then @cmd{SELECT IF}
7109 (@pxref{SELECT IF}).
7111 The filtering performed by @cmd{PROCESS IF} takes place immediately
7112 before cases pass to a procedure for analysis. Because @cmd{PROCESS
7113 IF} affects only a single procedure, its placement relative to
7114 @cmd{TEMPORARY} is unimportant.
7116 @cmd{PROCESS IF} is deprecated. It is included for compatibility with
7117 old command files. New syntax files should use @cmd{SELECT IF} or
7118 @cmd{FILTER} instead.
7120 @node SAMPLE, SELECT IF, PROCESS IF, Data Selection
7125 SAMPLE num1 [FROM num2].
7128 @cmd{SAMPLE} randomly samples a proportion of the cases in the active
7129 file. Unless it follows @cmd{TEMPORARY}, it operates as a
7130 transformation, permanently removing cases from the active file.
7132 The proportion to sample can be expressed as a single number between 0
7133 and 1. If @code{k} is the number specified, and @code{N} is the number
7134 of currently-selected cases in the active file, then after
7135 @code{SAMPLE @var{k}.}, approximately @code{k*N} cases will be
7138 The proportion to sample can also be specified in the style @code{SAMPLE
7139 @var{m} FROM @var{N}}. With this style, cases are selected as follows:
7143 If @var{N} is equal to the number of currently-selected cases in the
7144 active file, exactly @var{m} cases will be selected.
7147 If @var{N} is greater than the number of currently-selected cases in the
7148 active file, an equivalent proportion of cases will be selected.
7151 If @var{N} is less than the number of currently-selected cases in the
7152 active, exactly @var{m} cases will be selected @emph{from the first
7153 @var{N} cases in the active file.}
7156 @cmd{SAMPLE} and @cmd{SELECT IF} are performed in
7157 the order specified by the syntax file.
7159 @cmd{SAMPLE} is always performed before @code{N OF CASES}, regardless
7160 of ordering in the syntax file (@pxref{N OF CASES}).
7162 The same values for @cmd{SAMPLE} may result in different samples. To
7163 obtain the same sample, use the @code{SET} command to set the random
7164 number seed to the same value before each @cmd{SAMPLE}. Different
7165 samples may still result when the file is processed on systems with
7166 differing endianness or floating-point formats. By default, the
7167 random number seed is based on the system time.
7169 @node SELECT IF, SPLIT FILE, SAMPLE, Data Selection
7174 SELECT IF expression.
7177 @cmd{SELECT IF} selects cases for analysis based on the value of a
7178 boolean expression. Cases not selected are permanently eliminated
7179 from the active file, unless @cmd{TEMPORARY} is in effect
7180 (@pxref{TEMPORARY}).
7182 Specify a boolean expression (@pxref{Expressions}). If the value of the
7183 expression is true for a particular case, the case will be analyzed. If
7184 the expression has a false or missing value, then the case will be
7185 deleted from the data stream.
7187 Place @cmd{SELECT IF} as early in the command file as
7188 possible. Cases that are deleted early can be processed more
7189 efficiently in time and space.
7191 When @cmd{SELECT IF} is specified following @cmd{TEMPORARY}
7192 (@pxref{TEMPORARY}), the @cmd{LAG} function may not be used
7195 @node SPLIT FILE, TEMPORARY, SELECT IF, Data Selection
7200 Two possible syntaxes:
7201 SPLIT FILE BY var_list.
7205 @cmd{SPLIT FILE} allows multiple sets of data present in one data
7206 file to be analyzed separately using single statistical procedure
7209 Specify a list of variable names to analyze multiple sets of
7210 data separately. Groups of cases having the same values for these
7211 variables are analyzed by statistical procedure commands as one group.
7212 An independent analysis is carried out for each group of cases, and the
7213 variable values for the group are printed along with the analysis.
7215 Specify OFF to disable @cmd{SPLIT FILE} and resume analysis of the
7216 entire active file as a single group of data.
7218 When @cmd{SPLIT FILE} is specified after @cmd{TEMPORARY}, it affects only
7219 the next procedure (@pxref{TEMPORARY}).
7221 @node TEMPORARY, WEIGHT, SPLIT FILE, Data Selection
7229 @cmd{TEMPORARY} is used to make the effects of transformations
7230 following its execution temporary. These transformations will
7231 affect only the execution of the next procedure or procedure-like
7232 command. Their effects will not be saved to the active file.
7234 The only specification on @cmd{TEMPORARY} is the command name.
7236 @cmd{TEMPORARY} may not appear within a @cmd{DO IF} or @cmd{LOOP}
7237 construct. It may appear only once between procedures and
7238 procedure-like commands.
7240 Scratch variables cannot be used following @cmd{TEMPORARY}.
7242 An example may help to clarify:
7261 The data read by the first @cmd{DESCRIPTIVES} are 4, 5, 8,
7262 10.5, 13, 15. The data read by the first @cmd{DESCRIPTIVES} are 1, 2,
7265 @node WEIGHT, , TEMPORARY, Data Selection
7274 @cmd{WEIGHT} assigns cases varying weights,
7275 changing the frequency distribution of the active file. Execution of
7276 @cmd{WEIGHT} is delayed until data have been read.
7278 If a variable name is specified, @cmd{WEIGHT} causes the values of that
7279 variable to be used as weighting factors for subsequent statistical
7280 procedures. Use of keyword BY is optional but recommended. Weighting
7281 variables must be numeric. Scratch variables may not be used for
7282 weighting (@pxref{Scratch Variables}).
7284 When OFF is specified, subsequent statistical procedures will weight all
7287 A positive integer weighting factor @var{w} on a case will yield the
7288 same statistical output as would replicating the case @var{w} times.
7289 A weighting factor of 0 is treated for statistical purposes as if the
7290 case did not exist in the input. Weighting values need not be
7291 integers, but negative and system-missing values for the weighting
7292 variable are interpreted as weighting factors of 0. User-missing
7293 values are not treated specially.
7295 When @cmd{WEIGHT} is specified after @cmd{TEMPORARY}, it affects only
7296 the next procedure (@pxref{TEMPORARY}).
7298 @cmd{WEIGHT} does not cause cases in the active file to be replicated in
7301 @node Conditionals and Looping, Statistics, Data Selection, Top
7302 @chapter Conditional and Looping Constructs
7303 @cindex conditionals
7305 @cindex flow of control
7306 @cindex control flow
7308 This chapter documents PSPP commands used for conditional execution,
7309 looping, and flow of control.
7312 * BREAK:: Exit a loop.
7313 * DO IF:: Conditionally execute a block of code.
7314 * DO REPEAT:: Textually repeat a code block.
7315 * LOOP:: Repeat a block of code.
7318 @node BREAK, DO IF, Conditionals and Looping, Conditionals and Looping
7326 @cmd{BREAK} terminates execution of the innermost currently executing
7327 @cmd{LOOP} construct.
7329 @cmd{BREAK} is allowed only inside @cmd{LOOP}@dots{}@cmd{END LOOP}.
7330 @xref{LOOP}, for more details.
7332 @node DO IF, DO REPEAT, BREAK, Conditionals and Looping
7347 @cmd{DO IF} allows one of several sets of transformations to be
7348 executed, depending on user-specified conditions.
7350 If the specified boolean expression evaluates as true, then the block
7351 of code following @cmd{DO IF} is executed. If it evaluates as
7353 none of the code blocks is executed. If it is false, then
7354 the boolean expression on the first @cmd{ELSE IF}, if present, is tested in
7355 turn, with the same rules applied. If all expressions evaluate to
7356 false, then the @cmd{ELSE} code block is executed, if it is present.
7358 When @cmd{DO IF} or @cmd{ELSE IF} is specified following @cmd{TEMPORARY}
7359 (@pxref{TEMPORARY}), the @cmd{LAG} function may not be used
7362 @node DO REPEAT, LOOP, DO IF, Conditionals and Looping
7367 DO REPEAT repvar_name=expansion@dots{}.
7371 expansion takes one of the following forms:
7376 num_or_range takes one of the following forms:
7381 @cmd{DO REPEAT} repeats a block of code, textually substituting
7382 different variables, numbers, or strings into the block with each
7385 Specify a repeat variable name followed by an equals sign (@samp{=}) and
7386 the list of replacements. Replacements can be a list of variables
7387 (which may be existing variables or new variables or a combination
7388 thereof), of numbers, or of strings. When new variable names are
7389 specified, @cmd{DO REPEAT} creates them as numeric variables. When numbers
7390 are specified, runs of integers may be indicated with TO notation, for
7391 instance @samp{1 TO 5} and @samp{1 2 3 4 5} would be equivalent. There
7392 is no equivalent notation for string values.
7394 Multiple repeat variables can be specified. When this is done, each
7395 variable must have the same number of replacements.
7397 The code within @cmd{DO REPEAT} is repeated as many times as there are
7398 replacements for each variable. The first time, the first value for
7399 each repeat variable is substituted; the second time, the second value
7400 for each repeat variable is substituted; and so on.
7402 Repeat variable substitutions work like macros. They take place
7403 anywhere in a line that the repeat variable name occurs as a token,
7404 including command and subcommand names. For this reason it is not a
7405 good idea to select words commonly used in command and subcommand names
7406 as repeat variable identifiers.
7408 If PRINT is specified on @cmd{END REPEAT}, the commands after substitutions
7409 are made are printed to the listing file, prefixed by a plus sign
7412 @node LOOP, , DO REPEAT, Conditionals and Looping
7417 LOOP [index_var=start TO end [BY incr]] [IF condition].
7419 END LOOP [IF condition].
7422 @cmd{LOOP} iterates a group of commands. A number of
7423 termination options are offered.
7425 Specify index_var to make that variable count from one value to
7426 another by a particular increment. index_var must be a pre-existing
7427 numeric variable. start, end, and incr are numeric expressions
7428 (@pxref{Expressions}.)
7430 During the first iteration, index_var is set to the value of start.
7431 During each successive iteration, index_var is increased by the value of
7432 incr. If end > start, then the loop terminates when index_var > end;
7433 otherwise it terminates when index_var < end. If incr is not specified
7434 then it defaults to +1 or -1 as appropriate.
7436 If end > start and incr < 0, or if end < start and incr > 0, then the
7437 loop is never executed. index_var is nevertheless set to the value of
7440 Modifying index_var within the loop is allowed, but it has no effect on
7441 the value of index_var in the next iteration.
7443 Specify a boolean expression for the condition on @cmd{LOOP} to
7444 cause the loop to be executed only if the condition is true. If the
7445 condition is false or missing before the loop contents are executed the
7446 first time, the loop contents are not executed at all.
7448 If index and condition clauses are both present on @cmd{LOOP}, the index
7449 clause is always evaluated first.
7451 Specify a boolean expression for the condition on @cmd{END LOOP} to cause
7452 the loop to terminate if the condition is not true after the enclosed
7453 code block is executed. The condition is evaluated at the end of the
7454 loop, not at the beginning.
7456 If the index clause and both condition clauses are not present, then the
7457 loop is executed MXLOOPS (@pxref{SET}) times.
7459 @cmd{BREAK} also terminates @cmd{LOOP} execution (@pxref{BREAK}).
7461 When @cmd{LOOP} or @cmd{END LOOP} is specified following @cmd{TEMPORARY}
7462 (@pxref{TEMPORARY}), the @cmd{LAG} function may not be used
7465 @node Statistics, Utilities, Conditionals and Looping, Top
7468 This chapter documents the statistical procedures that PSPP supports so
7472 * DESCRIPTIVES:: Descriptive statistics.
7473 * FREQUENCIES:: Frequency tables.
7474 * CROSSTABS:: Crosstabulation tables.
7475 * T-TEST:: Test Hypotheses about means.
7478 @node DESCRIPTIVES, FREQUENCIES, Statistics, Statistics
7479 @section DESCRIPTIVES
7481 @vindex DESCRIPTIVES
7485 /MISSING=@{VARIABLE,LISTWISE@} @{INCLUDE,NOINCLUDE@}
7486 /FORMAT=@{LABELS,NOLABELS@} @{NOINDEX,INDEX@} @{LINE,SERIAL@}
7488 /STATISTICS=@{ALL,MEAN,SEMEAN,STDDEV,VARIANCE,KURTOSIS,
7489 SKEWNESS,RANGE,MINIMUM,MAXIMUM,SUM,DEFAULT,
7490 SESKEWNESS,SEKURTOSIS@}
7491 /SORT=@{NONE,MEAN,SEMEAN,STDDEV,VARIANCE,KURTOSIS,SKEWNESS,
7492 RANGE,MINIMUM,MAXIMUM,SUM,SESKEWNESS,SEKURTOSIS,NAME@}
7496 The @cmd{DESCRIPTIVES} procedure reads the active file and outputs
7498 statistics requested by the user. In addition, it can optionally
7501 The VARIABLES subcommand, which is required, specifies the list of
7502 variables to be analyzed. Keyword VARIABLES is optional.
7504 All other subcommands are optional:
7506 The MISSING subcommand determines the handling of missing variables. If
7507 INCLUDE is set, then user-missing values are included in the
7508 calculations. If NOINCLUDE is set, which is the default, user-missing
7509 values are excluded. If VARIABLE is set, then missing values are
7510 excluded on a variable by variable basis; if LISTWISE is set, then
7511 the entire case is excluded whenever any value in that case has a
7512 system-missing or, if INCLUDE is set, user-missing value.
7514 The FORMAT subcommand affects the output format. Currently the
7515 LABELS/NOLABELS and NOINDEX/INDEX settings are not used. When SERIAL is
7516 set, both valid and missing number of cases are listed in the output;
7517 when NOSERIAL is set, only valid cases are listed.
7519 The SAVE subcommand causes @cmd{DESCRIPTIVES} to calculate Z scores for all
7520 the specified variables. The Z scores are saved to new variables.
7521 Variable names are generated by trying first the original variable name
7522 with Z prepended and truncated to a maximum of 8 characters, then the
7523 names ZSC000 through ZSC999, STDZ00 through STDZ09, ZZZZ00 through
7524 ZZZZ09, ZQZQ00 through ZQZQ09, in that sequence. In addition, Z score
7525 variable names can be specified explicitly on VARIABLES in the variable
7526 list by enclosing them in parentheses after each variable.
7528 The STATISTICS subcommand specifies the statistics to be displayed:
7532 All of the statistics below.
7536 Standard error of the mean.
7542 Kurtosis and standard error of the kurtosis.
7544 Skewness and standard error of the skewness.
7554 Mean, standard deviation of the mean, minimum, maximum.
7556 Standard error of the kurtosis.
7558 Standard error of the skewness.
7561 The SORT subcommand specifies how the statistics should be sorted. Most
7562 of the possible values should be self-explanatory. NAME causes the
7563 statistics to be sorted by name. By default, the statistics are listed
7564 in the order that they are specified on the VARIABLES subcommand. The A
7565 and D settings request an ascending or descending sort order,
7568 @node FREQUENCIES, CROSSTABS, DESCRIPTIVES, Statistics
7569 @section FREQUENCIES
7575 /FORMAT=@{TABLE,NOTABLE,LIMIT(limit)@}
7576 @{STANDARD,CONDENSE,ONEPAGE[(onepage_limit)]@}
7578 @{AVALUE,DVALUE,AFREQ,DFREQ@}
7581 /MISSING=@{EXCLUDE,INCLUDE@}
7582 /STATISTICS=@{DEFAULT,MEAN,SEMEAN,MEDIAN,MODE,STDDEV,VARIANCE,
7583 KURTOSIS,SKEWNESS,RANGE,MINIMUM,MAXIMUM,SUM,
7584 SESKEWNESS,SEKURTOSIS,ALL,NONE@}
7586 /PERCENTILES=percent@dots{}
7588 (These options are not currently implemented.)
7595 /VARIABLES=var_list (low,high)@dots{}
7598 The @cmd{FREQUENCIES} procedure outputs frequency tables for specified
7600 @cmd{FREQUENCIES} can also calculate and display descriptive statistics
7601 (including median and mode) and percentiles.
7603 In the future, @cmd{FREQUENCIES} will also support graphical output in the
7604 form of bar charts and histograms. In addition, it will be able to
7605 support percentiles for grouped data.
7607 The VARIABLES subcommand is the only required subcommand. Specify the
7608 variables to be analyzed. In most cases, this is all that is required.
7609 This is known as @dfn{general mode}.
7611 Occasionally, one may want to invoke a special mode called @dfn{integer
7612 mode}. Normally, in general mode, PSPP will automatically determine
7613 what values occur in the data. In integer mode, the user specifies the
7614 range of values that the data assumes. To invoke this mode, specify a
7615 range of data values in parentheses, separated by a comma. Data values
7616 inside the range are truncated to the nearest integer, then assigned to
7617 that value. If values occur outside this range, they are discarded.
7619 The FORMAT subcommand controls the output format. It has several
7624 TABLE, the default, causes a frequency table to be output for every
7625 variable specified. NOTABLE prevents them from being output. LIMIT
7626 with a numeric argument causes them to be output except when there are
7627 more than the specified number of values in the table.
7630 STANDARD frequency tables contain more complete information, but also to
7631 take up more space on the printed page. CONDENSE frequency tables are
7632 less informative but take up less space. ONEPAGE with a numeric
7633 argument will output standard frequency tables if there are the
7634 specified number of values or less, condensed tables otherwise. ONEPAGE
7635 without an argument defaults to a threshold of 50 values.
7638 LABELS causes value labels to be displayed in STANDARD frequency
7639 tables. NOLABLES prevents this.
7642 Normally frequency tables are sorted in ascending order by value. This
7643 is AVALUE. DVALUE tables are sorted in descending order by value.
7644 AFREQ and DFREQ tables are sorted in ascending and descending order,
7645 respectively, by frequency count.
7648 SINGLE spaced frequency tables are closely spaced. DOUBLE spaced
7649 frequency tables have wider spacing.
7652 OLDPAGE and NEWPAGE are not currently used.
7655 The MISSING subcommand controls the handling of user-missing values.
7656 When EXCLUDE, the default, is set, user-missing values are not included
7657 in frequency tables or statistics. When INCLUDE is set, user-missing
7658 are included. System-missing values are never included in statistics,
7659 but are listed in frequency tables.
7661 The available STATISTICS are the same as available in @cmd{DESCRIPTIVES}
7662 (@pxref{DESCRIPTIVES}), with the addition of MEDIAN, the data's median
7663 value, and MODE, the mode. (If there are multiple modes, the smallest
7664 value is reported.) By default, the mean, standard deviation of the
7665 mean, minimum, and maximum are reported for each variable.
7667 PERCENTILES causes the specified percentiles to be reported.
7668 The percentiles should be presented at a list of numbers between 0
7670 The NTILES subcommand causes the percentiles to be reported at the
7671 boundaries of the data set divided into the specified number of ranges.
7672 For instance, @code{/NTILES=4} would cause quartiles to be reported.
7675 @node CROSSTABS, T-TEST, FREQUENCIES, Statistics
7681 /TABLES=var_list BY var_list [BY var_list]@dots{}
7682 /MISSING=@{TABLE,INCLUDE,REPORT@}
7683 /WRITE=@{NONE,CELLS,ALL@}
7684 /FORMAT=@{TABLES,NOTABLES@}
7685 @{LABELS,NOLABELS,NOVALLABS@}
7690 /CELLS=@{COUNT,ROW,COLUMN,TOTAL,EXPECTED,RESIDUAL,SRESIDUAL,
7691 ASRESIDUAL,ALL,NONE@}
7692 /STATISTICS=@{CHISQ,PHI,CC,LAMBDA,UC,BTAU,CTAU,RISK,GAMMA,D,
7693 KAPPA,ETA,CORR,ALL,NONE@}
7696 /VARIABLES=var_list (low,high)@dots{}
7699 The @cmd{CROSSTABS} procedure displays crosstabulation
7700 tables requested by the user. It can calculate several statistics for
7701 each cell in the crosstabulation tables. In addition, a number of
7702 statistics can be calculated for each table itself.
7704 The TABLES subcommand is used to specify the tables to be reported. Any
7705 number of dimensions is permitted, and any number of variables per
7706 dimension is allowed. The TABLES subcommand may be repeated as many
7707 times as needed. This is the only required subcommand in @dfn{general
7710 Occasionally, one may want to invoke a special mode called @dfn{integer
7711 mode}. Normally, in general mode, PSPP automatically determines
7712 what values occur in the data. In integer mode, the user specifies the
7713 range of values that the data assumes. To invoke this mode, specify the
7714 VARIABLES subcommand, giving a range of data values in parentheses for
7715 each variable to be used on the TABLES subcommand. Data values inside
7716 the range are truncated to the nearest integer, then assigned to that
7717 value. If values occur outside this range, they are discarded. When it
7718 is present, the VARIABLES subcommand must precede the TABLES
7721 In general mode, numeric and string variables may be specified on
7722 TABLES. Although long string variables are allowed, only their
7723 initial short-string parts are used. In integer mode, only numeric
7724 variables are allowed.
7726 The MISSING subcommand determines the handling of user-missing values.
7727 When set to TABLE, the default, missing values are dropped on a table by
7728 table basis. When set to INCLUDE, user-missing values are included in
7729 tables and statistics. When set to REPORT, which is allowed only in
7730 integer mode, user-missing values are included in tables but marked with
7731 an @samp{M} (for ``missing'') and excluded from statistical
7734 Currently the WRITE subcommand is ignored.
7736 The FORMAT subcommand controls the characteristics of the
7737 crosstabulation tables to be displayed. It has a number of possible
7742 TABLES, the default, causes crosstabulation tables to be output.
7743 NOTABLES suppresses them.
7746 LABELS, the default, allows variable labels and value labels to appear
7747 in the output. NOLABELS suppresses them. NOVALLABS displays variable
7748 labels but suppresses value labels.
7751 PIVOT, the default, causes each TABLES subcommand to be displayed in a
7752 pivot table format. NOPIVOT causes the old-style crosstabulation format
7756 AVALUE, the default, causes values to be sorted in ascending order.
7757 DVALUE asserts a descending sort order.
7760 INDEX/NOINDEX is currently ignored.
7763 BOX/NOBOX is currently ignored.
7766 The CELLS subcommand controls the contents of each cell in the displayed
7767 crosstabulation table. The possible settings are:
7783 Standardized residual.
7785 Adjusted standardized residual.
7789 Suppress cells entirely.
7792 @samp{/CELLS} without any settings specified requests COUNT, ROW,
7793 COLUMN, and TOTAL. If CELLS is not specified at all then only COUNT
7796 The STATISTICS subcommand selects statistics for computation:
7800 Pearson chi-square, likelihood ratio, Fisher's exact test, continuity
7801 correction, linear-by-linear association.
7805 Contingency coefficient.
7809 Uncertainty coefficient.
7825 Spearman correlation, Pearson's r.
7832 Selected statistics are only calculated when appropriate for the
7833 statistic. Certain statistics require tables of a particular size, and
7834 some statistics are calculated only in integer mode.
7836 @samp{/STATISTICS} without any settings selects CHISQ. If the
7837 STATISTICS subcommand is not given, no statistics are calculated.
7839 @strong{Please note:} Currently the implementation of CROSSTABS has the
7844 Pearson's R (but not Spearman) is off a little.
7846 T values for Spearman's R and Pearson's R are wrong.
7848 Significance of symmetric and directional measures is not calculated.
7850 Asymmetric ASEs and T values for lambda are wrong.
7852 ASE of Goodman and Kruskal's tau is not calculated.
7854 ASE of symmetric somers' d is wrong.
7856 Approximate T of uncertainty coefficient is wrong.
7859 Fixes for any of these deficiencies would be welcomed.
7861 @node T-TEST, , CROSSTABS, Statistics
7862 @comment node-name, next, previous, up
7868 /MISSING=@{ANALYSIS,LISTWISE@} @{EXCLUDE,INCLUDE@}
7869 /CRITERIA=CIN(confidence)
7877 (Independent Samples mode.)
7878 GROUPS=var(value1 [, value2])
7882 (Paired Samples mode.)
7883 PAIRS=var_list [WITH var_list [(PAIRED)] ]
7888 The @cmd{T-TEST} procedure outputs tables used in testing hypotheses about
7890 It operates in one of three modes:
7892 @item One Sample mode.
7893 @item Independent Groups mode.
7898 Each of these modes are described in more detail below.
7899 There are two optional subcommands which are common to all modes.
7901 The @cmd{/CRITERIA} subcommand tells PSPP the confidence interval used
7902 in the tests. The default value is 0.95.
7905 The @cmd{MISSING} subcommand determines the handling of missing
7907 If INCLUDE is set, then user-missing values are included in the
7908 calculations, but system-missing values are not.
7909 If EXCLUDE is set, which is the default, user-missing
7910 values are excluded as well as system-missing values.
7911 This is the default.
7913 If LISTWISE is set, then the entire case is excluded from analysis
7914 whenever any variable specified in the @cmd{/VARIABLES}, @cmd{/PAIRS} or
7915 @cmd{/GROUPS} subcommands contains a missing value.
7916 If ANALYSIS is set, then missing values are excluded only in the analysis for
7917 which they would be needed. This is the default.
7921 * One Sample Mode:: Testing against a hypothesised mean
7922 * Independent Samples Mode:: Testing two independent groups for equal mean
7923 * Paired Samples Mode:: Testing two interdependent groups for equal mean
7926 @node One Sample Mode, Independent Samples Mode, T-TEST, T-TEST
7927 @subsection One Sample Mode
7929 The @cmd{TESTVAL} subcommand invokes the One Sample mode.
7930 This mode is used to test a population mean against a hypothesised
7932 The value given to the @cmd{TESTVAL} subcommand is the value against
7933 which you wish to test.
7934 In this mode, you must also use the @cmd{/VARIABLES} subcommand to
7935 tell PSPP which variables you wish to test.
7937 @node Independent Samples Mode, Paired Samples Mode, One Sample Mode, T-TEST
7938 @comment node-name, next, previous, up
7939 @subsection Independent Samples Mode
7941 The @cmd{GROUPS} subcommand invokes Independent Samples mode or
7943 This mode is used to test whether two groups of values have the
7944 same population mean.
7945 In this mode, you must also use the @cmd{/VARIABLES} subcommand to
7946 tell PSPP the dependent variables you wish to test.
7948 The variable given in the @cmd{GROUPS} subcommand is the independent
7949 variable which determines to which group the samples belong.
7950 The values in parentheses are the specific values of the independent
7951 variable for each group.
7952 If the parentheses are omitted and no values are given, the default values
7953 of 1.0 and 2.0 are assumed.
7955 If the independent variable is numeric,
7956 it is acceptable to specify only one value inside the parentheses.
7957 If you do this, cases where the independent variable is
7958 less than or equal to this value belong to the first group, and cases
7959 greater than this value belong to the second group.
7960 When using this form of the @cmd{GROUPS} subcommand, missing values in
7961 the independent variable are excluded on a listwise basis, regardless
7962 of whether @cmd{/MISSING=LISTWISE} was specified.
7965 @node Paired Samples Mode, , Independent Samples Mode, T-TEST
7966 @comment node-name, next, previous, up
7967 @subsection Paired Samples Mode
7969 The @cmd{PAIRS} subcommand introduces Paired Samples mode.
7970 Use this mode when repeated measures have been taken from the same
7972 If the the @code{WITH} keyword is omitted, then tables for all
7973 combinations of variables given in the @cmd{PAIRS} subcommand are
7975 If the @code{WITH} keyword is given, and the @code{(PAIRED)} keyword
7976 is also given, then the number of variables preceding @code{WITH}
7977 must be the same as the number following it.
7978 In this case, tables for each respective pair of variables are
7980 In the event that the @code{WITH} keyword is given, but the
7981 @code{(PAIRED)} keyword is omitted, then tables for each combination
7982 of variable preceding @code{WITH} against variable following
7983 @code{WITH} are generated.
7986 @node Utilities, Not Implemented, Statistics, Top
7989 Commands that don't fit any other category are placed here.
7991 Most of these commands are not affected by commands like @cmd{IF} and
7993 they take effect only once, unconditionally, at the time that they are
7994 encountered in the input.
7997 * COMMENT:: Document your syntax file.
7998 * DOCUMENT:: Document the active file.
7999 * DISPLAY DOCUMENTS:: Display active file documents.
8000 * DISPLAY FILE LABEL:: Display the active file label.
8001 * DROP DOCUMENTS:: Remove documents from the active file.
8002 * ERASE:: Erase a file.
8003 * EXECUTE:: Execute pending transformations.
8004 * FILE LABEL:: Set the active file's label.
8005 * FINISH:: Terminate the PSPP session.
8006 * HOST:: Temporarily return to the operating system.
8007 * INCLUDE:: Include a file within the current one.
8008 * QUIT:: Terminate the PSPP session.
8009 * SET:: Adjust PSPP runtime parameters.
8010 * SHOW:: Display runtime parameters.
8011 * SUBTITLE:: Provide a document subtitle.
8012 * TITLE:: Provide a document title.
8015 @node COMMENT, DOCUMENT, Utilities, Utilities
8021 Two possibles syntaxes:
8022 COMMENT comment text @dots{} .
8023 *comment text @dots{} .
8026 @cmd{COMMENT} is ignored. It is used to provide information to
8027 the author and other readers of the PSPP syntax file.
8029 @cmd{COMMENT} can extend over any number of lines. Don't forget to
8030 terminate it with a dot or a blank line.
8032 @node DOCUMENT, DISPLAY DOCUMENTS, COMMENT, Utilities
8037 DOCUMENT documentary_text.
8040 @cmd{DOCUMENT} adds one or more lines of descriptive commentary to the
8041 active file. Documents added in this way are saved to system files.
8042 They can be viewed using @cmd{SYSFILE INFO} or @cmd{DISPLAY
8043 DOCUMENTS}. They can be removed from the active file with @cmd{DROP
8046 Specify the documentary text following the DOCUMENT keyword. You can
8047 extend the documentary text over as many lines as necessary. Lines are
8048 truncated at 80 characters width. Don't forget to terminate
8049 the command with a dot or a blank line.
8051 @node DISPLAY DOCUMENTS, DISPLAY FILE LABEL, DOCUMENT, Utilities
8052 @section DISPLAY DOCUMENTS
8053 @vindex DISPLAY DOCUMENTS
8059 @cmd{DISPLAY DOCUMENTS} displays the documents in the active file. Each
8060 document is preceded by a line giving the time and date that it was
8061 added. @xref{DOCUMENT}.
8063 @node DISPLAY FILE LABEL, DROP DOCUMENTS, DISPLAY DOCUMENTS, Utilities
8064 @section DISPLAY FILE LABEL
8065 @vindex DISPLAY FILE LABEL
8071 @cmd{DISPLAY FILE LABEL} displays the file label contained in the
8073 if any. @xref{FILE LABEL}.
8075 @node DROP DOCUMENTS, ERASE, DISPLAY FILE LABEL, Utilities
8076 @section DROP DOCUMENTS
8077 @vindex DROP DOCUMENTS
8083 @cmd{DROP DOCUMENTS} removes all documents from the active file.
8084 New documents can be added with @cmd{DOCUMENT} (@pxref{DOCUMENT}).
8086 @cmd{DROP DOCUMENTS} changes only the active file. It does not modify any
8087 system files stored on disk.
8090 @node ERASE, EXECUTE, DROP DOCUMENTS, Utilities
8091 @comment node-name, next, previous, up
8096 ERASE FILE file_name.
8099 @cmd{ERASE FILE} deletes a file from the local filesystem.
8100 file_name must be quoted.
8101 This command cannot be used if the SAFER setting is active.
8104 @node EXECUTE, FILE LABEL, ERASE, Utilities
8112 @cmd{EXECUTE} causes the active file to be read and all pending
8113 transformations to be executed.
8115 @node FILE LABEL, FINISH, EXECUTE, Utilities
8120 FILE LABEL file_label.
8123 @cmd{FILE LABEL} provides a title for the active file. This
8124 title will be saved into system files and portable files that are
8125 created during this PSPP run.
8127 file_label need not be quoted. If quotes are
8128 included, they become part of the file label.
8130 @node FINISH, HOST, FILE LABEL, Utilities
8138 @cmd{FINISH} terminates the current PSPP session and returns
8139 control to the operating system.
8141 This command is not valid in interactive mode.
8143 @node HOST, INCLUDE, FINISH, Utilities
8144 @comment node-name, next, previous, up
8152 @cmd{HOST} suspends the current PSPP session and temporarily returns control
8153 to the operating system.
8154 This command cannot be used if the SAFER setting is active.
8157 @node INCLUDE, QUIT, HOST, Utilities
8163 Two possible syntaxes:
8168 @cmd{INCLUDE} causes the PSPP command processor to read an
8169 additional command file as if it were included bodily in the current
8172 Include files may be nested to any depth, up to the limit of available
8175 @node QUIT, SET, INCLUDE, Utilities
8180 Two possible syntaxes:
8185 @cmd{QUIT} terminates the current PSPP session and returns control
8186 to the operating system.
8188 This command is not valid within a command file.
8190 @node SET, SHOW, QUIT, Utilities
8198 /BLANKS=@{SYSMIS,'.',number@}
8199 /DECIMAL=@{DOT,COMMA@}
8207 /CPROMPT='cprompt_string'
8208 /DPROMPT='dprompt_string'
8209 /ERRORBREAK=@{OFF,ON@}
8211 /MXWARNS=max_warnings
8213 /VIEWLENGTH=@{MINIMUM,MEDIAN,MAXIMUM,n_lines@}
8214 /VIEWWIDTH=n_characters
8218 /MITERATE=max_iterations
8222 /SEED=@{RANDOM,seed_value@}
8223 /UNDEFINED=@{WARN,NOWARN@}
8226 /CC@{A,B,C,D,E@}=@{'npre,pre,suf,nsuf','npre.pre.suf.nsuf'@}
8227 /DECIMAL=@{DOT,COMMA@}
8232 /ERRORS=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}
8234 /MESSAGES=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}
8235 /PRINTBACK=@{ON,OFF@}
8236 /RESULTS=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}
8243 (output driver options)
8244 /HEADERS=@{NO,YES,BLANK@}
8245 /LENGTH=@{NONE,length_in_lines@}
8248 /PAGER=@{OFF,"pager_name"@}
8249 /WIDTH=@{NARROW,WIDTH,n_characters@}
8252 /JOURNAL=@{ON,OFF@} [filename]
8253 /LOG=@{ON,OFF@} [filename]
8256 /COMPRESSION=@{ON,OFF@}
8257 /SCOMPRESSION=@{ON,OFF@}
8262 (obsolete settings accepted for compatibility, but ignored)
8263 /AUTOMENU=@{ON,OFF@}
8266 /BOXSTRING=@{'xxx','xxxxxxxxxxx'@}
8267 /CASE=@{UPPER,UPLOW@}
8272 /HELPWINDOWS=@{ON,OFF@}
8275 /LOWRES=@{AUTO,ON,OFF@}
8277 /MENUS=@{STANDARD,EXTENDED@}
8278 /MXMEMORY=max_memory
8279 /PTRANSLATE=@{ON,OFF@}
8281 /RUNREVIEW=@{AUTO,MANUAL@}
8283 /TB1=@{'xxx','xxxxxxxxxxx'@}
8285 /WORKDEV=drive_letter
8286 /WORKSPACE=workspace_size
8290 @cmd{SET} allows the user to adjust several parameters relating to
8291 PSPP's execution. Since there are many subcommands to this command, its
8292 subcommands will be examined in groups.
8294 On subcommands that take boolean values, ON and YES are synonym, and
8295 as are OFF and NO, when used as subcommand values.
8297 The data input subcommands affect the way that data is read from data
8298 files. The data input subcommands are
8302 This is the value assigned to an item data item that is empty or
8303 contains only whitespace. An argument of SYSMIS or '.' will cause the
8304 system-missing value to be assigned to null items. This is the
8305 default. Any real value may be assigned.
8308 The default DOT setting causes the decimal point character to be
8309 @samp{.}. A setting of COMMA causes the decimal point character to be
8313 Allows the default numeric input/output format to be specified. The
8314 default is F8.2. @xref{Input/Output Formats}.
8317 Program input subcommands affect the way that programs are parsed when
8318 they are typed interactively or run from a script. They are
8322 This is a single character indicating the end of a command. The default
8323 is @samp{.}. Don't change this.
8326 Whether a blank line is interpreted as ending the current command. The
8330 Interaction subcommands affect the way that PSPP interacts with an
8331 online user. The interaction subcommands are
8335 The command continuation prompt. The default is @samp{ > }.
8338 Prompt used when expecting data input within @cmd{BEGIN DATA} (@pxref{BEGIN
8339 DATA}). The default is @samp{data> }.
8342 Whether an error causes PSPP to stop processing the current command
8343 file after finishing the current command. The default is OFF.
8346 The maximum number of errors before PSPP halts processing of the current
8347 command file. The default is 50.
8350 The maximum number of warnings + errors before PSPP halts processing the
8351 current command file. The default is 100.
8354 The command prompt. The default is @samp{PSPP> }.
8357 The length of the screen in lines. MINIMUM means 25 lines, MEDIAN and
8358 MAXIMUM mean 43 lines. Otherwise specify the number of lines. Normally
8359 PSPP should auto-detect your screen size so this shouldn't have to be
8363 The width of the screen in characters. Normally 80 or 132.
8366 Program execution subcommands control the way that PSPP commands
8367 execute. The program execution subcommands are
8377 The maximum number of iterations for an uncontrolled loop (@pxref{LOOP}).
8380 The initial pseudo-random number seed. Set to a real number or to
8381 RANDOM, which will obtain an initial seed from the current time of day.
8387 Data output subcommands affect the format of output data. These
8396 Set up custom currency formats. The argument is a string which must
8397 contain exactly three commas or exactly three periods. If commas, then
8398 the grouping character for the currency format is @samp{,}, and the
8399 decimal point character is @samp{.}; if periods, then the situation is
8402 The commas or periods divide the string into four fields, which are, in
8403 order, the negative prefix, prefix, suffix, and negative suffix. When a
8404 value is formatted using the custom currency format, the prefix precedes
8405 the value formatted and the suffix follows it. In addition, if the
8406 value is negative, the negative prefix precedes the prefix and the
8407 negative suffix follows the suffix.
8410 The default DOT setting causes the decimal point character to be
8411 @samp{.}. A setting of COMMA causes the decimal point character to be
8415 Allows the default numeric input/output format to be specified. The
8416 default is F8.2. @xref{Input/Output Formats}.
8419 Output routing subcommands affect where the output of transformations
8420 and procedures is sent. These subcommands are
8425 If turned on, commands are written to the listing file as they are read
8426 from command files. The default is OFF.
8436 Output activation subcommands affect whether output devices of
8437 particular types are enabled. These subcommands are
8441 Enable or disable listing devices.
8444 Enable or disable printer devices.
8447 Enable or disable screen devices.
8450 Output driver option subcommands affect output drivers' settings. These
8463 Logging subcommands affect logging of commands executed to external
8464 files. These subcommands are
8472 System file subcommands affect the default format of system files
8473 produced by PSPP. These subcommands are
8480 Whether system files created by @cmd{SAVE} or @cmd{XSAVE} are
8481 compressed by default. The default is ON.
8484 Security subcommands affect the operations that commands are allowed to
8485 perform. The security subcommands are
8489 When set, this setting cannot ever be reset, for obvious security
8490 reasons. Setting this option disables the following operations:
8498 Pipe filenames (filenames beginning or ending with @samp{|}).
8501 Be aware that this setting does not guarantee safety (commands can still
8502 overwrite files, for instance) but it is an improvement.
8505 @node SHOW, SUBTITLE, SET, Utilities
8506 @comment node-name, next, previous, up
8516 @cmd{SHOW} can be used to display the current state of PSPP's
8517 execution parameters. All of the parameters which can be changed
8518 using @code{SET} @xref{SET}, can be examined using @cmd{SHOW}, by
8519 using a subcommand with the same name.
8520 In addition, @code{SHOW} supports the following subcommands:
8524 Show details of the lack of warranty for PSPP.
8526 Display the terms of PSPP's copyright licence @ref{License}.
8531 @node SUBTITLE, TITLE, SHOW, Utilities
8536 SUBTITLE 'subtitle_string'.
8538 SUBTITLE subtitle_string.
8541 @cmd{SUBTITLE} provides a subtitle to a particular PSPP
8542 run. This subtitle appears at the top of each output page below the
8543 title, if headers are enabled on the output device.
8545 Specify a subtitle as a string in quotes. The alternate syntax that did
8546 not require quotes is now obsolete. If it is used then the subtitle is
8547 converted to all uppercase.
8549 @node TITLE, , SUBTITLE, Utilities
8554 TITLE 'title_string'.
8559 @cmd{TITLE} provides a title to a particular PSPP run.
8560 This title appears at the top of each output page, if headers are enabled
8561 on the output device.
8563 Specify a title as a string in quotes. The alternate syntax that did
8564 not require quotes is now obsolete. If it is used then the title is
8565 converted to all uppercase.
8567 @node Not Implemented, Data File Format, Utilities, Top
8568 @chapter Not Implemented
8570 This chapter lists parts of the PSPP language that are not yet
8573 The following transformations and utilities are not yet implemented, but
8574 they will be supported in a later release.
8607 The following transformations and utilities are not implemented. There
8608 are no plans to support them in future releases. Contributions to
8609 implement them will still be accepted.
8631 NUMBERED and UNNUMBERED
8644 @node Data File Format, Portable File Format, Not Implemented, Top
8645 @chapter Data File Format
8647 PSPP necessarily uses the same format for system files as do the
8648 products with which it is compatible. This chapter is a description of
8651 There are three data types used in system files: 32-bit integers, 64-bit
8652 floating points, and 1-byte characters. In this document these will
8653 simply be referred to as @code{int32}, @code{flt64}, and @code{char},
8654 the names that are used in the PSPP source code. Every field of type
8655 @code{int32} or @code{flt64} is aligned on a 32-bit boundary.
8657 The endianness of data in PSPP system files is not specified. System
8658 files output on a computer of a particular endianness will have the
8659 endianness of that computer. However, PSPP can read files of either
8660 endianness, regardless of its host computer's endianness. PSPP
8661 translates endianness for both integer and floating point numbers.
8663 Floating point formats are also not specified. PSPP does not
8664 translate between floating point formats. This is unlikely to be a
8665 problem as all modern computer architectures use IEEE 754 format for
8666 floating point representation.
8668 The PSPP system-missing value is represented by the largest possible
8669 negative number in the floating point format; in C, this is most likely
8670 @code{-DBL_MAX}. There are two other important values used in missing
8671 values: @code{HIGHEST} and @code{LOWEST}. These are represented by the
8672 largest possible positive number (probably @code{DBL_MAX}) and the
8673 second-largest negative number. The latter must be determined in a
8674 system-dependent manner; in IEEE 754 format it is represented by value
8675 @code{0xffeffffffffffffe}.
8677 System files are divided into records. Each record begins with an
8678 @code{int32} giving a numeric record type. Individual record types are
8682 * File Header Record::
8684 * Value Label Record::
8685 * Value Label Variable Record::
8687 * Machine int32 Info Record::
8688 * Machine flt64 Info Record::
8689 * Miscellaneous Informational Records::
8690 * Dictionary Termination Record::
8694 @node File Header Record, Variable Record, Data File Format, Data File Format
8695 @section File Header Record
8697 The file header is always the first record in the file.
8700 struct sysfile_header
8710 char creation_date[9];
8711 char creation_time[8];
8712 char file_label[64];
8718 @item char rec_type[4];
8719 Record type code. Always set to @samp{$FL2}. This is the only record
8720 for which the record type is not of type @code{int32}.
8722 @item char prod_name[60];
8723 Product identification string. This always begins with the characters
8724 @samp{@@(#) SPSS DATA FILE}. PSPP uses the remaining characters to
8725 give its version and the operating system name; for example, @samp{GNU
8726 pspp 0.1.4 - sparc-sun-solaris2.5.2}. The string is truncated if it
8727 would be longer than 60 characters; otherwise it is padded on the right
8730 @item int32 layout_code;
8731 Always set to 2. PSPP reads this value to determine the
8734 @item int32 case_size;
8735 Number of data elements per case. This is the number of variables,
8736 except that long string variables add extra data elements (one for every
8737 8 characters after the first 8).
8739 @item int32 compressed;
8740 Set to 1 if the data in the file is compressed, 0 otherwise.
8742 @item int32 weight_index;
8743 If one of the variables in the data set is used as a weighting variable,
8744 set to the index of that variable. Otherwise, set to 0.
8747 Set to the number of cases in the file if it is known, or -1 otherwise.
8749 In the general case it is not possible to determine the number of cases
8750 that will be output to a system file at the time that the header is
8751 written. The way that this is dealt with is by writing the entire
8752 system file, including the header, then seeking back to the beginning of
8753 the file and writing just the @code{ncases} field. For `files' in which
8754 this is not valid, the seek operation fails. In this case,
8755 @code{ncases} remains -1.
8758 Compression bias. Always set to 100. The significance of this value is
8759 that only numbers between @code{(1 - bias)} and @code{(251 - bias)} can
8762 @item char creation_date[9];
8763 Set to the date of creation of the system file, in @samp{dd mmm yy}
8764 format, with the month as standard English abbreviations, using an
8765 initial capital letter and following with lowercase. If the date is not
8766 available then this field is arbitrarily set to @samp{01 Jan 70}.
8768 @item char creation_time[8];
8769 Set to the time of creation of the system file, in @samp{hh:mm:ss}
8770 format and using 24-hour time. If the time is not available then this
8771 field is arbitrarily set to @samp{00:00:00}.
8773 @item char file_label[64];
8774 Set the the file label declared by the user, if any. Padded on the
8777 @item char padding[3];
8778 Ignored padding bytes to make the structure a multiple of 32 bits in
8779 length. Set to zeros.
8782 @node Variable Record, Value Label Record, File Header Record, Data File Format
8783 @section Variable Record
8785 Immediately following the header must come the variable records. There
8786 must be one variable record for every variable and every 8 characters in
8787 a long string beyond the first 8; i.e., there must be exactly as many
8788 variable records as the value specified for @code{case_size} in the file
8792 struct sysfile_variable
8796 int32 has_var_label;
8797 int32 n_missing_values;
8802 /* The following two fields are present
8803 only if has_var_label is 1. */
8805 char label[/* variable length */];
8807 /* The following field is present only
8808 if n_missing_values is not 0. */
8809 flt64 missing_values[/* variable length*/];
8814 @item int32 rec_type;
8815 Record type code. Always set to 2.
8818 Variable type code. Set to 0 for a numeric variable. For a short
8819 string variable or the first part of a long string variable, this is set
8820 to the width of the string. For the second and subsequent parts of a
8821 long string variable, set to -1, and the remaining fields in the
8822 structure are ignored.
8824 @item int32 has_var_label;
8825 If this variable has a variable label, set to 1; otherwise, set to 0.
8827 @item int32 n_missing_values;
8828 If the variable has no missing values, set to 0. If the variable has
8829 one, two, or three discrete missing values, set to 1, 2, or 3,
8830 respectively. If the variable has a range for missing variables, set to
8831 -2; if the variable has a range for missing variables plus a single
8832 discrete value, set to -3.
8835 Print format for this variable. See below.
8838 Write format for this variable. See below.
8841 Variable name. The variable name must begin with a capital letter or
8842 the at-sign (@samp{@@}). Subsequent characters may also be octothorpes
8843 (@samp{#}), dollar signs (@samp{$}), underscores (@samp{_}), or full
8844 stops (@samp{.}). The variable name is padded on the right with spaces.
8846 @item int32 label_len;
8847 This field is present only if @code{has_var_label} is set to 1. It is
8848 set to the length, in characters, of the variable label, which must be a
8849 number between 0 and 120.
8851 @item char label[/* variable length */];
8852 This field is present only if @code{has_var_label} is set to 1. It has
8853 length @code{label_len}, rounded up to the nearest multiple of 32 bits.
8854 The first @code{label_len} characters are the variable's variable label.
8856 @item flt64 missing_values[/* variable length */];
8857 This field is present only if @code{n_missing_values} is not 0. It has
8858 the same number of elements as the absolute value of
8859 @code{n_missing_values}. For discrete missing values, each element
8860 represents one missing value. When a range is present, the first
8861 element denotes the minimum value in the range, and the second element
8862 denotes the maximum value in the range. When a range plus a value are
8863 present, the third element denotes the additional discrete missing
8864 value. HIGHEST and LOWEST are indicated as described in the chapter
8868 The @code{print} and @code{write} members of sysfile_variable are output
8869 formats coded into @code{int32} types. The LSB (least-significant byte)
8870 of the @code{int32} represents the number of decimal places, and the
8871 next two bytes in order of increasing significance represent field width
8872 and format type, respectively. The MSB (most-significant byte) is not
8873 used and should be set to zero.
8875 Format types are defined as follows:
8959 @node Value Label Record, Value Label Variable Record, Variable Record, Data File Format
8960 @section Value Label Record
8962 Value label records must follow the variable records and must precede
8963 the header termination record. Other than this, they may appear
8964 anywhere in the system file. Every value label record must be
8965 immediately followed by a label variable record, described below.
8967 Value label records begin with @code{rec_type}, an @code{int32} value
8968 set to the record type of 3. This is followed by @code{count}, an
8969 @code{int32} value set to the number of value labels present in this
8972 These two fields are followed by a series of @code{count} tuples. Each
8973 tuple is divided into two fields, the value and the label. The first of
8974 these, the value, is composed of a 64-bit value, which is either a
8975 @code{flt64} value or up to 8 characters (padded on the right to 8
8976 bytes) denoting a short string value. Whether the value is a
8977 @code{flt64} or a character string is not defined inside the value label
8980 The second field in the tuple, the label, has variable length. The
8981 first @code{char} is a count of the number of characters in the value
8982 label. The remainder of the field is the label itself. The field is
8983 padded on the right to a multiple of 64 bits in length.
8985 @node Value Label Variable Record, Document Record, Value Label Record, Data File Format
8986 @section Value Label Variable Record
8988 Every value label variable record must be immediately preceded by a
8989 value label record, described above.
8992 struct sysfile_value_label_variable
8996 int32 vars[/* variable length */];
9001 @item int32 rec_type;
9002 Record type. Always set to 4.
9005 Number of variables that the associated value labels from the value
9006 label record are to be applied.
9008 @item int32 vars[/* variable length];
9009 A list of variables to which to apply the value labels. There are
9010 @code{count} elements.
9013 @node Document Record, Machine int32 Info Record, Value Label Variable Record, Data File Format
9014 @section Document Record
9016 There must be no more than one document record per system file.
9017 Document records must follow the variable records and precede the
9018 dictionary termination record.
9021 struct sysfile_document
9025 char lines[/* variable length */][80];
9030 @item int32 rec_type;
9031 Record type. Always set to 6.
9033 @item int32 n_lines;
9034 Number of lines of documents present.
9036 @item char lines[/* variable length */][80];
9037 Document lines. The number of elements is defined by @code{n_lines}.
9038 Lines shorter than 80 characters are padded on the right with spaces.
9041 @node Machine int32 Info Record, Machine flt64 Info Record, Document Record, Data File Format
9042 @section Machine @code{int32} Info Record
9044 There must be no more than one machine @code{int32} info record per
9045 system file. Machine @code{int32} info records must follow the variable
9046 records and precede the dictionary termination record.
9049 struct sysfile_machine_int32_info
9058 int32 version_major;
9059 int32 version_minor;
9060 int32 version_revision;
9062 int32 floating_point_rep;
9063 int32 compression_code;
9065 int32 character_code;
9070 @item int32 rec_type;
9071 Record type. Always set to 7.
9073 @item int32 subtype;
9074 Record subtype. Always set to 3.
9077 Size of each piece of data in the data part, in bytes. Always set to 4.
9080 Number of pieces of data in the data part. Always set to 8.
9082 @item int32 version_major;
9083 PSPP major version number. In version @var{x}.@var{y}.@var{z}, this
9086 @item int32 version_minor;
9087 PSPP minor version number. In version @var{x}.@var{y}.@var{z}, this
9090 @item int32 version_revision;
9091 PSPP version revision number. In version @var{x}.@var{y}.@var{z},
9094 @item int32 machine_code;
9095 Machine code. PSPP always set this field to value to -1, but other
9098 @item int32 floating_point_rep;
9099 Floating point representation code. For IEEE 754 systems this is 1.
9100 IBM 370 sets this to 2, and DEC VAX E to 3.
9102 @item int32 compression_code;
9103 Compression code. Always set to 1.
9105 @item int32 endianness;
9106 Machine endianness. 1 indicates big-endian, 2 indicates little-endian.
9108 @item int32 character_code;
9109 Character code. 1 indicates EBCDIC, 2 indicates 7-bit ASCII, 3
9110 indicates 8-bit ASCII, 4 indicates DEC Kanji.
9113 @node Machine flt64 Info Record, Miscellaneous Informational Records, Machine int32 Info Record, Data File Format
9114 @section Machine @code{flt64} Info Record
9116 There must be no more than one machine @code{flt64} info record per
9117 system file. Machine @code{flt64} info records must follow the variable
9118 records and precede the dictionary termination record.
9121 struct sysfile_machine_flt64_info
9137 @item int32 rec_type;
9138 Record type. Always set to 7.
9140 @item int32 subtype;
9141 Record subtype. Always set to 4.
9144 Size of each piece of data in the data part, in bytes. Always set to 4.
9147 Number of pieces of data in the data part. Always set to 3.
9150 The system missing value.
9152 @item flt64 highest;
9153 The value used for HIGHEST in missing values.
9156 The value used for LOWEST in missing values.
9159 @node Miscellaneous Informational Records, Dictionary Termination Record, Machine flt64 Info Record, Data File Format
9160 @section Miscellaneous Informational Records
9162 Miscellaneous informational records must follow the variable records and
9163 precede the dictionary termination record.
9165 Miscellaneous informational records are ignored by PSPP when reading
9166 system files. They are not written by PSPP when writing system files.
9169 struct sysfile_misc_info
9178 char data[/* variable length */];
9183 @item int32 rec_type;
9184 Record type. Always set to 7.
9186 @item int32 subtype;
9187 Record subtype. May take any value. According to Aapi
9188 H@"am@"al@"ainen, value 5 indicates a set of grouped variables and 6
9189 indicates date info (probably related to USE).
9192 Size of each piece of data in the data part. Should have the value 4 or
9193 8, for @code{int32} and @code{flt64}, respectively.
9196 Number of pieces of data in the data part.
9198 @item char data[/* variable length */];
9199 Arbitrary data. There must be @code{size} times @code{count} bytes of
9203 @node Dictionary Termination Record, Data Record, Miscellaneous Informational Records, Data File Format
9204 @section Dictionary Termination Record
9206 The dictionary termination record must follow all other records, except
9207 for the actual cases, which it must precede. There must be exactly one
9208 dictionary termination record in every system file.
9211 struct sysfile_dict_term
9219 @item int32 rec_type;
9220 Record type. Always set to 999.
9223 Ignored padding. Should be set to 0.
9226 @node Data Record, , Dictionary Termination Record, Data File Format
9227 @section Data Record
9229 Data records must follow all other records in the data file. There must
9230 be at least one data record in every system file.
9232 The format of data records varies depending on whether the data is
9233 compressed. Regardless, the data is arranged in a series of 8-byte
9236 When data is not compressed, Every case is composed of @code{case_size}
9237 of these 8-byte elements, where @code{case_size} comes from the file
9238 header record (@pxref{File Header Record}). Each element corresponds to
9239 the variable declared in the respective variable record (@pxref{Variable
9240 Record}). Numeric values are given in @code{flt64} format; string
9241 values are literal characters string, padded on the right when
9244 Compressed data is arranged in the following manner: the first 8-byte
9245 element in the data section is divided into a series of 1-byte command
9246 codes. These codes have meanings as described below:
9250 Ignored. If the program writing the system file accumulates compressed
9251 data in blocks of fixed length, 0 bytes can be used to pad out extra
9252 bytes remaining at the end of a fixed-size block.
9255 These values indicate that the corresponding numeric variable has the
9256 value @code{(@var{code} - @var{bias})} for the case being read, where
9257 @var{code} is the value of the compression code and @var{bias} is the
9258 variable @code{compression_bias} from the file header. For example,
9259 code 105 with bias 100.0 (the normal value) indicates a numeric variable
9263 End of file. This code may or may not appear at the end of the data
9264 stream. PSPP always outputs this code but its use is not required.
9267 This value indicates that the numeric or string value is not
9268 compressible. The value is stored in the 8-byte element following the
9269 current block of command bytes. If this value appears twice in a block
9270 of command bytes, then it indicates the second element following the
9271 command bytes, and so on.
9274 Used to indicate a string value that is all spaces.
9277 Used to indicate the system-missing value.
9280 When the end of the first 8-byte element of command bytes is reached,
9281 any blocks of non-compressible values are skipped, and the next element
9282 of command bytes is read and interpreted, until the end of the file is
9285 @node Portable File Format, q2c Input Format, Data File Format, Top
9286 @chapter Portable File Format
9288 These days, most computers use the same internal data formats for
9289 integer and floating-point data, if one ignores little differences like
9290 big- versus little-endian byte ordering. However, occasionally it is
9291 necessary to exchange data between systems with incompatible data
9292 formats. This is what portable files are designed to do.
9294 @strong{Please note:} Although all of the following information is
9295 correct, as far as the author has been able to ascertain, it is gleaned
9296 from examination of ASCII-formatted portable files only, so some of it
9297 may be incorrect in the general case.
9300 * Portable File Characters::
9301 * Portable File Structure::
9302 * Portable File Header::
9303 * Version and Date Info Record::
9304 * Identification Records::
9305 * Variable Count Record::
9306 * Case Weight Variable Record::
9307 * Variable Records::
9308 * Value Label Records::
9309 * Portable File Data::
9312 @node Portable File Characters, Portable File Structure, Portable File Format, Portable File Format
9313 @section Portable File Characters
9315 Portable files are arranged as a series of lines of exactly 80
9316 characters each. Each line is terminated by a carriage-return,
9317 line-feed sequence ``new-lines''). New-lines are only used to avoid
9318 line length limits imposed by some OSes; they are not meaningful.
9320 The file must be terminated with a @samp{Z} character. In addition, if
9321 the final line in the file does not have exactly 80 characters, then it
9322 is padded on the right with @samp{Z} characters. (The file contents may
9323 be in any character set; the file contains a description of its own
9324 character set, as explained in the next section. Therefore, the
9325 @samp{Z} character is not necessarily an ASCII @samp{Z}.)
9327 For the rest of the description of the portable file format, new-lines
9328 and the trailing @samp{Z}s will be ignored, as if they did not exist,
9329 because they are not an important part of understanding the file
9332 @node Portable File Structure, Portable File Header, Portable File Characters, Portable File Format
9333 @section Portable File Structure
9335 Every portable file consists of the following records, in sequence:
9343 Version and date info.
9346 Product identification.
9349 Subproduct identification (optional).
9355 Case weight variable (optional).
9358 Variables. Each variable record may optionally be followed by a
9359 missing value record and a variable label record.
9362 Value labels (optional).
9368 Most records are identified by a single-character tag code. The file
9369 header and version info record do not have a tag.
9371 Other than these single-character codes, there are three types of fields
9372 in a portable file: floating-point, integer, and string. Floating-point
9373 fields have the following format:
9378 Zero or more leading spaces.
9381 Optional asterisk (@samp{*}), which indicates a missing value. The
9382 asterisk must be followed by a single character, generally a period
9383 (@samp{.}), but it appears that other characters may also be possible.
9384 This completes the specification of a missing value.
9387 Optional minus sign (@samp{-}) to indicate a negative number.
9390 A whole number, consisting of one or more base-30 digits: @samp{0}
9391 through @samp{9} plus capital letters @samp{A} through @samp{T}.
9394 Optional fraction, consisting of a radix point (@samp{.}) followed by
9395 one or more base-30 digits.
9398 Optional exponent, consisting of a plus or minus sign (@samp{+} or
9399 @samp{-}) followed by one or more base-30 digits.
9402 A forward slash (@samp{/}).
9405 Integer fields take a form identical to floating-point fields, but they
9406 may not contain a fraction.
9408 String fields take the form of a integer field having value @var{n},
9409 followed by exactly @var{n} characters, which are the string content.
9411 @node Portable File Header, Version and Date Info Record, Portable File Structure, Portable File Format
9412 @section Portable File Header
9414 Every portable file begins with a 464-byte header, consisting of a
9415 200-byte collection of vanity splash strings, followed by a 256-byte
9416 character set translation table, followed by an 8-byte tag string.
9418 The 200-byte segment is divided into five 40-byte sections, each of
9419 which represents the string @code{@var{charset} SPSS PORT FILE} in a
9420 different character set encoding, where @var{charset} is the name of
9421 the character set used in the file, e.g. @code{ASCII} or
9422 @code{EBCDIC}. Each string is padded on the right with spaces in its
9423 respective character set.
9425 It appears that these strings exist only to inform those who might view
9426 the file on a screen, and that they are not parsed by SPSS products.
9427 Thus, they can be safely ignored. For those interested, the strings are
9428 supposed to be in the following character sets, in the specified order:
9429 EBCDIC, 7-bit ASCII, CDC 6-bit ASCII, 6-bit ASCII, Honeywell 6-bit
9432 The 256-byte segment describes a mapping from the character set used in
9433 the portable file to an arbitrary character set having characters at the
9434 following positions:
9439 Control characters. Not important enough to describe in full here.
9447 Digits @samp{0} through @samp{9}.
9451 Capital letters @samp{A} through @samp{Z}.
9455 Lowercase letters @samp{a} through @samp{z}.
9467 Solid vertical pipe.
9471 Symbols @code{&[]!$*);^-/}
9475 Broken vertical pipe.
9479 Symbols @code{,%_>}?@code{`:} @c @code{?} is an inverted question mark
9483 British pound symbol.
9487 Symbols @code{@@'="}.
9491 Less than or equal symbol.
9523 Lower left corner box draw.
9527 Upper left corner box draw.
9531 Greater than or equal symbol.
9535 Superscript @samp{0} through @samp{9}.
9539 Lower right corner box draw.
9543 Upper right corner box draw.
9555 Superscript @samp{(}.
9559 Superscript @samp{)}.
9563 Horizontal dagger (?).
9567 Symbols @samp{@{@}\}.
9574 Centered dot, or bullet.
9581 Symbols that are not defined in a particular character set are set to
9582 the same value as symbol 64; i.e., to @samp{0}.
9584 The 8-byte tag string consists of the exact characters @code{SPSSPORT}
9585 in the portable file's character set, which can be used to verify that
9586 the file is indeed a portable file.
9588 @node Version and Date Info Record, Identification Records, Portable File Header, Portable File Format
9589 @section Version and Date Info Record
9591 This record does not have a tag code. It has the following structure:
9595 A single character identifying the file format version. The letter A
9596 represents version 0, and so on.
9599 An 8-character string field giving the file creation date in the format
9603 A 6-character string field giving the file creation time in the format
9607 @node Identification Records, Variable Count Record, Version and Date Info Record, Portable File Format
9608 @section Identification Records
9610 The product identification record has tag code @samp{1}. It consists of
9611 a single string field giving the name of the product that wrote the
9614 The subproduct identification record has tag code @samp{3}. It
9615 consists of a single string field giving additional information on the
9616 product that wrote the portable file.
9618 @node Variable Count Record, Case Weight Variable Record, Identification Records, Portable File Format
9619 @section Variable Count Record
9621 The variable count record has tag code @samp{4}. It consists of two
9622 integer fields. The first contains the number of variables in the file
9623 dictionary. The purpose of the second is unknown; it contains the value
9624 161 in all portable files examined so far.
9626 @node Case Weight Variable Record, Variable Records, Variable Count Record, Portable File Format
9627 @section Case Weight Variable Record
9629 The case weight variable record is optional. If it is present, it
9630 indicates the variable used for weighting cases; if it is absent,
9631 cases are unweighted. It has tag code @samp{6}. It consists of a
9632 single string field that names the weighting variable.
9634 @node Variable Records, Value Label Records, Case Weight Variable Record, Portable File Format
9635 @section Variable Records
9637 Each variable record represents a single variable. Variable records
9638 have tag code @samp{7}. They have the following structure:
9643 Width (integer). This is 0 for a numeric variable, and a number between 1
9644 and 255 for a string variable.
9647 Name (string). 1--8 characters long. Must be in all capitals.
9650 Print format. This is a set of three integer fields:
9655 Format type (@pxref{Variable Record}).
9658 Format width. 1--40.
9661 Number of decimal places. 1--40.
9665 Write format. Same structure as the print format described above.
9668 Each variable record can optionally be followed by a missing value
9669 record, which has tag code @samp{8}. A missing value record has one
9670 field, the missing value itself (a floating-point or string, as
9671 appropriate). Up to three of these missing value records can be used.
9673 There is also a record for missing value ranges, which has tag code
9674 @samp{B}. It is followed by two fields representing the range, which
9675 are floating-point or string as appropriate. If a missing value range
9676 is present, it may be followed by a single missing value record.
9678 Tag codes @samp{9} and @samp{A} represent @code{LO THRU @var{x}} and
9679 @code{@var{x} THRU HI} ranges, respectively. Each is followed by a
9680 single field representing @var{x}. If one of the ranges is present, it
9681 may be followed by a single missing value record.
9683 In addition, each variable record can optionally be followed by a
9684 variable label record, which has tag code @samp{C}. A variable label
9685 record has one field, the variable label itself (string).
9687 @node Value Label Records, Portable File Data, Variable Records, Portable File Format
9688 @section Value Label Records
9690 Value label records have tag code @samp{D}. They have the following
9695 Variable count (integer).
9698 List of variables (strings). The variable count specifies the number in
9699 the list. Variables are specified by their names. All variables must
9700 be of the same type (numeric or string).
9703 Label count (integer).
9706 List of (value, label) tuples. The label count specifies the number of
9707 tuples. Each tuple consists of a value, which is numeric or string as
9708 appropriate to the variables, followed by a label (string).
9711 @node Portable File Data, , Value Label Records, Portable File Format
9712 @section Portable File Data
9714 The data record has tag code @samp{F}. There is only one tag for all
9715 the data; thus, all the data must follow the dictionary. The data is
9716 terminated by the end-of-file marker @samp{Z}, which is not valid as the
9717 beginning of a data element.
9719 Data elements are output in the same order as the variable records
9720 describing them. String variables are output as string fields, and
9721 numeric variables are output as floating-point fields.
9723 @node q2c Input Format, Bugs, Portable File Format, Top
9724 @chapter @code{q2c} Input Format
9726 PSPP statistical procedures have a bizarre and somewhat irregular
9727 syntax. Despite this, a parser generator has been written that
9728 adequately addresses many of the possibilities and tries to provide
9729 hooks for the exceptional cases. This parser generator is named
9733 * Invoking q2c:: q2c command-line syntax.
9734 * q2c Input Structure:: High-level layout of the input file.
9735 * Grammar Rules:: Syntax of the grammar rules.
9738 @node Invoking q2c, q2c Input Structure, q2c Input Format, q2c Input Format
9739 @section Invoking q2c
9742 q2c @var{input.q} @var{output.c}
9745 @code{q2c} translates a @samp{.q} file into a @samp{.c} file. It takes
9746 exactly two command-line arguments, which are the input file name and
9747 output file name, respectively. @code{q2c} does not accept any
9748 command-line options.
9750 @node q2c Input Structure, Grammar Rules, Invoking q2c, q2c Input Format
9751 @section @code{q2c} Input Structure
9753 @code{q2c} input files are divided into two sections: the grammar rules
9754 and the supporting code. The @dfn{grammar rules}, which make up the
9755 first part of the input, are used to define the syntax of the
9756 statistical procedure to be parsed. The @dfn{supporting code},
9757 following the grammar rules, are copied largely unchanged to the output
9758 file, except for certain escapes.
9760 The most important lines in the grammar rules are used for defining
9761 procedure syntax. These lines can be prefixed with a dollar sign
9762 (@samp{$}), which prevents Emacs' CC-mode from munging them. Besides
9763 this, a bang (@samp{!}) at the beginning of a line causes the line,
9764 minus the bang, to be written verbatim to the output file (useful for
9765 comments). As a third special case, any line that begins with the exact
9766 characters @code{/* *INDENT} is ignored and not written to the output.
9767 This allows @code{.q} files to be processed through @code{indent}
9768 without being munged.
9770 The syntax of the grammar rules themselves is given in the following
9773 The supporting code is passed into the output file largely unchanged.
9774 However, the following escapes are supported. Each escape must appear
9775 on a line by itself.
9778 @item /* (header) */
9780 Expands to a series of C @code{#include} directives which include the
9781 headers that are required for the parser generated by @code{q2c}.
9783 @item /* (decls @var{scope}) */
9785 Expands to C variable and data type declarations for the variables and
9786 @code{enum}s input and output by the @code{q2c} parser. @var{scope}
9787 must be either @code{local} or @code{global}. @code{local} causes the
9788 declarations to be output as function locals. @code{global} causes them
9789 to be declared as @code{static} module variables; thus, @code{global} is
9790 a bit of a misnomer.
9792 @item /* (parser) */
9794 Expands to the entire parser. Must be enclosed within a C function.
9798 Expands to a set of calls to the @code{free} function for variables
9799 declared by the parser. Only needs to be invoked if subcommands of type
9800 @code{string} are used in the grammar rules.
9803 @node Grammar Rules, , q2c Input Structure, q2c Input Format
9804 @section Grammar Rules
9806 The grammar rules describe the format of the syntax that the parser
9807 generated by @code{q2c} will understand. The way that the grammar rules
9808 are included in @code{q2c} input file are described above.
9810 The grammar rules are divided into tokens of the following types:
9813 @item Identifier (@code{ID})
9815 An identifier token is a sequence of letters, digits, and underscores
9816 (@samp{_}). Identifiers are @emph{not} case-sensitive.
9818 @item String (@code{STRING})
9820 String tokens are initiated by a double-quote character (@samp{"}) and
9821 consist of all the characters between that double quote and the next
9822 double quote, which must be on the same line as the first. Within a
9823 string, a backslash can be used as a ``literal escape''. The only
9824 reasons to use a literal escape are to include a double quote or a
9825 backslash within a string.
9827 @item Special character
9829 Other characters, other than whitespace, constitute tokens in
9834 The syntax of the grammar rules is as follows:
9837 grammar-rules ::= ID : subcommands .
9838 subcommands ::= subcommand
9839 ::= subcommands ; subcommand
9842 The syntax begins with an ID or STRING token that gives the name of the
9843 procedure to be parsed. The rest of the syntax consists of subcommands
9844 separated by semicolons (@samp{;}) and terminated with a full stop
9848 subcommand ::= sbc-options ID sbc-defn
9851 ::= sbc-options sbc-options
9854 sbc-defn ::= opt-prefix = specifiers
9855 ::= [ ID ] = array-sbc
9856 ::= opt-prefix = sbc-special-form
9861 Each subcommand can be prefixed with one or more option characters. An
9862 asterisk (@samp{*}) is used to indicate the default subcommand; the
9863 keyword used for the default subcommand can be omitted in the PSPP
9864 syntax file. A plus sign (@samp{+}) is used to indicate that a
9865 subcommand can appear more than once; if it is not present then that
9866 subcommand can appear no more than once.
9868 The subcommand name appears after the option characters.
9870 There are three forms of subcommands. The first and most common form
9871 simply gives an equals sign (@samp{=}) and a list of specifiers, which
9872 can each be set to a single setting. The second form declares an array,
9873 which is a set of flags that can be individually turned on by the user.
9874 There are also several special forms that do not take a list of
9877 Arrays require an additional @code{ID} argument. This is used as a
9878 prefix, prepended to the variable names constructed from the
9879 specifiers. The other forms also allow an optional prefix to be
9883 array-sbc ::= alternatives
9884 ::= array-sbc , alternatives
9886 ::= alternatives | ID
9889 An array subcommand is a set of Boolean values that can independently be
9890 turned on by the user, listed separated by commas (@samp{,}). If an value has more
9891 than one name then these names are separated by pipes (@samp{|}).
9894 specifiers ::= specifier
9895 ::= specifiers , specifier
9896 specifier ::= opt-id : settings
9901 Ordinary subcommands (other than arrays and special forms) require a
9902 list of specifiers. Each specifier has an optional name and a list of
9903 settings. If the name is given then a correspondingly named variable
9904 will be used to store the user's choice of setting. If no name is given
9905 then there is no way to tell which setting the user picked; in this case
9906 the settings should probably have values attached.
9909 settings ::= setting
9910 ::= settings / setting
9911 setting ::= setting-options ID setting-value
9918 Individual settings are separated by forward slashes (@samp{/}). Each
9919 setting can be as little as an @code{ID} token, but options and values
9920 can optionally be included. The @samp{*} option means that, for this
9921 setting, the @code{ID} can be omitted. The @samp{!} option means that
9922 this option is the default for its specifier.
9926 ::= ( setting-value-2 )
9928 setting-value-2 ::= setting-value-options setting-value-type : ID
9929 setting-value-restriction
9930 setting-value-options ::=
9932 setting-value-type ::= N
9934 setting-value-restriction ::=
9938 Settings may have values. If the value must be enclosed in parentheses,
9939 then enclose the value declaration in parentheses. Declare the setting
9940 type as @samp{n} or @samp{d} for integer or floating point type,
9941 respectively. The given @code{ID} is used to construct a variable name.
9942 If option @samp{*} is given, then the value is optional; otherwise it
9943 must be specified whenever the corresponding setting is specified. A
9944 ``restriction'' can also be specified which is a string giving a C
9945 expression limiting the valid range of the value. The special escape
9946 @code{%s} should be used within the restriction to refer to the
9947 setting's value variable.
9950 sbc-special-form ::= VAR
9951 ::= VARLIST varlist-options
9952 ::= INTEGER opt-list
9955 ::= STRING @r{(the literal word STRING)} string-options
9962 ::= ( STRING STRING )
9965 The special forms are of the following types:
9970 A single variable name.
9974 A list of variables. If given, the string can be used to provide
9975 @code{PV_@var{*}} options to the call to @code{parse_variables}.
9979 A single integer value.
9983 A list of integers separated by spaces or commas.
9987 A single floating-point value.
9991 A list of floating-point values.
9995 A single positive integer value.
9999 A string value. If the options are given then the first string is an
10000 expression giving a restriction on the value of the string; the second
10001 string is an error message to display when the restriction is violated.
10005 A custom function is used to parse this subcommand. The function must
10006 have prototype @code{int custom_@var{name} (void)}. It should return 0
10007 on failure (when it has already issued an appropriate diagnostic), 1 on
10008 success, or 2 if it fails and the calling function should issue a syntax
10009 error on behalf of the custom handler.
10013 @node Bugs, Function Index, q2c Input Format, Top
10017 * Known bugs:: Pointers to other files.
10018 * Contacting the Author:: Where to send the bug reports.
10021 @node Known bugs, Contacting the Author, Bugs, Bugs
10022 @section Known bugs
10024 This is the list of known bugs in PSPP. In addition, @xref{Not
10025 Implemented}, and @xref{Functions Not Implemented}, for lists of bugs
10026 due to features not implemented. For known bugs in individual language
10027 features, see the documentation for that feature.
10031 Nothing has yet been tested exhaustively. Be cautious using PSPP to
10032 make important decisions.
10035 @code{make check} fails on some systems that don't like the syntax. I'm
10036 not sure why. If someone could make an attempt to track this down, it
10037 would be appreciated.
10040 PostScript driver bugs:
10044 Does not support driver arguments `max-fonts-simult' or
10045 `optimize-text-size'.
10048 Minor problems with font-encodings.
10051 Fails to align fonts along their baselines.
10054 Does not support certain bizarre line intersections--should
10055 never crop up in practice.
10058 Does not gracefully substitute for existing fonts whose
10059 encodings are missing.
10062 Does not perform italic correction or left italic correction
10066 Encapsulated PostScript is unimplemented.
10073 Does not support `infinite length' or `infinite width' paper.
10077 See below for information on reporting bugs not listed here.
10079 @node Contacting the Author, , Known bugs, Bugs
10080 @section Contacting the Author
10082 The author can be contacted at e-mail address
10087 @code{<blp@@gnu.org>}.
10090 PSPP bug reports should be sent to
10092 <bug-gnu-pspp@@gnu.org>.
10095 @code{<bug-gnu-pspp@@gnu.org>}.
10098 @node Function Index, Concept Index, Bugs, Top
10099 @chapter Function Index
10102 @node Concept Index, Command Index, Function Index, Top
10103 @chapter Concept Index
10106 @node Command Index, , Concept Index, Top
10107 @chapter Command Index
10113 @c Local Variables:
10114 @c compile-command: "makeinfo pspp.texi"