doc/utilities.texi

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