@menu
* ADD DOCUMENT:: Add documentary text to the active file.
+* CACHE:: Ignored for compatibility.
* CD:: Change the current directory.
* COMMENT:: Document your syntax file.
* DOCUMENT:: Document the active file.
* 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.
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
@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' [ENCODING='encoding'].
@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}) 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 optional ENCODING subcommand has the same meaning as on INSERT.
+
+@node INSERT
+@section INSERT
+@vindex INSERT
+
+@display
+ INSERT [FILE=]'file-name'
+ [CD=@{NO,YES@}]
+ [ERROR=@{CONTINUE,STOP@}]
+ [SYNTAX=@{BATCH,INTERACTIVE@}]
+ [ENCODING='encoding'].
+@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}.
+
+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}
+@item @code{Auto,@var{encoding}}
+Automatically detects whether a syntax file is encoded in
+@var{encoding} or in a Unicode encoding such as UTF-8, UTF-16, or
+UTF-32. The @var{encoding} may be an IANA character set name or
+@code{Locale} (the default). Only ASCII compatible encodings can
+automatically be distinguished from UTF-8 (the most common locale
+encodings are all ASCII-compatible).
+@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
-@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
/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@}
/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
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
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
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> }.
+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 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
-If turned on, commands are written to the listing file as they are read
-from command files. The default is OFF.
+These output routing subcommands are:
+
+@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
@table @asis
@item JOURNAL
-@item LOG
-Not currently used.
+@itemx LOG
+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
+written to the journal file, prefixed by @samp{>}. OFF disables use
+of the journal.
+
+The journal is named @file{pspp.jnl} by default. A different name may
+be specified.
@end table
System file subcommands affect the default format of system files
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
[CCE]
[COPYING]
[DECIMALS]
- [ENDCMD]
[FORMAT]
[LENGTH]
[MXERRS]
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
projects / pspp-builds.git / blobdiff