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