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.