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 * OUTPUT::                      Modify the appearance of the output.
  29 * PERMISSIONS::                 Change permissions on a file.
  30 * PRESERVE and RESTORE::        Saving settings and restoring them later.
  31 * SET::                         Adjust @pspp{} runtime parameters.
  32 * SHOW::                        Display runtime parameters.
  33 * SUBTITLE::                    Provide a document subtitle.
  34 * TITLE::                       Provide a document title.
  35 @end menu
  36
  37 @node ADD DOCUMENT
  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 @subcmd{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 @section ERASE
 170 @vindex ERASE
 171
 172 @display
 173 ERASE FILE @var{file_name}.
 174 @end display
 175
 176 @cmd{ERASE FILE} deletes a file from the local filesystem.
 177 @var{file_name} must be quoted.
 178 This command cannot be used if the SAFER (@pxref{SET}) setting is active.
 179
 180
 181 @node EXECUTE
 182 @section EXECUTE
 183 @vindex EXECUTE
 184
 185 @display
 186 EXECUTE.
 187 @end display
 188
 189 @cmd{EXECUTE} causes the active dataset to be read and all pending
 190 transformations to be executed.
 191
 192 @node FILE LABEL
 193 @section FILE LABEL
 194 @vindex FILE LABEL
 195
 196 @display
 197 FILE LABEL @var{file_label}.
 198 @end display
 199
 200 @cmd{FILE LABEL} provides a title for the active dataset.  This
 201 title will be saved into system files and portable files that are
 202 created during this @pspp{} run.
 203
 204 @var{file_label} should not be quoted.
 205 If quotes are included, they are literally interpreted and become part of the file label.
 206
 207 @node FINISH
 208 @section FINISH
 209 @vindex FINISH
 210
 211 @display
 212 FINISH.
 213 @end display
 214
 215 @cmd{FINISH} terminates the current @pspp{} session and returns
 216 control to the operating system.
 217
 218 @node HOST
 219 @section HOST
 220 @vindex HOST
 221
 222 @display
 223 HOST.
 224 HOST COMMAND=['@var{command}'...].
 225 @end display
 226
 227 @cmd{HOST} suspends the current @pspp{} session and temporarily returns control
 228 to the operating system.
 229 This command cannot be used if the SAFER (@pxref{SET}) setting is active.
 230
 231 If the @subcmd{COMMAND} subcommand is specified, as a sequence of shell
 232 commands as quoted strings within square brackets, then @pspp{} executes
 233 them together in a single subshell.
 234
 235 If no subcommands are specified, then @pspp{} invokes an interactive
 236 subshell.
 237
 238 @node INCLUDE
 239 @section INCLUDE
 240 @vindex INCLUDE
 241
 242 @display
 243         INCLUDE [FILE=]'@var{file_name}' [ENCODING='@var{encoding}'].
 244 @end display
 245
 246 @cmd{INCLUDE} causes the @pspp{} command processor to read an
 247 additional command file as if it were included bodily in the current
 248 command file.
 249 If errors are encountered in the included file, then command processing will
 250 stop and no more commands will be processed.
 251 Include files may be nested to any depth, up to the limit of available
 252 memory.
 253
 254 The @cmd{INSERT} command (@pxref{INSERT}) is a more flexible
 255 alternative to @cmd{INCLUDE}.  An @cmd{INCLUDE} command acts the same as
 256 @cmd{INSERT} with @subcmd{ERROR=STOP CD=NO SYNTAX=BATCH} specified.
 257
 258 The optional @subcmd{ENCODING} subcommand has the same meaning as with @cmd{INSERT}.
 259
 260 @node INSERT
 261 @section INSERT
 262 @vindex INSERT
 263
 264 @display
 265      INSERT [FILE=]'@var{file_name}'
 266         [CD=@{NO,YES@}]
 267         [ERROR=@{CONTINUE,STOP@}]
 268         [SYNTAX=@{BATCH,INTERACTIVE@}]
 269         [ENCODING=@{LOCALE, '@var{charset_name}'@}].
 270 @end display
 271
 272 @cmd{INSERT} is similar to @cmd{INCLUDE} (@pxref{INCLUDE})
 273 but somewhat more flexible.
 274 It causes the command processor to read a file as if it were embedded in the
 275 current command file.
 276
 277 If @subcmd{CD=YES} is specified, then before including the file, the
 278 current directory  will be changed to the directory of the included
 279 file.
 280 The default setting is @samp{CD=NO}.
 281 Note that this directory will remain current until it is
 282 changed explicitly (with the @cmd{CD} command, or a subsequent
 283 @cmd{INSERT} command with the @samp{CD=YES} option).
 284 It will not revert to its original setting even after the included
 285 file is finished processing.
 286
 287 If @subcmd{ERROR=STOP} is specified, errors encountered in the
 288 inserted file will cause processing to immediately cease.
 289 Otherwise processing will continue at the next command.
 290 The default setting is @subcmd{ERROR=CONTINUE}.
 291
 292 If @subcmd{SYNTAX=INTERACTIVE} is specified then the syntax contained in
 293 the included file must conform to interactive syntax
 294 conventions. @xref{Syntax Variants}.
 295 The default setting is @subcmd{SYNTAX=BATCH}.
 296
 297 @subcmd{ENCODING} optionally specifies the character set used by the included
 298 file.  Its argument, which is not case-sensitive, must be in one of
 299 the following forms:
 300
 301 @table @asis
 302 @item @subcmd{LOCALE}
 303 The encoding used by the system locale, or as overridden by the
 304 @cmd{SET} command (@pxref{SET}).  On GNU/Linux and other Unix-like systems,
 305 environment variables, e.g.@: @env{LANG} or @env{LC_ALL}, determine the
 306 system locale.
 307
 308 @item @var{charset_name}
 309 One of the character set names listed by @acronym{IANA} at
 310 @uref{http://www.iana.org/assignments/character-sets}.  Some examples
 311 are @code{ASCII} (United States), @code{ISO-8859-1} (western Europe),
 312 @code{EUC-JP} (Japan), and @code{windows-1252} (Windows).  Not all
 313 systems support all character sets.
 314
 315 @item @code{Auto,@var{encoding}}
 316 Automatically detects whether a syntax file is encoded in an Unicode
 317 encoding such as UTF-8, UTF-16, or UTF-32.  If it is not, then @pspp{}
 318 generally assumes that the file is encoded in @var{encoding} (an @acronym{IANA}
 319 character set name).  However, if @var{encoding} is UTF-8, and the
 320 syntax file is not valid UTF-8, @pspp{} instead assumes that the file
 321 is encoded in @code{windows-1252}.
 322
 323 For best results, @var{encoding} should be an @acronym{ASCII}-compatible
 324 encoding (the most common locale encodings are all @acronym{ASCII}-compatible),
 325 because encodings that are not @acronym{ASCII} compatible cannot be
 326 automatically distinguished from UTF-8.
 327
 328 @item @code{Auto}
 329 @item @code{Auto,Locale}
 330 Automatic detection, as above, with the default encoding taken from
 331 the system locale or the setting on @subcmd{SET LOCALE}.
 332 @end table
 333
 334 When ENCODING is not specified, the default is taken from the
 335 @option{--syntax-encoding} command option, if it was specified, and
 336 otherwise it is @code{Auto}.
 337
 338 @node OUTPUT
 339 @section OUTPUT
 340 @vindex OUTPUT
 341 @cindex precision, of output
 342 @cindex decimal places
 343
 344 @display
 345 OUTPUT MODIFY
 346        /SELECT TABLES
 347        /TABLECELLS SELECT = [ @{SIGNIFICANCE, COUNT@} ]
 348                    FORMAT = @var{fmt_spec}.
 349 @end display
 350 @note{In the above synopsis the characters @samp{[} and @samp{]} are literals.
 351 They must appear in the syntax to be interpreted.}
 352
 353 @cmd{OUTPUT} changes the appearance of the tables in which results are printed.
 354 In particular, it can be used to set the format and precision to which results are displayed.
 355
 356 After running this command, the default table appearance parameters will have been modified and  each
 357 new output table generated will use the new parameters.
 358
 359 Following @code{/TABLECELLS SELECT =} a list of cell classes must appear, enclosed in square
 360 brackets.  This list determines the classes of values should be selected for modification.
 361 Each class can be:
 362
 363 @table @asis
 364 @item SIGNIFICANCE
 365 Significance of tests (p-values).
 366
 367 @item COUNT
 368 Counts or sums of weights.
 369 @end table
 370
 371 The value of @var{fmt_spec} must be a valid output format (@pxref{Input and Output Formats}).
 372 Note that not all possible formats are meaningful for all classes.
 373
 374 @node PERMISSIONS
 375 @section PERMISSIONS
 376 @vindex PERMISSIONS
 377 @cindex mode
 378 @cindex file mode
 379 @cindex changing file permissions
 380
 381 @display
 382 PERMISSIONS
 383         FILE='@var{file_name}'
 384         /PERMISSIONS = @{READONLY,WRITEABLE@}.
 385 @end display
 386
 387 @cmd{PERMISSIONS} changes the permissions of a file.
 388 There is one mandatory subcommand which specifies the permissions to
 389 which the file should be changed.
 390 If you set a file's  permission  to @subcmd{READONLY}, then the file will become
 391 unwritable either by you or anyone else on the system.
 392 If you set the permission to @subcmd{WRITEABLE}, then the file will become
 393 writeable by you; the permissions afforded to others will be
 394 unchanged.
 395 This command cannot be used if the @subcmd{SAFER} (@pxref{SET}) setting is active.
 396
 397
 398 @node PRESERVE and RESTORE
 399 @section PRESERVE and RESTORE
 400 @vindex PRESERVE
 401 @vindex RESTORE
 402
 403 @display
 404 PRESERVE.
 405 @dots{}
 406 RESTORE.
 407 @end display
 408
 409 @cmd{PRESERVE} saves all of the settings that @cmd{SET} (@pxref{SET})
 410 can adjust.  A later @cmd{RESTORE} command restores those settings.
 411
 412 @cmd{PRESERVE} can be nested up to five levels deep.
 413
 414 @node SET
 415 @section SET
 416 @vindex SET
 417
 418 @display
 419 SET
 420
 421 (data input)
 422         /BLANKS=@{SYSMIS,'.',number@}
 423         /DECIMAL=@{DOT,COMMA@}
 424         /FORMAT=@var{fmt_spec}
 425         /EPOCH=@{AUTOMATIC,@var{year}@}
 426         /RIB=@{NATIVE,MSBFIRST,LSBFIRST,VAX@}
 427         /RRB=@{NATIVE,ISL,ISB,IDL,IDB,VF,VD,VG,ZS,ZL@}
 428
 429 (interaction)
 430         /MXERRS=@var{max_errs}
 431         /MXWARNS=@var{max_warnings}
 432         /WORKSPACE=@var{workspace_size}
 433
 434 (syntax execution)
 435         /LOCALE='@var{locale}'
 436         /MEXPAND=@{ON,OFF@}
 437         /MITERATE=@var{max_iterations}
 438         /MNEST=@var{max_nest}
 439         /MPRINT=@{ON,OFF@}
 440         /MXLOOPS=@var{max_loops}
 441         /SEED=@{RANDOM,@var{seed_value}@}
 442         /UNDEFINED=@{WARN,NOWARN@}
 443         /FUZZBITS=@var{fuzzbits}
 444
 445 (data output)
 446         /CC@{A,B,C,D,E@}=@{'@var{npre},@var{pre},@var{suf},@var{nsuf}','@var{npre}.@var{pre}.@var{suf}.@var{nsuf}'@}
 447         /DECIMAL=@{DOT,COMMA@}
 448         /FORMAT=@var{fmt_spec}
 449         /WIB=@{NATIVE,MSBFIRST,LSBFIRST,VAX@}
 450         /WRB=@{NATIVE,ISL,ISB,IDL,IDB,VF,VD,VG,ZS,ZL@}
 451
 452 (output routing)
 453         /ERRORS=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}
 454         /MESSAGES=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}
 455         /PRINTBACK=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}
 456         /RESULTS=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}
 457
 458 (output driver options)
 459         /HEADERS=@{NO,YES,BLANK@}
 460         /LENGTH=@{NONE,@var{n_lines}@}
 461         /MORE=@{ON,OFF@}
 462         /WIDTH=@{NARROW,WIDTH,@var{n_characters}@}
 463         /TNUMBERS=@{VALUES,LABELS,BOTH@}
 464         /TVARS=@{NAMES,LABELS,BOTH@}
 465
 466 (logging)
 467         /JOURNAL=@{ON,OFF@} ['@var{file_name}']
 468
 469 (system files)
 470         /COMPRESSION=@{ON,OFF@}
 471         /SCOMPRESSION=@{ON,OFF@}
 472
 473 (miscellaneous)
 474         /SAFER=ON
 475         /LOCALE='@var{string}'
 476
 477
 478 (obsolete settings accepted for compatibility, but ignored)
 479         /BOXSTRING=@{'@var{xxx}','@var{xxxxxxxxxxx}'@}
 480         /CASE=@{UPPER,UPLOW@}
 481         /CPI=cpi_value
 482         /HIGHRES=@{ON,OFF@}
 483         /HISTOGRAM='@var{c}'
 484         /LOWRES=@{AUTO,ON,OFF@}
 485         /LPI=@var{lpi_value}
 486         /MENUS=@{STANDARD,EXTENDED@}
 487         /MXMEMORY=@var{max_memory}
 488         /SCRIPTTAB='c'
 489         /TB1=@{'@var{xxx}','@var{xxxxxxxxxxx}'@}
 490         /TBFONTS='@var{string}'
 491         /XSORT=@{YES,NO@}
 492 @end display
 493
 494 @cmd{SET} allows the user to adjust several parameters relating to
 495 @pspp{}'s execution.  Since there are many subcommands to this command, its
 496 subcommands will be examined in groups.
 497
 498 For subcommands that take boolean values, @subcmd{ON} and @subcmd{YES} are synonymous,
 499 as are @subcmd{OFF} and @subcmd{NO}, when used as subcommand values.
 500
 501 The data input subcommands affect the way that data is read from data
 502 files.  The data input subcommands are
 503
 504 @table @asis
 505 @item BLANKS
 506 @anchor{SET BLANKS}
 507 This is the value assigned to an item data item that is empty or
 508 contains only white space.  An argument of SYSMIS or '.' will cause the
 509 system-missing value to be assigned to null items.  This is the
 510 default.  Any real value may be assigned.
 511
 512 @item DECIMAL
 513 @anchor{SET DECIMAL}
 514 This value may be set to @subcmd{DOT} or @subcmd{COMMA}.
 515 Setting it to @subcmd{DOT} causes the decimal point character to be
 516 @samp{.} and the grouping character to be @samp{,}.
 517 Setting it to @subcmd{COMMA}
 518 causes the decimal point character to be @samp{,} and the grouping
 519 character to be @samp{.}.
 520 The default value is determined from the system locale.
 521
 522 @item FORMAT
 523 Allows the default numeric input/output format to be specified.  The
 524 default is F8.2.  @xref{Input and Output Formats}.
 525
 526 @item EPOCH
 527 @anchor{SET EPOCH}
 528 Specifies the range of years used when a 2-digit year is read from a
 529 data file or used in a date construction expression (@pxref{Date
 530 Construction}).  If a 4-digit year is specified for the epoch, then
 531 2-digit years are interpreted starting from that year, known as the
 532 epoch.  If @subcmd{AUTOMATIC} (the default) is specified, then the epoch begins
 533 69 years before the current date.
 534
 535 @item RIB
 536 @anchor{SET RIB}
 537
 538 @pspp{} extension to set the byte ordering (endianness) used for reading
 539 data in IB or PIB format (@pxref{Binary and Hexadecimal Numeric
 540 Formats}).  In @subcmd{MSBFIRST} ordering, the most-significant byte appears at
 541 the left end of a IB or PIB field.  In @subcmd{LSBFIRST} ordering, the
 542 least-significant byte appears at the left end.  @subcmd{VAX} ordering is like
 543 @subcmd{MSBFIRST}, except that each pair of bytes is in reverse order.  @subcmd{NATIVE},
 544 the default, is equivalent to @subcmd{MSBFIRST} or @subcmd{LSBFIRST} depending on the
 545 native format of the machine running @pspp{}.
 546
 547 @item RRB
 548 @anchor{SET RRB}
 549
 550 @pspp{} extension to set the floating-point format used for reading data in
 551 RB format (@pxref{Binary and Hexadecimal Numeric Formats}).  The
 552 possibilities are:
 553
 554 @table @asis
 555 @item NATIVE
 556 The native format of the machine running @pspp{}.  Equivalent to either IDL
 557 or IDB.
 558
 559 @item ISL
 560 32-bit IEEE 754 single-precision floating point, in little-endian byte
 561 order.
 562
 563 @item ISB
 564 32-bit IEEE 754 single-precision floating point, in big-endian byte
 565 order.
 566
 567 @item IDL
 568 64-bit IEEE 754 double-precision floating point, in little-endian byte
 569 order.
 570
 571 @item IDB
 572 64-bit IEEE 754 double-precision floating point, in big-endian byte
 573 order.
 574
 575 @item VF
 576 32-bit VAX F format, in VAX-endian byte order.
 577
 578 @item VD
 579 64-bit VAX D format, in VAX-endian byte order.
 580
 581 @item VG
 582 64-bit VAX G format, in VAX-endian byte order.
 583
 584 @item ZS
 585 32-bit IBM Z architecture short format hexadecimal floating point, in
 586 big-endian byte order.
 587
 588 @item ZL
 589 64-bit IBM Z architecture long format hexadecimal floating point, in
 590 big-endian byte order.
 591
 592 Z architecture also supports IEEE 754 floating point.  The ZS and ZL
 593 formats are only for use with very old input files.
 594 @end table
 595 The default is NATIVE.
 596 @end table
 597
 598 Interaction subcommands affect the way that @pspp{} interacts with an
 599 online user.  The interaction subcommands are
 600
 601 @table @asis
 602 @item MXERRS
 603 The maximum number of errors before @pspp{} halts processing of the current
 604 command file.  The default is 50.
 605
 606 @item MXWARNS
 607 The maximum number of warnings + errors before @pspp{} halts processing the
 608 current command file.
 609 The special value of zero means that all warning situations should be ignored.
 610 No warnings will be issued, except a single initial warning advising the user
 611 that warnings will not be given.
 612 The default value is 100.
 613 @end table
 614
 615 Syntax execution subcommands control the way that @pspp{} commands
 616 execute.  The syntax execution subcommands are
 617
 618 @table @asis
 619 @item LOCALE
 620 Overrides the system locale for the purpose of reading and writing
 621 syntax and data files.  The argument should be a locale name in the
 622 general form @code{@var{language}_@var{country}.@var{encoding}}, where @var{language}
 623 and @var{country} are 2-character language and country abbreviations,
 624 respectively, and @var{encoding} is an @acronym{IANA} character set name.
 625 Example locales are @code{en_US.UTF-8} (UTF-8 encoded English as
 626 spoken in the United States) and @code{ja_JP.EUC-JP} (EUC-JP encoded
 627 Japanese as spoken in Japan).
 628
 629 @item MEXPAND
 630 @itemx MITERATE
 631 @itemx MNEST
 632 @itemx MPRINT
 633 Currently not used.
 634
 635 @item MXLOOPS
 636 The maximum number of iterations for an uncontrolled loop (@pxref{LOOP}).
 637 The default @var{max_loops} is 40.
 638
 639 @item SEED
 640 The initial pseudo-random number seed.  Set to a real number or to
 641 RANDOM, which will obtain an initial seed from the current time of day.
 642
 643 @item UNDEFINED
 644 Currently not used.
 645
 646 @item FUZZBITS
 647 @anchor{SET FUZZBITS}
 648 The maximum number of bits of errors in the least-significant places
 649 to accept for rounding up a value that is almost halfway between two
 650 possibilities for rounding with the RND operator (@pxref{Miscellaneous
 651 Mathematics}).  The default @var{fuzzbits} is 6.
 652
 653 @item WORKSPACE
 654 The maximum amount of memory (in kilobytes) that @pspp{} will use to store data being processed.
 655 If memory in excess of the workspace size is required, then @pspp{} will start
 656 to use temporary files to store the data.
 657 Setting a higher value will, in general, mean procedures will run faster,
 658 but may cause other applications to run slower.
 659 On platforms without virtual memory management, setting a very large workspace
 660 may cause @pspp{} to abort.
 661 @cindex workspace
 662 @cindex memory, amount used to store cases
 663 @end table
 664
 665 Data output subcommands affect the format of output data.  These
 666 subcommands are
 667
 668 @table @asis
 669 @item CCA
 670 @itemx CCB
 671 @itemx CCC
 672 @itemx CCD
 673 @itemx CCE
 674 @anchor{CCx Settings}
 675
 676 Set up custom currency formats.  @xref{Custom Currency Formats}, for
 677 details.
 678
 679 @item DECIMAL
 680 The default @subcmd{DOT} setting causes the decimal point character to be
 681 @samp{.}.  A setting of @subcmd{COMMA} causes the decimal point character to be
 682 @samp{,}.
 683
 684 @item FORMAT
 685 Allows the default numeric input/output format to be specified.  The
 686 default is F8.2.  @xref{Input and Output Formats}.
 687
 688 @item WIB
 689 @anchor{SET WIB}
 690
 691 @pspp{} extension to set the byte ordering (endianness) used for writing
 692 data in IB or PIB format (@pxref{Binary and Hexadecimal Numeric
 693 Formats}).  In @subcmd{MSBFIRST} ordering, the most-significant byte appears at
 694 the left end of a IB or PIB field.  In @subcmd{LSBFIRST} ordering, the
 695 least-significant byte appears at the left end.  @subcmd{VAX} ordering is like
 696 @subcmd{MSBFIRST}, except that each pair of bytes is in reverse order.  @subcmd{NATIVE},
 697 the default, is equivalent to @subcmd{MSBFIRST} or @subcmd{LSBFIRST} depending on the
 698 native format of the machine running @pspp{}.
 699
 700 @item WRB
 701 @anchor{SET WRB}
 702
 703 @pspp{} extension to set the floating-point format used for writing data in
 704 RB format (@pxref{Binary and Hexadecimal Numeric Formats}).  The choices
 705 are the same as @subcmd{SET RIB}.  The default is @subcmd{NATIVE}.
 706 @end table
 707
 708 In the @pspp{} text-based interface, the output routing subcommands
 709 affect where output is sent.  The following values are allowed for
 710 each of these subcommands:
 711
 712 @table @asis
 713 @item OFF
 714 @item NONE
 715 Discard this kind of output.
 716
 717 @item TERMINAL
 718 Write this output to the terminal, but not to listing files and other
 719 output devices.
 720
 721 @item LISTING
 722 Write this output to listing files and other output devices, but not
 723 to the terminal.
 724
 725 @item ON
 726 @itemx BOTH
 727 Write this type of output to all output devices.
 728 @end table
 729
 730 These output routing subcommands are:
 731
 732 @table @asis
 733 @item ERRORS
 734 Applies to error and warning messages.  The default is @subcmd{BOTH}.
 735
 736 @item MESSAGES
 737 Applies to notes.  The default is @subcmd{BOTH}.
 738
 739 @item PRINTBACK
 740 Determines whether the syntax used for input is printed back as part
 741 of the output.  The default is @subcmd{NONE}.
 742
 743 @item RESULTS
 744 Applies to everything not in one of the above categories, such as the
 745 results of statistical procedures.  The default is @subcmd{BOTH}.
 746 @end table
 747
 748 These subcommands have no effect on output in the @pspp{} GUI
 749 environment.
 750
 751 Output driver option subcommands affect output drivers' settings.  These
 752 subcommands are
 753
 754 @table @asis
 755 @item HEADERS
 756 @itemx LENGTH
 757 @itemx MORE
 758 @itemx WIDTH
 759 @itemx TNUMBERS
 760 The @subcmd{TNUMBERS} option sets the way in which values are displayed in output tables.
 761 The valid settings are @subcmd{VALUES}, @subcmd{LABELS} and @subcmd{BOTH}.
 762 If @subcmd{TNUMBERS} is set to @subcmd{VALUES}, then all values are displayed with their literal value
 763 (which for a numeric value is a number and for a string value an alphanumeric string).
 764 If @subcmd{TNUMBERS} is set to @subcmd{LABELS}, then values are displayed using their assigned labels if any.
 765 (@xref{VALUE LABELS}.)
 766 If the a value has no label, then it will be displayed using its literal value.
 767 If @subcmd{TNUMBERS} is set to @subcmd{BOTH}, then values will be displayed with both their label
 768 (if any) and their literal value in parentheses.
 769 @item TVARS
 770 The @subcmd{TVARS} option sets the way in which variables are displayed in output tables.
 771 The valid settings are @subcmd{NAMES}, @subcmd{LABELS} and @subcmd{BOTH}.
 772 If @subcmd{TVARS} is set to @subcmd{NAMES}, then all variables are displayed using their names.
 773 If @subcmd{TVARS} is set to @subcmd{LABELS}, then variables are displayed using their label if one
 774 has been set.  If no label has been set, then the name will be used.
 775 (@xref{VARIABLE LABELS}.)
 776 If @subcmd{TVARS} is set to @subcmd{BOTH}, then variables will be displayed with both their label
 777 (if any) and their name in parentheses.
 778 @end table
 779
 780 @cindex headers
 781 @cindex length
 782 @cindex more
 783 @cindex pager
 784 @cindex width
 785 @cindex tnumbers
 786
 787
 788 Logging subcommands affect logging of commands executed to external
 789 files.  These subcommands are
 790
 791 @table @asis
 792 @item JOURNAL
 793 @itemx LOG
 794 These subcommands, which are synonyms, control the journal.  The
 795 default is @subcmd{ON}, which causes commands entered interactively to be
 796 written to the journal file.  Commands included from syntax files that
 797 are included interactively and error messages printed by @pspp{} are also
 798 written to the journal file, prefixed by @samp{>}.  @subcmd{OFF} disables use
 799 of the journal.
 800
 801 The journal is named @file{pspp.jnl} by default.  A different name may
 802 be specified.
 803 @end table
 804
 805 System file subcommands affect the default format of system files
 806 produced by @pspp{}.  These subcommands are
 807
 808 @table @asis
 809 @item COMPRESSION
 810 Not currently used.
 811
 812 @item SCOMPRESSION
 813 Whether system files created by @cmd{SAVE} or @cmd{XSAVE} are
 814 compressed by default.  The default is @subcmd{ON}.
 815 @end table
 816
 817 Security subcommands affect the operations that commands are allowed to
 818 perform.  The security subcommands are
 819
 820 @table @asis
 821 @item SAFER
 822 Setting this option disables the following operations:
 823
 824 @itemize @bullet
 825 @item
 826 The @cmd{ERASE} command.
 827 @item
 828 The @cmd{HOST} command.
 829 @item
 830 The @cmd{PERMISSIONS} command.
 831 @item
 832 Pipes (file names beginning or ending with @samp{|}).
 833 @end itemize
 834
 835 Be aware that this setting does not guarantee safety (commands can still
 836 overwrite files, for instance) but it is an improvement.
 837 When set, this setting cannot be reset during the same session, for
 838 obvious security reasons.
 839
 840 @item LOCALE
 841 @cindex locale
 842 @cindex encoding, characters
 843 This item is used to set the default character encoding.
 844 The encoding may be specified either as an encoding name or alias
 845 (see @url{http://www.iana.org/assignments/character-sets}), or
 846 as a locale name.
 847 If given as a locale name, only the character encoding of the
 848 locale is relevant.
 849
 850 System files written by @pspp{} will use this encoding.
 851 System files read by @pspp{}, for which the encoding is unknown, will be
 852 interpreted using this encoding.
 853
 854 The full list of valid encodings and locale names/alias are operating system
 855 dependent.
 856 The following are all examples of acceptable syntax on common GNU/Linux
 857 systems.
 858 @example
 859 SET LOCALE='iso-8859-1'.
 860
 861 SET LOCALE='ru_RU.cp1251'.
 862
 863 SET LOCALE='japanese'.
 864 @end example
 865
 866 Contrary to intuition, this command does not affect any aspect
 867 of the system's locale.
 868 @end table
 869
 870 @node SHOW
 871 @section SHOW
 872 @vindex SHOW
 873
 874 @display
 875 SHOW
 876         [ALL]
 877         [BLANKS]
 878         [CC]
 879         [CCA]
 880         [CCB]
 881         [CCC]
 882         [CCD]
 883         [CCE]
 884         [COPYING]
 885         [DECIMALS]
 886         [DIRECTORY]
 887         [ENVIRONMENT]
 888         [FORMAT]
 889         [FUZZBITS]
 890         [LENGTH]
 891         [MXERRS]
 892         [MXLOOPS]
 893         [MXWARNS]
 894         [N]
 895         [SCOMPRESSION]
 896         [TEMPDIR]
 897         [UNDEFINED]
 898         [VERSION]
 899         [WARRANTY]
 900         [WEIGHT]
 901         [WIDTH]
 902 @end display
 903
 904 @cmd{SHOW} can be used to display the current state of @pspp{}'s execution
 905 parameters.  Parameters that can be changed using @cmd{SET}
 906 (@pxref{SET}), can be examined using @cmd{SHOW} using the subcommand
 907 with the same name.  @cmd{SHOW} supports the following additional
 908 subcommands:
 909
 910 @table @asis
 911 @item @subcmd{ALL}
 912 Show all settings.
 913 @item @subcmd{CC}
 914 Show all custom currency settings (@subcmd{CCA} through @subcmd{CCE}).
 915 @item @subcmd{DIRECTORY}
 916 Shows the current working directory.
 917 @item @subcmd{ENVIRONMENT}
 918 Shows the operating system details.
 919 @item @subcmd{N}
 920 Reports the number of cases in the active dataset.  The reported number is not
 921 weighted.  If no dataset is defined, then @samp{Unknown} will be reported.
 922 @item @subcmd{TEMPDIR}
 923 Shows the path of the directory where temporary files will be stored.
 924 @item @subcmd{VERSION}
 925 Shows the version of this installation of @pspp{}.
 926 @item @subcmd{WARRANTY}
 927 Show details of the lack of warranty for @pspp{}.
 928 @item @subcmd{COPYING} / @subcmd{LICENSE}
 929 Display the terms of @pspp{}'s copyright licence (@pxref{License}).
 930 @end table
 931
 932 Specifying @cmd{SHOW} without any subcommands is equivalent to @subcmd{SHOW ALL}.
 933
 934 @node SUBTITLE
 935 @section SUBTITLE
 936 @vindex SUBTITLE
 937
 938 @display
 939 SUBTITLE '@var{subtitle_string}'.
 940   or
 941 SUBTITLE @var{subtitle_string}.
 942 @end display
 943
 944 @cmd{SUBTITLE} provides a subtitle to a particular @pspp{}
 945 run.  This subtitle appears at the top of each output page below the
 946 title, if headers are enabled on the output device.
 947
 948 Specify a subtitle as a string in quotes.  The alternate syntax that did
 949 not require quotes is now obsolete.  If it is used then the subtitle is
 950 converted to all uppercase.
 951
 952 @node TITLE
 953 @section TITLE
 954 @vindex TITLE
 955
 956 @display
 957 TITLE '@var{title_string}'.
 958   or
 959 TITLE @var{title_string}.
 960 @end display
 961
 962 @cmd{TITLE} provides a title to a particular @pspp{} run.
 963 This title appears at the top of each output page, if headers are enabled
 964 on the output device.
 965
 966 Specify a title as a string in quotes.  The alternate syntax that did
 967 not require quotes is now obsolete.  If it is used then the title is
 968 converted to all uppercase.