+@c PSPP - a program for statistical analysis.
+@c Copyright (C) 2017, 2020 Free Software Foundation, Inc.
+@c Permission is granted to copy, distribute and/or modify this document
+@c under the terms of the GNU Free Documentation License, Version 1.3
+@c or any later version published by the Free Software Foundation;
+@c with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+@c A copy of the license is included in the section entitled "GNU
+@c Free Documentation License".
+@c
@node Utilities
@chapter Utilities
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.
+* OUTPUT:: Modify the appearance of the output.
* 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.
@end menu
@node ADD DOCUMENT
-@comment node-name, next, previous, up
@section ADD DOCUMENT
@vindex ADD DOCUMENT
@display
-ADD DOCUMENT
+ADD DOCUMENT
'line one' 'line two' @dots{} 'last line' .
@end display
-@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.
+@cmd{ADD DOCUMENT} adds one or more lines of descriptive commentary to
+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
+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
CD 'new directory' .
-@end display
+@end display
-@cmd{CD} changes the current directory. The new directory will become that specified by the command.
+@cmd{CD} changes the current directory. The new directory becomes
+that specified by the command.
@node COMMENT
@section COMMENT
@vindex COMMENT
@vindex *
-@display
-Two possibles syntaxes:
- COMMENT comment text @dots{} .
- *comment text @dots{} .
+@display
+Comment commands:
+ COMMENT comment text @dots{} .
+ *comment text @dots{} .
+
+Comments within a line of syntax:
+ FREQUENCIES /VARIABLES=v0 v1 v2. /* All our categorical variables.
@end display
@cmd{COMMENT} is ignored. It is used to provide information to
-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.
+the author and other readers of the @pspp{} syntax file.
+@cmd{COMMENT} can extend over any number of lines. It ends at a dot
+at the end of a line or a blank line. The comment may contain any
+characters.
+PSPP also supports comments within a line of syntax, introduced with
+@samp{/*}. These comments end at the first @samp{*/} or at the end of
+the line, whichever comes first. A line that contains just this kind
+of comment is considered blank and ends the current command.
@node DOCUMENT
@section DOCUMENT
@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.
-It is interpreted literally --- any quotes or other punctuation marks
-will be included in the file.
-You can extend the documentary text over as many lines as necessary.
+Specify the @var{documentary text} following the @subcmd{DOCUMENT} keyword.
+It is interpreted literally---any quotes or other punctuation marks
+are included in the file.
+You can extend the documentary text over as many lines as necessary,
+including blank lines to separate paragraphs.
Lines are truncated at 80 bytes. Don't forget to terminate
-the command with a dot or a blank line. @xref{ADD DOCUMENT}.
+the command with a dot at the end of a line. @xref{ADD DOCUMENT}.
@node DISPLAY DOCUMENTS
@section DISPLAY DOCUMENTS
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
@section ECHO
@vindex ECHO
-@display
+@display
ECHO 'arbitrary text' .
@end display
Use @cmd{ECHO} to write arbitrary text to the output stream. The text should be enclosed in quotation marks following the normal rules for string tokens (@pxref{Tokens}).
@node ERASE
-@comment node-name, next, previous, up
@section ERASE
@vindex ERASE
@display
-ERASE FILE file_name.
+ERASE FILE @var{file_name}.
@end display
-@cmd{ERASE FILE} deletes a file from the local filesystem.
-file_name must be quoted.
-This command cannot be used if the SAFER setting is active.
+@cmd{ERASE FILE} deletes a file from the local file system.
+@var{file_name} must be quoted.
+This command cannot be used if the SAFER (@pxref{SET}) setting is active.
@node EXECUTE
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
@vindex FILE LABEL
@display
-FILE LABEL file_label.
+FILE LABEL @var{file_label}.
@end display
-@cmd{FILE LABEL} provides a title for the active file. This
-title will be saved into system files and portable files that are
-created during this PSPP run.
+@cmd{FILE LABEL} provides a title for the active dataset. This
+title is saved into system files and portable files that are
+created during this @pspp{} run.
-file_label need not be quoted. If quotes are
-included, they become part of the file label.
+@var{file_label} should not be quoted.
+If quotes are included, they are literally interpreted and become part of the file label.
@node FINISH
@section FINISH
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
-@comment node-name, next, previous, up
@section HOST
@vindex HOST
+In the syntax below, the square brackets must be included in the
+command syntax and do not indicate that that their contents are
+optional.
+
@display
-HOST.
+HOST COMMAND=['@var{command}'...]
+ TIMELIMIT=@var{secs}.
@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.
+@cmd{HOST} executes one or more commands, each provided as a string in
+the required @subcmd{COMMAND} subcommand, in the shell of the
+underlying operating system. PSPP runs each command in a separate
+shell process and waits for it to finish before running the next one.
+If a command fails (with a nonzero exit status, or because it is
+killed by a signal), then PSPP does not run any remaining commands.
+
+PSPP provides @file{/dev/null} as the shell's standard input. If a
+process needs to read from stdin, redirect from a file or device, or
+use a pipe.
+
+PSPP displays the shell's standard output and standard error as PSPP
+output. Redirect to a file or @code{/dev/null} or another device if
+this is not desired.
+The following example runs @code{rsync} to copy a file from a remote
+server to the local file @file{data.txt}, writing @code{rsync}'s own
+output to @file{rsync-log.txt}. PSPP displays the command's error
+output, if any. If @code{rsync} needs to prompt the user (@i{e.g.}@: to
+obtain a password), the command fails. Only if the @code{rsync}
+succeeds, PSPP then runs the @code{sha512sum} command.
+
+@example
+HOST COMMAND=['rsync remote:data.txt data.txt > rsync-log.txt'
+ 'sha512sum -c data.txt.sha512sum].
+@end example
+
+By default, PSPP waits as long as necessary for the series of commands
+to complete. Use the optional @subcmd{TIMELIMIT} subcommand to limit
+the execution time to the specified number of seconds.
+
+PSPP built for mingw does not support all the features of
+@subcmd{HOST}.
+
+PSPP rejects this command if the SAFER (@pxref{SET}) setting is
+active.
@node INCLUDE
@section INCLUDE
@vindex INCLUDE
@display
- INCLUDE [FILE=]'file-name'.
+ INCLUDE [FILE=]'@var{file_name}' [ENCODING='@var{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
-stop and no more commands will be processed.
+If errors are encountered in the included file, then command
+processing stops and no more commands are 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 @cmd{INCLUDE} command acts the same as
+@cmd{INSERT} with @subcmd{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 with @cmd{INSERT}.
@node INSERT
@section INSERT
@vindex INSERT
@display
- INSERT [FILE=]'file-name'
+ INSERT [FILE=]'@var{file_name}'
[CD=@{NO,YES@}]
[ERROR=@{CONTINUE,STOP@}]
- [SYNTAX=@{BATCH,INTERACTIVE@}].
+ [SYNTAX=@{BATCH,INTERACTIVE@}]
+ [ENCODING=@{LOCALE, '@var{charset_name}'@}].
@end display
-@cmd{INSERT} is similar to @cmd{INCLUDE} (@pxref{INCLUDE})
+@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
+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.
+If @subcmd{CD=YES} is specified, then before including the file, the
+current directory becomes the directory of the included
+file.
The default setting is @samp{CD=NO}.
-Note that this directory will remain current until it is
+Note that this directory remains 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
+It does 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 @subcmd{ERROR=STOP} is specified, errors encountered in the
+inserted file causes processing to immediately cease.
+Otherwise processing continues at the next command.
+The default setting is @subcmd{ERROR=CONTINUE}.
-If @samp{SYNTAX=INTERACTIVE} is specified then the syntax contained in
+If @subcmd{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}.
+The default setting is @subcmd{SYNTAX=BATCH}.
+
+@subcmd{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 @subcmd{LOCALE}
+The encoding used by the system locale, or as overridden by the
+@cmd{SET} command (@pxref{SET}). On GNU/Linux and other Unix-like systems,
+environment variables, @i{e.g.}@: @env{LANG} or @env{LC_ALL}, determine the
+system locale.
+
+@item @var{charset_name}
+One of the character set names listed by @acronym{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 @acronym{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 @acronym{ASCII}-compatible
+encoding (the most common locale encodings are all @acronym{ASCII}-compatible),
+because encodings that are not @acronym{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 @subcmd{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 OUTPUT
+@section OUTPUT
+@vindex OUTPUT
+@cindex precision, of output
+@cindex decimal places
+
+@display
+OUTPUT MODIFY
+ /SELECT TABLES
+ /TABLECELLS SELECT = [ @var{class}... ]
+ FORMAT = @var{fmt_spec}.
+@end display
+@note{In the above synopsis the characters @samp{[} and @samp{]} are literals.
+They must appear in the syntax to be interpreted.}
+
+@cmd{OUTPUT} changes the appearance of the tables in which results are
+printed. In particular, it can be used to set the format and precision
+to which results are displayed.
+
+After running this command, the default table appearance parameters
+will have been modified and each new output table generated uses
+the new parameters.
+
+Following @code{/TABLECELLS SELECT =} a list of cell classes must
+appear, enclosed in square brackets. This list determines the classes
+of values should be selected for modification. Each class can be:
+
+@table @asis
+@item RESIDUAL
+Residual values. Default: @t{F40.2}.
+
+@item CORRELATION
+Correlations. Default: @t{F40.3}.
+
+@item PERCENT
+Percentages. Default: @t{PCT40.1}.
+
+@item SIGNIFICANCE
+Significance of tests (p-values). Default: @t{F40.3}.
+
+@item COUNT
+Counts or sums of weights. For a weighted data set, the default is
+the weight variable's print format. For an unweighted data set, the
+default is F40.0.
+@end table
+
+For most other numeric values that appear in tables, @code{SET FORMAT}
+may be used to specify the format (@pxref{SET FORMAT}).
+
+The value of @var{fmt_spec} must be a valid output format (@pxref{Input and Output Formats}).
+Note that not all possible formats are meaningful for all classes.
@node PERMISSIONS
@section PERMISSIONS
@display
PERMISSIONS
- FILE='file-name'
+ FILE='@var{file_name}'
/PERMISSIONS = @{READONLY,WRITEABLE@}.
@end display
-@cmd{PERMISSIONS} changes the permissions of a file.
+@cmd{PERMISSIONS} changes the permissions of a file.
There is one mandatory subcommand which specifies the permissions to
-which the file should be changed.
-If you set a file's permission to READONLY, then the file will become
-unwritable either by you or anyone else on the system.
-If you set the permission to WRITEABLE, then the file will become
-writeable by you; the permissions afforded to others will be
-unchanged.
-This command cannot be used if the SAFER setting is active.
+which the file should be changed.
+If you set a file's permission to @subcmd{READONLY}, then the file
+will become unwritable either by you or anyone else on the system.
+If you set the permission to @subcmd{WRITEABLE}, then the file becomes
+writeable by you; the permissions afforded to others are unchanged.
+This command cannot be used if the @subcmd{SAFER} (@pxref{SET})
+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
(data input)
/BLANKS=@{SYSMIS,'.',number@}
/DECIMAL=@{DOT,COMMA@}
- /FORMAT=fmt_spec
- /EPOCH=@{AUTOMATIC,year@}
+ /FORMAT=@var{fmt_spec}
+ /EPOCH=@{AUTOMATIC,@var{year}@}
/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)
- /MEXPAND=@{ON,OFF@}
- /MITERATE=max_iterations
- /MNEST=max_nest
- /MPRINT=@{ON,OFF@}
- /MXLOOPS=max_loops
- /SEED=@{RANDOM,seed_value@}
+ /MXERRS=@var{max_errs}
+ /MXWARNS=@var{max_warnings}
+ /WORKSPACE=@var{workspace_size}
+
+(syntax execution)
+ /LOCALE='@var{locale}'
+ /MXLOOPS=@var{max_loops}
+ /SEED=@{RANDOM,@var{seed_value}@}
/UNDEFINED=@{WARN,NOWARN@}
+ /FUZZBITS=@var{fuzzbits}
+ /SCALEMIN=@var{count}
(data output)
- /CC@{A,B,C,D,E@}=@{'npre,pre,suf,nsuf','npre.pre.suf.nsuf'@}
+ /CC@{A,B,C,D,E@}=@{'@var{npre},@var{pre},@var{suf},@var{nsuf}','@var{npre}.@var{pre}.@var{suf}.@var{nsuf}'@}
/DECIMAL=@{DOT,COMMA@}
- /FORMAT=fmt_spec
+ /FORMAT=@var{fmt_spec}
+ /LEADZERO=@{ON,OFF@}
+ /MDISPLAY=@{TEXT,TABLES@}
+ /SMALL=@var{number}
/WIB=@{NATIVE,MSBFIRST,LSBFIRST,VAX@}
/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@}
+ /LENGTH=@{NONE,@var{n_lines}@}
+ /WIDTH=@{NARROW,WIDTH,@var{n_characters}@}
+ /TNUMBERS=@{VALUES,LABELS,BOTH@}
+ /TVARS=@{NAMES,LABELS,BOTH@}
+ /TLOOK=@{NONE,@var{file}@}
(logging)
- /JOURNAL=@{ON,OFF@} ['file-name']
+ /JOURNAL=@{ON,OFF@} ['@var{file_name}']
(system files)
- /COMPRESSION=@{ON,OFF@}
/SCOMPRESSION=@{ON,OFF@}
(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@}
- /LPI=lpi_value
- /MENUS=@{STANDARD,EXTENDED@}
- /MXMEMORY=max_memory
- /SCRIPTTAB='c'
- /TB1=@{'xxx','xxxxxxxxxxx'@}
- /TBFONTS='string'
- /XSORT=@{YES,NO@}
+ /LOCALE='@var{string}'
+
+(macros)
+ /MEXPAND=@{ON,OFF@}
+ /MPRINT=@{ON,OFF@}
+ /MITERATE=@var{number}
+ /MNEST=@var{number}
+
+(settings not yet implemented, but accepted and ignored)
+ /BASETEXTDIRECTION=@{AUTOMATIC,RIGHTTOLEFT,LEFTTORIGHT@}
+ /BLOCK='@var{c}'
+ /BOX=@{'@var{xxx}','@var{xxxxxxxxxxx}'@}
+ /CACHE=@{ON,OFF@}
+ /CELLSBREAK=@var{number}
+ /COMPRESSION=@{ON,OFF@}
+ /CMPTRANS=@{ON,OFF@}
+ /HEADER=@{NO,YES,BLANK@}
@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
-subcommands will be examined in groups.
+@pspp{}'s execution. Since there are many subcommands to this command, its
+subcommands are examined in groups.
-On subcommands that take boolean values, ON and YES are synonym, and
-as are OFF and NO, when used as subcommand values.
+For subcommands that take boolean values, @subcmd{ON} and @subcmd{YES} are synonymous,
+as are @subcmd{OFF} and @subcmd{NO}, when used as subcommand values.
The data input subcommands affect the way that data is read from data
files. The data input subcommands are
@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
+contains only white space. An argument of SYSMIS or '.' causes the
system-missing value to be assigned to null items. This is the
default. Any real value may be assigned.
@item DECIMAL
@anchor{SET DECIMAL}
-This value may be set to DOT or COMMA.
-Setting it to DOT causes the decimal point character to be
+This value may be set to @subcmd{DOT} or @subcmd{COMMA}.
+Setting it to @subcmd{DOT} causes the decimal point character to be
@samp{.} and the grouping character to be @samp{,}.
-Setting it to COMMA
+Setting it to @subcmd{COMMA}
causes the decimal point character to be @samp{,} and the grouping
character to be @samp{.}.
+If the setting is @subcmd{COMMA}, then @samp{,} is not treated
+as a field separator in the @cmd{DATA LIST} command (@pxref{DATA LIST}).
The default value is determined from the system locale.
@item FORMAT
+@anchor{SET FORMAT}
Allows the default numeric input/output format to be specified. The
default is F8.2. @xref{Input and Output Formats}.
data file or used in a date construction expression (@pxref{Date
Construction}). If a 4-digit year is specified for the epoch, then
2-digit years are interpreted starting from that year, known as the
-epoch. If AUTOMATIC (the default) is specified, then the epoch begins
+epoch. If @subcmd{AUTOMATIC} (the default) is specified, then the epoch begins
69 years before the current date.
@item RIB
-@anchor{SET 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.
+Formats}). In @subcmd{MSBFIRST} ordering, the most-significant byte appears at
+the left end of a IB or PIB field. In @subcmd{LSBFIRST} ordering, the
+least-significant byte appears at the left end. @subcmd{VAX} ordering is like
+@subcmd{MSBFIRST}, except that each pair of bytes is in reverse order. @subcmd{NATIVE},
+the default, is equivalent to @subcmd{MSBFIRST} or @subcmd{LSBFIRST} depending on the
+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
@item ZS
32-bit IBM Z architecture short format hexadecimal floating point, in
-big-endian byte order.
+big-endian byte order.
@item ZL
64-bit IBM Z architecture long format hexadecimal floating point, in
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 are issued, except a single initial warning advising you
+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 MEXPAND
-@itemx MITERATE
-@itemx MNEST
-@itemx MPRINT
-Currently not used.
+@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{@var{language}_@var{country}.@var{encoding}}, where @var{language}
+and @var{country} are 2-character language and country abbreviations,
+respectively, and @var{encoding} is an @acronym{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 MXLOOPS
-The maximum number of iterations for an uncontrolled loop (@pxref{LOOP}).
+@anchor{SET MXLOOPS}
+
+The maximum number of iterations for an uncontrolled loop
+(@pxref{LOOP}), and for any loop in the matrix language (@pxref{Matrix
+LOOP and BREAK Commands}). The default @var{max_loops} is 40.
@item SEED
-The initial pseudo-random number seed. Set to a real number or to
-RANDOM, which will obtain an initial seed from the current time of day.
+@anchor{SET SEED}
+The initial pseudo-random number seed. Set it to a real number or to
+RANDOM, to obtain an initial seed from the current time of day.
@item UNDEFINED
Currently not used.
+@item FUZZBITS
+@anchor{SET FUZZBITS}
+The maximum number of bits of errors in the least-significant places
+to accept for rounding up a value that is almost halfway between two
+possibilities for rounding with the RND operator (@pxref{Miscellaneous
+Mathematics}). The default @var{fuzzbits} is 6.
+
+@item SCALEMIN
+@anchor{SET SCALEMIN}
+The minimum number of distinct valid values for @pspp{} to assume that
+a variable has a scale measurement level. @xref{Measurement Level}.
+
@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.
+The maximum amount of memory (in kilobytes) that @pspp{} uses to
+store data being processed. If memory in excess of the workspace size
+is required, then @pspp{} starts to use temporary files to store
+the data. Setting a higher value means that procedures
+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
details.
@item DECIMAL
-The default DOT setting causes the decimal point character to be
-@samp{.}. A setting of COMMA causes the decimal point character to be
+The default @subcmd{DOT} setting causes the decimal point character to be
+@samp{.}. A setting of @subcmd{COMMA} causes the decimal point character to be
@samp{,}.
@item FORMAT
Allows the default numeric input/output format to be specified. The
default is F8.2. @xref{Input and Output Formats}.
+@item LEADZERO
+@anchor{SET LEADZERO}
+
+Controls whether numbers with magnitude less than one are displayed
+with a zero before the decimal point. For example, with @code{SET
+LEADZERO=OFF}, which is the default, one-half is shown as 0.5, and
+with @code{SET LEADZERO=ON}, it is shown as .5. This setting affects
+only the @code{F}, @code{COMMA}, and @code{DOT} formats.
+
+@item MDISPLAY
+@anchor{SET MDISPLAY}
+
+Controls how the @code{PRINT} command within
+@code{MATRIX}@dots{}@code{END MATRIX} outputs matrices. With the
+default @subcmd{TEXT}, @code{PRINT} outputs matrices as text. Change
+this setting to @code{TABLES} to instead output matrices as pivot
+tables. @xref{Matrix PRINT Command}, for more information.
+
+@item SMALL
+This controls how @pspp{} formats small numbers in pivot tables, in
+cases where @pspp{} does not otherwise have a well-defined format for
+the numbers. When such a number has a magnitude less than the value
+set here, @pspp{} formats the number in scientific notation;
+otherwise, it formats it in standard notation. The default is 0.0001.
+Set a value of 0 to disable scientific notation.
+
@item WIB
-@anchor{SET 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.
+Formats}). In @subcmd{MSBFIRST} ordering, the most-significant byte appears at
+the left end of a IB or PIB field. In @subcmd{LSBFIRST} ordering, the
+least-significant byte appears at the left end. @subcmd{VAX} ordering is like
+@subcmd{MSBFIRST}, except that each pair of bytes is in reverse order. @subcmd{NATIVE},
+the default, is equivalent to @subcmd{MSBFIRST} or @subcmd{LSBFIRST} depending on the
+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.
+are the same as @subcmd{SET RIB}. The default is @subcmd{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 @subcmd{BOTH}.
+
+@item MESSAGES
+Applies to notes. The default is @subcmd{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 @subcmd{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 @subcmd{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 @subcmd{TNUMBERS} option sets the way in which values are displayed in output tables.
+The valid settings are @subcmd{VALUES}, @subcmd{LABELS} and @subcmd{BOTH}.
+If @subcmd{TNUMBERS} is set to @subcmd{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 @subcmd{TNUMBERS} is set to @subcmd{LABELS}, then values are displayed using their assigned labels if any.
+(@xref{VALUE LABELS}.)
+If the value has no label, then the literal value is used for display.
+If @subcmd{TNUMBERS} is set to @subcmd{BOTH}, then values are displayed with both their label
+(if any) and their literal value in parentheses.
+@item TVARS
+The @subcmd{TVARS} option sets the way in which variables are displayed in output tables.
+The valid settings are @subcmd{NAMES}, @subcmd{LABELS} and @subcmd{BOTH}.
+If @subcmd{TVARS} is set to @subcmd{NAMES}, then all variables are displayed using their names.
+If @subcmd{TVARS} is set to @subcmd{LABELS}, then variables are displayed using their label if one
+has been set. If no label has been set, then the name is used.
+(@xref{VARIABLE LABELS}.)
+If @subcmd{TVARS} is set to @subcmd{BOTH}, then variables are displayed with both their label
+(if any) and their name in parentheses.
+@item TLOOK
+The @subcmd{TLOOK} option sets the style used for subsequent table
+output. Specifying @subcmd{NONE} makes @pspp{} use the default
+built-in style. Otherwise, specifying @var{file} makes @pspp{} search
+for an @file{.stt} or @file{.tlo} file in the same way as specifying
+@option{--table-look=@var{file}} the @pspp{} command line (@pxref{Main
+Options}).
@end table
@cindex headers
@cindex length
-@cindex listing
-@cindex more
-@cindex pager
+@cindex pager
@cindex width
+@cindex tnumbers
Logging subcommands affect logging of commands executed to external
@item JOURNAL
@itemx LOG
These subcommands, which are synonyms, control the journal. The
-default is ON, which causes commands entered interactively to be
+default is @subcmd{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
+are included interactively and error messages printed by @pspp{} are also
+written to the journal file, prefixed by @samp{>}. @subcmd{OFF} disables use
of the journal.
The journal is named @file{pspp.jnl} by default. A different name may
@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
-Not currently used.
-
@item SCOMPRESSION
Whether system files created by @cmd{SAVE} or @cmd{XSAVE} are
-compressed by default. The default is ON.
+compressed by default. The default is @subcmd{ON}.
@end table
Security subcommands affect the operations that commands are allowed to
@itemize @bullet
@item
-The ERASE command.
+The @cmd{ERASE} command.
@item
-The HOST command.
+The @cmd{HOST} command.
@item
-The PERMISSIONS command.
+The @cmd{PERMISSIONS} command.
@item
Pipes (file names beginning or ending with @samp{|}).
@end itemize
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
+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{} use this encoding.
+System files read by @pspp{}, for which the encoding is unknown, are
interpreted using this encoding.
The full list of valid encodings and locale names/alias are operating system
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
+Contrary to intuition, this command does not affect any aspect
of the system's locale.
@end table
+The following subcommands affect the interpretation of macros.
+
+@table @asis
+@item MEXPAND
+@anchor{SET MEXPAND}
+Controls whether macros are expanded. The default is ON.
+
+@item MPRINT
+@anchor{SET MPRINT}
+Controls whether the expansion of macros is included in output. This
+is separate from whether command syntax in general is included in
+output. The default is OFF.
+
+@item MITERATE
+@anchor{SET MITERATE}
+Limits the number of iterations executed in @code{!DO} loops within
+macros. This does not affect other language constructs such as
+@cmd{LOOP}. This must be set to a positive integer. The default is
+1000.
+
+@item MNEST
+@anchor{SET MNEST}
+Limits the number of levels of nested macro expansions. This must be
+set to a positive integer. The default is 50.
+@end table
+
+The following subcommands are not yet implemented, but PSPP accepts
+them and ignores the settings.
+
+@table @asis
+@item BASETEXTDIRECTION
+@itemx BLOCK
+@itemx BOX
+@itemx CACHE
+@itemx CELLSBREAK
+@itemx COMPRESSION
+@itemx CMPTRANS
+@itemx HEADER
+@end table
+
@node SHOW
-@comment node-name, next, previous, up
@section SHOW
@vindex SHOW
[CCE]
[COPYING]
[DECIMALS]
- [ENDCMD]
+ [DIRECTORY]
+ [ENVIRONMENT]
[FORMAT]
+ [FUZZBITS]
[LENGTH]
+ [MEXPAND]
+ [MPRINT]
+ [MITERATE]
+ [MNEST]
[MXERRS]
[MXLOOPS]
[MXWARNS]
+ [N]
[SCOMPRESSION]
+ [SYSTEM]
+ [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
+with the same name. @cmd{SHOW} supports the following additional
subcommands:
-@table @code
-@item ALL
+@table @asis
+@item @subcmd{ALL}
Show all settings.
-@item CC
-Show all custom currency settings (CCA through CCE).
-@item WARRANTY
-Show details of the lack of warranty for PSPP.
-@item COPYING
-Display the terms of PSPP's copyright licence (@pxref{License}).
+@item @subcmd{CC}
+Show all custom currency settings (@subcmd{CCA} through @subcmd{CCE}).
+@item @subcmd{DIRECTORY}
+Shows the current working directory.
+@item @subcmd{ENVIRONMENT}
+Shows the operating system details.
+@item @subcmd{N}
+Reports the number of cases in the active dataset. The reported number is not
+weighted. If no dataset is defined, then @samp{Unknown} is reported.
+@item @subcmd{SYSTEM}
+Shows information about how PSPP was built. This information is
+useful in bug reports. @xref{Bugs}, for details.
+@item @subcmd{TEMPDIR}
+Shows the path of the directory where temporary files are stored.
+@item @subcmd{VERSION}
+Shows the version of this installation of @pspp{}.
+@item @subcmd{WARRANTY}
+Show details of the lack of warranty for @pspp{}.
+@item @subcmd{COPYING} / @subcmd{LICENSE}
+Display the terms of @pspp{}'s copyright licence (@pxref{License}).
@end table
-Specifying @cmd{SHOW} without any subcommands is equivalent to SHOW ALL.
+Specifying @cmd{SHOW} without any subcommands is equivalent to @subcmd{SHOW ALL}.
@node SUBTITLE
@section SUBTITLE
@vindex SUBTITLE
@display
-SUBTITLE 'subtitle_string'.
+SUBTITLE '@var{subtitle_string}'.
or
-SUBTITLE subtitle_string.
+SUBTITLE @var{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.
@vindex TITLE
@display
-TITLE 'title_string'.
+TITLE '@var{title_string}'.
or
-TITLE title_string.
+TITLE @var{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