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