encountered in the input.
@menu
-* ADD DOCUMENT:: Add documentary text to the active file.
+* ADD DOCUMENT:: Add documentary text to the active dataset.
+* CACHE:: Ignored for compatibility.
* CD:: Change the current directory.
* COMMENT:: Document your syntax file.
-* DOCUMENT:: Document the active file.
-* DISPLAY DOCUMENTS:: Display active file documents.
-* DISPLAY FILE LABEL:: Display the active file label.
-* DROP DOCUMENTS:: Remove documents from the active file.
+* DOCUMENT:: Document the active dataset.
+* DISPLAY DOCUMENTS:: Display active dataset documents.
+* DISPLAY FILE LABEL:: Display the active dataset label.
+* DROP DOCUMENTS:: Remove documents from the active dataset.
* ECHO:: Write a string to the output stream.
* ERASE:: Erase a file.
* EXECUTE:: Execute pending transformations.
-* FILE LABEL:: Set the active file's label.
-* FINISH:: Terminate the PSPP session.
+* FILE LABEL:: Set the active dataset's label.
+* FINISH:: Terminate the @pspp{} session.
* HOST:: Temporarily return to the operating system.
* INCLUDE:: Include a file within the current one.
* INSERT:: Insert a file within the current one.
* PERMISSIONS:: Change permissions on a file.
-* SET:: Adjust PSPP runtime parameters.
+* PRESERVE and RESTORE:: Saving settings and restoring them later.
+* SET:: Adjust @pspp{} runtime parameters.
* SHOW:: Display runtime parameters.
* SUBTITLE:: Provide a document subtitle.
* TITLE:: Provide a document title.
@cmd{ADD DOCUMENT} adds one or more lines of descriptive commentary to
-the active file. Documents added in this way are saved to system files.
+the active dataset. Documents added in this way are saved to system files.
They can be viewed using @cmd{SYSFILE INFO} or @cmd{DISPLAY
-DOCUMENTS}. They can be removed from the active file with @cmd{DROP
+DOCUMENTS}. They can be removed from the active dataset with @cmd{DROP
DOCUMENTS}.
Each line of documentary text must be enclosed in quotation marks, and
may not be more than 80 bytes long. @xref{DOCUMENT}.
+@node CACHE
+@section CACHE
+@vindex CACHE
+
+@display
+CACHE.
+@end display
+
+This command is accepted, for compatibility, but it has no effect.
+
@node CD
@section CD
@vindex CD
@end display
@cmd{COMMENT} is ignored. It is used to provide information to
-the author and other readers of the PSPP syntax file.
+the author and other readers of the @pspp{} syntax file.
@cmd{COMMENT} can extend over any number of lines. Don't forget to
terminate it with a dot or a blank line.
@end display
@cmd{DOCUMENT} adds one or more lines of descriptive commentary to the
-active file. Documents added in this way are saved to system files.
+active dataset. Documents added in this way are saved to system files.
They can be viewed using @cmd{SYSFILE INFO} or @cmd{DISPLAY
-DOCUMENTS}. They can be removed from the active file with @cmd{DROP
+DOCUMENTS}. They can be removed from the active dataset with @cmd{DROP
DOCUMENTS}.
Specify the @var{documentary text} following the DOCUMENT keyword.
DISPLAY DOCUMENTS.
@end display
-@cmd{DISPLAY DOCUMENTS} displays the documents in the active file. Each
+@cmd{DISPLAY DOCUMENTS} displays the documents in the active dataset. Each
document is preceded by a line giving the time and date that it was
added. @xref{DOCUMENT}.
@end display
@cmd{DISPLAY FILE LABEL} displays the file label contained in the
-active file,
+active dataset,
if any. @xref{FILE LABEL}.
-This command is a PSPP extension.
+This command is a @pspp{} extension.
@node DROP DOCUMENTS
@section DROP DOCUMENTS
DROP DOCUMENTS.
@end display
-@cmd{DROP DOCUMENTS} removes all documents from the active file.
+@cmd{DROP DOCUMENTS} removes all documents from the active dataset.
New documents can be added with @cmd{DOCUMENT} (@pxref{DOCUMENT}).
-@cmd{DROP DOCUMENTS} changes only the active file. It does not modify any
+@cmd{DROP DOCUMENTS} changes only the active dataset. It does not modify any
system files stored on disk.
@node ECHO
EXECUTE.
@end display
-@cmd{EXECUTE} causes the active file to be read and all pending
+@cmd{EXECUTE} causes the active dataset to be read and all pending
transformations to be executed.
@node FILE LABEL
FILE LABEL file_label.
@end display
-@cmd{FILE LABEL} provides a title for the active file. This
+@cmd{FILE LABEL} provides a title for the active dataset. This
title will be saved into system files and portable files that are
-created during this PSPP run.
+created during this @pspp{} run.
file_label need not be quoted. If quotes are
included, they become part of the file label.
FINISH.
@end display
-@cmd{FINISH} terminates the current PSPP session and returns
+@cmd{FINISH} terminates the current @pspp{} session and returns
control to the operating system.
@node HOST
@display
HOST.
+HOST COMMAND=['command'...].
@end display
-@cmd{HOST} suspends the current PSPP session and temporarily returns control
+@cmd{HOST} suspends the current @pspp{} session and temporarily returns control
to the operating system.
This command cannot be used if the SAFER setting is active.
+If the @subcmd{COMMAND} subcommand is specified, as a sequence of shell
+commands as quoted strings within square brackets, then @pspp{} executes
+them together in a single subshell.
+
+If no subcommands are specified, then @pspp{} invokes an interactive
+subshell.
@node INCLUDE
@section INCLUDE
@vindex INCLUDE
@display
- INCLUDE [FILE=]'file-name'.
+ INCLUDE [FILE=]'file-name' [ENCODING='encoding'].
@end display
-@cmd{INCLUDE} causes the PSPP command processor to read an
+@cmd{INCLUDE} causes the @pspp{} command processor to read an
additional command file as if it were included bodily in the current
command file.
If errors are encountered in the included file, then command processing will
Include files may be nested to any depth, up to the limit of available
memory.
+The @cmd{INSERT} command (@pxref{INSERT}) is a more flexible
+alternative to @cmd{INCLUDE}. An INCLUDE command acts the same as
+INSERT with ERROR=STOP CD=NO SYNTAX=BATCH specified.
-The @cmd{INSERT} command (@pxref{INSERT}) may be used instead of
-@cmd{INCLUDE} if you require more flexible options.
-The syntax
-@example
-INCLUDE FILE=@var{file-name}.
-@end example
-@noindent
-functions identically to
-@example
-INSERT FILE=@var{file-name} ERROR=STOP CD=NO SYNTAX=BATCH.
-@end example
-
+The optional @subcmd{ENCODING} subcommand has the same meaning as on INSERT.
@node INSERT
@section INSERT
INSERT [FILE=]'file-name'
[CD=@{NO,YES@}]
[ERROR=@{CONTINUE,STOP@}]
- [SYNTAX=@{BATCH,INTERACTIVE@}].
+ [SYNTAX=@{BATCH,INTERACTIVE@}]
+ [ENCODING='encoding'].
@end display
@cmd{INSERT} is similar to @cmd{INCLUDE} (@pxref{INCLUDE})
conventions. @xref{Syntax Variants}.
The default setting is @samp{SYNTAX=BATCH}.
+ENCODING optionally specifies the character set used by the included
+file. Its argument, which is not case-sensitive, must be in one of
+the following forms:
+
+@table @asis
+@item @code{Locale}
+The encoding used by the system locale, or as overridden by the SET
+LOCALE command (@pxref{SET}). On Unix systems, environment variables,
+e.g.@: @env{LANG} or @env{LC_ALL}, determine the system locale.
+
+@item IANA character set name
+One of the character set names listed by IANA at
+@uref{http://www.iana.org/assignments/character-sets}. Some examples
+are @code{ASCII} (United States), @code{ISO-8859-1} (western Europe),
+@code{EUC-JP} (Japan), and @code{windows-1252} (Windows). Not all
+systems support all character sets.
+
+@item @code{Auto,@var{encoding}}
+Automatically detects whether a syntax file is encoded in an Unicode
+encoding such as UTF-8, UTF-16, or UTF-32. If it is not, then @pspp{}
+generally assumes that the file is encoded in @var{encoding} (an IANA
+character set name). However, if @var{encoding} is UTF-8, and the
+syntax file is not valid UTF-8, @pspp{} instead assumes that the file
+is encoded in @code{windows-1252}.
+
+For best results, @var{encoding} should be an ASCII-compatible
+encoding (the most common locale encodings are all ASCII-compatible),
+because encodings that are not ASCII compatible cannot be
+automatically distinguished from UTF-8.
+
+@item @code{Auto}
+@item @code{Auto,Locale}
+Automatic detection, as above, with the default encoding taken from
+the system locale or the setting on SET LOCALE.
+@end table
+
+When ENCODING is not specified, the default is taken from the
+@option{--syntax-encoding} command option, if it was specified, and
+otherwise it is @code{Auto}.
+
@node PERMISSIONS
@section PERMISSIONS
@vindex PERMISSIONS
This command cannot be used if the SAFER setting is active.
+@node PRESERVE and RESTORE
+@section PRESERVE and RESTORE
+@vindex PRESERVE
+@vindex RESTORE
+
+@display
+PRESERVE.
+@dots{}
+RESTORE.
+@end display
+
+@cmd{PRESERVE} saves all of the settings that @cmd{SET} (@pxref{SET})
+can adjust. A later @cmd{RESTORE} command restores those settings.
+
+@cmd{PRESERVE} can be nested up to five levels deep.
+
@node SET
@section SET
@vindex SET
/RIB=@{NATIVE,MSBFIRST,LSBFIRST,VAX@}
/RRB=@{NATIVE,ISL,ISB,IDL,IDB,VF,VD,VG,ZS,ZL@}
-(program input)
- /ENDCMD='.'
- /NULLINE=@{ON,OFF@}
-
(interaction)
- /CPROMPT='cprompt_string'
- /DPROMPT='dprompt_string'
- /ERRORBREAK=@{OFF,ON@}
/MXERRS=max_errs
/MXWARNS=max_warnings
- /PROMPT='prompt'
/WORKSPACE=workspace_size
-(program execution)
+(syntax execution)
+ /LOCALE='locale'
/MEXPAND=@{ON,OFF@}
/MITERATE=max_iterations
/MNEST=max_nest
/WRB=@{NATIVE,ISL,ISB,IDL,IDB,VF,VD,VG,ZS,ZL@}
(output routing)
- /ECHO=@{ON,OFF@}
/ERRORS=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}
- /INCLUDE=@{ON,OFF@}
/MESSAGES=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}
- /PRINTBACK=@{ON,OFF@}
+ /PRINTBACK=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}
/RESULTS=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}
(output driver options)
/HEADERS=@{NO,YES,BLANK@}
/LENGTH=@{NONE,length_in_lines@}
- /LISTING=@{ON,OFF,'file-name'@}
/MORE=@{ON,OFF@}
/WIDTH=@{NARROW,WIDTH,n_characters@}
+ /TNUMBERS=@{VALUES,LABELS,BOTH@}
(logging)
/JOURNAL=@{ON,OFF@} ['file-name']
/BOXSTRING=@{'xxx','xxxxxxxxxxx'@}
/CASE=@{UPPER,UPLOW@}
/CPI=cpi_value
- /DISK=@{ON,OFF@}
/HIGHRES=@{ON,OFF@}
/HISTOGRAM='c'
/LOWRES=@{AUTO,ON,OFF@}
@end display
@cmd{SET} allows the user to adjust several parameters relating to
-PSPP's execution. Since there are many subcommands to this command, its
+@pspp{}'s execution. Since there are many subcommands to this command, its
subcommands will be examined in groups.
-On subcommands that take boolean values, ON and YES are synonym, and
+For subcommands that take boolean values, ON and YES are synonymous,
as are OFF and NO, when used as subcommand values.
The data input subcommands affect the way that data is read from data
@item RIB
@anchor{SET RIB}
-PSPP extension to set the byte ordering (endianness) used for reading
+@pspp{} extension to set the byte ordering (endianness) used for reading
data in IB or PIB format (@pxref{Binary and Hexadecimal Numeric
Formats}). In MSBFIRST ordering, the most-significant byte appears at
the left end of a IB or PIB field. In LSBFIRST ordering, the
least-significant byte appears at the left end. VAX ordering is like
MSBFIRST, except that each pair of bytes is in reverse order. NATIVE,
the default, is equivalent to MSBFIRST or LSBFIRST depending on the
-native format of the machine running PSPP.
+native format of the machine running @pspp{}.
@item RRB
@anchor{SET RRB}
-PSPP extension to set the floating-point format used for reading data in
+@pspp{} extension to set the floating-point format used for reading data in
RB format (@pxref{Binary and Hexadecimal Numeric Formats}). The
possibilities are:
@table @asis
@item NATIVE
-The native format of the machine running PSPP. Equivalent to either IDL
+The native format of the machine running @pspp{}. Equivalent to either IDL
or IDB.
@item ISL
The default is NATIVE.
@end table
-Program input subcommands affect the way that programs are parsed when
-they are typed interactively or run from a command file. They are
-
-@table @asis
-@item ENDCMD
-This is a single character indicating the end of a command. The default
-is @samp{.}. Don't change this.
-
-@item NULLINE
-Whether a blank line is interpreted as ending the current command. The
-default is ON.
-@end table
-
-Interaction subcommands affect the way that PSPP interacts with an
+Interaction subcommands affect the way that @pspp{} interacts with an
online user. The interaction subcommands are
@table @asis
-@item CPROMPT
-The command continuation prompt. The default is @samp{ > }.
-
-@item DPROMPT
-Prompt used when expecting data input within @cmd{BEGIN DATA} (@pxref{BEGIN
-DATA}). The default is @samp{data> }.
-
-@item ERRORBREAK
-Whether an error causes PSPP to stop processing the current command
-file after finishing the current command. The default is OFF.
-
@item MXERRS
-The maximum number of errors before PSPP halts processing of the current
+The maximum number of errors before @pspp{} halts processing of the current
command file. The default is 50.
@item MXWARNS
-The maximum number of warnings + errors before PSPP halts processing the
-current command file. The default is 100.
-
-@item PROMPT
-The command prompt. The default is @samp{PSPP> }.
+The maximum number of warnings + errors before @pspp{} halts processing the
+current command file.
+The special value of zero means that all warning situations should be ignored.
+No warnings will be issued, except a single initial warning advising the user
+that warnings will not be given.
+The default value is 100.
@end table
-Program execution subcommands control the way that PSPP commands
-execute. The program execution subcommands are
+Syntax execution subcommands control the way that @pspp{} commands
+execute. The syntax execution subcommands are
@table @asis
+@item LOCALE
+Overrides the system locale for the purpose of reading and writing
+syntax and data files. The argument should be a locale name in the
+general form @code{language_country.encoding}, where @code{language}
+and @code{country} are 2-character language and country abbreviations,
+respectively, and @code{encoding} is an IANA character set name.
+Example locales are @code{en_US.UTF-8} (UTF-8 encoded English as
+spoken in the United States) and @code{ja_JP.EUC-JP} (EUC-JP encoded
+Japanese as spoken in Japan).
+
@item MEXPAND
@itemx MITERATE
@itemx MNEST
@item MXLOOPS
The maximum number of iterations for an uncontrolled loop (@pxref{LOOP}).
+The default MXLOOPS is 40.
@item SEED
The initial pseudo-random number seed. Set to a real number or to
Currently not used.
@item WORKSPACE
-The maximum amount of memory that PSPP will use to store data being processed.
-If memory in excess of the workspace size is required, then PSPP will start
+The maximum amount of memory that @pspp{} will use to store data being processed.
+If memory in excess of the workspace size is required, then @pspp{} will start
to use temporary files to store the data.
Setting a higher value will, in general, mean procedures will run faster,
but may cause other applications to run slower.
On platforms without virtual memory management, setting a very large workspace
-may cause PSPP to abort.
+may cause @pspp{} to abort.
@cindex workspace
@cindex memory, amount used to store cases
@end table
@item WIB
@anchor{SET WIB}
-PSPP extension to set the byte ordering (endianness) used for writing
+@pspp{} extension to set the byte ordering (endianness) used for writing
data in IB or PIB format (@pxref{Binary and Hexadecimal Numeric
Formats}). In MSBFIRST ordering, the most-significant byte appears at
the left end of a IB or PIB field. In LSBFIRST ordering, the
least-significant byte appears at the left end. VAX ordering is like
MSBFIRST, except that each pair of bytes is in reverse order. NATIVE,
the default, is equivalent to MSBFIRST or LSBFIRST depending on the
-native format of the machine running PSPP.
+native format of the machine running @pspp{}.
@item WRB
@anchor{SET WRB}
-PSPP extension to set the floating-point format used for writing data in
+@pspp{} extension to set the floating-point format used for writing data in
RB format (@pxref{Binary and Hexadecimal Numeric Formats}). The choices
are the same as SET RIB. The default is NATIVE.
@end table
-Output routing subcommands affect where the output of transformations
-and procedures is sent. These subcommands are
+In the @pspp{} text-based interface, the output routing subcommands
+affect where output is sent. The following values are allowed for
+each of these subcommands:
@table @asis
-@item ECHO
+@item OFF
+@item NONE
+Discard this kind of output.
+
+@item TERMINAL
+Write this output to the terminal, but not to listing files and other
+output devices.
+
+@item LISTING
+Write this output to listing files and other output devices, but not
+to the terminal.
-If turned on, commands are written to the listing file as they are read
-from command files. The default is OFF.
+@item ON
+@itemx BOTH
+Write this type of output to all output devices.
+@end table
+
+These output routing subcommands are:
+
+@table @asis
+@item ERRORS
+Applies to error and warning messages. The default is BOTH.
+
+@item MESSAGES
+Applies to notes. The default is BOTH.
-@itemx ERRORS
-@itemx INCLUDE
-@itemx MESSAGES
@item PRINTBACK
+Determines whether the syntax used for input is printed back as part
+of the output. The default is NONE.
+
@item RESULTS
-Currently not used.
+Applies to everything not in one of the above categories, such as the
+results of statistical procedures. The default is BOTH.
@end table
+These subcommands have no effect on output in the @pspp{} GUI
+environment.
+
Output driver option subcommands affect output drivers' settings. These
subcommands are
@table @asis
@item HEADERS
@itemx LENGTH
-@itemx LISTING
@itemx MORE
-@itemx PAGER
@itemx WIDTH
+@itemx TNUMBERS
+The TNUMBERS option sets the way in which values are displayed in output tables.
+The valid settings are VALUES, LABELS and BOTH.
+If TNUMBERS is set to VALUES, then all values are displayed with their literal value
+(which for a numeric value is a number and for a string value an alphanumeric string).
+If TNUMBERS is set to LABELS, then values are displayed using their assigned labels if any.
+(@xref{VALUE LABELS}.)
+If the a value has no label, then it will be displayed using its literal value.
+If TNUMBERS is set to BOTH, then values will be displayed with both their label
+(if any) and their literal value in parenthesis.
@end table
@cindex headers
@cindex length
-@cindex listing
@cindex more
@cindex pager
@cindex width
+@cindex tnumbers
Logging subcommands affect logging of commands executed to external
These subcommands, which are synonyms, control the journal. The
default is ON, which causes commands entered interactively to be
written to the journal file. Commands included from syntax files that
-are included interactively and error messages printed by PSPP are also
+are included interactively and error messages printed by @pspp{} are also
written to the journal file, prefixed by @samp{>}. OFF disables use
of the journal.
@end table
System file subcommands affect the default format of system files
-produced by PSPP. These subcommands are
+produced by @pspp{}. These subcommands are
@table @asis
@item COMPRESSION
If given as a locale name, only the character encoding of the
locale is relevant.
-System files written by PSPP will use this encoding.
-System files read by PSPP, for which the encoding is unknown, will be
+System files written by @pspp{} will use this encoding.
+System files read by @pspp{}, for which the encoding is unknown, will be
interpreted using this encoding.
The full list of valid encodings and locale names/alias are operating system
[CCE]
[COPYING]
[DECIMALS]
- [ENDCMD]
+ [DIRECTORY]
+ [ENVIRONMENT]
[FORMAT]
[LENGTH]
[MXERRS]
[MXLOOPS]
[MXWARNS]
[SCOMPRESSION]
+ [TEMPDIR]
[UNDEFINED]
+ [VERSION]
[WARRANTY]
[WEIGHT]
[WIDTH]
@end display
-@cmd{SHOW} can be used to display the current state of PSPP's execution
+@cmd{SHOW} can be used to display the current state of @pspp{}'s execution
parameters. Parameters that can be changed using @cmd{SET}
(@pxref{SET}), can be examined using @cmd{SHOW} using the subcommand
with the same name. @code{SHOW} supports the following additional
Show all settings.
@item CC
Show all custom currency settings (CCA through CCE).
+@item DIRECTORY
+Shows the current working directory.
+@item ENVIRONMENT
+Shows the operating system details.
+@item TEMPDIR
+Shows the path of the directory where temporary files will be stored.
+@item VERSION
+Shows the version of this installation of @pspp{}.
@item WARRANTY
-Show details of the lack of warranty for PSPP.
-@item COPYING
-Display the terms of PSPP's copyright licence (@pxref{License}).
+Show details of the lack of warranty for @pspp{}.
+@item COPYING / LICENSE
+Display the terms of @pspp{}'s copyright licence (@pxref{License}).
@end table
Specifying @cmd{SHOW} without any subcommands is equivalent to SHOW ALL.
SUBTITLE subtitle_string.
@end display
-@cmd{SUBTITLE} provides a subtitle to a particular PSPP
+@cmd{SUBTITLE} provides a subtitle to a particular @pspp{}
run. This subtitle appears at the top of each output page below the
title, if headers are enabled on the output device.
TITLE title_string.
@end display
-@cmd{TITLE} provides a title to a particular PSPP run.
+@cmd{TITLE} provides a title to a particular @pspp{} run.
This title appears at the top of each output page, if headers are enabled
on the output device.
projects / pspp / blobdiff