@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.
+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,
@section ECHO
@vindex ECHO
-@display
+@display
ECHO 'arbitrary text' .
@end display
@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.
+
+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 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 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.
-If no subcommands are specified, then @pspp{} invokes an interactive
-subshell.
+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}
@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
+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
/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
@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
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.
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
@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 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 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
projects / pspp / blobdiff