pertaining to single respondent is a case.
This chapter examines
the PSPP commands for defining variables and reading and writing data.
+There are alternative commands to read data from predefined sources
+such as system files or databases (@xref{GET, GET DATA}.)
@quotation Note
These commands tell PSPP how to read data, but the data will not
@menu
* BEGIN DATA:: Embed data within a syntax file.
* CLOSE FILE HANDLE:: Close a file handle.
+* DATAFILE ATTRIBUTE:: Set custom attributes on data files.
+* DATASET:: Manage multiple datasets.
* DATA LIST:: Fundamental data reading command.
* END CASE:: Output the current case.
* END FILE:: Terminate the current input program.
* FILE HANDLE:: Support for special file formats.
* INPUT PROGRAM:: Support for complex input programs.
-* LIST:: List cases in the active file.
-* NEW FILE:: Clear the active file and dictionary.
+* LIST:: List cases in the active dataset.
+* NEW FILE:: Clear the active dataset.
* PRINT:: Display values in print formats.
* PRINT EJECT:: Eject the current page then print.
* PRINT SPACE:: Print blank lines.
Afterward
@cmd{FILE HANDLE}.
-If the file handle name refers to a scratch file, then the storage
-associated with the scratch file in memory or on disk will be freed.
-If the scratch file is in use, e.g.@: it has been specified on a
-@cmd{GET} command whose execution has not completed, then freeing is
-delayed until it is no longer in use.
-
The file named INLINE, which represents data entered between @cmd{BEGIN
DATA} and @cmd{END DATA}, cannot be closed. Attempts to close it with
@cmd{CLOSE FILE HANDLE} have no effect.
@cmd{CLOSE FILE HANDLE} is a PSPP extension.
+@node DATAFILE ATTRIBUTE
+@section DATAFILE ATTRIBUTE
+@vindex DATAFILE ATTRIBUTE
+
+@display
+DATAFILE ATTRIBUTE
+ ATTRIBUTE=name('value') [name('value')]@dots{}
+ ATTRIBUTE=name@b{[}index@b{]}('value') [name@b{[}index@b{]}('value')]@dots{}
+ DELETE=name [name]@dots{}
+ DELETE=name@b{[}index@b{]} [name@b{[}index@b{]}]@dots{}
+@end display
+
+@cmd{DATAFILE ATTRIBUTE} adds, modifies, or removes user-defined
+attributes associated with the active dataset. Custom data file
+attributes are not interpreted by PSPP, but they are saved as part of
+system files and may be used by other software that reads them.
+
+Use the ATTRIBUTE subcommand to add or modify a custom data file
+attribute. Specify the name of the attribute as an identifier
+(@pxref{Tokens}), followed by the desired value, in parentheses, as a
+quoted string. Attribute names that begin with @code{$} are reserved
+for PSPP's internal use, and attribute names that begin with @code{@@}
+or @code{$@@} are not displayed by most PSPP commands that display
+other attributes. Other attribute names are not treated specially.
+
+Attributes may also be organized into arrays. To assign to an array
+element, add an integer array index enclosed in square brackets
+(@code{[} and @code{]}) between the attribute name and value. Array
+indexes start at 1, not 0. An attribute array that has a single
+element (number 1) is not distinguished from a non-array attribute.
+
+Use the DELETE subcommand to delete an attribute. Specify an
+attribute name by itself to delete an entire attribute, including all
+array elements for attribute arrays. Specify an attribute name
+followed by an array index in square brackets to delete a single
+element of an attribute array. In the latter case, all the array
+elements numbered higher than the deleted element are shifted down,
+filling the vacated position.
+
+To associate custom attributes with particular variables, instead of
+with the entire active dataset, use @cmd{VARIABLE ATTRIBUTE}
+(@pxref{VARIABLE ATTRIBUTE}) instead.
+
+@cmd{DATAFILE ATTRIBUTE} takes effect immediately. It is not affected
+by conditional and looping structures such as @cmd{DO IF} or
+@cmd{LOOP}.
+
+@node DATASET
+@section DATASET commands
+@vindex DATASET
+
+@display
+DATASET NAME name [WINDOW=@{ASIS,FRONT@}].
+DATASET ACTIVATE name [WINDOW=@{ASIS,FRONT@}].
+DATASET COPY name [WINDOW=@{MINIMIZED,HIDDEN,FRONT@}].
+DATASET DECLARE name [WINDOW=@{MINIMIZED,HIDDEN,FRONT@}].
+DATASET CLOSE @{name,*,ALL@}.
+DATASET DISPLAY.
+@end display
+
+The @cmd{DATASET} commands simplify use of multiple datasets within a
+PSPP session. They allow datasets to be created and destroyed. At
+any given time, most PSPP commands work with a single dataset, called
+the active dataset.
+
+@vindex DATASET NAME
+The DATASET NAME command gives the active dataset the specified name, or
+if it already had a name, it renames it. If another dataset already
+had the given name, that dataset is deleted.
+
+@vindex DATASET ACTIVATE
+The DATASET ACTIVATE command selects the named dataset, which must
+already exist, as the active dataset. Before switching the active
+dataset, any pending transformations are executed, as if @cmd{EXECUTE}
+had been specified. If the active dataset is unnamed before
+switching, then it is deleted and becomes unavailable after switching.
+
+@vindex DATASET COPY
+The DATASET COPY command creates a new dataset with the specified
+name, whose contents are a copy of the active dataset. Any pending
+transformations are executed, as if @cmd{EXECUTE} had been specified,
+before making the copy. If a dataset with the given name already
+exists, it is replaced. If the name is the name of the active
+dataset, then the active dataset becomes unnamed.
+
+@vindex DATASET DECLARE
+The DATASET DECLARE command creates a new dataset that is initially
+``empty,'' that is, it has no dictionary or data. If a dataset with
+the given name already exists, this has no effect. The new dataset
+can be used with commands that support output to a dataset,
+e.g. AGGREGATE (@pxref{AGGREGATE}).
+
+@vindex DATASET CLOSE
+The DATASET CLOSE command deletes a dataset. If the active dataset is
+specified by name, or if @samp{*} is specified, then the active
+dataset becomes unnamed. If a different dataset is specified by name,
+then it is deleted and becomes unavailable. Specifying ALL deletes
+all datasets except for the active dataset, which becomes unnamed.
+
+@vindex DATASET DISPLAY
+The DATASET DISPLAY command lists all the currently defined datasets.
+
+Many DATASET commands accept an optional WINDOW subcommand. In the
+PSPPIRE GUI, the value given for this subcommand influences how the
+dataset's window is displayed. Outside the GUI, the WINDOW subcommand
+has no effect. The valid values are:
+
+@table @asis
+@item ASIS
+Do not change how the window is displayed. This is the default for
+DATASET NAME and DATASET ACTIVATE.
+
+@item FRONT
+Raise the dataset's window to the top. Make it the default dataset
+for running syntax.
+
+@item MINIMIZED
+Display the window ``minimized'' to an icon. Prefer other datasets
+for running syntax. This is the default for DATASET COPY and DATASET
+DECLARE.
+
+@item HIDDEN
+Hide the dataset's window. Prefer other datasets for running syntax.
+@end table
+
@node DATA LIST
@section DATA LIST
@vindex DATA LIST
@display
DATA LIST [FIXED]
@{TABLE,NOTABLE@}
- [FILE='file-name']
+ [FILE='file-name' [ENCODING='encoding']]
[RECORDS=record_count]
[END=end_var]
[SKIP=record_count]
file handle (@pxref{File Handles}). If the FILE subcommand is not used,
then input is assumed to be specified within the command file using
@cmd{BEGIN DATA}@dots{}@cmd{END DATA} (@pxref{BEGIN DATA}).
+The ENCODING subcommand may only be used if the FILE subcommand is also used.
+It specifies the character encoding of the file.
The optional RECORDS subcommand, which takes a single integer as an
argument, is used to specify the number of lines per record. If RECORDS
@itemize @bullet
@item
-@code{NAME}, a 10-character-wide long string variable, in columns 1
+@code{NAME}, a 10-character-wide string variable, in columns 1
through 10.
@item
@code{ID}, a numeric variable, in columns 1-5 of the first record.
@item
-@code{NAME}, a 30-character long string variable, in columns 7-36 of the
+@code{NAME}, a 30-character string variable, in columns 7-36 of the
first record.
@item
-@code{SURNAME}, a 30-character long string variable, in columns 38-67 of
+@code{SURNAME}, a 30-character string variable, in columns 38-67 of
the first record.
@item
-@code{MINITIAL}, a 1-character short string variable, in column 69 of
+@code{MINITIAL}, a 1-character string variable, in column 69 of
the first record.
@item
DATA LIST FREE
[(@{TAB,'c'@}, @dots{})]
[@{NOTABLE,TABLE@}]
- [FILE='file-name']
+ [FILE='file-name' [ENCODING='encoding']]
[SKIP=record_cnt]
/var_spec@dots{}
DATA LIST LIST
[(@{TAB,'c'@}, @dots{})]
[@{NOTABLE,TABLE@}]
- [FILE='file-name']
+ [FILE='file-name' [ENCODING='encoding']]
[SKIP=record_count]
/var_spec@dots{}
/MODE=360
/RECFORM=@{FIXED,VARIABLE,SPANNED@}
[/LRECL=rec_len]
-
-To explicitly declare a scratch handle:
- FILE HANDLE handle_name
- /MODE=SCRATCH
@end display
Use @cmd{FILE HANDLE} to associate a file handle name with a file and
set. Thus, when the host's native character set is based on ASCII,
these fields are effectively padded with character @code{X'80'}. This
wart is implemented for compatibility.
-
-@item
-SCRATCH mode is a PSPP extension that designates the file handle as a
-scratch file handle.
-Its use is usually unnecessary because file handle names that begin with
-@samp{#} are assumed to refer to scratch files. @pxref{File Handles},
-for more information.
@end itemize
The NAME subcommand specifies the name of the file associated with the
@end example
The above example reads data from file @file{a.data}, then from
-@file{b.data}, and concatenates them into a single active file.
+@file{b.data}, and concatenates them into a single active dataset.
@c If you change this example, change the regression test4 in
@c tests/command/input-program.sh to match.
LIST/FORMAT=NUMBERED.
@end example
-The above example causes an active file to be created consisting of 50
+The above example causes an active dataset to be created consisting of 50
random variates between 0 and 10.
@node LIST
LIST
/VARIABLES=var_list
/CASES=FROM start_index TO end_index BY incr_index
- /FORMAT=@{UNNUMBERED,NUMBERED@} @{WRAP,SINGLE@}
- @{NOWEIGHT,WEIGHT@}
+ /FORMAT=@{UNNUMBERED,NUMBERED@} @{WRAP,SINGLE@}
@end display
The @cmd{LIST} procedure prints the values of specified variables to the
The VARIABLES subcommand specifies the variables whose values are to be
printed. Keyword VARIABLES is optional. If VARIABLES subcommand is not
-specified then all variables in the active file are printed.
+specified then all variables in the active dataset are printed.
The CASES subcommand can be used to specify a subset of cases to be
printed. Specify FROM and the case number of the first case to print,
The FORMAT subcommand can be used to change the output format. NUMBERED
will print case numbers along with each case; UNNUMBERED, the default,
causes the case numbers to be omitted. The WRAP and SINGLE settings are
-currently not used. WEIGHT will cause case weights to be printed along
-with variable values; NOWEIGHT, the default, causes case weights to be
-omitted from the output.
+currently not used.
Case numbers start from 1. They are counted after all transformations
have been considered.
NEW FILE.
@end display
-@cmd{NEW FILE} command clears the current active file.
+@cmd{NEW FILE} command clears the dictionary and data from the current
+active dataset.
@node PRINT
@section PRINT
system-missing value as a field filled with spaces. Binary formats
are an exception.
@end itemize
-@setfilename ignored
projects / pspp / blobdiff