lex_get_text_buffer_read: Avoid potential buffer overflow.
[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         /TNUMBERS=@{VALUES,LABELS,BOTH@}
419
420 (logging)
421         /JOURNAL=@{ON,OFF@} ['file-name']
422
423 (system files)
424         /COMPRESSION=@{ON,OFF@}
425         /SCOMPRESSION=@{ON,OFF@}
426
427 (miscellaneous)
428         /SAFER=ON
429         /LOCALE='string'
430
431
432 (obsolete settings accepted for compatibility, but ignored)
433         /BOXSTRING=@{'xxx','xxxxxxxxxxx'@}
434         /CASE=@{UPPER,UPLOW@}
435         /CPI=cpi_value
436         /HIGHRES=@{ON,OFF@}
437         /HISTOGRAM='c'
438         /LOWRES=@{AUTO,ON,OFF@}
439         /LPI=lpi_value
440         /MENUS=@{STANDARD,EXTENDED@}
441         /MXMEMORY=max_memory
442         /SCRIPTTAB='c'
443         /TB1=@{'xxx','xxxxxxxxxxx'@}
444         /TBFONTS='string'
445         /XSORT=@{YES,NO@}
446 @end display
447
448 @cmd{SET} allows the user to adjust several parameters relating to
449 PSPP's execution.  Since there are many subcommands to this command, its
450 subcommands will be examined in groups.
451
452 On subcommands that take boolean values, ON and YES are synonym, and
453 as are OFF and NO, when used as subcommand values.
454
455 The data input subcommands affect the way that data is read from data
456 files.  The data input subcommands are
457
458 @table @asis
459 @item BLANKS
460 @anchor{SET BLANKS}
461 This is the value assigned to an item data item that is empty or
462 contains only white space.  An argument of SYSMIS or '.' will cause the
463 system-missing value to be assigned to null items.  This is the
464 default.  Any real value may be assigned.
465
466 @item DECIMAL
467 @anchor{SET DECIMAL}
468 This value may be set to DOT or COMMA.
469 Setting it to DOT causes the decimal point character to be
470 @samp{.} and the grouping character to be @samp{,}.
471 Setting it to COMMA
472 causes the decimal point character to be @samp{,} and the grouping
473 character to be @samp{.}.
474 The default value is determined from the system locale.
475
476 @item FORMAT
477 Allows the default numeric input/output format to be specified.  The
478 default is F8.2.  @xref{Input and Output Formats}.
479
480 @item EPOCH
481 @anchor{SET EPOCH}
482 Specifies the range of years used when a 2-digit year is read from a
483 data file or used in a date construction expression (@pxref{Date
484 Construction}).  If a 4-digit year is specified for the epoch, then
485 2-digit years are interpreted starting from that year, known as the
486 epoch.  If AUTOMATIC (the default) is specified, then the epoch begins
487 69 years before the current date.
488
489 @item RIB
490 @anchor{SET RIB} 
491
492 PSPP extension to set the byte ordering (endianness) used for reading
493 data in IB or PIB format (@pxref{Binary and Hexadecimal Numeric
494 Formats}).  In MSBFIRST ordering, the most-significant byte appears at
495 the left end of a IB or PIB field.  In LSBFIRST ordering, the
496 least-significant byte appears at the left end.  VAX ordering is like
497 MSBFIRST, except that each pair of bytes is in reverse order.  NATIVE,
498 the default, is equivalent to MSBFIRST or LSBFIRST depending on the
499 native format of the machine running PSPP.
500
501 @item RRB
502 @anchor{SET RRB}
503
504 PSPP extension to set the floating-point format used for reading data in
505 RB format (@pxref{Binary and Hexadecimal Numeric Formats}).  The
506 possibilities are:
507
508 @table @asis
509 @item NATIVE
510 The native format of the machine running PSPP.  Equivalent to either IDL
511 or IDB.
512
513 @item ISL
514 32-bit IEEE 754 single-precision floating point, in little-endian byte
515 order.
516
517 @item ISB
518 32-bit IEEE 754 single-precision floating point, in big-endian byte
519 order.
520
521 @item IDL
522 64-bit IEEE 754 double-precision floating point, in little-endian byte
523 order.
524
525 @item IDB
526 64-bit IEEE 754 double-precision floating point, in big-endian byte
527 order.
528
529 @item VF
530 32-bit VAX F format, in VAX-endian byte order.
531
532 @item VD
533 64-bit VAX D format, in VAX-endian byte order.
534
535 @item VG
536 64-bit VAX G format, in VAX-endian byte order.
537
538 @item ZS
539 32-bit IBM Z architecture short format hexadecimal floating point, in
540 big-endian byte order.  
541
542 @item ZL
543 64-bit IBM Z architecture long format hexadecimal floating point, in
544 big-endian byte order.
545
546 Z architecture also supports IEEE 754 floating point.  The ZS and ZL
547 formats are only for use with very old input files.
548 @end table
549 The default is NATIVE.
550 @end table
551
552 Interaction subcommands affect the way that PSPP interacts with an
553 online user.  The interaction subcommands are
554
555 @table @asis
556 @item MXERRS
557 The maximum number of errors before PSPP halts processing of the current
558 command file.  The default is 50.
559
560 @item MXWARNS
561 The maximum number of warnings + errors before PSPP halts processing the
562 current command file.  
563 The special value of zero means that all warning situations should be ignored.
564 No warnings will be issued, except a single initial warning advising the user
565 that warnings will not be given.
566 The default value is 100.
567 @end table
568
569 Syntax execution subcommands control the way that PSPP commands
570 execute.  The syntax execution subcommands are
571
572 @table @asis
573 @item LOCALE
574 Overrides the system locale for the purpose of reading and writing
575 syntax and data files.  The argument should be a locale name in the
576 general form @code{language_country.encoding}, where @code{language}
577 and @code{country} are 2-character language and country abbreviations,
578 respectively, and @code{encoding} is an IANA character set name.
579 Example locales are @code{en_US.UTF-8} (UTF-8 encoded English as
580 spoken in the United States) and @code{ja_JP.EUC-JP} (EUC-JP encoded
581 Japanese as spoken in Japan).
582
583 @item MEXPAND
584 @itemx MITERATE
585 @itemx MNEST
586 @itemx MPRINT
587 Currently not used.
588
589 @item MXLOOPS
590 The maximum number of iterations for an uncontrolled loop (@pxref{LOOP}).
591 The default MXLOOPS is 40.
592
593 @item SEED
594 The initial pseudo-random number seed.  Set to a real number or to
595 RANDOM, which will obtain an initial seed from the current time of day.
596
597 @item UNDEFINED
598 Currently not used.
599
600 @item WORKSPACE
601 The maximum amount of memory that PSPP will use to store data being processed.
602 If memory in excess of the workspace size is required, then PSPP will start
603 to use temporary files to store the data.
604 Setting a higher value will, in general, mean procedures will run faster, 
605 but may cause other applications to run slower.
606 On platforms without virtual memory management, setting a very large workspace
607 may cause PSPP to abort.
608 @cindex workspace
609 @cindex memory, amount used to store cases
610 @end table
611
612 Data output subcommands affect the format of output data.  These
613 subcommands are
614
615 @table @asis
616 @item CCA
617 @itemx CCB
618 @itemx CCC
619 @itemx CCD
620 @itemx CCE
621 @anchor{CCx Settings}
622
623 Set up custom currency formats.  @xref{Custom Currency Formats}, for
624 details.
625
626 @item DECIMAL
627 The default DOT setting causes the decimal point character to be
628 @samp{.}.  A setting of COMMA causes the decimal point character to be
629 @samp{,}.
630
631 @item FORMAT
632 Allows the default numeric input/output format to be specified.  The
633 default is F8.2.  @xref{Input and Output Formats}.
634
635 @item WIB
636 @anchor{SET WIB} 
637
638 PSPP extension to set the byte ordering (endianness) used for writing
639 data in IB or PIB format (@pxref{Binary and Hexadecimal Numeric
640 Formats}).  In MSBFIRST ordering, the most-significant byte appears at
641 the left end of a IB or PIB field.  In LSBFIRST ordering, the
642 least-significant byte appears at the left end.  VAX ordering is like
643 MSBFIRST, except that each pair of bytes is in reverse order.  NATIVE,
644 the default, is equivalent to MSBFIRST or LSBFIRST depending on the
645 native format of the machine running PSPP.
646
647 @item WRB
648 @anchor{SET WRB}
649
650 PSPP extension to set the floating-point format used for writing data in
651 RB format (@pxref{Binary and Hexadecimal Numeric Formats}).  The choices
652 are the same as SET RIB.  The default is NATIVE.
653 @end table
654
655 In the PSPP text-based interface, the output routing subcommands
656 affect where output is sent.  The following values are allowed for
657 each of these subcommands:
658
659 @table @asis
660 @item OFF
661 @item NONE
662 Discard this kind of output.
663
664 @item TERMINAL
665 Write this output to the terminal, but not to listing files and other
666 output devices.
667
668 @item LISTING
669 Write this output to listing files and other output devices, but not
670 to the terminal.
671
672 @item ON
673 @itemx BOTH
674 Write this type of output to all output devices.
675 @end table
676
677 These output routing subcommands are:
678
679 @table @asis
680 @item ERRORS
681 Applies to error and warning messages.  The default is BOTH.
682
683 @item MESSAGES
684 Applies to notes.  The default is BOTH.
685
686 @item PRINTBACK
687 Determines whether the syntax used for input is printed back as part
688 of the output.  The default is NONE.
689
690 @item RESULTS
691 Applies to everything not in one of the above categories, such as the
692 results of statistical procedures.  The default is BOTH.
693 @end table
694
695 These subcommands have no effect on output in the PSPP GUI
696 environment.
697
698 Output driver option subcommands affect output drivers' settings.  These
699 subcommands are
700
701 @table @asis
702 @item HEADERS
703 @itemx LENGTH
704 @itemx MORE
705 @itemx WIDTH
706 @itemx TNUMBERS
707 The TNUMBERS option sets the way in which values are displayed in output tables.
708 The valid settings are VALUES, LABELS and BOTH.
709 If TNUMBERS is set to VALUES, then all values are displayed with their literal value 
710 (which for a numeric value is a number and for a string value an alphanumeric string).
711 If TNUMBERS is set to LABELS, then values are displayed using their assigned labels if any.
712 (@xref{VALUE LABELS}.)
713 If the a value has no label, then it will be displayed using its literal value.
714 If TNUMBERS is set to BOTH, then values will be displayed with both their label
715 (if any) and their literal value in parenthesis.
716 @end table
717
718 @cindex headers
719 @cindex length
720 @cindex more
721 @cindex pager 
722 @cindex width
723 @cindex tnumbers
724
725
726 Logging subcommands affect logging of commands executed to external
727 files.  These subcommands are
728
729 @table @asis
730 @item JOURNAL
731 @itemx LOG
732 These subcommands, which are synonyms, control the journal.  The
733 default is ON, which causes commands entered interactively to be
734 written to the journal file.  Commands included from syntax files that
735 are included interactively and error messages printed by PSPP are also
736 written to the journal file, prefixed by @samp{>}.  OFF disables use
737 of the journal.
738
739 The journal is named @file{pspp.jnl} by default.  A different name may
740 be specified.
741 @end table
742
743 System file subcommands affect the default format of system files
744 produced by PSPP.  These subcommands are
745
746 @table @asis
747 @item COMPRESSION
748 Not currently used.
749
750 @item SCOMPRESSION
751 Whether system files created by @cmd{SAVE} or @cmd{XSAVE} are
752 compressed by default.  The default is ON.
753 @end table
754
755 Security subcommands affect the operations that commands are allowed to
756 perform.  The security subcommands are
757
758 @table @asis
759 @item SAFER
760 Setting this option disables the following operations:
761
762 @itemize @bullet
763 @item
764 The ERASE command.
765 @item
766 The HOST command.
767 @item
768 The PERMISSIONS command.
769 @item
770 Pipes (file names beginning or ending with @samp{|}).
771 @end itemize
772
773 Be aware that this setting does not guarantee safety (commands can still
774 overwrite files, for instance) but it is an improvement.
775 When set, this setting cannot be reset during the same session, for
776 obvious security reasons.
777
778 @item LOCALE
779 @cindex locale
780 @cindex encoding, characters
781 This item is used to set the default character encoding.
782 The encoding may be specified either as an encoding name or alias
783 (see @url{http://www.iana.org/assignments/character-sets}), or
784 as a locale name.
785 If given as a locale name, only the character encoding of the 
786 locale is relevant.
787
788 System files written by PSPP will use this encoding.
789 System files read by PSPP, for which the encoding is unknown, will be
790 interpreted using this encoding.
791
792 The full list of valid encodings and locale names/alias are operating system
793 dependent.
794 The following are all examples of acceptable syntax on common GNU/Linux
795 systems.
796 @example
797
798 SET LOCALE='iso-8859-1'.
799
800 SET LOCALE='ru_RU.cp1251'.
801
802 SET LOCALE='japanese'.
803
804 @end example
805
806 Contrary to the intuition, this command does not affect any aspect 
807 of the system's locale.
808 @end table
809
810 @node SHOW
811 @comment  node-name,  next,  previous,  up
812 @section SHOW
813 @vindex SHOW
814
815 @display
816 SHOW
817         [ALL]
818         [BLANKS]
819         [CC]
820         [CCA]
821         [CCB]
822         [CCC]
823         [CCD]
824         [CCE]
825         [COPYING]
826         [DECIMALS]
827         [FORMAT]
828         [LENGTH]
829         [MXERRS]
830         [MXLOOPS]
831         [MXWARNS]
832         [SCOMPRESSION]
833         [UNDEFINED]
834         [WARRANTY]
835         [WEIGHT]
836         [WIDTH]
837 @end display
838
839 @cmd{SHOW} can be used to display the current state of PSPP's execution
840 parameters.  Parameters that can be changed using @cmd{SET}
841 (@pxref{SET}), can be examined using @cmd{SHOW} using the subcommand
842 with the same name.  @code{SHOW} supports the following additional
843 subcommands:
844
845 @table @code
846 @item ALL
847 Show all settings.
848 @item CC
849 Show all custom currency settings (CCA through CCE).
850 @item WARRANTY
851 Show details of the lack of warranty for PSPP.
852 @item COPYING
853 Display the terms of PSPP's copyright licence (@pxref{License}).
854 @end table
855
856 Specifying @cmd{SHOW} without any subcommands is equivalent to SHOW ALL.
857
858 @node SUBTITLE
859 @section SUBTITLE
860 @vindex SUBTITLE
861
862 @display
863 SUBTITLE 'subtitle_string'.
864   or
865 SUBTITLE subtitle_string.
866 @end display
867
868 @cmd{SUBTITLE} provides a subtitle to a particular PSPP
869 run.  This subtitle appears at the top of each output page below the
870 title, if headers are enabled on the output device.
871
872 Specify a subtitle as a string in quotes.  The alternate syntax that did
873 not require quotes is now obsolete.  If it is used then the subtitle is
874 converted to all uppercase.
875
876 @node TITLE
877 @section TITLE
878 @vindex TITLE
879
880 @display
881 TITLE 'title_string'.
882   or
883 TITLE title_string.
884 @end display
885
886 @cmd{TITLE} provides a title to a particular PSPP run.
887 This title appears at the top of each output page, if headers are enabled
888 on the output device.
889
890 Specify a title as a string in quotes.  The alternate syntax that did
891 not require quotes is now obsolete.  If it is used then the title is
892 converted to all uppercase.