Fixed crash when interactions have no instances

[pspp-builds.git] / doc / language.texi

diff --git a/doc/language.texi b/doc/language.texi
index 5381668c705ad38675c924d2147858a8b2790c82..a5ef4b69d6e338084847b97278a1357d8478ebaa 100644 (file)
--- a/doc/language.texi
+++ b/doc/language.texi
@@ -13,7 +13,7 @@ Later chapters will describe individual commands in detail.
 * Types of Commands::           Commands come in several flavors.
 * Order of Commands::           Commands combine to form syntax files.
 * Missing Observations::        Handling missing observations.
 * Types of Commands::           Commands come in several flavors.
 * Order of Commands::           Commands combine to form syntax files.
 * Missing Observations::        Handling missing observations.

-* Variables::                   The unit of data storage.
+* Datasets::                    Data organization.

 * Files::                       Files used by PSPP.
 * File Handles::                How files are named.
 * BNF::                         How command syntax is described.
 * Files::                       Files used by PSPP.
 * File Handles::                How files are named.
 * BNF::                         How command syntax is described.


@@ -255,7 +255,7 @@ of Commands}, for details.
 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 @dfn{procedure} is any command that causes the
 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 @dfn{procedure} is any command that causes the

-active file (the data) to be read.
+active dataset (the data) to be read.

 @end table
 
 @node Order of Commands
 @end table
 
 @node Order of Commands


@@ -296,7 +296,7 @@ Valid in any state.
 When executed in the initial or procedure state, causes a transition to
 the transformation state.  
 @item
 When executed in the initial or procedure state, causes a transition to
 the transformation state.  
 @item

-Clears the active file if executed in the procedure or transformation
+Clears the active dataset if executed in the procedure or transformation

 state.
 @end itemize
 
 state.
 @end itemize
 


@@ -307,7 +307,7 @@ Invalid in INPUT PROGRAM and FILE TYPE states.
 @item
 Causes a transition to the INPUT PROGRAM state.  
 @item
 @item
 Causes a transition to the INPUT PROGRAM state.  
 @item

-Clears the active file.
+Clears the active dataset.

 @end itemize
 
 @item @cmd{FILE TYPE}
 @end itemize
 
 @item @cmd{FILE TYPE}


@@ -317,7 +317,7 @@ Invalid in INPUT PROGRAM and FILE TYPE states.
 @item
 Causes a transition to the FILE TYPE state.
 @item
 @item
 Causes a transition to the FILE TYPE state.
 @item

-Clears the active file.
+Clears the active dataset.

 @end itemize
 
 @item Other file definition commands
 @end itemize
 
 @item Other file definition commands


@@ -327,7 +327,7 @@ Invalid in INPUT PROGRAM and FILE TYPE states.
 @item
 Cause a transition to the transformation state.
 @item
 @item
 Cause a transition to the transformation state.
 @item

-Clear the active file, except for @cmd{ADD FILES}, @cmd{MATCH FILES},
+Clear the active dataset, except for @cmd{ADD FILES}, @cmd{MATCH FILES},

 and @cmd{UPDATE}.
 @end itemize
 
 and @cmd{UPDATE}.
 @end itemize
 


@@ -380,19 +380,29 @@ 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:
 treated in the same way as the system-missing value.
 
 For more information on missing values, see the following sections:

-@ref{Variables}, @ref{MISSING VALUES}, @ref{Expressions}.  See also the
+@ref{Datasets}, @ref{MISSING VALUES}, @ref{Expressions}.  See also the

 documentation on individual procedures for information on how they
 handle missing values.
 
 documentation on individual procedures for information on how they
 handle missing values.
 

-@node Variables
-@section Variables
-@cindex variables
+@node Datasets
+@section Datasets
+@cindex dataset
+@cindex variable

 @cindex dictionary
 
 @cindex dictionary
 

-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 @dfn{dictionary}.  
-Some details of variables are described in the sections below.
+PSPP works with data organized into @dfn{datasets}.  A dataset
+consists of a set of @dfn{variables}, which taken together are said to
+form a @dfn{dictionary}, and one or more @dfn{cases}, each of which
+has one value for each variable.
+
+At any given time PSPP has exactly one distinguished dataset, called
+the @dfn{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 @cmd{DATASET} commands
+can choose a new active dataset from among those that are open, as
+well as create and destroy datasets (@pxref{DATASET}).
+
+The sections below describe variables in more detail.

 
 @menu
 * Attributes::                  Attributes of variables.
 
 @menu
 * Attributes::                  Attributes of variables.


@@ -530,7 +540,7 @@ System missing value, in format F1.
 
 @cindex @code{$TIME}
 @item $TIME
 
 @cindex @code{$TIME}
 @item $TIME

-Number of seconds between midnight 14 Oct 1582 and the time the active file
+Number of seconds between midnight 14 Oct 1582 and the time the active dataset

 was read, in format F20.
 
 @cindex @code{$WIDTH}
 was read, in format F20.
 
 @cindex @code{$WIDTH}


@@ -576,7 +586,7 @@ 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 @cmd{DATA LIST} that read data or
 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 @cmd{DATA LIST} that read data or

-syntax files into the PSPP active file.
+syntax files into the PSPP active dataset.

 
 Every input format corresponds to a default @dfn{output format} that
 specifies the formatting used when the value is output later.  It is
 
 Every input format corresponds to a default @dfn{output format} that
 specifies the formatting used when the value is output later.  It is


@@ -1254,7 +1264,7 @@ format is A format with half the input width.
 
 @cindex scratch variables
 Most of the time, variables don't retain their values between cases.
 
 @cindex 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,
+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
 @cmd{COMPUTE} or
 another transformation, they're initialized to the system-missing value
 in which case they assume the value read, or, if created with
 @cmd{COMPUTE} or
 another transformation, they're initialized to the system-missing value


@@ -1307,14 +1317,6 @@ 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.
 
 statistical procedures.  The output files may be in any number of formats,
 depending on how PSPP is configured.
 

-@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 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
 @cindex system file
 @cindex file, system
 @item system file


@@ -1327,24 +1329,14 @@ cases.  @cmd{GET} and @cmd{SAVE} read and write system files.
 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.
 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 File Handles
 @section File Handles
 @cindex file handles
 
 @end table
 
 @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
+A @dfn{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 @samp{'} or
 @samp{"}.
 
 name of a file as a string, that is, enclosed within @samp{'} or
 @samp{"}.
 


@@ -1365,15 +1357,6 @@ 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.
 
 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},
 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},


@@ -1389,8 +1372,7 @@ file'' embedded into the syntax file between @cmd{BEGIN DATA} and
 
 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
 
 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
+HANDLE}.  @xref{CLOSE FILE HANDLE}, for

 more information.
 
 @node BNF
 more information.
 
 @node BNF