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 * CACHE::                       Ignored for compatibility.
  14 * CD::                          Change the current directory.
  15 * COMMENT::                     Document your syntax file.
  16 * DOCUMENT::                    Document the active file.
  17 * DISPLAY DOCUMENTS::           Display active file documents.
  18 * DISPLAY FILE LABEL::          Display the active file label.
  19 * DROP DOCUMENTS::              Remove documents from the active file.
  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 file'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 file.  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 file 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 file.  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 file 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 file.  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 file,
 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 file.
 153 New documents can be added with @cmd{DOCUMENT} (@pxref{DOCUMENT}).
 154
 155 @cmd{DROP DOCUMENTS} changes only the active file.  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 file 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 file.  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'.
 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
 257 The @cmd{INSERT} command (@pxref{INSERT}) may be used instead of
 258 @cmd{INCLUDE} if you require more flexible options.
 259 The syntax
 260 @example
 261 INCLUDE FILE=@var{file-name}.
 262 @end example
 263 @noindent
 264 functions identically to
 265 @example
 266 INSERT FILE=@var{file-name} ERROR=STOP CD=NO SYNTAX=BATCH.
 267 @end example
 268
 269
 270 @node INSERT
 271 @section INSERT
 272 @vindex INSERT
 273
 274 @display
 275      INSERT [FILE=]'file-name'
 276         [CD=@{NO,YES@}]
 277         [ERROR=@{CONTINUE,STOP@}]
 278         [SYNTAX=@{BATCH,INTERACTIVE@}].
 279 @end display
 280
 281 @cmd{INSERT} is similar to @cmd{INCLUDE} (@pxref{INCLUDE})
 282 but somewhat more flexible.
 283 It causes the command processor to read a file as if it were embedded in the
 284 current command file.
 285
 286 If @samp{CD=YES} is specified, then before including the file, the
 287 current directory  will be changed to the directory of the included
 288 file.
 289 The default setting is @samp{CD=NO}.
 290 Note that this directory will remain current until it is
 291 changed explicitly (with the @cmd{CD} command, or a subsequent
 292 @cmd{INSERT} command with the @samp{CD=YES} option).
 293 It will not revert to its original setting even after the included
 294 file is finished processing.
 295
 296 If @samp{ERROR=STOP} is specified, errors encountered in the
 297 inserted file will cause processing to immediately cease.
 298 Otherwise processing will continue at the next command.
 299 The default setting is @samp{ERROR=CONTINUE}.
 300
 301 If @samp{SYNTAX=INTERACTIVE} is specified then the syntax contained in
 302 the included file must conform to interactive syntax
 303 conventions. @xref{Syntax Variants}.
 304 The default setting is @samp{SYNTAX=BATCH}.
 305
 306 @node PERMISSIONS
 307 @section PERMISSIONS
 308 @vindex PERMISSIONS
 309 @cindex mode
 310 @cindex file mode
 311 @cindex changing file permissions
 312
 313 @display
 314 PERMISSIONS
 315         FILE='file-name'
 316         /PERMISSIONS = @{READONLY,WRITEABLE@}.
 317 @end display
 318
 319 @cmd{PERMISSIONS} changes the permissions of a file.
 320 There is one mandatory subcommand which specifies the permissions to
 321 which the file should be changed.
 322 If you set a file's  permission  to READONLY, then the file will become
 323 unwritable either by you or anyone else on the system.
 324 If you set the permission to WRITEABLE, then the file will become
 325 writeable by you; the permissions afforded to others will be
 326 unchanged.
 327 This command cannot be used if the SAFER setting is active.
 328
 329
 330 @node PRESERVE and RESTORE
 331 @section PRESERVE and RESTORE
 332 @vindex PRESERVE
 333 @vindex RESTORE
 334
 335 @display
 336 PRESERVE.
 337 @dots{}
 338 RESTORE.
 339 @end display
 340
 341 @cmd{PRESERVE} saves all of the settings that @cmd{SET} (@pxref{SET})
 342 can adjust.  A later @cmd{RESTORE} command restores those settings.
 343
 344 @cmd{PRESERVE} can be nested up to five levels deep.
 345
 346 @node SET
 347 @section SET
 348 @vindex SET
 349
 350 @display
 351 SET
 352
 353 (data input)
 354         /BLANKS=@{SYSMIS,'.',number@}
 355         /DECIMAL=@{DOT,COMMA@}
 356         /FORMAT=fmt_spec
 357         /EPOCH=@{AUTOMATIC,year@}
 358         /RIB=@{NATIVE,MSBFIRST,LSBFIRST,VAX@}
 359         /RRB=@{NATIVE,ISL,ISB,IDL,IDB,VF,VD,VG,ZS,ZL@}
 360
 361 (program input)
 362         /ENDCMD='.'
 363         /NULLINE=@{ON,OFF@}
 364
 365 (interaction)
 366         /CPROMPT='cprompt_string'
 367         /DPROMPT='dprompt_string'
 368         /MXERRS=max_errs
 369         /MXWARNS=max_warnings
 370         /PROMPT='prompt'
 371         /WORKSPACE=workspace_size
 372
 373 (program execution)
 374         /MEXPAND=@{ON,OFF@}
 375         /MITERATE=max_iterations
 376         /MNEST=max_nest
 377         /MPRINT=@{ON,OFF@}
 378         /MXLOOPS=max_loops
 379         /SEED=@{RANDOM,seed_value@}
 380         /UNDEFINED=@{WARN,NOWARN@}
 381
 382 (data output)
 383         /CC@{A,B,C,D,E@}=@{'npre,pre,suf,nsuf','npre.pre.suf.nsuf'@}
 384         /DECIMAL=@{DOT,COMMA@}
 385         /FORMAT=fmt_spec
 386         /WIB=@{NATIVE,MSBFIRST,LSBFIRST,VAX@}
 387         /WRB=@{NATIVE,ISL,ISB,IDL,IDB,VF,VD,VG,ZS,ZL@}
 388
 389 (output routing)
 390         /ERRORS=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}
 391         /MESSAGES=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}
 392         /PRINTBACK=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}
 393         /RESULTS=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}
 394
 395 (output driver options)
 396         /HEADERS=@{NO,YES,BLANK@}
 397         /LENGTH=@{NONE,length_in_lines@}
 398         /MORE=@{ON,OFF@}
 399         /WIDTH=@{NARROW,WIDTH,n_characters@}
 400
 401 (logging)
 402         /JOURNAL=@{ON,OFF@} ['file-name']
 403
 404 (system files)
 405         /COMPRESSION=@{ON,OFF@}
 406         /SCOMPRESSION=@{ON,OFF@}
 407
 408 (miscellaneous)
 409         /SAFER=ON
 410         /LOCALE='string'
 411
 412
 413 (obsolete settings accepted for compatibility, but ignored)
 414         /BOXSTRING=@{'xxx','xxxxxxxxxxx'@}
 415         /CASE=@{UPPER,UPLOW@}
 416         /CPI=cpi_value
 417         /HIGHRES=@{ON,OFF@}
 418         /HISTOGRAM='c'
 419         /LOWRES=@{AUTO,ON,OFF@}
 420         /LPI=lpi_value
 421         /MENUS=@{STANDARD,EXTENDED@}
 422         /MXMEMORY=max_memory
 423         /SCRIPTTAB='c'
 424         /TB1=@{'xxx','xxxxxxxxxxx'@}
 425         /TBFONTS='string'
 426         /XSORT=@{YES,NO@}
 427 @end display
 428
 429 @cmd{SET} allows the user to adjust several parameters relating to
 430 PSPP's execution.  Since there are many subcommands to this command, its
 431 subcommands will be examined in groups.
 432
 433 On subcommands that take boolean values, ON and YES are synonym, and
 434 as are OFF and NO, when used as subcommand values.
 435
 436 The data input subcommands affect the way that data is read from data
 437 files.  The data input subcommands are
 438
 439 @table @asis
 440 @item BLANKS
 441 @anchor{SET BLANKS}
 442 This is the value assigned to an item data item that is empty or
 443 contains only white space.  An argument of SYSMIS or '.' will cause the
 444 system-missing value to be assigned to null items.  This is the
 445 default.  Any real value may be assigned.
 446
 447 @item DECIMAL
 448 @anchor{SET DECIMAL}
 449 This value may be set to DOT or COMMA.
 450 Setting it to DOT causes the decimal point character to be
 451 @samp{.} and the grouping character to be @samp{,}.
 452 Setting it to COMMA
 453 causes the decimal point character to be @samp{,} and the grouping
 454 character to be @samp{.}.
 455 The default value is determined from the system locale.
 456
 457 @item FORMAT
 458 Allows the default numeric input/output format to be specified.  The
 459 default is F8.2.  @xref{Input and Output Formats}.
 460
 461 @item EPOCH
 462 @anchor{SET EPOCH}
 463 Specifies the range of years used when a 2-digit year is read from a
 464 data file or used in a date construction expression (@pxref{Date
 465 Construction}).  If a 4-digit year is specified for the epoch, then
 466 2-digit years are interpreted starting from that year, known as the
 467 epoch.  If AUTOMATIC (the default) is specified, then the epoch begins
 468 69 years before the current date.
 469
 470 @item RIB
 471 @anchor{SET RIB}
 472
 473 PSPP extension to set the byte ordering (endianness) used for reading
 474 data in IB or PIB format (@pxref{Binary and Hexadecimal Numeric
 475 Formats}).  In MSBFIRST ordering, the most-significant byte appears at
 476 the left end of a IB or PIB field.  In LSBFIRST ordering, the
 477 least-significant byte appears at the left end.  VAX ordering is like
 478 MSBFIRST, except that each pair of bytes is in reverse order.  NATIVE,
 479 the default, is equivalent to MSBFIRST or LSBFIRST depending on the
 480 native format of the machine running PSPP.
 481
 482 @item RRB
 483 @anchor{SET RRB}
 484
 485 PSPP extension to set the floating-point format used for reading data in
 486 RB format (@pxref{Binary and Hexadecimal Numeric Formats}).  The
 487 possibilities are:
 488
 489 @table @asis
 490 @item NATIVE
 491 The native format of the machine running PSPP.  Equivalent to either IDL
 492 or IDB.
 493
 494 @item ISL
 495 32-bit IEEE 754 single-precision floating point, in little-endian byte
 496 order.
 497
 498 @item ISB
 499 32-bit IEEE 754 single-precision floating point, in big-endian byte
 500 order.
 501
 502 @item IDL
 503 64-bit IEEE 754 double-precision floating point, in little-endian byte
 504 order.
 505
 506 @item IDB
 507 64-bit IEEE 754 double-precision floating point, in big-endian byte
 508 order.
 509
 510 @item VF
 511 32-bit VAX F format, in VAX-endian byte order.
 512
 513 @item VD
 514 64-bit VAX D format, in VAX-endian byte order.
 515
 516 @item VG
 517 64-bit VAX G format, in VAX-endian byte order.
 518
 519 @item ZS
 520 32-bit IBM Z architecture short format hexadecimal floating point, in
 521 big-endian byte order.
 522
 523 @item ZL
 524 64-bit IBM Z architecture long format hexadecimal floating point, in
 525 big-endian byte order.
 526
 527 Z architecture also supports IEEE 754 floating point.  The ZS and ZL
 528 formats are only for use with very old input files.
 529 @end table
 530 The default is NATIVE.
 531 @end table
 532
 533 Program input subcommands affect the way that programs are parsed when
 534 they are typed interactively or run from a command file.  They are
 535
 536 @table @asis
 537 @item ENDCMD
 538 This is a single character indicating the end of a command.  The default
 539 is @samp{.}.  Don't change this.
 540
 541 @item NULLINE
 542 Whether a blank line is interpreted as ending the current command.  The
 543 default is ON.
 544 @end table
 545
 546 Interaction subcommands affect the way that PSPP interacts with an
 547 online user.  The interaction subcommands are
 548
 549 @table @asis
 550 @item CPROMPT
 551 The command continuation prompt.  The default is @samp{    > }.
 552
 553 @item DPROMPT
 554 Prompt used when expecting data input within @cmd{BEGIN DATA} (@pxref{BEGIN
 555 DATA}).  The default is @samp{data> }.
 556
 557 @item MXERRS
 558 The maximum number of errors before PSPP halts processing of the current
 559 command file.  The default is 50.
 560
 561 @item MXWARNS
 562 The maximum number of warnings + errors before PSPP halts processing the
 563 current command file.
 564 The special value of zero means that all warning situations should be ignored.
 565 No warnings will be issued, except a single initial warning advising the user
 566 that warnings will not be given.
 567 The default value is 100.
 568
 569 @item PROMPT
 570 The command prompt.  The default is @samp{PSPP> }.
 571 @end table
 572
 573 Program execution subcommands control the way that PSPP commands
 574 execute.  The program execution subcommands are
 575
 576 @table @asis
 577 @item MEXPAND
 578 @itemx MITERATE
 579 @itemx MNEST
 580 @itemx MPRINT
 581 Currently not used.
 582
 583 @item MXLOOPS
 584 The maximum number of iterations for an uncontrolled loop (@pxref{LOOP}).
 585
 586 @item SEED
 587 The initial pseudo-random number seed.  Set to a real number or to
 588 RANDOM, which will obtain an initial seed from the current time of day.
 589
 590 @item UNDEFINED
 591 Currently not used.
 592
 593 @item WORKSPACE
 594 The maximum amount of memory that PSPP will use to store data being processed.
 595 If memory in excess of the workspace size is required, then PSPP will start
 596 to use temporary files to store the data.
 597 Setting a higher value will, in general, mean procedures will run faster,
 598 but may cause other applications to run slower.
 599 On platforms without virtual memory management, setting a very large workspace
 600 may cause PSPP to abort.
 601 @cindex workspace
 602 @cindex memory, amount used to store cases
 603 @end table
 604
 605 Data output subcommands affect the format of output data.  These
 606 subcommands are
 607
 608 @table @asis
 609 @item CCA
 610 @itemx CCB
 611 @itemx CCC
 612 @itemx CCD
 613 @itemx CCE
 614 @anchor{CCx Settings}
 615
 616 Set up custom currency formats.  @xref{Custom Currency Formats}, for
 617 details.
 618
 619 @item DECIMAL
 620 The default DOT setting causes the decimal point character to be
 621 @samp{.}.  A setting of COMMA causes the decimal point character to be
 622 @samp{,}.
 623
 624 @item FORMAT
 625 Allows the default numeric input/output format to be specified.  The
 626 default is F8.2.  @xref{Input and Output Formats}.
 627
 628 @item WIB
 629 @anchor{SET WIB}
 630
 631 PSPP extension to set the byte ordering (endianness) used for writing
 632 data in IB or PIB format (@pxref{Binary and Hexadecimal Numeric
 633 Formats}).  In MSBFIRST ordering, the most-significant byte appears at
 634 the left end of a IB or PIB field.  In LSBFIRST ordering, the
 635 least-significant byte appears at the left end.  VAX ordering is like
 636 MSBFIRST, except that each pair of bytes is in reverse order.  NATIVE,
 637 the default, is equivalent to MSBFIRST or LSBFIRST depending on the
 638 native format of the machine running PSPP.
 639
 640 @item WRB
 641 @anchor{SET WRB}
 642
 643 PSPP extension to set the floating-point format used for writing data in
 644 RB format (@pxref{Binary and Hexadecimal Numeric Formats}).  The choices
 645 are the same as SET RIB.  The default is NATIVE.
 646 @end table
 647
 648 In the PSPP text-based interface, the output routing subcommands
 649 affect where output is sent.  The following values are allowed for
 650 each of these subcommands:
 651
 652 @table @asis
 653 @item OFF
 654 @item NONE
 655 Discard this kind of output.
 656
 657 @item TERMINAL
 658 Write this output to the terminal, but not to listing files and other
 659 output devices.
 660
 661 @item LISTING
 662 Write this output to listing files and other output devices, but not
 663 to the terminal.
 664
 665 @item ON
 666 @itemx BOTH
 667 Write this type of output to all output devices.
 668 @end table
 669
 670 These output routing subcommands are:
 671
 672 @table @asis
 673 @item ERRORS
 674 Applies to error and warning messages.  The default is BOTH.
 675
 676 @itemx MESSAGES
 677 Applies to notes.  The default is BOTH.
 678
 679 @itemx PRINTBACK
 680 Determines whether the syntax used for input is printed back as part
 681 of the output.  The default is NONE.
 682
 683 @itemx RESULTS
 684 Applies to everything not in one of the above categories, such as the
 685 results of statistical procedures.  The default is BOTH.
 686 @end table
 687
 688 These subcommands have no effect on output in the PSPP GUI
 689 environment.
 690
 691 Output driver option subcommands affect output drivers' settings.  These
 692 subcommands are
 693
 694 @table @asis
 695 @item HEADERS
 696 @itemx LENGTH
 697 @itemx MORE
 698 @itemx PAGER
 699 @itemx WIDTH
 700 @end table
 701
 702 @cindex headers
 703 @cindex length
 704 @cindex more
 705 @cindex pager
 706 @cindex width
 707
 708
 709 Logging subcommands affect logging of commands executed to external
 710 files.  These subcommands are
 711
 712 @table @asis
 713 @item JOURNAL
 714 @itemx LOG
 715 These subcommands, which are synonyms, control the journal.  The
 716 default is ON, which causes commands entered interactively to be
 717 written to the journal file.  Commands included from syntax files that
 718 are included interactively and error messages printed by PSPP are also
 719 written to the journal file, prefixed by @samp{>}.  OFF disables use
 720 of the journal.
 721
 722 The journal is named @file{pspp.jnl} by default.  A different name may
 723 be specified.
 724 @end table
 725
 726 System file subcommands affect the default format of system files
 727 produced by PSPP.  These subcommands are
 728
 729 @table @asis
 730 @item COMPRESSION
 731 Not currently used.
 732
 733 @item SCOMPRESSION
 734 Whether system files created by @cmd{SAVE} or @cmd{XSAVE} are
 735 compressed by default.  The default is ON.
 736 @end table
 737
 738 Security subcommands affect the operations that commands are allowed to
 739 perform.  The security subcommands are
 740
 741 @table @asis
 742 @item SAFER
 743 Setting this option disables the following operations:
 744
 745 @itemize @bullet
 746 @item
 747 The ERASE command.
 748 @item
 749 The HOST command.
 750 @item
 751 The PERMISSIONS command.
 752 @item
 753 Pipes (file names beginning or ending with @samp{|}).
 754 @end itemize
 755
 756 Be aware that this setting does not guarantee safety (commands can still
 757 overwrite files, for instance) but it is an improvement.
 758 When set, this setting cannot be reset during the same session, for
 759 obvious security reasons.
 760
 761 @item LOCALE
 762 @cindex locale
 763 @cindex encoding, characters
 764 This item is used to set the default character encoding.
 765 The encoding may be specified either as an encoding name or alias
 766 (see @url{http://www.iana.org/assignments/character-sets}), or
 767 as a locale name.
 768 If given as a locale name, only the character encoding of the
 769 locale is relevant.
 770
 771 System files written by PSPP will use this encoding.
 772 System files read by PSPP, for which the encoding is unknown, will be
 773 interpreted using this encoding.
 774
 775 The full list of valid encodings and locale names/alias are operating system
 776 dependent.
 777 The following are all examples of acceptable syntax on common GNU/Linux
 778 systems.
 779 @example
 780
 781 SET LOCALE='iso-8859-1'.
 782
 783 SET LOCALE='ru_RU.cp1251'.
 784
 785 SET LOCALE='japanese'.
 786
 787 @end example
 788
 789 Contrary to the intuition, this command does not affect any aspect
 790 of the system's locale.
 791 @end table
 792
 793 @node SHOW
 794 @comment  node-name,  next,  previous,  up
 795 @section SHOW
 796 @vindex SHOW
 797
 798 @display
 799 SHOW
 800         [ALL]
 801         [BLANKS]
 802         [CC]
 803         [CCA]
 804         [CCB]
 805         [CCC]
 806         [CCD]
 807         [CCE]
 808         [COPYING]
 809         [DECIMALS]
 810         [ENDCMD]
 811         [FORMAT]
 812         [LENGTH]
 813         [MXERRS]
 814         [MXLOOPS]
 815         [MXWARNS]
 816         [SCOMPRESSION]
 817         [UNDEFINED]
 818         [WARRANTY]
 819         [WEIGHT]
 820         [WIDTH]
 821 @end display
 822
 823 @cmd{SHOW} can be used to display the current state of PSPP's execution
 824 parameters.  Parameters that can be changed using @cmd{SET}
 825 (@pxref{SET}), can be examined using @cmd{SHOW} using the subcommand
 826 with the same name.  @code{SHOW} supports the following additional
 827 subcommands:
 828
 829 @table @code
 830 @item ALL
 831 Show all settings.
 832 @item CC
 833 Show all custom currency settings (CCA through CCE).
 834 @item WARRANTY
 835 Show details of the lack of warranty for PSPP.
 836 @item COPYING
 837 Display the terms of PSPP's copyright licence (@pxref{License}).
 838 @end table
 839
 840 Specifying @cmd{SHOW} without any subcommands is equivalent to SHOW ALL.
 841
 842 @node SUBTITLE
 843 @section SUBTITLE
 844 @vindex SUBTITLE
 845
 846 @display
 847 SUBTITLE 'subtitle_string'.
 848   or
 849 SUBTITLE subtitle_string.
 850 @end display
 851
 852 @cmd{SUBTITLE} provides a subtitle to a particular PSPP
 853 run.  This subtitle appears at the top of each output page below the
 854 title, if headers are enabled on the output device.
 855
 856 Specify a subtitle as a string in quotes.  The alternate syntax that did
 857 not require quotes is now obsolete.  If it is used then the subtitle is
 858 converted to all uppercase.
 859
 860 @node TITLE
 861 @section TITLE
 862 @vindex TITLE
 863
 864 @display
 865 TITLE 'title_string'.
 866   or
 867 TITLE title_string.
 868 @end display
 869
 870 @cmd{TITLE} provides a title to a particular PSPP run.
 871 This title appears at the top of each output page, if headers are enabled
 872 on the output device.
 873
 874 Specify a title as a string in quotes.  The alternate syntax that did
 875 not require quotes is now obsolete.  If it is used then the title is
 876 converted to all uppercase.