CTABLES strings work
[pspp] / doc / utilities.texi
1 @c PSPP - a program for statistical analysis.
2 @c Copyright (C) 2017, 2020 Free Software Foundation, Inc.
3 @c Permission is granted to copy, distribute and/or modify this document
4 @c under the terms of the GNU Free Documentation License, Version 1.3
5 @c or any later version published by the Free Software Foundation;
6 @c with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
7 @c A copy of the license is included in the section entitled "GNU
8 @c Free Documentation License".
9 @c
10 @node Utilities
11 @chapter Utilities
12
13 Commands that don't fit any other category are placed here.
14
15 Most of these commands are not affected by commands like @cmd{IF} and
16 @cmd{LOOP}:
17 they take effect only once, unconditionally, at the time that they are
18 encountered in the input.
19
20 @menu
21 * ADD DOCUMENT::                Add documentary text to the active dataset.
22 * CACHE::                       Ignored for compatibility.
23 * CD::                          Change the current directory.
24 * COMMENT::                     Document your syntax file.
25 * DOCUMENT::                    Document the active dataset.
26 * DISPLAY DOCUMENTS::           Display active dataset documents.
27 * DISPLAY FILE LABEL::          Display the active dataset label.
28 * DROP DOCUMENTS::              Remove documents from the active dataset.
29 * ECHO::                        Write a string to the output stream.
30 * ERASE::                       Erase a file.
31 * EXECUTE::                     Execute pending transformations.
32 * FILE LABEL::                  Set the active dataset's label.
33 * FINISH::                      Terminate the @pspp{} session.
34 * HOST::                        Temporarily return to the operating system.
35 * INCLUDE::                     Include a file within the current one.
36 * INSERT::                      Insert a file within the current one.
37 * OUTPUT::                      Modify the appearance of the output.
38 * PERMISSIONS::                 Change permissions on a file.
39 * PRESERVE and RESTORE::        Saving settings and restoring them later.
40 * SET::                         Adjust @pspp{} runtime parameters.
41 * SHOW::                        Display runtime parameters.
42 * SUBTITLE::                    Provide a document subtitle.
43 * TITLE::                       Provide a document title.
44 @end menu
45
46 @node ADD DOCUMENT
47 @section ADD DOCUMENT
48 @vindex  ADD DOCUMENT
49
50 @display
51 ADD DOCUMENT
52     'line one' 'line two' @dots{} 'last line' .
53 @end display
54
55
56 @cmd{ADD DOCUMENT} adds one or more lines of descriptive commentary to
57 the active dataset.  Documents added in this way are saved to system files.
58 They can be viewed using @cmd{SYSFILE INFO} or @cmd{DISPLAY
59 DOCUMENTS}.  They can be removed from the active dataset with @cmd{DROP
60 DOCUMENTS}.
61
62 Each line of documentary text must be enclosed in quotation marks, and
63 may not be more than 80 bytes long. @xref{DOCUMENT}.
64
65 @node CACHE
66 @section CACHE
67 @vindex CACHE
68
69 @display
70 CACHE.
71 @end display
72
73 This command is accepted, for compatibility, but it has no effect.
74
75 @node CD
76 @section CD
77 @vindex CD
78 @cindex directory
79 @cindex changing directory
80
81 @display
82 CD 'new directory' .
83 @end display
84
85 @cmd{CD} changes the current directory.  The new directory becomes
86 that specified by the command.
87
88 @node COMMENT
89 @section COMMENT
90 @vindex COMMENT
91 @vindex *
92
93 @display
94 Comment commands:
95     COMMENT comment text @dots{} .
96     *comment text @dots{} .
97
98 Comments within a line of syntax:
99     FREQUENCIES /VARIABLES=v0 v1 v2.  /* All our categorical variables.
100 @end display
101
102 @cmd{COMMENT} is ignored.  It is used to provide information to
103 the author and other readers of the @pspp{} syntax file.
104
105 @cmd{COMMENT} can extend over any number of lines.  It ends at a dot
106 at the end of a line or a blank line.  The comment may contain any
107 characters.
108
109 PSPP also supports comments within a line of syntax, introduced with
110 @samp{/*}.  These comments end at the first @samp{*/} or at the end of
111 the line, whichever comes first.  A line that contains just this kind
112 of comment is considered blank and ends the current command.
113
114 @node DOCUMENT
115 @section DOCUMENT
116 @vindex DOCUMENT
117
118 @display
119 DOCUMENT @var{documentary_text}.
120 @end display
121
122 @cmd{DOCUMENT} adds one or more lines of descriptive commentary to the
123 active dataset.  Documents added in this way are saved to system files.
124 They can be viewed using @cmd{SYSFILE INFO} or @cmd{DISPLAY
125 DOCUMENTS}.  They can be removed from the active dataset with @cmd{DROP
126 DOCUMENTS}.
127
128 Specify the @var{documentary text} following the @subcmd{DOCUMENT} keyword.
129 It is interpreted literally---any quotes or other punctuation marks
130 are included in the file.
131 You can extend the documentary text over as many lines as necessary,
132 including blank lines to separate paragraphs.
133 Lines are truncated at 80 bytes.  Don't forget to terminate
134 the command with a dot at the end of a line. @xref{ADD DOCUMENT}.
135
136 @node DISPLAY DOCUMENTS
137 @section DISPLAY DOCUMENTS
138 @vindex DISPLAY DOCUMENTS
139
140 @display
141 DISPLAY DOCUMENTS.
142 @end display
143
144 @cmd{DISPLAY DOCUMENTS} displays the documents in the active dataset.  Each
145 document is preceded by a line giving the time and date that it was
146 added.  @xref{DOCUMENT}.
147
148 @node DISPLAY FILE LABEL
149 @section DISPLAY FILE LABEL
150 @vindex DISPLAY FILE LABEL
151
152 @display
153 DISPLAY FILE LABEL.
154 @end display
155
156 @cmd{DISPLAY FILE LABEL} displays the file label contained in the
157 active dataset,
158 if any.  @xref{FILE LABEL}.
159
160 This command is a @pspp{} extension.
161
162 @node DROP DOCUMENTS
163 @section DROP DOCUMENTS
164 @vindex DROP DOCUMENTS
165
166 @display
167 DROP DOCUMENTS.
168 @end display
169
170 @cmd{DROP DOCUMENTS} removes all documents from the active dataset.
171 New documents can be added with @cmd{DOCUMENT} (@pxref{DOCUMENT}).
172
173 @cmd{DROP DOCUMENTS} changes only the active dataset.  It does not modify any
174 system files stored on disk.
175
176 @node ECHO
177 @section ECHO
178 @vindex ECHO
179
180 @display
181 ECHO 'arbitrary text' .
182 @end display
183
184 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}).
185
186 @node ERASE
187 @section ERASE
188 @vindex ERASE
189
190 @display
191 ERASE FILE @var{file_name}.
192 @end display
193
194 @cmd{ERASE FILE} deletes a file from the local file system.
195 @var{file_name} must be quoted.
196 This command cannot be used if the SAFER (@pxref{SET}) setting is active.
197
198
199 @node EXECUTE
200 @section EXECUTE
201 @vindex EXECUTE
202
203 @display
204 EXECUTE.
205 @end display
206
207 @cmd{EXECUTE} causes the active dataset to be read and all pending
208 transformations to be executed.
209
210 @node FILE LABEL
211 @section FILE LABEL
212 @vindex FILE LABEL
213
214 @display
215 FILE LABEL @var{file_label}.
216 @end display
217
218 @cmd{FILE LABEL} provides a title for the active dataset.  This
219 title is saved into system files and portable files that are
220 created during this @pspp{} run.
221
222 @var{file_label} should not be quoted.
223 If quotes are included, they are literally interpreted and become part of the file label.
224
225 @node FINISH
226 @section FINISH
227 @vindex FINISH
228
229 @display
230 FINISH.
231 @end display
232
233 @cmd{FINISH} terminates the current @pspp{} session and returns
234 control to the operating system.
235
236 @node HOST
237 @section HOST
238 @vindex HOST
239
240 In the syntax below, the square brackets must be included in the
241 command syntax and do not indicate that that their contents are
242 optional.
243
244 @display
245 HOST COMMAND=['@var{command}'...]
246      TIMELIMIT=@var{secs}.
247 @end display
248
249 @cmd{HOST} executes one or more commands, each provided as a string in
250 the required @subcmd{COMMAND} subcommand, in the shell of the
251 underlying operating system.  PSPP runs each command in a separate
252 shell process and waits for it to finish before running the next one.
253 If a command fails (with a nonzero exit status, or because it is
254 killed by a signal), then PSPP does not run any remaining commands.
255
256 PSPP provides @file{/dev/null} as the shell's standard input.  If a
257 process needs to read from stdin, redirect from a file or device, or
258 use a pipe.
259
260 PSPP displays the shell's standard output and standard error as PSPP
261 output.  Redirect to a file or @code{/dev/null} or another device if
262 this is not desired.
263
264 The following example runs @code{rsync} to copy a file from a remote
265 server to the local file @file{data.txt}, writing @code{rsync}'s own
266 output to @file{rsync-log.txt}.  PSPP displays the command's error
267 output, if any.  If @code{rsync} needs to prompt the user (@i{e.g.}@: to
268 obtain a password), the command fails.  Only if the @code{rsync}
269 succeeds, PSPP then runs the @code{sha512sum} command.
270
271 @example
272 HOST COMMAND=['rsync remote:data.txt data.txt > rsync-log.txt'
273               'sha512sum -c data.txt.sha512sum].
274 @end example
275
276 By default, PSPP waits as long as necessary for the series of commands
277 to complete.  Use the optional @subcmd{TIMELIMIT} subcommand to limit
278 the execution time to the specified number of seconds.
279
280 PSPP built for mingw does not support all the features of
281 @subcmd{HOST}.
282
283 PSPP rejects this command if the SAFER (@pxref{SET}) setting is
284 active.
285
286 @node INCLUDE
287 @section INCLUDE
288 @vindex INCLUDE
289
290 @display
291         INCLUDE [FILE=]'@var{file_name}' [ENCODING='@var{encoding}'].
292 @end display
293
294 @cmd{INCLUDE} causes the @pspp{} command processor to read an
295 additional command file as if it were included bodily in the current
296 command file.
297 If errors are encountered in the included file, then command
298 processing stops and no more commands are processed.
299 Include files may be nested to any depth, up to the limit of available
300 memory.
301
302 The @cmd{INSERT} command (@pxref{INSERT}) is a more flexible
303 alternative to @cmd{INCLUDE}.  An @cmd{INCLUDE} command acts the same as
304 @cmd{INSERT} with @subcmd{ERROR=STOP CD=NO SYNTAX=BATCH} specified.
305
306 The optional @subcmd{ENCODING} subcommand has the same meaning as with @cmd{INSERT}.
307
308 @node INSERT
309 @section INSERT
310 @vindex INSERT
311
312 @display
313      INSERT [FILE=]'@var{file_name}'
314         [CD=@{NO,YES@}]
315         [ERROR=@{CONTINUE,STOP@}]
316         [SYNTAX=@{BATCH,INTERACTIVE@}]
317         [ENCODING=@{LOCALE, '@var{charset_name}'@}].
318 @end display
319
320 @cmd{INSERT} is similar to @cmd{INCLUDE} (@pxref{INCLUDE})
321 but somewhat more flexible.
322 It causes the command processor to read a file as if it were embedded in the
323 current command file.
324
325 If @subcmd{CD=YES} is specified, then before including the file, the
326 current directory becomes the directory of the included
327 file.
328 The default setting is @samp{CD=NO}.
329 Note that this directory remains current until it is
330 changed explicitly (with the @cmd{CD} command, or a subsequent
331 @cmd{INSERT} command with the @samp{CD=YES} option).
332 It does not revert to its original setting even after the included
333 file is finished processing.
334
335 If @subcmd{ERROR=STOP} is specified, errors encountered in the
336 inserted file causes processing to immediately cease.
337 Otherwise processing continues at the next command.
338 The default setting is @subcmd{ERROR=CONTINUE}.
339
340 If @subcmd{SYNTAX=INTERACTIVE} is specified then the syntax contained in
341 the included file must conform to interactive syntax
342 conventions. @xref{Syntax Variants}.
343 The default setting is @subcmd{SYNTAX=BATCH}.
344
345 @subcmd{ENCODING} optionally specifies the character set used by the included
346 file.  Its argument, which is not case-sensitive, must be in one of
347 the following forms:
348
349 @table @asis
350 @item @subcmd{LOCALE}
351 The encoding used by the system locale, or as overridden by the
352 @cmd{SET} command (@pxref{SET}).  On GNU/Linux and other Unix-like systems,
353 environment variables, @i{e.g.}@: @env{LANG} or @env{LC_ALL}, determine the
354 system locale.
355
356 @item @var{charset_name}
357 One of the character set names listed by @acronym{IANA} at
358 @uref{http://www.iana.org/assignments/character-sets}.  Some examples
359 are @code{ASCII} (United States), @code{ISO-8859-1} (western Europe),
360 @code{EUC-JP} (Japan), and @code{windows-1252} (Windows).  Not all
361 systems support all character sets.
362
363 @item @code{Auto,@var{encoding}}
364 Automatically detects whether a syntax file is encoded in an Unicode
365 encoding such as UTF-8, UTF-16, or UTF-32.  If it is not, then @pspp{}
366 generally assumes that the file is encoded in @var{encoding} (an @acronym{IANA}
367 character set name).  However, if @var{encoding} is UTF-8, and the
368 syntax file is not valid UTF-8, @pspp{} instead assumes that the file
369 is encoded in @code{windows-1252}.
370
371 For best results, @var{encoding} should be an @acronym{ASCII}-compatible
372 encoding (the most common locale encodings are all @acronym{ASCII}-compatible),
373 because encodings that are not @acronym{ASCII} compatible cannot be
374 automatically distinguished from UTF-8.
375
376 @item @code{Auto}
377 @item @code{Auto,Locale}
378 Automatic detection, as above, with the default encoding taken from
379 the system locale or the setting on @subcmd{SET LOCALE}.
380 @end table
381
382 When ENCODING is not specified, the default is taken from the
383 @option{--syntax-encoding} command option, if it was specified, and
384 otherwise it is @code{Auto}.
385
386 @node OUTPUT
387 @section OUTPUT
388 @vindex OUTPUT
389 @cindex precision, of output
390 @cindex decimal places
391
392 @display
393 OUTPUT MODIFY
394        /SELECT TABLES
395        /TABLECELLS SELECT = [ @var{class}... ]
396                    FORMAT = @var{fmt_spec}.
397 @end display
398 @note{In the above synopsis the characters @samp{[} and @samp{]} are literals.
399 They must appear in the syntax to be interpreted.}
400
401 @cmd{OUTPUT} changes the appearance of the tables in which results are
402 printed. In particular, it can be used to set the format and precision
403 to which results are displayed.
404
405 After running this command, the default table appearance parameters
406 will have been modified and  each new output table generated uses
407 the new parameters.
408
409 Following @code{/TABLECELLS SELECT =} a list of cell classes must
410 appear, enclosed in square brackets.  This list determines the classes
411 of values should be selected for modification. Each class can be:
412
413 @table @asis
414 @item RESIDUAL
415 Residual values.  Default: @t{F40.2}.
416
417 @item CORRELATION
418 Correlations.  Default: @t{F40.3}.
419
420 @item PERCENT
421 Percentages.  Default: @t{PCT40.1}.
422
423 @item SIGNIFICANCE
424 Significance of tests (p-values).  Default: @t{F40.3}.
425
426 @item COUNT
427 Counts or sums of weights.  For a weighted data set, the default is
428 the weight variable's print format.  For an unweighted data set, the
429 default is F40.0.
430 @end table
431
432 For most other numeric values that appear in tables, @code{SET FORMAT}
433 may be used to specify the format (@pxref{SET FORMAT}).
434
435 The value of @var{fmt_spec} must be a valid output format (@pxref{Input and Output Formats}).
436 Note that not all possible formats are meaningful for all classes.
437
438 @node PERMISSIONS
439 @section PERMISSIONS
440 @vindex PERMISSIONS
441 @cindex mode
442 @cindex file mode
443 @cindex changing file permissions
444
445 @display
446 PERMISSIONS
447         FILE='@var{file_name}'
448         /PERMISSIONS = @{READONLY,WRITEABLE@}.
449 @end display
450
451 @cmd{PERMISSIONS} changes the permissions of a file.
452 There is one mandatory subcommand which specifies the permissions to
453 which the file should be changed.
454 If you set a file's  permission  to @subcmd{READONLY}, then the file
455 will become unwritable either by you or anyone else on the system.
456 If you set the permission to @subcmd{WRITEABLE}, then the file becomes
457 writeable by you; the permissions afforded to others are unchanged.
458 This command cannot be used if the @subcmd{SAFER} (@pxref{SET})
459 setting is active.
460
461
462 @node PRESERVE and RESTORE
463 @section PRESERVE and RESTORE
464 @vindex PRESERVE
465 @vindex RESTORE
466
467 @display
468 PRESERVE.
469 @dots{}
470 RESTORE.
471 @end display
472
473 @cmd{PRESERVE} saves all of the settings that @cmd{SET} (@pxref{SET})
474 can adjust.  A later @cmd{RESTORE} command restores those settings.
475
476 @cmd{PRESERVE} can be nested up to five levels deep.
477
478 @node SET
479 @section SET
480 @vindex SET
481
482 @display
483 SET
484
485 (data input)
486         /BLANKS=@{SYSMIS,'.',number@}
487         /DECIMAL=@{DOT,COMMA@}
488         /FORMAT=@var{fmt_spec}
489         /EPOCH=@{AUTOMATIC,@var{year}@}
490         /RIB=@{NATIVE,MSBFIRST,LSBFIRST,VAX@}
491         /RRB=@{NATIVE,ISL,ISB,IDL,IDB,VF,VD,VG,ZS,ZL@}
492
493 (interaction)
494         /MXERRS=@var{max_errs}
495         /MXWARNS=@var{max_warnings}
496         /WORKSPACE=@var{workspace_size}
497
498 (syntax execution)
499         /LOCALE='@var{locale}'
500         /MXLOOPS=@var{max_loops}
501         /SEED=@{RANDOM,@var{seed_value}@}
502         /UNDEFINED=@{WARN,NOWARN@}
503         /FUZZBITS=@var{fuzzbits}
504         /SCALEMIN=@var{count}
505
506 (data output)
507         /CC@{A,B,C,D,E@}=@{'@var{npre},@var{pre},@var{suf},@var{nsuf}','@var{npre}.@var{pre}.@var{suf}.@var{nsuf}'@}
508         /DECIMAL=@{DOT,COMMA@}
509         /FORMAT=@var{fmt_spec}
510         /LEADZERO=@{ON,OFF@}
511         /MDISPLAY=@{TEXT,TABLES@}
512         /SMALL=@var{number}
513         /WIB=@{NATIVE,MSBFIRST,LSBFIRST,VAX@}
514         /WRB=@{NATIVE,ISL,ISB,IDL,IDB,VF,VD,VG,ZS,ZL@}
515
516 (output routing)
517         /ERRORS=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}
518         /MESSAGES=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}
519         /PRINTBACK=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}
520         /RESULTS=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}
521
522 (output driver options)
523         /HEADERS=@{NO,YES,BLANK@}
524         /LENGTH=@{NONE,@var{n_lines}@}
525         /WIDTH=@{NARROW,WIDTH,@var{n_characters}@}
526         /TNUMBERS=@{VALUES,LABELS,BOTH@}
527         /TVARS=@{NAMES,LABELS,BOTH@}
528         /TLOOK=@{NONE,@var{file}@}
529
530 (logging)
531         /JOURNAL=@{ON,OFF@} ['@var{file_name}']
532
533 (system files)
534         /SCOMPRESSION=@{ON,OFF@}
535
536 (miscellaneous)
537         /SAFER=ON
538         /LOCALE='@var{string}'
539
540 (macros)
541         /MEXPAND=@{ON,OFF@}
542         /MPRINT=@{ON,OFF@}
543         /MITERATE=@var{number}
544         /MNEST=@var{number}
545
546 (settings not yet implemented, but accepted and ignored)
547         /BASETEXTDIRECTION=@{AUTOMATIC,RIGHTTOLEFT,LEFTTORIGHT@}
548         /BLOCK='@var{c}'
549         /BOX=@{'@var{xxx}','@var{xxxxxxxxxxx}'@}
550         /CACHE=@{ON,OFF@}
551         /CELLSBREAK=@var{number}
552         /COMPRESSION=@{ON,OFF@}
553         /CMPTRANS=@{ON,OFF@}
554         /HEADER=@{NO,YES,BLANK@}
555 @end display
556
557 @cmd{SET} allows the user to adjust several parameters relating to
558 @pspp{}'s execution.  Since there are many subcommands to this command, its
559 subcommands are examined in groups.
560
561 For subcommands that take boolean values, @subcmd{ON} and @subcmd{YES} are synonymous,
562 as are @subcmd{OFF} and @subcmd{NO}, when used as subcommand values.
563
564 The data input subcommands affect the way that data is read from data
565 files.  The data input subcommands are
566
567 @table @asis
568 @item BLANKS
569 @anchor{SET BLANKS}
570 This is the value assigned to an item data item that is empty or
571 contains only white space.  An argument of SYSMIS or '.'  causes the
572 system-missing value to be assigned to null items.  This is the
573 default.  Any real value may be assigned.
574
575 @item DECIMAL
576 @anchor{SET DECIMAL}
577 This value may be set to @subcmd{DOT} or @subcmd{COMMA}.
578 Setting it to @subcmd{DOT} causes the decimal point character to be
579 @samp{.} and the grouping character to be @samp{,}.
580 Setting it to @subcmd{COMMA}
581 causes the decimal point character to be @samp{,} and the grouping
582 character to be @samp{.}.
583 If the setting is @subcmd{COMMA}, then @samp{,} is not treated
584 as a field separator in the @cmd{DATA LIST} command (@pxref{DATA LIST}).
585 The default value is determined from the system locale.
586
587 @item FORMAT
588 @anchor{SET FORMAT}
589 Allows the default numeric input/output format to be specified.  The
590 default is F8.2.  @xref{Input and Output Formats}.
591
592 @item EPOCH
593 @anchor{SET EPOCH}
594 Specifies the range of years used when a 2-digit year is read from a
595 data file or used in a date construction expression (@pxref{Date
596 Construction}).  If a 4-digit year is specified for the epoch, then
597 2-digit years are interpreted starting from that year, known as the
598 epoch.  If @subcmd{AUTOMATIC} (the default) is specified, then the epoch begins
599 69 years before the current date.
600
601 @item RIB
602 @anchor{SET RIB}
603
604 @pspp{} extension to set the byte ordering (endianness) used for reading
605 data in IB or PIB format (@pxref{Binary and Hexadecimal Numeric
606 Formats}).  In @subcmd{MSBFIRST} ordering, the most-significant byte appears at
607 the left end of a IB or PIB field.  In @subcmd{LSBFIRST} ordering, the
608 least-significant byte appears at the left end.  @subcmd{VAX} ordering is like
609 @subcmd{MSBFIRST}, except that each pair of bytes is in reverse order.  @subcmd{NATIVE},
610 the default, is equivalent to @subcmd{MSBFIRST} or @subcmd{LSBFIRST} depending on the
611 native format of the machine running @pspp{}.
612
613 @item RRB
614 @anchor{SET RRB}
615
616 @pspp{} extension to set the floating-point format used for reading data in
617 RB format (@pxref{Binary and Hexadecimal Numeric Formats}).  The
618 possibilities are:
619
620 @table @asis
621 @item NATIVE
622 The native format of the machine running @pspp{}.  Equivalent to either IDL
623 or IDB.
624
625 @item ISL
626 32-bit IEEE 754 single-precision floating point, in little-endian byte
627 order.
628
629 @item ISB
630 32-bit IEEE 754 single-precision floating point, in big-endian byte
631 order.
632
633 @item IDL
634 64-bit IEEE 754 double-precision floating point, in little-endian byte
635 order.
636
637 @item IDB
638 64-bit IEEE 754 double-precision floating point, in big-endian byte
639 order.
640
641 @item VF
642 32-bit VAX F format, in VAX-endian byte order.
643
644 @item VD
645 64-bit VAX D format, in VAX-endian byte order.
646
647 @item VG
648 64-bit VAX G format, in VAX-endian byte order.
649
650 @item ZS
651 32-bit IBM Z architecture short format hexadecimal floating point, in
652 big-endian byte order.
653
654 @item ZL
655 64-bit IBM Z architecture long format hexadecimal floating point, in
656 big-endian byte order.
657
658 Z architecture also supports IEEE 754 floating point.  The ZS and ZL
659 formats are only for use with very old input files.
660 @end table
661 The default is NATIVE.
662 @end table
663
664 Interaction subcommands affect the way that @pspp{} interacts with an
665 online user.  The interaction subcommands are
666
667 @table @asis
668 @item MXERRS
669 The maximum number of errors before @pspp{} halts processing of the current
670 command file.  The default is 50.
671
672 @item MXWARNS
673 The maximum number of warnings + errors before @pspp{} halts processing the
674 current command file.
675 The special value of zero means that all warning situations should be ignored.
676 No warnings are issued, except a single initial warning advising you
677 that warnings will not be given.
678 The default value is 100.
679 @end table
680
681 Syntax execution subcommands control the way that @pspp{} commands
682 execute.  The syntax execution subcommands are
683
684 @table @asis
685 @item LOCALE
686 Overrides the system locale for the purpose of reading and writing
687 syntax and data files.  The argument should be a locale name in the
688 general form @code{@var{language}_@var{country}.@var{encoding}}, where @var{language}
689 and @var{country} are 2-character language and country abbreviations,
690 respectively, and @var{encoding} is an @acronym{IANA} character set name.
691 Example locales are @code{en_US.UTF-8} (UTF-8 encoded English as
692 spoken in the United States) and @code{ja_JP.EUC-JP} (EUC-JP encoded
693 Japanese as spoken in Japan).
694
695 @item MXLOOPS
696 @anchor{SET MXLOOPS}
697
698 The maximum number of iterations for an uncontrolled loop
699 (@pxref{LOOP}), and for any loop in the matrix language (@pxref{Matrix
700 LOOP and BREAK Commands}).  The default @var{max_loops} is 40.
701
702 @item SEED
703 @anchor{SET SEED}
704 The initial pseudo-random number seed.  Set it to a real number or to
705 RANDOM, to obtain an initial seed from the current time of day.
706
707 @item UNDEFINED
708 Currently not used.
709
710 @item FUZZBITS
711 @anchor{SET FUZZBITS}
712 The maximum number of bits of errors in the least-significant places
713 to accept for rounding up a value that is almost halfway between two
714 possibilities for rounding with the RND operator (@pxref{Miscellaneous
715 Mathematics}).  The default @var{fuzzbits} is 6.
716
717 @item SCALEMIN
718 @anchor{SET SCALEMIN}
719 The minimum number of distinct valid values for @pspp{} to assume that
720 a variable has a scale measurement level.  @xref{Measurement Level}.
721
722 @item WORKSPACE
723 The maximum amount of memory (in kilobytes) that @pspp{} uses to
724 store data being processed.  If memory in excess of the workspace size
725 is required, then @pspp{} starts to use temporary files to store
726 the data.   Setting a higher value means that procedures
727 run faster, but may cause other applications to run slower.
728 On platforms without virtual memory management, setting a very large
729 workspace may cause @pspp{} to abort.
730 @cindex workspace
731 @cindex memory, amount used to store cases
732 @end table
733
734 Data output subcommands affect the format of output data.  These
735 subcommands are
736
737 @table @asis
738 @item CCA
739 @itemx CCB
740 @itemx CCC
741 @itemx CCD
742 @itemx CCE
743 @anchor{CCx Settings}
744
745 Set up custom currency formats.  @xref{Custom Currency Formats}, for
746 details.
747
748 @item DECIMAL
749 The default @subcmd{DOT} setting causes the decimal point character to be
750 @samp{.}.  A setting of @subcmd{COMMA} causes the decimal point character to be
751 @samp{,}.
752
753 @item FORMAT
754 Allows the default numeric input/output format to be specified.  The
755 default is F8.2.  @xref{Input and Output Formats}.
756
757 @item LEADZERO
758 @anchor{SET LEADZERO}
759
760 Controls whether numbers with magnitude less than one are displayed
761 with a zero before the decimal point.  For example, with @code{SET
762 LEADZERO=OFF}, which is the default, one-half is shown as 0.5, and
763 with @code{SET LEADZERO=ON}, it is shown as .5.  This setting affects
764 only the @code{F}, @code{COMMA}, and @code{DOT} formats.
765
766 @item MDISPLAY
767 @anchor{SET MDISPLAY}
768
769 Controls how the @code{PRINT} command within
770 @code{MATRIX}@dots{}@code{END MATRIX} outputs matrices.  With the
771 default @subcmd{TEXT}, @code{PRINT} outputs matrices as text.  Change
772 this setting to @code{TABLES} to instead output matrices as pivot
773 tables.  @xref{Matrix PRINT Command}, for more information.
774
775 @item SMALL
776 This controls how @pspp{} formats small numbers in pivot tables, in
777 cases where @pspp{} does not otherwise have a well-defined format for
778 the numbers.  When such a number has a magnitude less than the value
779 set here, @pspp{} formats the number in scientific notation;
780 otherwise, it formats it in standard notation.  The default is 0.0001.
781 Set a value of 0 to disable scientific notation.
782
783 @item WIB
784 @anchor{SET WIB}
785
786 @pspp{} extension to set the byte ordering (endianness) used for writing
787 data in IB or PIB format (@pxref{Binary and Hexadecimal Numeric
788 Formats}).  In @subcmd{MSBFIRST} ordering, the most-significant byte appears at
789 the left end of a IB or PIB field.  In @subcmd{LSBFIRST} ordering, the
790 least-significant byte appears at the left end.  @subcmd{VAX} ordering is like
791 @subcmd{MSBFIRST}, except that each pair of bytes is in reverse order.  @subcmd{NATIVE},
792 the default, is equivalent to @subcmd{MSBFIRST} or @subcmd{LSBFIRST} depending on the
793 native format of the machine running @pspp{}.
794
795 @item WRB
796 @anchor{SET WRB}
797
798 @pspp{} extension to set the floating-point format used for writing data in
799 RB format (@pxref{Binary and Hexadecimal Numeric Formats}).  The choices
800 are the same as @subcmd{SET RIB}.  The default is @subcmd{NATIVE}.
801 @end table
802
803 In the @pspp{} text-based interface, the output routing subcommands
804 affect where output is sent.  The following values are allowed for
805 each of these subcommands:
806
807 @table @asis
808 @item OFF
809 @item NONE
810 Discard this kind of output.
811
812 @item TERMINAL
813 Write this output to the terminal, but not to listing files and other
814 output devices.
815
816 @item LISTING
817 Write this output to listing files and other output devices, but not
818 to the terminal.
819
820 @item ON
821 @itemx BOTH
822 Write this type of output to all output devices.
823 @end table
824
825 These output routing subcommands are:
826
827 @table @asis
828 @item ERRORS
829 Applies to error and warning messages.  The default is @subcmd{BOTH}.
830
831 @item MESSAGES
832 Applies to notes.  The default is @subcmd{BOTH}.
833
834 @item PRINTBACK
835 Determines whether the syntax used for input is printed back as part
836 of the output.  The default is @subcmd{NONE}.
837
838 @item RESULTS
839 Applies to everything not in one of the above categories, such as the
840 results of statistical procedures.  The default is @subcmd{BOTH}.
841 @end table
842
843 These subcommands have no effect on output in the @pspp{} GUI
844 environment.
845
846 Output driver option subcommands affect output drivers' settings.  These
847 subcommands are
848
849 @table @asis
850 @item HEADERS
851 @itemx LENGTH
852 @itemx WIDTH
853 @itemx TNUMBERS
854 The @subcmd{TNUMBERS} option sets the way in which values are displayed in output tables.
855 The valid settings are @subcmd{VALUES}, @subcmd{LABELS} and @subcmd{BOTH}.
856 If @subcmd{TNUMBERS} is set to @subcmd{VALUES}, then all values are displayed with their literal value
857 (which for a numeric value is a number and for a string value an alphanumeric string).
858 If @subcmd{TNUMBERS} is set to @subcmd{LABELS}, then values are displayed using their assigned labels if any.
859 (@xref{VALUE LABELS}.)
860 If the value has no label, then the literal value is used for display.
861 If @subcmd{TNUMBERS} is set to @subcmd{BOTH}, then values are displayed with both their label
862 (if any) and their literal value in parentheses.
863 @item TVARS
864 @anchor{SET TVARS}
865 The @subcmd{TVARS} option sets the way in which variables are displayed in output tables.
866 The valid settings are @subcmd{NAMES}, @subcmd{LABELS} and @subcmd{BOTH}.
867 If @subcmd{TVARS} is set to @subcmd{NAMES}, then all variables are displayed using their names.
868 If @subcmd{TVARS} is set to @subcmd{LABELS}, then variables are displayed using their label if one
869 has been set.  If no label has been set, then the name is used.
870 (@xref{VARIABLE LABELS}.)
871 If @subcmd{TVARS} is set to @subcmd{BOTH}, then variables are displayed with both their label
872 (if any) and their name in parentheses.
873 @item TLOOK
874 The @subcmd{TLOOK} option sets the style used for subsequent table
875 output.  Specifying @subcmd{NONE} makes @pspp{} use the default
876 built-in style.  Otherwise, specifying @var{file} makes @pspp{} search
877 for an @file{.stt} or @file{.tlo} file in the same way as specifying
878 @option{--table-look=@var{file}} the @pspp{} command line (@pxref{Main
879 Options}).
880 @end table
881
882 @cindex headers
883 @cindex length
884 @cindex pager
885 @cindex width
886 @cindex tnumbers
887
888
889 Logging subcommands affect logging of commands executed to external
890 files.  These subcommands are
891
892 @table @asis
893 @item JOURNAL
894 @itemx LOG
895 These subcommands, which are synonyms, control the journal.  The
896 default is @subcmd{ON}, which causes commands entered interactively to be
897 written to the journal file.  Commands included from syntax files that
898 are included interactively and error messages printed by @pspp{} are also
899 written to the journal file, prefixed by @samp{>}.  @subcmd{OFF} disables use
900 of the journal.
901
902 The journal is named @file{pspp.jnl} by default.  A different name may
903 be specified.
904 @end table
905
906 System file subcommands affect the default format of system files
907 produced by @pspp{}.  These subcommands are
908
909 @table @asis
910 @item SCOMPRESSION
911 Whether system files created by @cmd{SAVE} or @cmd{XSAVE} are
912 compressed by default.  The default is @subcmd{ON}.
913 @end table
914
915 Security subcommands affect the operations that commands are allowed to
916 perform.  The security subcommands are
917
918 @table @asis
919 @item SAFER
920 Setting this option disables the following operations:
921
922 @itemize @bullet
923 @item
924 The @cmd{ERASE} command.
925 @item
926 The @cmd{HOST} command.
927 @item
928 The @cmd{PERMISSIONS} command.
929 @item
930 Pipes (file names beginning or ending with @samp{|}).
931 @end itemize
932
933 Be aware that this setting does not guarantee safety (commands can still
934 overwrite files, for instance) but it is an improvement.
935 When set, this setting cannot be reset during the same session, for
936 obvious security reasons.
937
938 @item LOCALE
939 @cindex locale
940 @cindex encoding, characters
941 This item is used to set the default character encoding.
942 The encoding may be specified either as an encoding name or alias
943 (see @url{http://www.iana.org/assignments/character-sets}), or
944 as a locale name.
945 If given as a locale name, only the character encoding of the
946 locale is relevant.
947
948 System files written by @pspp{} use this encoding.
949 System files read by @pspp{}, for which the encoding is unknown, are
950 interpreted using this encoding.
951
952 The full list of valid encodings and locale names/alias are operating system
953 dependent.
954 The following are all examples of acceptable syntax on common GNU/Linux
955 systems.
956 @example
957 SET LOCALE='iso-8859-1'.
958
959 SET LOCALE='ru_RU.cp1251'.
960
961 SET LOCALE='japanese'.
962 @end example
963
964 Contrary to intuition, this command does not affect any aspect
965 of the system's locale.
966 @end table
967
968 The following subcommands affect the interpretation of macros.
969
970 @table @asis
971 @item MEXPAND
972 @anchor{SET MEXPAND}
973 Controls whether macros are expanded.  The default is ON.
974
975 @item MPRINT
976 @anchor{SET MPRINT}
977 Controls whether the expansion of macros is included in output.  This
978 is separate from whether command syntax in general is included in
979 output.  The default is OFF.
980
981 @item MITERATE
982 @anchor{SET MITERATE}
983 Limits the number of iterations executed in @code{!DO} loops within
984 macros.  This does not affect other language constructs such as
985 @cmd{LOOP}.  This must be set to a positive integer.  The default is
986 1000.
987
988 @item MNEST
989 @anchor{SET MNEST}
990 Limits the number of levels of nested macro expansions.  This must be
991 set to a positive integer.  The default is 50.
992 @end table
993
994 The following subcommands are not yet implemented, but PSPP accepts
995 them and ignores the settings.
996
997 @table @asis
998 @item BASETEXTDIRECTION
999 @itemx BLOCK
1000 @itemx BOX
1001 @itemx CACHE
1002 @itemx CELLSBREAK
1003 @itemx COMPRESSION
1004 @itemx CMPTRANS
1005 @itemx HEADER
1006 @end table
1007
1008 @node SHOW
1009 @section SHOW
1010 @vindex SHOW
1011
1012 @display
1013 SHOW
1014         [ALL]
1015         [BLANKS]
1016         [CC]
1017         [CCA]
1018         [CCB]
1019         [CCC]
1020         [CCD]
1021         [CCE]
1022         [COPYING]
1023         [DECIMALS]
1024         [DIRECTORY]
1025         [ENVIRONMENT]
1026         [FORMAT]
1027         [FUZZBITS]
1028         [LENGTH]
1029         [MEXPAND]
1030         [MPRINT]
1031         [MITERATE]
1032         [MNEST]
1033         [MXERRS]
1034         [MXLOOPS]
1035         [MXWARNS]
1036         [N]
1037         [SCOMPRESSION]
1038         [SYSTEM]
1039         [TEMPDIR]
1040         [UNDEFINED]
1041         [VERSION]
1042         [WARRANTY]
1043         [WEIGHT]
1044         [WIDTH]
1045 @end display
1046
1047 @cmd{SHOW} can be used to display the current state of @pspp{}'s execution
1048 parameters.  Parameters that can be changed using @cmd{SET}
1049 (@pxref{SET}), can be examined using @cmd{SHOW} using the subcommand
1050 with the same name.  @cmd{SHOW} supports the following additional
1051 subcommands:
1052
1053 @table @asis
1054 @item @subcmd{ALL}
1055 Show all settings.
1056 @item @subcmd{CC}
1057 Show all custom currency settings (@subcmd{CCA} through @subcmd{CCE}).
1058 @item @subcmd{DIRECTORY}
1059 Shows the current working directory.
1060 @item @subcmd{ENVIRONMENT}
1061 Shows the operating system details.
1062 @item @subcmd{N}
1063 Reports the number of cases in the active dataset.  The reported number is not
1064 weighted.  If no dataset is defined, then @samp{Unknown} is reported.
1065 @item @subcmd{SYSTEM}
1066 Shows information about how PSPP was built.  This information is
1067 useful in bug reports.  @xref{Bugs}, for details.
1068 @item @subcmd{TEMPDIR}
1069 Shows the path of the directory where temporary files are stored.
1070 @item @subcmd{VERSION}
1071 Shows the version of this installation of @pspp{}.
1072 @item @subcmd{WARRANTY}
1073 Show details of the lack of warranty for @pspp{}.
1074 @item @subcmd{COPYING} / @subcmd{LICENSE}
1075 Display the terms of @pspp{}'s copyright licence (@pxref{License}).
1076 @end table
1077
1078 Specifying @cmd{SHOW} without any subcommands is equivalent to @subcmd{SHOW ALL}.
1079
1080 @node SUBTITLE
1081 @section SUBTITLE
1082 @vindex SUBTITLE
1083
1084 @display
1085 SUBTITLE '@var{subtitle_string}'.
1086   or
1087 SUBTITLE @var{subtitle_string}.
1088 @end display
1089
1090 @cmd{SUBTITLE} provides a subtitle to a particular @pspp{}
1091 run.  This subtitle appears at the top of each output page below the
1092 title, if headers are enabled on the output device.
1093
1094 Specify a subtitle as a string in quotes.  The alternate syntax that did
1095 not require quotes is now obsolete.  If it is used then the subtitle is
1096 converted to all uppercase.
1097
1098 @node TITLE
1099 @section TITLE
1100 @vindex TITLE
1101
1102 @display
1103 TITLE '@var{title_string}'.
1104   or
1105 TITLE @var{title_string}.
1106 @end display
1107
1108 @cmd{TITLE} provides a title to a particular @pspp{} run.
1109 This title appears at the top of each output page, if headers are enabled
1110 on the output device.
1111
1112 Specify a title as a string in quotes.  The alternate syntax that did
1113 not require quotes is now obsolete.  If it is used then the title is
1114 converted to all uppercase.