+@c PSPP - a program for statistical analysis.
+@c Copyright (C) 2017 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
* 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.
* PRESERVE and RESTORE:: Saving settings and restoring them later.
* SET:: Adjust @pspp{} runtime parameters.
@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
+@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 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
@display
CD 'new directory' .
-@end display
+@end display
@cmd{CD} changes the current directory. The new directory will become that specified by the command.
@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
DOCUMENTS}. They can be removed from the active dataset with @cmd{DROP
DOCUMENTS}.
-Specify the @var{documentary text} following the @subcmd{DOCUMENT} keyword.
-It is interpreted literally --- any quotes or other punctuation marks
+Specify the @var{documentary text} following the @subcmd{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.
+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
@section ECHO
@vindex ECHO
-@display
+@display
ECHO 'arbitrary text' .
@end display
ERASE FILE @var{file_name}.
@end display
-@cmd{ERASE FILE} deletes a file from the local filesystem.
+@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.
@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}'...].
+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 (@pxref{SET}) 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.
-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.
+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.
-If no subcommands are specified, then @pspp{} invokes an interactive
-subshell.
+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
@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
+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.
[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 @subcmd{CD=YES} is specified, then before including the file, the
current directory will be changed to the directory of the included
-file.
+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
@table @asis
@item @subcmd{LOCALE}
-The encoding used by the system locale, or as overridden by the
+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, e.g.@: @env{LANG} or @env{LC_ALL}, determine the
+environment variables, @i{e.g.}@: @env{LANG} or @env{LC_ALL}, determine the
system locale.
@item @var{charset_name}
@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 will use 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
@vindex PERMISSIONS
/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.
+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 will become
/MXLOOPS=@var{max_loops}
/SEED=@{RANDOM,@var{seed_value}@}
/UNDEFINED=@{WARN,NOWARN@}
+ /FUZZBITS=@var{fuzzbits}
(data output)
/CC@{A,B,C,D,E@}=@{'@var{npre},@var{pre},@var{suf},@var{nsuf}','@var{npre}.@var{pre}.@var{suf}.@var{nsuf}'@}
(output driver options)
/HEADERS=@{NO,YES,BLANK@}
/LENGTH=@{NONE,@var{n_lines}@}
- /MORE=@{ON,OFF@}
/WIDTH=@{NARROW,WIDTH,@var{n_characters}@}
/TNUMBERS=@{VALUES,LABELS,BOTH@}
/TVARS=@{NAMES,LABELS,BOTH@}
@pspp{}'s execution. Since there are many subcommands to this command, its
subcommands will be examined in groups.
-For subcommands that take boolean values, @subcmd{ON} and @subcmd{YES} are synonymous,
+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
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{,} will not be 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}.
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
data in IB or PIB format (@pxref{Binary and Hexadecimal Numeric
@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
@item MXWARNS
The maximum number of warnings + errors before @pspp{} halts processing the
-current command file.
+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.
@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 WORKSPACE
-The maximum amount of memory that @pspp{} will use to store data being processed.
+The maximum amount of memory (in kilobytes) 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,
+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.
default is F8.2. @xref{Input and Output Formats}.
@item WIB
-@anchor{SET WIB}
+@anchor{SET WIB}
@pspp{} extension to set the byte ordering (endianness) used for writing
data in IB or PIB format (@pxref{Binary and Hexadecimal Numeric
@table @asis
@item HEADERS
@itemx LENGTH
-@itemx MORE
@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
+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}.)
@cindex headers
@cindex length
-@cindex more
-@cindex pager
+@cindex pager
@cindex width
@cindex tnumbers
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.
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
[DIRECTORY]
[ENVIRONMENT]
[FORMAT]
+ [FUZZBITS]
[LENGTH]
[MXERRS]
[MXLOOPS]
projects / pspp / blobdiff