* automake.mk: Add new file.

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

diff --git a/doc/files.texi b/doc/files.texi
index 479fc0671960cd5a8fb82632239062053eaa7b17..b4bdfb8c0eacaa9a677e6ef2c3b2bef209d1c984 100644 (file)
--- a/doc/files.texi
+++ b/doc/files.texi
@@ -1,4 +1,4 @@
-@node System and Portable Files, Variable Attributes, Data Input and Output, Top
+@node System and Portable Files

 @chapter System Files and Portable Files
 
 The commands in this chapter read, write, and examine system files and
 @chapter System Files and Portable Files
 
 The commands in this chapter read, write, and examine system files and


@@ -8,6 +8,7 @@ portable files.
 * APPLY DICTIONARY::            Apply system file dictionary to active file.
 * EXPORT::                      Write to a portable file.
 * GET::                         Read from a system file.
 * APPLY DICTIONARY::            Apply system file dictionary to active file.
 * EXPORT::                      Write to a portable file.
 * GET::                         Read from a system file.

+* GET DATA::                    Read from foreign files.

 * IMPORT::                      Read from a portable file.
 * MATCH FILES::                 Merge system files.
 * SAVE::                        Write to a system file.
 * IMPORT::                      Read from a portable file.
 * MATCH FILES::                 Merge system files.
 * SAVE::                        Write to a system file.


@@ -156,6 +157,72 @@ is read later, when a procedure is executed.
 Use of @cmd{GET} to read a portable file or scratch file is a PSPP
 extension.
 
 Use of @cmd{GET} to read a portable file or scratch file is a PSPP
 extension.
 

+@node GET DATA
+@section GET DATA
+@vindex GET DATA
+
+@display
+GET DATA /TYPE=gnm
+        /FILE=@{'file-name'@}
+        
+        /SHEET=@{NAME 'sheet-name', INDEX n@}
+        /CELLRANGE=@{RANGE 'range', FULL@}
+        /READNAMES=@{ON, OFF@}
+        /ASSUMEDVARWIDTH=n.
+@end display
+
+The @cmd{GET DATA} command is used to read files and other data sources 
+created by other applications. 
+When this command is executed, the current dictionary and active file are
+replaced  with variables and data read from the specified source.
+The TYPE subcommand is mandatory and determines the type of the file or source to read.
+Currently @samp{gnm} is the only supported type.
+
+@cindex Gnumeric
+@cindex spreadsheet files
+The @samp{gnm} type is used to read spreadsheet files created by 
+Gnumeric (@url{http://gnumeric.org}).
+With this type, the FILE subcommand must be used, to specify the
+spreadsheet file to read.  
+All other subcommands are optional.
+The format of each variable is determined by the format of the spreadsheet 
+cell containing the first datum for the variable.
+If this cell is of string (text) format, then the width of the variable is
+determined from the length of the string it contains, unless the 
+ASSUMEDVARWIDTH subcommand is given.
+
+The SHEET subcommand specifies the sheet within the spreadsheet file to read.
+There are two forms of the SHEET subcommand.
+In the first form,
+@samp{/SHEET=name @var{sheet-name}}, the string @var{sheet-name} is the
+name of the sheet to read.
+In the second form, @samp{/SHEET=index @var{idx}}, @var{idx} is a
+integer which is the index of the sheet to read.
+The first sheet has the index 1.
+If the SHEET subcommand is omitted, then the command will read the
+first sheet in the file.
+
+The CELLRANGE subcommand specifies the range of cells within the sheet to read.
+If the subcommand is given as @samp{/CELLRANGE=FULL}, then the entire
+sheet  is read.
+To read only part of a sheet, use the form 
+@samp{/CELLRANGE=range '@var{top-left-cell}:@var{bottom-right-cell}'}.
+For example, the subcommand @samp{/CELLRANGE=range 'C3:P19'} reads 
+columns C--P, and rows 3--19 inclusive.
+If no CELLRANGE subcommand is given, then the entire sheet is read.
+
+If @samp{/READNAMES=ON} is specified, then the contents of cells of
+the first row are used as the names of the variables in which to store
+the data from subsequent rows. 
+If the READNAMES command is omitted, or if @samp{/READNAMES=OFF} is
+used, then the variables  receive automatically assigned names.
+
+The ASSUMEDVARWIDTH subcommand specifies the maximum width of string
+variables read  from the file.
+If omitted, the default value is determined from the length of the 
+string in the first spreadsheet cell for each variable.
+
+

 @node IMPORT
 @section IMPORT
 @vindex IMPORT
 @node IMPORT
 @section IMPORT
 @vindex IMPORT


@@ -195,12 +262,12 @@ extension.
 @display
 MATCH FILES
         /@{FILE,TABLE@}=@{*,'file-name'@}
 @display
 MATCH FILES
         /@{FILE,TABLE@}=@{*,'file-name'@}

-        /DROP=var_list
-        /KEEP=var_list

         /RENAME=(src_names=target_names)@dots{}
         /IN=var_name
 
         /RENAME=(src_names=target_names)@dots{}
         /IN=var_name
 

-        /BY var_list
+        /BY=var_list
+        /DROP=var_list
+        /KEEP=var_list

         /FIRST=var_name
         /LAST=var_name
         /MAP
         /FIRST=var_name
         /LAST=var_name
         /MAP


@@ -208,38 +275,33 @@ MATCH FILES
 
 @cmd{MATCH FILES} merges one or more system, portable, or scratch files,
 optionally
 
 @cmd{MATCH FILES} merges one or more system, portable, or scratch files,
 optionally

-including the active file.  Records with the same values for BY
-variables are combined into a single record.  Records with different
+including the active file.  Cases with the same values for BY
+variables are combined into a single case.  Cases with different

 values are output in order.  Thus, multiple sorted files are
 combined into a single sorted file based on the value of the BY
 variables.  The results of the merge become the new active file.
 
 values are output in order.  Thus, multiple sorted files are
 combined into a single sorted file based on the value of the BY
 variables.  The results of the merge become the new active file.
 

-The BY subcommand specifies a list of variables that are used to match
-records from each of the files.  Variables specified must exist
-in all the files specified on FILE and TABLE.  BY should usually be
-specified.  If TABLE or IN is used then BY is required.
-

 Specify FILE with a system, portable, or scratch file as a file name
 string or file handle
 (@pxref{File Handles}), or with an asterisk (@samp{*}) to
 indicate the current active file.  The files specified on FILE are
 merged together based on the BY variables, or combined case-by-case if
 Specify FILE with a system, portable, or scratch file as a file name
 string or file handle
 (@pxref{File Handles}), or with an asterisk (@samp{*}) to
 indicate the current active file.  The files specified on FILE are
 merged together based on the BY variables, or combined case-by-case if

-BY is not specified.  Normally at least two FILE subcommands should be
-specified.
+BY is not specified.

 
 Specify TABLE with a file to use it as a @dfn{table
 
 Specify TABLE with a file to use it as a @dfn{table

-lookup file}.  Records in table lookup files are not used up after
+lookup file}.  Cases in table lookup files are not used up after

 they've been used once.  This means that data in table lookup files can
 they've been used once.  This means that data in table lookup files can

-correspond to any number of records in FILE files.  Table lookup files
+correspond to any number of cases in FILE files.  Table lookup files

 correspond to lookup tables in traditional relational database systems.
 correspond to lookup tables in traditional relational database systems.

-It is incorrect to have records with duplicate BY values in table lookup
-files.
+If a table lookup file contains more than one case with a given set of
+BY variables, only the first case is used.

 
 

-Any number of FILE and TABLE subcommands may be specified.  Each
-instance of FILE or TABLE can be followed by any sequence of DROP,
-KEEP, or RENAME subcommands.  These have the same form and meaning as
-the corresponding subcommands of @cmd{GET} (@pxref{GET}), but apply
-only to variables in the given file.
+Any number of FILE and TABLE subcommands may be specified.
+Ordinarily, at least two FILE subcommands, or one FILE and at least
+one TABLE, should be specified.  Each instance of FILE or TABLE can be
+followed by any sequence of RENAME subcommands.  These have the same
+form and meaning as the corresponding subcommands of @cmd{GET}
+(@pxref{GET}), but apply only to variables in the given file.

 
 Each FILE or TABLE may optionally be followed by an IN subcommand,
 which creates a numeric variable with the specified name and format
 
 Each FILE or TABLE may optionally be followed by an IN subcommand,
 which creates a numeric variable with the specified name and format


@@ -247,11 +309,38 @@ F1.0.  The IN variable takes value 1 in a case if the given file
 contributed a row to the merged file, 0 otherwise.  The DROP, KEEP,
 and RENAME subcommands do not affect IN variables.
 
 contributed a row to the merged file, 0 otherwise.  The DROP, KEEP,
 and RENAME subcommands do not affect IN variables.
 

-Variables belonging to files that are not present for the current case
-are set to the system-missing value for numeric variables or spaces for
-string variables.
+When more than one FILE or TABLE contains a variable with a given
+name, those variables must all have the same type (numeric or string)
+and, for string variables, the same width.  This rules applies to
+variable names after renaming with RENAME; thus, RENAME can be used to
+resolve conflicts.

 
 

-FIRST, LAST, and MAP are currently ignored.
+FILE and TABLE must be specified at the beginning of the command, with
+any RENAME or IN specifications immediately after the corresponding
+FILE or TABLE.  These subcommands are followed by BY, DROP, KEEP,
+FIRST, LAST, and MAP.
+
+The BY subcommand specifies a list of variables that are used to match
+cases from each of the files.  When TABLE or IN is used, BY is
+required; otherwise, it is optional.  When BY is specified, all the
+files named on FILE and TABLE subcommands must be sorted in ascending
+order of the BY variables.  Variables belonging to files that are not
+present for the current case are set to the system-missing value for
+numeric variables or spaces for string variables.
+
+The DROP and KEEP subcommands allow variables to be dropped from or
+reordered within the new active file.  These subcommands have the same
+form and meaning as the corresponding subcommands of @cmd{GET}
+(@pxref{GET}).  They apply to the new active file as a whole, not to
+individual input files.  The variable names specified on DROP and KEEP
+are those after any renaming with RENAME.
+
+The optional FIRST and LAST subcommands name variables that @cmd{MATCH
+FILES} adds to the active file.  The new variables are numeric with
+print and write format F1.0.  The value of the FIRST variable is 1 in
+the first case with a given set of values for the BY variables, and 0
+in other cases.  Similarly, the LAST variable is 1 in the last case
+with a given of BY values, and 0 in other cases.

 
 @cmd{MATCH FILES} may not be specified following @cmd{TEMPORARY}
 (@pxref{TEMPORARY}) if the active file is used as an input source.
 
 @cmd{MATCH FILES} may not be specified following @cmd{TEMPORARY}
 (@pxref{TEMPORARY}) if the active file is used as an input source.


@@ -350,7 +439,7 @@ a system file and displays information on its dictionary.
 @vindex XEXPORT
 
 @display
 @vindex XEXPORT
 
 @display

-EXPORT
+XEXPORT

         /OUTFILE='file-name'
         /DIGITS=n
         /DROP=var_list
         /OUTFILE='file-name'
         /DIGITS=n
         /DROP=var_list


@@ -378,7 +467,7 @@ the data is read by a procedure or procedure-like command.
 
 @xref{EXPORT}, for more information.
 
 
 @xref{EXPORT}, for more information.
 

-@node XSAVE,  , XEXPORT, System and Portable Files
+@node XSAVE

 @section XSAVE
 @vindex XSAVE
 
 @section XSAVE
 @vindex XSAVE