X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=doc%2Futilities.texi;h=8dce637cc89a92b30cc267cedeb47b94d48df48b;hb=refs%2Fheads%2Fctables10;hp=6882aa2165f525aa2b12ae466da5d762eabe95af;hpb=9e0e4996fad6563f0a1ce628b80db5c23ef8279e;p=pspp diff --git a/doc/utilities.texi b/doc/utilities.texi index 6882aa2165..8dce637cc8 100644 --- a/doc/utilities.texi +++ b/doc/utilities.texi @@ -1,3 +1,12 @@ +@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 @@ -9,48 +18,60 @@ they take effect only once, unconditionally, at the time that they are 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 @@ -59,28 +80,36 @@ may not be more than 80 bytes long. @xref{DOCUMENT}. @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 @@ -91,17 +120,18 @@ DOCUMENT @var{documentary_text}. @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 @@ -111,7 +141,7 @@ the command with a dot or a blank line. @xref{ADD DOCUMENT}. 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}. @@ -124,10 +154,10 @@ DISPLAY FILE LABEL. @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 @@ -137,34 +167,33 @@ This command is a PSPP extension. 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 @@ -175,7 +204,7 @@ This command cannot be used if the SAFER setting is active. 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 @@ -183,15 +212,15 @@ transformations to be executed. @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 @@ -201,88 +230,210 @@ included, they become part of the file label. 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 @@ -293,20 +444,36 @@ The default setting is @samp{SYNTAX=BATCH}. @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 @@ -318,90 +485,79 @@ 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} (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} + /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 @@ -410,21 +566,24 @@ 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}. @@ -434,31 +593,31 @@ Specifies the range of years used when a 2-digit year is read from a 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 @@ -488,7 +647,7 @@ order. @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 @@ -500,74 +659,67 @@ formats are only for use with very old input files. 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 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 @@ -587,69 +739,135 @@ Set up custom currency formats. @xref{Custom Currency Formats}, for 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 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. -If turned on, commands are written to the listing file as they are read -from command files. The default is OFF. +@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: + +@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 +@anchor{SET 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 @@ -659,10 +877,10 @@ files. These subcommands are @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 @@ -670,15 +888,12 @@ be specified. @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 @@ -690,11 +905,11 @@ Setting this option disables the following operations: @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 @@ -711,11 +926,11 @@ 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 +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 @@ -723,21 +938,58 @@ 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 +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 @@ -753,49 +1005,73 @@ 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. @@ -808,12 +1084,12 @@ converted to all uppercase. @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.