@quotation
@strong{Please note:} PSPP is not even close to completion.
-Only a few actual statistical procedures are implemented. PSPP
+Only a few statistical procedures are implemented. PSPP
is a work in progress.
@end quotation
* Missing Observations:: Handling missing observations.
* Variables:: The unit of data storage.
* Files:: Files used by PSPP.
+* File Handles:: How files are named.
* BNF:: How command syntax is described.
@end menu
@end example
@cindex case-sensitivity
-Identifiers may be up any length, but only the first 64 bytes are
+Identifiers may be any length, but only the first 64 bytes are
significant. Identifiers are not case-sensitive: @code{foobar},
@code{Foobar}, @code{FooBar}, @code{FOOBAR}, and @code{FoObaR} are
different representations of the same identifier.
punctuator only as the last character on a line (except white space).
When it is the last non-space character on a line, a period is not
treated as part of another token, even if it would otherwise be part
-of e.g.@: an identifier or a floating-point number.
+of, e.g.@:, an identifier or a floating-point number.
Actually, the character that ends a command can be changed with
@cmd{SET}'s ENDCMD subcommand (@pxref{SET}), but we do not recommend
The command name may be followed by one or more @dfn{subcommands}.
Each subcommand begins with a subcommand name, which may be
abbreviated to its first three letters. Some subcommands accept a
-series of one or more specifications, which follow the subcommand name
-and, optionally separated from it by an equals sign (@samp{=}), and
-optionally separated from each other by commas. Each subcommand must
-be separated from the next (if any) by a forward slash (@samp{/}).
+series of one or more specifications, which follow the subcommand
+name, optionally separated from it by an equals sign
+(@samp{=}). Specifications may be separated from each other
+by commas or spaces. Each subcommand must be separated from the next (if any)
+by a forward slash (@samp{/}).
There are multiple ways to mark the end of a command. The most common
way is to end the last line of the command with a period (@samp{.}) as
of an interactive user, any line that contains a non-space character
in the leftmost column begins a new command. Thus, each command
consists of a flush-left line followed by any number of lines indented
-from the left margin. In this mode, a plus sign, minus sign, or
-period (@samp{+}, @samp{@minus{}}, or @samp{.}) as the first character
+from the left margin. In this mode, a plus or minus sign
+(@samp{+}, @samp{@minus{}}) as the first character
in a line is ignored and causes that line to begin a new command,
which allows for visual indentation of a command without that command
being considered part of the previous command.
-Sometimes, one encounters syntax files that are intended to be
-interpreted in interactive mode rather than batch mode. When this
-occurs, use the @samp{-i} command line option to force interpretation
-in interactive mode (@pxref{Language control options}).
-
@node Types of Commands, Order of Commands, Commands, Language
@section Types of Commands
@item File definition commands
@cindex file definition commands
Give instructions for reading data from text files or from special
-binary ``system files''. Most of these commands discard any previous
-data or variables to replace it with the new data and
-variables. At least one must appear before the first command in any of
+binary ``system files''. Most of these commands replace any previous
+data or variables with new data or
+variables. At least one file definition command must appear before the first command in any of
the categories below. @xref{Data Input and Output}.
@item Input program commands
@cindex input program commands
-Though rarely used, these provide powerful tools for reading data files
+Though rarely used, these provide tools for reading data files
in arbitrary textual or binary formats. @xref{INPUT PROGRAM}.
@item Transformations
@cindex order of commands
PSPP does not place many restrictions on ordering of commands. The
-main restriction is that variables must be defined they are otherwise
+main restriction is that variables must be defined before they are otherwise
referenced. This section describes the details of command ordering,
but most users will have no need to refer to them.
distinction between the @cmd{INPUT PROGRAM} and @cmd{FILE TYPE}
@emph{commands} and the INPUT PROGRAM and FILE TYPE @emph{states}.)
-PSPP starts up in the initial state. Each successful completion
+PSPP starts in the initial state. Each successful completion
of a command may cause a state transition. Each type of command has its
own rules for state transitions:
@cindex variables, system
There are seven system variables. These are not like ordinary
-variables, as they are not stored in each case. They can only be used
+variables because system variables are not always stored. They can be used only
in expressions. These system variables, whose values and output formats
cannot be modified, are described below.
included then it is assumed to be 0. Some formats do not allow @var{d}
to be specified.
-When an input format is specified on @cmd{DATA LIST} or another
-command, then
-it is converted to an output format for the purposes of @cmd{PRINT}
-and other
-data output commands. For most purposes, input and output formats are
-the same; the salient differences are described below.
+When @cmd{DATA LIST} or another command specifies an input format,
+that format is converted to an output format for the purposes of
+@cmd{PRINT} and other data output commands. For most purposes, input
+and output formats are the same; the salient differences are described
+below.
Below are listed the input and output formats supported by PSPP. If an
input format is mapped to a different output format by default, then
@item PIB @result{} F: 1 <= iw,ow <= 8
Positive integer binary format. The field is interpreted as a
fixed-point positive binary number. The location of the decimal point
-is implied. Endianness is teh same as the host machine.
+is implied. Endianness is the same as the host machine.
The default output format follows the rules for IB format.
@item DATETIMEw.d: 17 <= iw,ow <= 40
Date and time format. Input format: leader + day + date-delimiter +
-month + date-delimiter + yaer + time-delimiter + hour24 + time-delimiter
+month + date-delimiter + year + time-delimiter + hour24 + time-delimiter
+ minute + opt-second. Output format: @samp{DD-MMM-YYYY HH:MM}. If
@var{w} > 19 then seconds @samp{:SS} is added. If @var{w} > 22 and
@var{d} > 0 then fractional seconds @samp{.SS} are added.
names begin with an octothorpe (@samp{#}).
Scratch variables have the same properties as variables left with
-@cmd{LEAVE}:
-they retain their values between cases, and for the first case they are
-initialized to 0 or blanks. They have the additional property that they
-are deleted before the execution of any procedure. For this reason,
-scratch variables can't be used for analysis. To obtain the same
-effect, use @cmd{COMPUTE} (@pxref{COMPUTE}) to copy the scratch variable's
-value into an ordinary variable, then analysis that variable.
-
-@node Files, BNF, Variables, Language
+@cmd{LEAVE}: they retain their values between cases, and for the first
+case they are initialized to 0 or blanks. They have the additional
+property that they are deleted before the execution of any procedure.
+For this reason, scratch variables can't be used for analysis. To use
+a scratch variable in an analysis, use @cmd{COMPUTE} (@pxref{COMPUTE})
+to copy its value into an ordinary variable, then use that ordinary
+variable in the analysis.
+
+@node Files
@section Files Used by PSPP
PSPP makes use of many files each time it runs. Some of these it
@cindex syntax file
@item command file
@itemx syntax file
-These names (synonyms) refer to the file that contains instructions to
-PSPP that tell it what to do. The syntax file's name is specified on
-the PSPP command line. Syntax files can also be pulled in with
+These names (synonyms) refer to the file that contains instructions
+that tell PSPP what to do. The syntax file's name is specified on
+the PSPP command line. Syntax files can also be read with
@cmd{INCLUDE} (@pxref{INCLUDE}).
@cindex file, data
@cindex data file
@item data file
-Data files contain raw data in ASCII format suitable for being read in
-by @cmd{DATA LIST}. Data can be embedded in the syntax
-file with @cmd{BEGIN DATA} and @cmd{END DATA}: this makes the
-syntax file a data file too.
+Data files contain raw data in text or binary format. Data can also
+be embedded in a syntax file with @cmd{BEGIN DATA} and @cmd{END DATA}.
@cindex file, output
@cindex output file
@cindex active file
@cindex file, active
@item active file
-The active file is the ``file'' on which all PSPP procedures
-are performed. The active file contains variable definitions and
-cases. The active file is not necessarily a disk file: it is stored
-in memory if there is room.
+The active file is the ``file'' on which all PSPP procedures are
+performed. The active file consists of a dictionary and a set of cases.
+The active file is not necessarily a disk file: it is stored in memory
+if there is room.
+
+@cindex system file
+@cindex file, system
+@item system file
+System files are binary files that store a dictionary and a set of
+cases. @cmd{GET} and @cmd{SAVE} read and write system files.
+
+@cindex portable file
+@cindex file, portable
+@item portable file
+Portable files are files in a text-based format that store a dictionary
+and a set of cases. @cmd{IMPORT} and @cmd{EXPORT} read and write
+portable files.
+
+@cindex scratch file
+@cindex file, scratch
+@item scratch file
+Scratch files consist of a dictionary and cases and may be stored in
+memory or on disk. Most procedures that act on a system file or
+portable file can use a scratch file instead. The contents of scratch
+files persist within a single PSPP session only. @cmd{GET} and
+@cmd{SAVE} can be used to read and write scratch files. Scratch files
+are a PSPP extension.
@end table
-@node BNF, , Files, Language
+@node File Handles
+@section File Handles
+@cindex file handles
+
+A @dfn{file handle} is a reference to a data file, system file, portable
+file, or scratch file. Most often, a file handle is specified as the
+name of a file as a string, that is, enclosed within @samp{'} or
+@samp{"}.
+
+PSPP also supports declaring named file handles with the @cmd{FILE
+HANDLE} command. This command associates an identifier of your choice
+(the file handle's name) with a file. Later, the file handle name can
+be substituted for the name of the file. When PSPP syntax accesses a
+file multiple times, declaring a named file handle simplifies updating
+the syntax later to use a different file. Use of @cmd{FILE HANDLE} is
+also required to read data files in binary formats. @xref{FILE HANDLE},
+for more information.
+
+PSPP assumes that a file handle name that begins with @samp{#} refers to
+a scratch file, unless the name has already been declared on @cmd{FILE
+HANDLE} to refer to another kind of file. A scratch file is similar to
+a system file, except that it persists only for the duration of a given
+PSPP session. Most commands that read or write a system or portable
+file, such as @cmd{GET} and @cmd{SAVE}, also accept scratch file
+handles. Scratch file handles may also be declared explicitly with
+@cmd{FILE HANDLE}. Scratch files are a PSPP extension.
+
+In some circumstances, PSPP must distinguish whether a file handle
+refers to a system file or a portable file. When this is necessary to
+read a file, e.g.@: as an input file for @cmd{GET} or @cmd{MATCH FILES},
+PSPP uses the file's contents to decide. In the context of writing a
+file, e.g.@: as an output file for @cmd{SAVE} or @cmd{AGGREGATE}, PSPP
+decides based on the file's name: if it ends in @samp{.por} (with any
+capitalization), then PSPP writes a portable file; otherwise, PSPP
+writes a system file.
+
+INLINE is reserved as a file handle name. It refers to the ``data
+file'' embedded into the syntax file between @cmd{BEGIN DATA} and
+@cmd{END DATA}. @xref{BEGIN DATA}, for more information.
+
+The file to which a file handle refers may be reassigned on a later
+@cmd{FILE HANDLE} command if it is first closed using @cmd{CLOSE FILE
+HANDLE}. The @cmd{CLOSE FILE HANDLE} command is also useful to free the
+storage associated with a scratch file. @xref{CLOSE FILE HANDLE}, for
+more information.
+
+@node BNF
@section Backus-Naur Form
@cindex BNF
@cindex Backus-Naur Form
@item
Words in all-uppercase are PSPP keyword tokens. In BNF, these are
often called @dfn{terminals}. There are some special terminals, which
-are actually written in lowercase for clarity:
+are written in lowercase for clarity:
@table @asis
@cindex @code{number}
projects / pspp-builds.git / blobdiff