* 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.
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
@display
MATCH FILES
/@{FILE,TABLE@}=@{*,'file-name'@}
- /DROP=var_list
- /KEEP=var_list
/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
@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.
-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
-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
-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
-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.
-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
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.
@vindex XEXPORT
@display
-EXPORT
+XEXPORT
/OUTFILE='file-name'
/DIGITS=n
/DROP=var_list
projects / pspp-builds.git / blobdiff