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.