The PSPP language
*****************

     Please note: PSPP is not even close to completion. Only a few actual statistical procedures are implemented.  PSPP is a work in progress.

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

Tokens
======

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

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

Identifiers
     Identifiers are names that specify variable names, commands, or command details.

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

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

               .  _  $  #  @

       * Variable names may be any length, but only the first 8 characters are significant.

       * Identifiers are not case-sensitive: foobar, Foobar, FooBar, FOOBAR, and FoObaR are different representations of the same identifier.

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

       * Whether an identifier is a keyword depends on the context.

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

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

       * Since keywords are identifiers, all the rules for identifiers apply. Specifically, they must be delimited as are other identifiers: WITH is a reserved keyword, but WITHOUT is a valid variable name.

     Caution: It is legal to end a variable name with a period, but don't do it!  The variable name will be misinterpreted when it is the final token on a line: FOO. will be divided into two separate tokens, FOO and ., the terminal dot. See Forming commands of tokens.

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

          1234  3.14159265359  .707106781185  8945.

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

Strings
     Strings are literal sequences of characters enclosed in pairs of single quotes (') or double quotes (").

       * Whitespace and case of letters are significant inside strings.

       * Whitespace characters inside a string are not delimiters.

       * To include single-quote characters in a string, enclose the string in double quotes.

       * To include double-quote characters in a string, enclose the string in single quotes.

       * It is not possible to put both single- and double-quote characters inside one string.

Hexstrings
     Hexstrings are string variants that use hex digits to specify characters.

       * A hexstring may be used anywhere that an ordinary string is allowed.

       * A hexstring begins with X' or x', and ends with '.

       * No whitespace is allowed between the initial X and '.

       * Double quotes " may be used in place of single quotes ' if done in both places.

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

       * If there is an odd number of hex digits, the missing last digit is assumed to be 0.

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

       * Please note also: The character with value 00 is reserved for internal use by PSPP.  Its use in strings causes an error and replacement with a blank space (in ASCII, hex 20, decimal 32).

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

          ,  /  =  (  )

Operators
     Operators describe mathematical operations.  Some operators are delimiters:

          (  )  +  -  *  /  **

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

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

          AND  EQ  GE  GT  LE  LT  NE  OR

Terminal Dot
     A period (.) at the end of a line (except for whitespace) is one type of a terminal dot, although not every terminal dot is a period at the end of a line.  See Forming commands of tokens.  A period is a terminal dot only when it is at the end of a line; otherwise it is part of a floating-point number.  (A period outside a number in the middle of a line is an error.)

          Please note: The character used for the terminal dot can be changed with SET's ENDCMD subcommand (see SET).  This is strongly discouraged, and throughout all the remainder of this manual it will be assumed that the default setting is in effect.

Forming commands of tokens
==========================

Most PSPP commands share a common structure, diagrammed below:

     CMD... [SBC[=][SPEC [[,]SPEC]...]] [[/[=][SPEC [[,]SPEC]...]]...].

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

  * A command begins with a command name of one or more keywords, such as FREQUENCIES, DATA LIST, or N OF CASES.  CMD may be abbreviated to its first word if that is unambiguous; each word in CMD may be abbreviated to a unique prefix of three or more characters as described above.

  * The command name may be followed by one or more subcommands:

       - Each subcommand begins with a unique keyword, indicated by SBC above.  This is analogous to the command name.

       - The subcommand name is optionally followed by an equals sign (=).

       - Some subcommands accept a series of one or more specifications (SPEC), optionally separated by commas.

       - Each subcommand must be separated from the next (if any) by a forward slash (/).

  * Each command must be terminated with a terminal dot. The terminal dot may be given one of three ways:

       - (most commonly) A period character at the very end of a line, as described above.

       - (only if NULLINE is on: see Setting user preferences, for more details.)  A completely blank line.

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

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

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

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

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

Types of Commands
=================

Commands in PSPP are divided roughly into six categories:

Utility commands
     Set or display various global options that affect PSPP operations. May appear anywhere in a syntax file.  See Utility commands.

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

Input program commands
     Though rarely used, these provide powerful tools for reading data files in arbitrary textual or binary formats.  See INPUT PROGRAM.

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

Restricted transformations
     Same as transformations for most purposes.  See Order of Commands, for a detailed description of the differences.

Procedures
     Analyze data, writing results of analyses to the listing file.  Cause transformations specified earlier in the file to be performed.  In a more general sense, a procedure is any command that causes the active file (the data) to be read.

Order of Commands
=================

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

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

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

Utility commands

       * Legal in all states.

       * Do not cause state transitions.  Exception: when N OF CASES is executed in the procedure state, it causes a transition to the transformation state.

DATA LIST

       * Legal in all states.

       * When executed in the initial or procedure state, causes a transition to the transformation state.

       * Clears the active file if executed in the procedure or transformation state.

INPUT PROGRAM

       * Invalid in INPUT PROGRAM and FILE TYPE states.

       * Causes a transition to the INPUT PROGRAM state.

       * Clears the active file.

FILE TYPE

       * Invalid in INPUT PROGRAM and FILE TYPE states.

       * Causes a transition to the FILE TYPE state.

       * Clears the active file.

Other file definition commands

       * Invalid in INPUT PROGRAM and FILE TYPE states.

       * Cause a transition to the transformation state.

       * Clear the active file, except for ADD FILES, MATCH FILES, and UPDATE.

Transformations

       * Invalid in initial and FILE TYPE states.

       * Cause a transition to the transformation state.

Restricted transformations

       * Invalid in initial, INPUT PROGRAM, and FILE TYPE states.

       * Cause a transition to the transformation state.

Procedures

       * Invalid in initial, INPUT PROGRAM, and FILE TYPE states.

       * Cause a transition to the procedure state.

Handling missing observations
=============================

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

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

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

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

Variables
=========

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

Attributes of Variables
-----------------------

Each variable has a number of attributes, including:

Name
     This is an identifier.  Each variable must have a different name. See Tokens.

Type
     Numeric or string.

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

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

Position
     Variables in the dictionary are arranged in a specific order. DISPLAY can be used to show this order: see DISPLAY.

Initialization
     Either reinitialized to 0 or spaces for each case, or left at its existing value.  See LEAVE.

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

Variable label
     A string that describes the variable.  See VARIABLE LABELS.

Value label
     Optionally, these associate each possible value of the variable with a string.  See VALUE LABELS.

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

Write format
     Similar to print format, but used by certain commands that are designed to write to binary files.  See WRITE FORMATS.

Variables Automatically Defined by PSPP
---------------------------------------

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

$CASENUM
     Case number of the case at the moment.  This changes as cases are shuffled around.

$DATE
     Date the PSPP process was started, in format A9, following the pattern DD MMM YY.

$JDATE
     Number of days between 15 Oct 1582 and the time the PSPP process was started.

$LENGTH
     Page length, in lines, in format F11.

$SYSMIS
     System missing value, in format F1.

$TIME
     Number of seconds between midnight 14 Oct 1582 and the time the active file was read, in format F20.

$WIDTH
     Page width, in characters, in format F3.

Lists of variable names
-----------------------

There are several ways to specify a set of variables:

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

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

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

       * The syntax X1 TO X5 defines 5 variables:

            - X1

            - X2

            - X3

            - X4

            - X5

       * The syntax ITEM0008 TO ITEM0013 defines 6 variables:

            - ITEM0008

            - ITEM0009

            - ITEM0010

            - ITEM0011

            - ITEM0012

            - ITEM0013

       * Each of the syntaxes QUES001 TO QUES9 and QUES6 TO QUES3 are invalid, although for different reasons, which should be evident.

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

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

Input and Output Formats
------------------------

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

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

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

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

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

     The default output format is the same as the input format, except if D > 1.  In that case the output W is always made to be at least 2 + D.

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

     The default output W is the largest of the input W, the input D + 7, and 10.  The default output D is the input D, but at least 3.

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

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

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

     The default output W is the input W, but at least 2.

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

     The default output W is the input W, but at least 2.

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

     The default output format is F with the same W and D, except if D > 1.  In that case the output W is always made to be at least 2 + D.

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

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

     The default output format is F8.2 if D is 0.  Otherwise it is F, with output W as 9 + input D and output D as input D.

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

     The default output format follows the rules for IB format.

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

     The default output format follows the rules for IB format.

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

     The default output format follows the rules for IB format.

RBw => F: 2 <= iw,ow <= 8

     Binary C architecture-dependent ``double'' format.  For a standard IEEE754 implementation W should be 8.

     The default output format follows the rules for IB format.

PIBHEXw.d => F: 2 <= iw,ow <= 16
     PIB format encoded as textual hex digit pairs.  W must be even.

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

RBHEXw => F: 4 <= iw,ow <= 16

     RB format encoded as textual hex digits pairs.  W must be even.

     The default output format is F8.2.

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

     User-defined custom currency formats.  May not be used as an input format.  See SET, for more details.

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

leader
     All formats accept an optional whitespace leader.

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

day-count
     An integer representing a number of days.

date-delimiter
     One or more characters of whitespace or the following characters: - / . ,

month
     A month name in one of the following forms:

       * An integer between 1 and 12.

       * Roman numerals representing an integer between 1 and 12.

       * At least the first three characters of an English month name (January, February, ...).

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

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

quarter
     An integer between 1 and 4 representing a quarter.

q-delimiter
     The letter Q or q.

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

wk-delimiter
     The letters wk in any case.

time-delimiter
     At least one characters of whitespace or : or ..

hour
     An integer greater than 0 representing an hour.

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

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

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

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

spaces
     Any amount or no amount of whitespace.

sign
     An optional positive or negative sign.

trailer
     All formats accept an optional whitespace trailer.

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

DATEw: 9 <= iw,ow <= 40
     Date format. Input format: leader + day + date-delimiter + month + date-delimiter + year + trailer.  Output format: DD-MMM-YY for W < 11, DD-MMM-YYYY otherwise.

EDATEw: 8 <= iw,ow <= 40
     European date format.  Input format same as DATE.  Output format: DD.MM.YY for W < 10, DD.MM.YYYY otherwise.

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

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

JDATEw: 5 <= iw,ow <= 40
     Julian date format.  Input format: leader + julian + trailer.  Output format: YYDDD for W < 7, YYYYDDD otherwise.

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

MOYRw: 6 <= iw,ow <= 40
     Month/year format.  Input format: leader + month + date-delimiter + year + trailer.  Output format: MMM YY for W < 8, MMM YYYY otherwise.

WKYRw: 6 <= iw <= 40, 8 <= ow <= 40
     Week/year format.  Input format: leader + week + wk-delimiter + year + trailer.  Output format: WW WK YY for W < 10, WW WK YYYY otherwise.

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

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

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

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

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

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

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

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

     The default output W is half the input W.

Scratch Variables
-----------------

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

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

Scratch variables have the same properties as variables left with 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 COMPUTE (see COMPUTE) to copy the scratch variable's value into an ordinary variable, then analysis that variable.

Files Used by PSPP
==================

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

command file
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 INCLUDE (see INCLUDE).

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

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

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.

Backus-Naur Form
================

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

  * Words in all-uppercase are PSPP keyword tokens.  In BNF, these are often called terminals.  There are some special terminals, which are actually written in lowercase for clarity:

     number
          A real number.

     integer
          An integer number.

     string
          A string.

     var-name
          A single variable name.

     =, /, +, -, etc.
          Operators and punctuators.

     .
          The terminal dot.  This is not necessarily an actual dot in the syntax file: see Commands, for more details.

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

     var-list
          A list of one or more variable names or the keyword ALL.

     expression
          An expression.  See Expressions, for details.

  * ::= means ``is defined as''.  The left side of ::= gives the name of the nonterminal being defined.  The right side of ::= gives the definition of that nonterminal.  If the right side is empty, then one possible expansion of that nonterminal is nothing.  A BNF definition is called a production.

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

  * The first nonterminal defined in a set of productions is called the start symbol.  The start symbol defines the entire syntax for that command.