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