The pspp language
*****************

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

Tokens
======

pspp divides most syntax file lines into series of short chunks called tokens. 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.  Each type of token is described below.

Identifiers
     Identifiers are names that typically specify variables, commands, or subcommands.  The first character in an identifier must be a letter, #, or @.  The remaining characters in the identifier must be letters, digits, or one of the following special characters:

          .  _  $  #  @

     Identifiers may be any length, but only the first 64 bytes are significant.  Identifiers are not case-sensitive: foobar, Foobar, FooBar, FOOBAR, and FoObaR are different representations of the same identifier.

     Some identifiers are reserved.  Reserved identifiers may not be used in any context besides those explicitly described in this manual.  The reserved identifiers are:

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

Keywords
     Keywords are a subclass of identifiers that form a fixed part of command syntax.  For example, command and subcommand names are keywords.  Keywords may be abbreviated to their first 3 characters if this abbreviation is unambiguous.  (Unique abbreviations of 3 or more characters are also accepted: FRE, FREQ, and FREQUENCIES are equivalent when the last is a keyword.)

     Reserved identifiers are always used as keywords.  Other identifiers may be used both as keywords and as user-defined identifiers, such as variable names.

Numbers
     Numbers are expressed in decimal.  A decimal point is optional. Numbers may be expressed in scientific notation by adding e and a base-10 exponent, so that 1.234e3 has the value 1234.  Here are some more examples of valid numbers:

          -5  3.14159265359  1e100  -.707  8945.

     Negative numbers are expressed with a - prefix.  However, in situations where a literal - token is expected, what appears to be a negative number is treated as - followed by a positive number.

     No white space is allowed within a number token, except for horizontal white space between - and the rest of the number.

     The last example above, 8945. is interpreted as two tokens, 8945 and ., if it is the last token on a line. See Forming commands of tokens.

Strings
     Strings are literal sequences of characters enclosed in pairs of single quotes (') or double quotes (").  To include the character used for quoting in the string, double it, e.g. 'it''s an apostrophe'.  White space and case of letters are significant inside strings.

     Strings can be concatenated using +, so that "a" + 'b' + 'c' is equivalent to 'abc'.  So that a long string may be broken across lines, a line break may precede or follow, or both precede and follow, the +.  (However, an entirely blank line preceding or following the + is interpreted as ending the current command.)

     Strings may also be expressed as hexadecimal character values by prefixing the initial quote character by x or X. Regardless of the syntax file or active dataset's encoding, the hexadecimal digits in the string are interpreted as Unicode characters in UTF-8 encoding.

     Individual Unicode code points may also be expressed by specifying the hexadecimal code point number in single or double quotes preceded by u or U.  For example, Unicode code point U+1D11E, the musical G clef character, could be expressed as U'1D11E'. Invalid Unicode code points (above U+10FFFF or in between U+D800 and U+DFFF) are not allowed.

     When strings are concatenated with +, each segment's prefix is considered individually.  For example, 'The G clef symbol is:' + u"1d11e" + "." inserts a G clef symbol in the middle of an otherwise plain text string.

Punctuators and Operators
     These tokens are the punctuators and operators:

          ,  /  =  (  )  +  -  *  /  **  <  <=  <>  >  >=  ~=  &  |  .

     Most of these appear within the syntax of commands, but the period (.) punctuator is used only at the end of a command.  It is a punctuator only as the last character on a line (except white space). When it is the last non-space character on a line, a period is not treated as part of another token, even if it would otherwise be part of, e.g., an identifier or a floating-point number.

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

Most pspp commands share a common structure.  A command begins with a command name, such as FREQUENCIES, DATA LIST, or N OF CASES.  The command name may be abbreviated to its first word, and each word in the command name may be abbreviated to its first three or more characters, where these abbreviations are unambiguous.

The command name may be followed by one or more 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, optionally separated from it by an equals sign (=). 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 (/).

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 (.) as described in the previous section (see Tokens).  A blank line, or one that consists only of white space or comments, also ends a command.

Syntax Variants
===============

There are three variants of command syntax, which vary only in how they detect the end of one command and the start of the next.

In interactive mode, which is the default for syntax typed at a command prompt, a period as the last non-blank character on a line ends a command.  A blank line also ends a command.

In batch mode, an end-of-line period or a blank line also ends a command.  Additionally, it treats any line that has a non-blank character in the leftmost column as beginning a new command.  Thus, in batch mode the second and subsequent lines in a command must be indented.

Regardless of the syntax mode, a plus sign, minus sign, or period in the leftmost column of a line is ignored and causes that line to begin a new command.  This is most useful in batch mode, in which the first line of a new command could not otherwise be indented, but it is accepted regardless of syntax mode.

The default mode for reading commands from a file is auto mode. It is the same as batch mode, except that a line with a non-blank in the leftmost column only starts a new command if that line begins with the name of a pspp command.  This correctly interprets most valid pspp syntax files regardless of the syntax mode for which they are intended.

The --interactive (or -i) or --batch (or -b) options set the syntax mode for files listed on the pspp command line.  See Main Options, for more details.

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 replace any previous data or variables with new data or variables.  At least one file definition command must appear before the first command in any of the categories below.  See Data Input and Output.

Input program commands
     Though rarely used, these provide 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
     Transformations that cannot appear in certain contexts.  See Order of Commands, for details.

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 dataset (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 before they are otherwise referenced.  This section describes the details of command ordering, but most users will have no need to refer to them.

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 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

       * Valid in any state.

       * 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

       * Valid in any state.

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

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

INPUT PROGRAM

       * Invalid in input-program and file-type states.

       * Causes a transition to the intput-program state.

       * Clears the active dataset.

FILE TYPE

       * Invalid in intput-program and file-type states.

       * Causes a transition to the file-type state.

       * Clears the active dataset.

Other file definition commands

       * Invalid in input-program and file-type states.

       * Cause a transition to the transformation state.

       * Clear the active dataset, 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 a value; it means that the actual value is unknown.  Procedures automatically exclude from analyses those observations or cases that have missing values.  Details of missing value exclusion depend on the procedure and can often be controlled by the user; refer to descriptions of individual procedures for details.

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.

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

Datasets
========

pspp works with data organized into datasets.  A dataset consists of a set of variables, which taken together are said to form a dictionary, and one or more cases, each of which has one value for each variable.

At any given time pspp has exactly one distinguished dataset, called the active dataset.  Most pspp commands work only with the active dataset.  In addition to the active dataset, pspp also supports any number of additional open datasets.  The DATASET commands can choose a new active dataset from among those that are open, as well as create and destroy datasets (see DATASET).

The sections below describe variables in more detail.

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

Each variable has a number of attributes, including:

Name
     An identifier, up to 64 bytes long.  Each variable must have a different name. See Tokens.

     Some system variable names begin with $, but user-defined variables' names may not begin with $.

     The final character in a variable name should not be ., because such an identifier will be misinterpreted when it is the final token on a line: FOO. is divided into two separate tokens, FOO and ., indicating end-of-command.  See Tokens.

     The final character in a variable name should not be _, because some such identifiers are used for special purposes by pspp procedures.

     As with all pspp identifiers, variable names are not case-sensitive. pspp capitalizes variable names on output the same way they were capitalized at their point of definition in the input.

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 may be used in a few contexts where long string variables (those with widths greater than 8) are not allowed.

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 Input and Output Formats.

Write format
     Similar to print format, but used by the WRITE command (see WRITE).

Custom attributes
     User-defined associations between names and values.  See VARIABLE ATTRIBUTE.

Role
     The intended role of a variable for use in dialog boxes in graphical user interfaces.  See VARIABLE ROLE.

Variables Automatically Defined by pspp
---------------------------------------

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

$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.

$DATE11
     Date the pspp process was started, in format A11, following the pattern DD-MMM-YYYY.

$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 dataset was read, in format F20.

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

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

To refer to a set of variables, list their names one after another. Optionally, their names may be separated by commas.  To include a range of variables from the dictionary in the list, write the name of the first and last variable in the range, separated by TO.  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.

Commands that define variables, such as DATA LIST, give TO an alternate meaning.  With these commands, TO define sequences of variables whose names end in consecutive integers.  The syntax is two identifiers that begin with the same root and end with numbers, separated by TO.  The syntax X1 TO X5 defines 5 variables, named X1, X2, X3, X4, and X5.  The syntax ITEM0008 TO ITEM0013 defines 6 variables, named ITEM0008, ITEM0009, ITEM0010, ITEM0011, ITEM0012, and ITEM00013.  The syntaxes QUES001 TO QUES9 and QUES6 TO QUES3 are invalid.

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.

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

An input format describes how to interpret the contents of an input field as a number or a string.  It might specify that the field contains an ordinary decimal number, a time or date, a number in binary or hexadecimal notation, or one of several other notations.  Input formats are used by commands such as DATA LIST that read data or syntax files into the pspp active dataset.

Every input format corresponds to a default output format that specifies the formatting used when the value is output later.  It is always possible to explicitly specify an output format that resembles the input format.  Usually, this is the default, but in cases where the input format is unfriendly to human readability, such as binary or hexadecimal formats, the default output format is an easier-to-read decimal format.

Every variable has two output formats, called its print format and write format.  Print formats are used in most output contexts; write formats are used only by WRITE (see WRITE).  Newly created variables have identical print and write formats, and FORMATS, the most commonly used command for changing formats (see FORMATS), sets both of them to the same value as well.  Thus, most of the time, the distinction between print and write formats is unimportant.

Input and output formats are specified to pspp with a format specification of the form TYPEW or TYPEW.D, where TYPE is one of the format types described later, W is a field width measured in columns, and D is an optional number of decimal places.  If D is omitted, a value of 0 is assumed.  Some formats do not allow a nonzero D to be specified.

The following sections describe the input and output formats supported by pspp.

Basic Numeric Formats
.....................

The basic numeric formats are used for input and output of real numbers in standard or scientific notation.  The following table shows an example of how each format displays positive and negative numbers with the default decimal point setting:

Format    3141.59     -3141.59
F8.2          3141.59     -3141.59
COMMA9.2      3,141.59    -3,141.59
DOT9.2        3.141,59    -3.141,59
DOLLAR10.2    $3,141.59   -$3,141.59
PCT9.2        3141.59%    -3141.59%
E8.1          3.1E+003    -3.1E+003

On output, numbers in F format are expressed in standard decimal notation with the requested number of decimal places.  The other formats output some variation on this style:

  * Numbers in COMMA format are additionally grouped every three digits by inserting a grouping character.  The grouping character is ordinarily a comma, but it can be changed to a period (see SET DECIMAL).

  * DOT format is like COMMA format, but it interchanges the role of the decimal point and grouping characters.  That is, the current grouping character is used as a decimal point and vice versa.

  * DOLLAR format is like COMMA format, but it prefixes the number with $.

  * PCT format is like F format, but adds % after the number.

  * The E format always produces output in scientific notation.

On input, the basic numeric formats accept positive and numbers in standard decimal notation or scientific notation.  Leading and trailing spaces are allowed.  An empty or all-spaces field, or one that contains only a single period, is treated as the system missing value.

In scientific notation, the exponent may be introduced by a sign (+ or -), or by one of the letters e or d (in uppercase or lowercase), or by a letter followed by a sign.  A single space may follow the letter or the sign or both.

On fixed-format DATA LIST (see DATA LIST FIXED) and in a few other contexts, decimals are implied when the field does not contain a decimal point.  In F6.5 format, for example, the field 314159 is taken as the value 3.14159 with implied decimals.  Decimals are never implied if an explicit decimal point is present or if scientific notation is used.

E and F formats accept the basic syntax already described.  The other formats allow some additional variations:

  * COMMA, DOLLAR, and DOT formats ignore grouping characters within the integer part of the input field.  The identity of the grouping character depends on the format.

  * DOLLAR format allows a dollar sign to precede the number.  In a negative number, the dollar sign may precede or follow the minus sign.

  * PCT format allows a percent sign to follow the number.

All of the basic number formats have a maximum field width of 40 and accept no more than 16 decimal places, on both input and output.  Some additional restrictions apply:

  * As input formats, the basic numeric formats allow no more decimal places than the field width.  As output formats, the field width must be greater than the number of decimal places; that is, large enough to allow for a decimal point and the number of requested decimal places. DOLLAR and PCT formats must allow an additional column for $ or %.

  * The default output format for a given input format increases the field width enough to make room for optional input characters.  If an input format calls for decimal places, the width is increased by 1 to make room for an implied decimal point.  COMMA, DOT, and DOLLAR formats also increase the output width to make room for grouping characters.  DOLLAR and PCT further increase the output field width by 1 to make room for $ or %.  The increased output width is capped at 40, the maximum field width.

  * The E format is exceptional.  For output, E format has a minimum width of 7 plus the number of decimal places.  The default output format for an E input format is an E format with at least 3 decimal places and thus a minimum width of 10.

More details of basic numeric output formatting are given below:

  * Output rounds to nearest, with ties rounded away from zero.  Thus, 2.5 is output as 3 in F1.0 format, and -1.125 as -1.13 in F5.1 format.

  * The system-missing value is output as a period in a field of spaces, placed in the decimal point's position, or in the rightmost column if no decimal places are requested.  A period is used even if the decimal point character is a comma.

  * A number that does not fill its field is right-justified within the field.

  * A number is too large for its field causes decimal places to be dropped to make room.  If dropping decimals does not make enough room, scientific notation is used if the field is wide enough.  If a number does not fit in the field, even in scientific notation, the overflow is indicated by filling the field with asterisks (*).

  * COMMA, DOT, and DOLLAR formats insert grouping characters only if space is available for all of them.  Grouping characters are never inserted when all decimal places must be dropped.  Thus, 1234.56 in COMMA5.2 format is output as  1235 without a comma, even though there is room for one, because all decimal places were dropped.

  * DOLLAR or PCT format drop the $ or % only if the number would not fit at all without it.  Scientific notation with $ or % is preferred to ordinary decimal notation without it.

  * Except in scientific notation, a decimal point is included only when it is followed by a digit.  If the integer part of the number being output is 0, and a decimal point is included, then pspp ordinarily drops the zero before the decimal point.  However, in F, COMMA, or DOT formats, pspp keeps the zero if SET LEADZERO is set to ON (see SET LEADZERO).

     In scientific notation, the number always includes a decimal point, even if it is not followed by a digit.

  * A negative number includes a minus sign only in the presence of a nonzero digit: -0.01 is output as -.01 in F4.2 format but as .0 in F4.1 format.  Thus, a ``negative zero'' never includes a minus sign.

  * In negative numbers output in DOLLAR format, the dollar sign follows the negative sign.  Thus, -9.99 in DOLLAR6.2 format is output as -$9.99.

  * In scientific notation, the exponent is output as E followed by + or - and exactly three digits.  Numbers with magnitude less than 10**-999 or larger than 10**999 are not supported by most computers, but if they are supported then their output is considered to overflow the field and they are output as asterisks.

  * On most computers, no more than 15 decimal digits are significant in output, even if more are printed.  In any case, output precision cannot be any higher than input precision; few data sets are accurate to 15 digits of precision.  Unavoidable loss of precision in intermediate calculations may also reduce precision of output.

  * Special values such as infinities and ``not a number'' values are usually converted to the system-missing value before printing.  In a few circumstances, these values are output directly.  In fields of width 3 or greater, special values are output as however many characters fit from +Infinity or -Infinity for infinities, from NaN for ``not a number,'' or from Unknown for other values (if any are supported by the system).  In fields under 3 columns wide, special values are output as asterisks.

Custom Currency Formats
.......................

The custom currency formats are closely related to the basic numeric formats, but they allow users to customize the output format.  The SET command configures custom currency formats, using the syntax

     SET CCX="STRING".

where X is A, B, C, D, or E, and STRING is no more than 16 characters long.

STRING must contain exactly three commas or exactly three periods (but not both), except that a single quote character may be used to ``escape'' a following comma, period, or single quote.  If three commas are used, commas are used for grouping in output, and a period is used as the decimal point.  Uses of periods reverses these roles.

The commas or periods divide STRING into four fields, called the negative prefix, prefix, suffix, and negative suffix, respectively.  The prefix and suffix are added to output whenever space is available.  The negative prefix and negative suffix are always added to a negative number when the output includes a nonzero digit.

The following syntax shows how custom currency formats could be used to reproduce basic numeric formats:

     SET CCA="-,,,".  /* Same as COMMA.
     SET CCB="-...".  /* Same as DOT.
     SET CCC="-,$,,". /* Same as DOLLAR.
     SET CCD="-,,%,". /* Like PCT, but groups with commas.

Here are some more examples of custom currency formats.  The final example shows how to use a single quote to escape a delimiter:

     SET CCA=",EUR,,-".   /* Euro.
     SET CCB="(,USD ,,)". /* US dollar.
     SET CCC="-.R$..".    /* Brazilian real.
     SET CCD="-,, NIS,".  /* Israel shekel.
     SET CCE="-.Rp'. ..". /* Indonesia Rupiah.

These formats would yield the following output:

Format    3145.59           -3145.59
CCA12.2    EUR3,145.59          EUR3,145.59-
CCB14.2     USD 3,145.59   (USD 3,145.59)
CCC11.2    R$3.145,59           -R$3.145,59
CCD13.2    3,145.59 NIS         -3,145.59 NIS
CCE10.0    Rp. 3.146            -Rp. 3.146

The default for all the custom currency formats is -,,,, equivalent to COMMA format.

Legacy Numeric Formats
......................

The N and Z numeric formats provide compatibility with legacy file formats.  They have much in common:

  * Output is rounded to the nearest representable value, with ties rounded away from zero.

  * Numbers too large to display are output as a field filled with asterisks (*).

  * The decimal point is always implicitly the specified number of digits from the right edge of the field, except that Z format input allows an explicit decimal point.

  * Scientific notation may not be used.

  * The system-missing value is output as a period in a field of spaces. The period is placed just to the right of the implied decimal point in Z format, or at the right end in N format or in Z format if no decimal places are requested.  A period is used even if the decimal point character is a comma.

  * Field width may range from 1 to 40.  Decimal places may range from 0 up to the field width, to a maximum of 16.

  * When a legacy numeric format used for input is converted to an output format, it is changed into the equivalent F format.  The field width is increased by 1 if any decimal places are specified, to make room for a decimal point.  For Z format, the field width is increased by 1 more column, to make room for a negative sign.  The output field width is capped at 40 columns.

N Format
........

The N format supports input and output of fields that contain only digits.  On input, leading or trailing spaces, a decimal point, or any other non-digit character causes the field to be read as the system-missing value.  As a special exception, an N format used on DATA LIST FREE or DATA LIST LIST is treated as the equivalent F format.

On output, N pads the field on the left with zeros.  Negative numbers are output like the system-missing value.

Z Format
........

The Z format is a ``zoned decimal'' format used on IBM mainframes.  Z format encodes the sign as part of the final digit, which must be one of the following:

     0123456789
     {ABCDEFGHI
     }JKLMNOPQR

where the characters in each row represent digits 0 through 9 in order. Characters in the first two rows indicate a positive sign; those in the third indicate a negative sign.

On output, Z fields are padded on the left with spaces.  On input, leading and trailing spaces are ignored.  Any character in an input field other than spaces, the digit characters above, and . causes the field to be read as system-missing.

The decimal point character for input and output is always ., even if the decimal point character is a comma (see SET DECIMAL).

Nonzero, negative values output in Z format are marked as negative even when no nonzero digits are output.  For example, -0.2 is output in Z1.0 format as J.  The ``negative zero'' value supported by most machines is output as positive.

Binary and Hexadecimal Numeric Formats
......................................

The binary and hexadecimal formats are primarily designed for compatibility with existing machine formats, not for human readability. All of them therefore have a F format as default output format.  Some of these formats are only portable between machines with compatible byte ordering (endianness) or floating-point format.

Binary formats use byte values that in text files are interpreted as special control functions, such as carriage return and line feed.  Thus, data in binary formats should not be included in syntax files or read from data files with variable-length records, such as ordinary text files.  They may be read from or written to data files with fixed-length records.  See FILE HANDLE, for information on working with fixed-length records.

P and PK Formats
................

These are binary-coded decimal formats, in which every byte (except the last, in P format) represents two decimal digits.  The most-significant 4 bits of the first byte is the most-significant decimal digit, the least-significant 4 bits of the first byte is the next decimal digit, and so on.

In P format, the most-significant 4 bits of the last byte are the least-significant decimal digit.  The least-significant 4 bits represent the sign: decimal 15 indicates a negative value, decimal 13 indicates a positive value.

Numbers are rounded downward on output.  The system-missing value and numbers outside representable range are output as zero.

The maximum field width is 16.  Decimal places may range from 0 up to the number of decimal digits represented by the field.

The default output format is an F format with twice the input field width, plus one column for a decimal point (if decimal places were requested).

IB and PIB Formats
..................

These are integer binary formats.  IB reads and writes 2's complement binary integers, and PIB reads and writes unsigned binary integers.  The byte ordering is by default the host machine's, but SET RIB may be used to select a specific byte ordering for reading (see SET RIB) and SET WIB, similarly, for writing (see SET WIB).

The maximum field width is 8.  Decimal places may range from 0 up to the number of decimal digits in the largest value representable in the field width.

The default output format is an F format whose width is the number of decimal digits in the largest value representable in the field width, plus 1 if the format has decimal places.

RB Format
.........

This is a binary format for real numbers.  By default it reads and writes the host machine's floating-point format, but SET RRB may be used to select an alternate floating-point format for reading (see SET RRB) and SET WRB, similarly, for writing (see SET WRB).

The recommended field width depends on the floating-point format. NATIVE (the default format), IDL, IDB, VD, VG, and ZL formats should use a field width of 8.  ISL, ISB, VF, and ZS formats should use a field width of 4.  Other field widths do not produce useful results.  The maximum field width is 8.  No decimal places may be specified.

The default output format is F8.2.

PIBHEX and RBHEX Formats
........................

These are hexadecimal formats, for reading and writing binary formats where each byte has been recoded as a pair of hexadecimal digits.

A hexadecimal field consists solely of hexadecimal digits 0...9 and A...F.  Uppercase and lowercase are accepted on input; output is in uppercase.

Other than the hexadecimal representation, these formats are equivalent to PIB and RB formats, respectively.  However, bytes in PIBHEX format are always ordered with the most-significant byte first (big-endian order), regardless of the host machine's native byte order or pspp settings.

Field widths must be even and between 2 and 16.  RBHEX format allows no decimal places; PIBHEX allows as many decimal places as a PIB format with half the given width.

Time and Date Formats
.....................

In pspp, a time is an interval.  The time formats translate between human-friendly descriptions of time intervals and pspp's internal representation of time intervals, which is simply the number of seconds in the interval.  pspp has three time formats:

Time Format   Template                    Example
MTIME      MM:SS.ss               91:17.01
TIME       hh:MM:SS.ss            01:31:17.01
DTIME      DD HH:MM:SS.ss         00 04:31:17.01

A date is a moment in the past or the future.  Internally, pspp represents a date as the number of seconds since the epoch, midnight, Oct. 14, 1582.  The date formats translate between human-readable dates and pspp's numeric representation of dates and times.  pspp has several date formats:

Date Format   Template                    Example
DATE       dd-mmm-yyyy            01-OCT-1978
ADATE      mm/dd/yyyy             10/01/1978
EDATE      dd.mm.yyyy             01.10.1978
JDATE      yyyyjjj                1978274
SDATE      yyyy/mm/dd             1978/10/01
QYR        q Q yyyy               3 Q 1978
MOYR       mmm yyyy               OCT 1978
WKYR       ww WK yyyy             40 WK 1978
DATETIME   dd-mmm-yyyy HH:MM:SS.ss   01-OCT-1978 04:31:17.01
YMDHMS     yyyy-mm-dd HH:MM:SS.ss   1978-01-OCT 04:31:17.01

The templates in the preceding tables describe how the time and date formats are input and output:

dd
     Day of month, from 1 to 31.  Always output as two digits.

mm
mmm
     Month.  In output, mm is output as two digits, mmm as the first three letters of an English month name (January, February, ...).  In input, both of these formats, plus Roman numerals, are accepted.

yyyy
     Year.  In output, DATETIME and YMDHMS always produce 4-digit years; other formats can produce a 2- or 4-digit year.  The century assumed for 2-digit years depends on the EPOCH setting (see SET EPOCH). In output, a year outside the epoch causes the whole field to be filled with asterisks (*).

jjj
     Day of year (Julian day), from 1 to 366.  This is exactly three digits giving the count of days from the start of the year.  January 1 is considered day 1.

q
     Quarter of year, from 1 to 4.  Quarters start on January 1, April 1, July 1, and October 1.

ww
     Week of year, from 1 to 53.  Output as exactly two digits.  January 1 is the first day of week 1.

DD
     Count of days, which may be positive or negative.  Output as at least two digits.

hh
     Count of hours, which may be positive or negative.  Output as at least two digits.

HH
     Hour of day, from 0 to 23.  Output as exactly two digits.

MM
     In MTIME, count of minutes, which may be positive or negative.  Output as at least two digits.

     In other formats, minute of hour, from 0 to 59.  Output as exactly two digits.

SS.ss
     Seconds within minute, from 0 to 59.  The integer part is output as exactly two digits.  On output, seconds and fractional seconds may or may not be included, depending on field width and decimal places.  On input, seconds and fractional seconds are optional.  The DECIMAL setting controls the character accepted and displayed as the decimal point (see SET DECIMAL).

For output, the date and time formats use the delimiters indicated in the table.  For input, date components may be separated by spaces or by one of the characters -, /, ., or ,, and time components may be separated by spaces or :.  On input, the Q separating quarter from year and the WK separating week from year may be uppercase or lowercase, and the spaces around them are optional.

On input, all time and date formats accept any amount of leading and trailing white space.

The maximum width for time and date formats is 40 columns.  Minimum input and output width for each of the time and date formats is shown below:

Format   Min. Input Width   Min. Output Width   Option
DATE   8   9   4-digit year
ADATE   8   8   4-digit year
EDATE   8   8   4-digit year
JDATE   5   5   4-digit year
SDATE   8   8   4-digit year
QYR   4   6   4-digit year
MOYR   6   6   4-digit year
WKYR   6   8   4-digit year
DATETIME   17   17   seconds
YMDHMS   12   16   seconds
MTIME   4   5
TIME   5   5   seconds
DTIME   8   8   seconds

In the table, ``Option'' describes what increased output width enables:

4-digit year
     A field 2 columns wider than the minimum includes a 4-digit year. (DATETIME and YMDHMS formats always include a 4-digit year.)

seconds
     A field 3 columns wider than the minimum includes seconds as well as minutes.  A field 5 columns wider than minimum, or more, can also include a decimal point and fractional seconds (but no more than allowed by the format's decimal places).

For the time and date formats, the default output format is the same as the input format, except that pspp increases the field width, if necessary, to the minimum allowed for output.

Time or dates narrower than the field width are right-justified within the field.

When a time or date exceeds the field width, characters are trimmed from the end until it fits.  This can occur in an unusual situation, e.g. with a year greater than 9999 (which adds an extra digit), or for a negative value on MTIME, TIME, or DTIME (which adds a leading minus sign).

The system-missing value is output as a period at the right end of the field.

Date Component Formats
......................

The WKDAY and MONTH formats provide input and output for the names of weekdays and months, respectively.

On output, these formats convert a number between 1 and 7, for WKDAY, or between 1 and 12, for MONTH, into the English name of a day or month, respectively.  If the name is longer than the field, it is trimmed to fit.  If the name is shorter than the field, it is padded on the right with spaces.  Values outside the valid range, and the system-missing value, are output as all spaces.

On input, English weekday or month names (in uppercase or lowercase) are converted back to their corresponding numbers.  Weekday and month names may be abbreviated to their first 2 or 3 letters, respectively.

The field width may range from 2 to 40, for WKDAY, or from 3 to 40, for MONTH.  No decimal places are allowed.

The default output format is the same as the input format.

String Formats
..............

The A and AHEX formats are the only ones that may be assigned to string variables.  Neither format allows any decimal places.

In A format, the entire field is treated as a string value.  The field width may range from 1 to 32,767, the maximum string width.  The default output format is the same as the input format.

In AHEX format, the field is composed of characters in a string encoded as hex digit pairs.  On output, hex digits are output in uppercase; on input, uppercase and lowercase are both accepted.  The default output format is A format with half the input width.

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 dataset, 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 use a scratch variable in an analysis, use COMPUTE (see COMPUTE) to copy its value into an ordinary variable, then use that ordinary variable in the analysis.

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

data file
     Data files contain raw data in text or binary format.  Data can also be embedded in a syntax file with BEGIN DATA and END DATA.

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.

system file
     System files are binary files that store a dictionary and a set of cases.  GET and SAVE read and write system files.

portable file
     Portable files are files in a text-based format that store a dictionary and a set of cases.  IMPORT and EXPORT read and write portable files.

File Handles
============

A file handle is a reference to a data file, system file, or portable file.  Most often, a file handle is specified as the name of a file as a string, that is, enclosed within ' or ".

A file name string that begins or ends with | is treated as the name of a command to pipe data to or from.  You can use this feature to read data over the network using a program such as curl (e.g. GET '|curl -s -S http://example.com/mydata.sav'), to read compressed data from a file using a program such as zcat (e.g. GET '|zcat mydata.sav.gz'), and for many other purposes.

pspp also supports declaring named file handles with the 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 FILE HANDLE is also required to read data files in binary formats.  See FILE HANDLE, for more information.

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 GET or MATCH FILES, pspp uses the file's contents to decide.  In the context of writing a file, e.g. as an output file for SAVE or AGGREGATE, pspp decides based on the file's name: if it ends in .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 BEGIN DATA and END DATA.  See BEGIN DATA, for more information.

The file to which a file handle refers may be reassigned on a later FILE HANDLE command if it is first closed using CLOSE FILE HANDLE.  See CLOSE FILE HANDLE, for more information.

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 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 end of the command.  This is not necessarily an actual dot in the syntax file (see Commands).

  * 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.