* 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.
+* PRESERVE and RESTORE:: Saving settings and restoring them later.
* SET:: Adjust PSPP runtime parameters.
* SHOW:: Display runtime parameters.
* SUBTITLE:: Provide a document subtitle.
@display
HOST.
+HOST COMMAND=['command'...].
@end display
@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 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
-@vindex @@
@display
-Two possible syntaxes:
- INCLUDE 'file-name'.
- @@file-name.
+ INCLUDE [FILE=]'file-name'.
@end display
@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
+stop and no more commands will be processed.
Include files may be nested to any depth, up to the limit of available
memory.
+
+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
+
+
+@node INSERT
+@section INSERT
+@vindex INSERT
+
+@display
+ INSERT [FILE=]'file-name'
+ [CD=@{NO,YES@}]
+ [ERROR=@{CONTINUE,STOP@}]
+ [SYNTAX=@{BATCH,INTERACTIVE@}].
+@end display
+
+@cmd{INSERT} is similar to @cmd{INCLUDE} (@pxref{INCLUDE})
+but somewhat more flexible.
+It causes the command processor to read a file as if it were embedded in the
+current command file.
+
+If @samp{CD=YES} is specified, then before including the file, the
+current directory will be changed to the directory of the included
+file.
+The default setting is @samp{CD=NO}.
+Note that this directory will remain current until it is
+changed explicitly (with the @cmd{CD} command, or a subsequent
+@cmd{INSERT} command with the @samp{CD=YES} option).
+It will not revert to its original setting even after the included
+file is finished processing.
+
+If @samp{ERROR=STOP} is specified, errors encountered in the
+inserted file will cause processing to immediately cease.
+Otherwise processing will continue at the next command.
+The default setting is @samp{ERROR=CONTINUE}.
+
+If @samp{SYNTAX=INTERACTIVE} is specified then the syntax contained in
+the included file must conform to interactive syntax
+conventions. @xref{Syntax Variants}.
+The default setting is @samp{SYNTAX=BATCH}.
+
@node PERMISSIONS
-@comment node-name, next, previous, up
@section PERMISSIONS
@vindex PERMISSIONS
@cindex mode
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
(interaction)
/CPROMPT='cprompt_string'
/DPROMPT='dprompt_string'
- /ERRORBREAK=@{OFF,ON@}
/MXERRS=max_errs
/MXWARNS=max_warnings
/PROMPT='prompt'
+ /WORKSPACE=workspace_size
(program execution)
/MEXPAND=@{ON,OFF@}
/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@}
/COMPRESSION=@{ON,OFF@}
/SCOMPRESSION=@{ON,OFF@}
-(security)
+(miscellaneous)
/SAFER=ON
+ /LOCALE='string'
+
(obsolete settings accepted for compatibility, but ignored)
/BOXSTRING=@{'xxx','xxxxxxxxxxx'@}
/CASE=@{UPPER,UPLOW@}
/CPI=cpi_value
- /DISK=@{ON,OFF@}
/HIGHRES=@{ON,OFF@}
/HISTOGRAM='c'
/LOWRES=@{AUTO,ON,OFF@}
/SCRIPTTAB='c'
/TB1=@{'xxx','xxxxxxxxxxx'@}
/TBFONTS='string'
- /WORKSPACE=workspace_size
/XSORT=@{YES,NO@}
@end display
@table @asis
@item BLANKS
+@anchor{SET BLANKS}
This is the value assigned to an item data item that is empty or
contains only white space. An argument of SYSMIS or '.' will cause the
system-missing value to be assigned to null items. This is the
@item DECIMAL
@anchor{SET DECIMAL}
-The default DOT setting causes the decimal point character to be
-@samp{.} and the grouping character to be @samp{,}. A setting of COMMA
+This value may be set to DOT or COMMA.
+Setting it to DOT causes the decimal point character to be
+@samp{.} and the grouping character to be @samp{,}.
+Setting it to COMMA
causes the decimal point character to be @samp{,} and the grouping
character to be @samp{.}.
+The default value is determined from the system locale.
@item FORMAT
Allows the default numeric input/output format to be specified. The
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
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.
+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.
@item PROMPT
The command prompt. The default is @samp{PSPP> }.
@item UNDEFINED
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
+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.
+@cindex workspace
+@cindex memory, amount used to store cases
@end table
Data output subcommands affect the format of output data. These
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.
+
+@item ON
+@itemx BOTH
+Write this type of output to all output devices.
+@end table
+
+These output routing subcommands are:
-If turned on, commands are written to the listing file as they are read
-from command files. The default is OFF.
+@table @asis
+@item ERRORS
+Applies to error and warning messages. The default is BOTH.
-@itemx ERRORS
-@itemx INCLUDE
@itemx MESSAGES
-@item PRINTBACK
-@item RESULTS
-Currently not used.
+Applies to notes. The default is BOTH.
+
+@itemx PRINTBACK
+Determines whether the syntax used for input is printed back as part
+of the output. The default is NONE.
+
+@itemx RESULTS
+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
@cindex headers
@cindex length
-@cindex listing
@cindex more
@cindex pager
@cindex width
overwrite files, for instance) but it is an improvement.
When set, this setting cannot be reset during the same session, for
obvious security reasons.
+
+@item LOCALE
+@cindex locale
+@cindex encoding, characters
+This item is used to set the default character encoding.
+The encoding may be specified either as an encoding name or alias
+(see @url{http://www.iana.org/assignments/character-sets}), or
+as a locale name.
+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
+interpreted using this encoding.
+
+The full list of valid encodings and locale names/alias are operating system
+dependent.
+The following are all examples of acceptable syntax on common GNU/Linux
+systems.
+@example
+
+SET LOCALE='iso-8859-1'.
+
+SET LOCALE='ru_RU.cp1251'.
+
+SET LOCALE='japanese'.
+
+@end example
+
+Contrary to the intuition, this command does not affect any aspect
+of the system's locale.
@end table
@node SHOW
Specify a title as a string in quotes. The alternate syntax that did
not require quotes is now obsolete. If it is used then the title is
converted to all uppercase.
-@setfilename ignored