gui: Fix Glib warnings for dialogs in realize and configure callbacks.
[pspp-builds.git] / 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 * PERMISSIONS::                 Change permissions on a file.
29 * PRESERVE and RESTORE::        Saving settings and restoring them later.
30 * SET::                         Adjust PSPP runtime parameters.
31 * SHOW::                        Display runtime parameters.
32 * SUBTITLE::                    Provide a document subtitle.
33 * TITLE::                       Provide a document title.
34 @end menu
35
36 @node ADD DOCUMENT
37 @comment  node-name,  next,  previous,  up
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 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 @comment  node-name,  next,  previous,  up
170 @section ERASE
171 @vindex ERASE
172
173 @display
174 ERASE FILE file_name.
175 @end display
176
177 @cmd{ERASE FILE} deletes a file from the local filesystem.
178 file_name must be quoted.
179 This command cannot be used if the SAFER setting is active.
180
181
182 @node EXECUTE
183 @section EXECUTE
184 @vindex EXECUTE
185
186 @display
187 EXECUTE.
188 @end display
189
190 @cmd{EXECUTE} causes the active dataset to be read and all pending
191 transformations to be executed.
192
193 @node FILE LABEL
194 @section FILE LABEL
195 @vindex FILE LABEL
196
197 @display
198 FILE LABEL file_label.
199 @end display
200
201 @cmd{FILE LABEL} provides a title for the active dataset.  This
202 title will be saved into system files and portable files that are
203 created during this PSPP run.
204
205 file_label need not be quoted.  If quotes are
206 included, they become part of the file label.
207
208 @node FINISH
209 @section FINISH
210 @vindex FINISH
211
212 @display
213 FINISH.
214 @end display
215
216 @cmd{FINISH} terminates the current PSPP session and returns
217 control to the operating system.
218
219 @node HOST
220 @comment  node-name,  next,  previous,  up
221 @section HOST
222 @vindex HOST
223
224 @display
225 HOST.
226 HOST COMMAND=['command'...].
227 @end display
228
229 @cmd{HOST} suspends the current PSPP session and temporarily returns control 
230 to the operating system.
231 This command cannot be used if the SAFER setting is active.
232
233 If the COMMAND subcommand is specified, as a sequence of shell
234 commands as quoted strings within square brackets, then PSPP executes
235 them together in a single subshell.
236
237 If no subcommands are specified, then PSPP invokes an interactive
238 subshell.
239
240 @node INCLUDE
241 @section INCLUDE
242 @vindex INCLUDE
243
244 @display
245         INCLUDE [FILE=]'file-name' [ENCODING='encoding'].
246 @end display
247
248 @cmd{INCLUDE} causes the PSPP command processor to read an
249 additional command file as if it were included bodily in the current
250 command file.
251 If errors are encountered in the included file, then command processing will 
252 stop and no more commands will be processed.
253 Include files may be nested to any depth, up to the limit of available
254 memory.
255
256 The @cmd{INSERT} command (@pxref{INSERT}) is a more flexible
257 alternative to @cmd{INCLUDE}.  An INCLUDE command acts the same as
258 INSERT with ERROR=STOP CD=NO SYNTAX=BATCH specified.
259
260 The optional ENCODING subcommand has the same meaning as on INSERT.
261
262 @node INSERT
263 @section INSERT
264 @vindex INSERT
265
266 @display
267      INSERT [FILE=]'file-name'
268         [CD=@{NO,YES@}]
269         [ERROR=@{CONTINUE,STOP@}]
270         [SYNTAX=@{BATCH,INTERACTIVE@}]
271         [ENCODING='encoding'].
272 @end display
273
274 @cmd{INSERT} is similar to @cmd{INCLUDE} (@pxref{INCLUDE}) 
275 but somewhat more flexible.
276 It causes the command processor to read a file as if it were embedded in the 
277 current command file.
278
279 If @samp{CD=YES} is specified, then before including the file, the
280 current directory  will be changed to the directory of the included
281 file.  
282 The default setting is @samp{CD=NO}.
283 Note that this directory will remain current until it is
284 changed explicitly (with the @cmd{CD} command, or a subsequent
285 @cmd{INSERT} command with the @samp{CD=YES} option).
286 It will not revert to its original setting even after the included
287 file is finished processing.
288
289 If @samp{ERROR=STOP} is specified, errors encountered in the
290 inserted file will cause processing to immediately cease.
291 Otherwise processing will continue at the next command.
292 The default setting is @samp{ERROR=CONTINUE}.
293
294 If @samp{SYNTAX=INTERACTIVE} is specified then the syntax contained in
295 the included file must conform to interactive syntax
296 conventions. @xref{Syntax Variants}.
297 The default setting is @samp{SYNTAX=BATCH}.
298
299 ENCODING optionally specifies the character set used by the included
300 file.  Its argument, which is not case-sensitive, must be in one of
301 the following forms:
302
303 @table @asis
304 @item @code{Locale}
305 The encoding used by the system locale, or as overridden by the SET
306 LOCALE command (@pxref{SET}).  On Unix systems, environment variables,
307 e.g.@: @env{LANG} or @env{LC_ALL}, determine the system locale.
308
309 @item IANA character set name
310 One of the character set names listed by IANA at
311 @uref{http://www.iana.org/assignments/character-sets}.  Some examples
312 are @code{ASCII} (United States), @code{ISO-8859-1} (western Europe),
313 @code{EUC-JP} (Japan), and @code{windows-1252} (Windows).  Not all
314 systems support all character sets.
315
316 @item @code{Auto}
317 @item @code{Auto,@var{encoding}}
318 Automatically detects whether a syntax file is encoded in
319 @var{encoding} or in a Unicode encoding such as UTF-8, UTF-16, or
320 UTF-32.  The @var{encoding} may be an IANA character set name or
321 @code{Locale} (the default).  Only ASCII compatible encodings can
322 automatically be distinguished from UTF-8 (the most common locale
323 encodings are all ASCII-compatible).
324 @end table
325
326 When ENCODING is not specified, the default is taken from the
327 @option{--syntax-encoding} command option, if it was specified, and
328 otherwise it is @code{Auto}.
329
330 @node PERMISSIONS
331 @section PERMISSIONS
332 @vindex PERMISSIONS
333 @cindex mode
334 @cindex file mode
335 @cindex changing file permissions
336
337 @display
338 PERMISSIONS
339         FILE='file-name'
340         /PERMISSIONS = @{READONLY,WRITEABLE@}.
341 @end display
342
343 @cmd{PERMISSIONS} changes the permissions of a file.  
344 There is one mandatory subcommand which specifies the permissions to
345 which the file should be changed.  
346 If you set a file's  permission  to READONLY, then the file will become
347 unwritable either by you or anyone else on the system.
348 If you set the permission to WRITEABLE, then the file will become
349 writeable by you; the permissions afforded to others will be
350 unchanged.
351 This command cannot be used if the SAFER setting is active.
352
353
354 @node PRESERVE and RESTORE
355 @section PRESERVE and RESTORE
356 @vindex PRESERVE
357 @vindex RESTORE
358
359 @display
360 PRESERVE.
361 @dots{}
362 RESTORE.
363 @end display
364
365 @cmd{PRESERVE} saves all of the settings that @cmd{SET} (@pxref{SET})
366 can adjust.  A later @cmd{RESTORE} command restores those settings.
367
368 @cmd{PRESERVE} can be nested up to five levels deep.
369
370 @node SET
371 @section SET
372 @vindex SET
373
374 @display
375 SET
376
377 (data input)
378         /BLANKS=@{SYSMIS,'.',number@}
379         /DECIMAL=@{DOT,COMMA@}
380         /FORMAT=fmt_spec
381         /EPOCH=@{AUTOMATIC,year@}
382         /RIB=@{NATIVE,MSBFIRST,LSBFIRST,VAX@}
383         /RRB=@{NATIVE,ISL,ISB,IDL,IDB,VF,VD,VG,ZS,ZL@}
384
385 (interaction)
386         /MXERRS=max_errs
387         /MXWARNS=max_warnings
388         /WORKSPACE=workspace_size
389
390 (syntax execution)
391         /LOCALE='locale'
392         /MEXPAND=@{ON,OFF@}
393         /MITERATE=max_iterations
394         /MNEST=max_nest
395         /MPRINT=@{ON,OFF@}
396         /MXLOOPS=max_loops
397         /SEED=@{RANDOM,seed_value@}
398         /UNDEFINED=@{WARN,NOWARN@}
399
400 (data output)
401         /CC@{A,B,C,D,E@}=@{'npre,pre,suf,nsuf','npre.pre.suf.nsuf'@}
402         /DECIMAL=@{DOT,COMMA@}
403         /FORMAT=fmt_spec
404         /WIB=@{NATIVE,MSBFIRST,LSBFIRST,VAX@}
405         /WRB=@{NATIVE,ISL,ISB,IDL,IDB,VF,VD,VG,ZS,ZL@}
406
407 (output routing)
408         /ERRORS=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}
409         /MESSAGES=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}
410         /PRINTBACK=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}
411         /RESULTS=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}
412
413 (output driver options)
414         /HEADERS=@{NO,YES,BLANK@}
415         /LENGTH=@{NONE,length_in_lines@}
416         /MORE=@{ON,OFF@}
417         /WIDTH=@{NARROW,WIDTH,n_characters@}
418
419 (logging)
420         /JOURNAL=@{ON,OFF@} ['file-name']
421
422 (system files)
423         /COMPRESSION=@{ON,OFF@}
424         /SCOMPRESSION=@{ON,OFF@}
425
426 (miscellaneous)
427         /SAFER=ON
428         /LOCALE='string'
429
430
431 (obsolete settings accepted for compatibility, but ignored)
432         /BOXSTRING=@{'xxx','xxxxxxxxxxx'@}
433         /CASE=@{UPPER,UPLOW@}
434         /CPI=cpi_value
435         /HIGHRES=@{ON,OFF@}
436         /HISTOGRAM='c'
437         /LOWRES=@{AUTO,ON,OFF@}
438         /LPI=lpi_value
439         /MENUS=@{STANDARD,EXTENDED@}
440         /MXMEMORY=max_memory
441         /SCRIPTTAB='c'
442         /TB1=@{'xxx','xxxxxxxxxxx'@}
443         /TBFONTS='string'
444         /XSORT=@{YES,NO@}
445 @end display
446
447 @cmd{SET} allows the user to adjust several parameters relating to
448 PSPP's execution.  Since there are many subcommands to this command, its
449 subcommands will be examined in groups.
450
451 On subcommands that take boolean values, ON and YES are synonym, and
452 as are OFF and NO, when used as subcommand values.
453
454 The data input subcommands affect the way that data is read from data
455 files.  The data input subcommands are
456
457 @table @asis
458 @item BLANKS
459 @anchor{SET BLANKS}
460 This is the value assigned to an item data item that is empty or
461 contains only white space.  An argument of SYSMIS or '.' will cause the
462 system-missing value to be assigned to null items.  This is the
463 default.  Any real value may be assigned.
464
465 @item DECIMAL
466 @anchor{SET DECIMAL}
467 This value may be set to DOT or COMMA.
468 Setting it to DOT causes the decimal point character to be
469 @samp{.} and the grouping character to be @samp{,}.
470 Setting it to COMMA
471 causes the decimal point character to be @samp{,} and the grouping
472 character to be @samp{.}.
473 The default value is determined from the system locale.
474
475 @item FORMAT
476 Allows the default numeric input/output format to be specified.  The
477 default is F8.2.  @xref{Input and Output Formats}.
478
479 @item EPOCH
480 @anchor{SET EPOCH}
481 Specifies the range of years used when a 2-digit year is read from a
482 data file or used in a date construction expression (@pxref{Date
483 Construction}).  If a 4-digit year is specified for the epoch, then
484 2-digit years are interpreted starting from that year, known as the
485 epoch.  If AUTOMATIC (the default) is specified, then the epoch begins
486 69 years before the current date.
487
488 @item RIB
489 @anchor{SET RIB} 
490
491 PSPP extension to set the byte ordering (endianness) used for reading
492 data in IB or PIB format (@pxref{Binary and Hexadecimal Numeric
493 Formats}).  In MSBFIRST ordering, the most-significant byte appears at
494 the left end of a IB or PIB field.  In LSBFIRST ordering, the
495 least-significant byte appears at the left end.  VAX ordering is like
496 MSBFIRST, except that each pair of bytes is in reverse order.  NATIVE,
497 the default, is equivalent to MSBFIRST or LSBFIRST depending on the
498 native format of the machine running PSPP.
499
500 @item RRB
501 @anchor{SET RRB}
502
503 PSPP extension to set the floating-point format used for reading data in
504 RB format (@pxref{Binary and Hexadecimal Numeric Formats}).  The
505 possibilities are:
506
507 @table @asis
508 @item NATIVE
509 The native format of the machine running PSPP.  Equivalent to either IDL
510 or IDB.
511
512 @item ISL
513 32-bit IEEE 754 single-precision floating point, in little-endian byte
514 order.
515
516 @item ISB
517 32-bit IEEE 754 single-precision floating point, in big-endian byte
518 order.
519
520 @item IDL
521 64-bit IEEE 754 double-precision floating point, in little-endian byte
522 order.
523
524 @item IDB
525 64-bit IEEE 754 double-precision floating point, in big-endian byte
526 order.
527
528 @item VF
529 32-bit VAX F format, in VAX-endian byte order.
530
531 @item VD
532 64-bit VAX D format, in VAX-endian byte order.
533
534 @item VG
535 64-bit VAX G format, in VAX-endian byte order.
536
537 @item ZS
538 32-bit IBM Z architecture short format hexadecimal floating point, in
539 big-endian byte order.  
540
541 @item ZL
542 64-bit IBM Z architecture long format hexadecimal floating point, in
543 big-endian byte order.
544
545 Z architecture also supports IEEE 754 floating point.  The ZS and ZL
546 formats are only for use with very old input files.
547 @end table
548 The default is NATIVE.
549 @end table
550
551 Interaction subcommands affect the way that PSPP interacts with an
552 online user.  The interaction subcommands are
553
554 @table @asis
555 @item MXERRS
556 The maximum number of errors before PSPP halts processing of the current
557 command file.  The default is 50.
558
559 @item MXWARNS
560 The maximum number of warnings + errors before PSPP halts processing the
561 current command file.  
562 The special value of zero means that all warning situations should be ignored.
563 No warnings will be issued, except a single initial warning advising the user
564 that warnings will not be given.
565 The default value is 100.
566 @end table
567
568 Syntax execution subcommands control the way that PSPP commands
569 execute.  The syntax execution subcommands are
570
571 @table @asis
572 @item LOCALE
573 Overrides the system locale for the purpose of reading and writing
574 syntax and data files.  The argument should be a locale name in the
575 general form @code{language_country.encoding}, where @code{language}
576 and @code{country} are 2-character language and country abbreviations,
577 respectively, and @code{encoding} is an IANA character set name.
578 Example locales are @code{en_US.UTF-8} (UTF-8 encoded English as
579 spoken in the United States) and @code{ja_JP.EUC-JP} (EUC-JP encoded
580 Japanese as spoken in Japan).
581
582 @item MEXPAND
583 @itemx MITERATE
584 @itemx MNEST
585 @itemx MPRINT
586 Currently not used.
587
588 @item MXLOOPS
589 The maximum number of iterations for an uncontrolled loop (@pxref{LOOP}).
590
591 @item SEED
592 The initial pseudo-random number seed.  Set to a real number or to
593 RANDOM, which will obtain an initial seed from the current time of day.
594
595 @item UNDEFINED
596 Currently not used.
597
598 @item WORKSPACE
599 The maximum amount of memory that PSPP will use to store data being processed.
600 If memory in excess of the workspace size is required, then PSPP will start
601 to use temporary files to store the data.
602 Setting a higher value will, in general, mean procedures will run faster, 
603 but may cause other applications to run slower.
604 On platforms without virtual memory management, setting a very large workspace
605 may cause PSPP to abort.
606 @cindex workspace
607 @cindex memory, amount used to store cases
608 @end table
609
610 Data output subcommands affect the format of output data.  These
611 subcommands are
612
613 @table @asis
614 @item CCA
615 @itemx CCB
616 @itemx CCC
617 @itemx CCD
618 @itemx CCE
619 @anchor{CCx Settings}
620
621 Set up custom currency formats.  @xref{Custom Currency Formats}, for
622 details.
623
624 @item DECIMAL
625 The default DOT setting causes the decimal point character to be
626 @samp{.}.  A setting of COMMA causes the decimal point character to be
627 @samp{,}.
628
629 @item FORMAT
630 Allows the default numeric input/output format to be specified.  The
631 default is F8.2.  @xref{Input and Output Formats}.
632
633 @item WIB
634 @anchor{SET WIB} 
635
636 PSPP extension to set the byte ordering (endianness) used for writing
637 data in IB or PIB format (@pxref{Binary and Hexadecimal Numeric
638 Formats}).  In MSBFIRST ordering, the most-significant byte appears at
639 the left end of a IB or PIB field.  In LSBFIRST ordering, the
640 least-significant byte appears at the left end.  VAX ordering is like
641 MSBFIRST, except that each pair of bytes is in reverse order.  NATIVE,
642 the default, is equivalent to MSBFIRST or LSBFIRST depending on the
643 native format of the machine running PSPP.
644
645 @item WRB
646 @anchor{SET WRB}
647
648 PSPP extension to set the floating-point format used for writing data in
649 RB format (@pxref{Binary and Hexadecimal Numeric Formats}).  The choices
650 are the same as SET RIB.  The default is NATIVE.
651 @end table
652
653 In the PSPP text-based interface, the output routing subcommands
654 affect where output is sent.  The following values are allowed for
655 each of these subcommands:
656
657 @table @asis
658 @item OFF
659 @item NONE
660 Discard this kind of output.
661
662 @item TERMINAL
663 Write this output to the terminal, but not to listing files and other
664 output devices.
665
666 @item LISTING
667 Write this output to listing files and other output devices, but not
668 to the terminal.
669
670 @item ON
671 @itemx BOTH
672 Write this type of output to all output devices.
673 @end table
674
675 These output routing subcommands are:
676
677 @table @asis
678 @item ERRORS
679 Applies to error and warning messages.  The default is BOTH.
680
681 @itemx MESSAGES
682 Applies to notes.  The default is BOTH.
683
684 @itemx PRINTBACK
685 Determines whether the syntax used for input is printed back as part
686 of the output.  The default is NONE.
687
688 @itemx RESULTS
689 Applies to everything not in one of the above categories, such as the
690 results of statistical procedures.  The default is BOTH.
691 @end table
692
693 These subcommands have no effect on output in the PSPP GUI
694 environment.
695
696 Output driver option subcommands affect output drivers' settings.  These
697 subcommands are
698
699 @table @asis
700 @item HEADERS
701 @itemx LENGTH
702 @itemx MORE
703 @itemx PAGER 
704 @itemx WIDTH
705 @end table
706
707 @cindex headers
708 @cindex length
709 @cindex more
710 @cindex pager 
711 @cindex width
712
713
714 Logging subcommands affect logging of commands executed to external
715 files.  These subcommands are
716
717 @table @asis
718 @item JOURNAL
719 @itemx LOG
720 These subcommands, which are synonyms, control the journal.  The
721 default is ON, which causes commands entered interactively to be
722 written to the journal file.  Commands included from syntax files that
723 are included interactively and error messages printed by PSPP are also
724 written to the journal file, prefixed by @samp{>}.  OFF disables use
725 of the journal.
726
727 The journal is named @file{pspp.jnl} by default.  A different name may
728 be specified.
729 @end table
730
731 System file subcommands affect the default format of system files
732 produced by PSPP.  These subcommands are
733
734 @table @asis
735 @item COMPRESSION
736 Not currently used.
737
738 @item SCOMPRESSION
739 Whether system files created by @cmd{SAVE} or @cmd{XSAVE} are
740 compressed by default.  The default is ON.
741 @end table
742
743 Security subcommands affect the operations that commands are allowed to
744 perform.  The security subcommands are
745
746 @table @asis
747 @item SAFER
748 Setting this option disables the following operations:
749
750 @itemize @bullet
751 @item
752 The ERASE command.
753 @item
754 The HOST command.
755 @item
756 The PERMISSIONS command.
757 @item
758 Pipes (file names beginning or ending with @samp{|}).
759 @end itemize
760
761 Be aware that this setting does not guarantee safety (commands can still
762 overwrite files, for instance) but it is an improvement.
763 When set, this setting cannot be reset during the same session, for
764 obvious security reasons.
765
766 @item LOCALE
767 @cindex locale
768 @cindex encoding, characters
769 This item is used to set the default character encoding.
770 The encoding may be specified either as an encoding name or alias
771 (see @url{http://www.iana.org/assignments/character-sets}), or
772 as a locale name.
773 If given as a locale name, only the character encoding of the 
774 locale is relevant.
775
776 System files written by PSPP will use this encoding.
777 System files read by PSPP, for which the encoding is unknown, will be
778 interpreted using this encoding.
779
780 The full list of valid encodings and locale names/alias are operating system
781 dependent.
782 The following are all examples of acceptable syntax on common GNU/Linux
783 systems.
784 @example
785
786 SET LOCALE='iso-8859-1'.
787
788 SET LOCALE='ru_RU.cp1251'.
789
790 SET LOCALE='japanese'.
791
792 @end example
793
794 Contrary to the intuition, this command does not affect any aspect 
795 of the system's locale.
796 @end table
797
798 @node SHOW
799 @comment  node-name,  next,  previous,  up
800 @section SHOW
801 @vindex SHOW
802
803 @display
804 SHOW
805         [ALL]
806         [BLANKS]
807         [CC]
808         [CCA]
809         [CCB]
810         [CCC]
811         [CCD]
812         [CCE]
813         [COPYING]
814         [DECIMALS]
815         [FORMAT]
816         [LENGTH]
817         [MXERRS]
818         [MXLOOPS]
819         [MXWARNS]
820         [SCOMPRESSION]
821         [UNDEFINED]
822         [WARRANTY]
823         [WEIGHT]
824         [WIDTH]
825 @end display
826
827 @cmd{SHOW} can be used to display the current state of PSPP's execution
828 parameters.  Parameters that can be changed using @cmd{SET}
829 (@pxref{SET}), can be examined using @cmd{SHOW} using the subcommand
830 with the same name.  @code{SHOW} supports the following additional
831 subcommands:
832
833 @table @code
834 @item ALL
835 Show all settings.
836 @item CC
837 Show all custom currency settings (CCA through CCE).
838 @item WARRANTY
839 Show details of the lack of warranty for PSPP.
840 @item COPYING
841 Display the terms of PSPP's copyright licence (@pxref{License}).
842 @end table
843
844 Specifying @cmd{SHOW} without any subcommands is equivalent to SHOW ALL.
845
846 @node SUBTITLE
847 @section SUBTITLE
848 @vindex SUBTITLE
849
850 @display
851 SUBTITLE 'subtitle_string'.
852   or
853 SUBTITLE subtitle_string.
854 @end display
855
856 @cmd{SUBTITLE} provides a subtitle to a particular PSPP
857 run.  This subtitle appears at the top of each output page below the
858 title, if headers are enabled on the output device.
859
860 Specify a subtitle as a string in quotes.  The alternate syntax that did
861 not require quotes is now obsolete.  If it is used then the subtitle is
862 converted to all uppercase.
863
864 @node TITLE
865 @section TITLE
866 @vindex TITLE
867
868 @display
869 TITLE 'title_string'.
870   or
871 TITLE title_string.
872 @end display
873
874 @cmd{TITLE} provides a title to a particular PSPP run.
875 This title appears at the top of each output page, if headers are enabled
876 on the output device.
877
878 Specify a title as a string in quotes.  The alternate syntax that did
879 not require quotes is now obsolete.  If it is used then the title is
880 converted to all uppercase.