doc/utilities.texi

   1 @c PSPP - a program for statistical analysis.
   2 @c Copyright (C) 2017, 2020, 2023 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 becomes
  86 that specified by the command.
  87
  88 @node COMMENT
  89 @section COMMENT
  90 @vindex COMMENT
  91 @vindex *
  92
  93 @display
  94 Comment commands:
  95     COMMENT comment text @dots{} .
  96     *comment text @dots{} .
  97
  98 Comments within a line of syntax:
  99     FREQUENCIES /VARIABLES=v0 v1 v2.  /* All our categorical variables.
 100 @end display
 101
 102 @cmd{COMMENT} is ignored.  It is used to provide information to
 103 the author and other readers of the @pspp{} syntax file.
 104
 105 @cmd{COMMENT} can extend over any number of lines.  It ends at a dot
 106 at the end of a line or a blank line.  The comment may contain any
 107 characters.
 108
 109 PSPP also supports comments within a line of syntax, introduced with
 110 @samp{/*}.  These comments end at the first @samp{*/} or at the end of
 111 the line, whichever comes first.  A line that contains just this kind
 112 of comment is considered blank and ends the current command.
 113
 114 @node DOCUMENT
 115 @section DOCUMENT
 116 @vindex DOCUMENT
 117
 118 @display
 119 DOCUMENT @var{documentary_text}.
 120 @end display
 121
 122 @cmd{DOCUMENT} adds one or more lines of descriptive commentary to the
 123 active dataset.  Documents added in this way are saved to system files.
 124 They can be viewed using @cmd{SYSFILE INFO} or @cmd{DISPLAY
 125 DOCUMENTS}.  They can be removed from the active dataset with @cmd{DROP
 126 DOCUMENTS}.
 127
 128 Specify the @var{documentary text} following the @subcmd{DOCUMENT} keyword.
 129 It is interpreted literally---any quotes or other punctuation marks
 130 are included in the file.
 131 You can extend the documentary text over as many lines as necessary,
 132 including blank lines to separate paragraphs.
 133 Lines are truncated at 80 bytes.  Don't forget to terminate
 134 the command with a dot at the end of a line. @xref{ADD DOCUMENT}.
 135
 136 @node DISPLAY DOCUMENTS
 137 @section DISPLAY DOCUMENTS
 138 @vindex DISPLAY DOCUMENTS
 139
 140 @display
 141 DISPLAY DOCUMENTS.
 142 @end display
 143
 144 @cmd{DISPLAY DOCUMENTS} displays the documents in the active dataset.  Each
 145 document is preceded by a line giving the time and date that it was
 146 added.  @xref{DOCUMENT}.
 147
 148 @node DISPLAY FILE LABEL
 149 @section DISPLAY FILE LABEL
 150 @vindex DISPLAY FILE LABEL
 151
 152 @display
 153 DISPLAY FILE LABEL.
 154 @end display
 155
 156 @cmd{DISPLAY FILE LABEL} displays the file label contained in the
 157 active dataset,
 158 if any.  @xref{FILE LABEL}.
 159
 160 This command is a @pspp{} extension.
 161
 162 @node DROP DOCUMENTS
 163 @section DROP DOCUMENTS
 164 @vindex DROP DOCUMENTS
 165
 166 @display
 167 DROP DOCUMENTS.
 168 @end display
 169
 170 @cmd{DROP DOCUMENTS} removes all documents from the active dataset.
 171 New documents can be added with @cmd{DOCUMENT} (@pxref{DOCUMENT}).
 172
 173 @cmd{DROP DOCUMENTS} changes only the active dataset.  It does not modify any
 174 system files stored on disk.
 175
 176 @node ECHO
 177 @section ECHO
 178 @vindex ECHO
 179
 180 @display
 181 ECHO 'arbitrary text' .
 182 @end display
 183
 184 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}).
 185
 186 @node ERASE
 187 @section ERASE
 188 @vindex ERASE
 189
 190 @display
 191 ERASE FILE @var{file_name}.
 192 @end display
 193
 194 @cmd{ERASE FILE} deletes a file from the local file system.
 195 @var{file_name} must be quoted.
 196 This command cannot be used if the SAFER (@pxref{SET}) setting is active.
 197
 198
 199 @node EXECUTE
 200 @section EXECUTE
 201 @vindex EXECUTE
 202
 203 @display
 204 EXECUTE.
 205 @end display
 206
 207 @cmd{EXECUTE} causes the active dataset to be read and all pending
 208 transformations to be executed.
 209
 210 @node FILE LABEL
 211 @section FILE LABEL
 212 @vindex FILE LABEL
 213
 214 @display
 215 FILE LABEL @var{file_label}.
 216 @end display
 217
 218 @cmd{FILE LABEL} provides a title for the active dataset.  This
 219 title is saved into system files and portable files that are
 220 created during this @pspp{} run.
 221
 222 @var{file_label} should not be quoted.
 223 If quotes are included, they are literally interpreted and become part of the file label.
 224
 225 @node FINISH
 226 @section FINISH
 227 @vindex FINISH
 228
 229 @display
 230 FINISH.
 231 @end display
 232
 233 @cmd{FINISH} terminates the current @pspp{} session and returns
 234 control to the operating system.
 235
 236 @node HOST
 237 @section HOST
 238 @vindex HOST
 239
 240 In the syntax below, the square brackets must be included in the
 241 command syntax and do not indicate that that their contents are
 242 optional.
 243
 244 @display
 245 HOST COMMAND=['@var{command}'...]
 246      TIMELIMIT=@var{secs}.
 247 @end display
 248
 249 @cmd{HOST} executes one or more commands, each provided as a string in
 250 the required @subcmd{COMMAND} subcommand, in the shell of the
 251 underlying operating system.  PSPP runs each command in a separate
 252 shell process and waits for it to finish before running the next one.
 253 If a command fails (with a nonzero exit status, or because it is
 254 killed by a signal), then PSPP does not run any remaining commands.
 255
 256 PSPP provides @file{/dev/null} as the shell's standard input.  If a
 257 process needs to read from stdin, redirect from a file or device, or
 258 use a pipe.
 259
 260 PSPP displays the shell's standard output and standard error as PSPP
 261 output.  Redirect to a file or @code{/dev/null} or another device if
 262 this is not desired.
 263
 264 The following example runs @code{rsync} to copy a file from a remote
 265 server to the local file @file{data.txt}, writing @code{rsync}'s own
 266 output to @file{rsync-log.txt}.  PSPP displays the command's error
 267 output, if any.  If @code{rsync} needs to prompt the user (@i{e.g.}@: to
 268 obtain a password), the command fails.  Only if the @code{rsync}
 269 succeeds, PSPP then runs the @code{sha512sum} command.
 270
 271 @example
 272 HOST COMMAND=['rsync remote:data.txt data.txt > rsync-log.txt'
 273               'sha512sum -c data.txt.sha512sum].
 274 @end example
 275
 276 By default, PSPP waits as long as necessary for the series of commands
 277 to complete.  Use the optional @subcmd{TIMELIMIT} subcommand to limit
 278 the execution time to the specified number of seconds.
 279
 280 PSPP built for mingw does not support all the features of
 281 @subcmd{HOST}.
 282
 283 PSPP rejects this command if the SAFER (@pxref{SET}) setting is
 284 active.
 285
 286 @node INCLUDE
 287 @section INCLUDE
 288 @vindex INCLUDE
 289
 290 @display
 291         INCLUDE [FILE=]'@var{file_name}' [ENCODING='@var{encoding}'].
 292 @end display
 293
 294 @cmd{INCLUDE} causes the @pspp{} command processor to read an
 295 additional command file as if it were included bodily in the current
 296 command file.
 297 If errors are encountered in the included file, then command
 298 processing stops and no more commands are processed.
 299 Include files may be nested to any depth, up to the limit of available
 300 memory.
 301
 302 The @cmd{INSERT} command (@pxref{INSERT}) is a more flexible
 303 alternative to @cmd{INCLUDE}.  An @cmd{INCLUDE} command acts the same as
 304 @cmd{INSERT} with @subcmd{ERROR=STOP CD=NO SYNTAX=BATCH} specified.
 305
 306 The optional @subcmd{ENCODING} subcommand has the same meaning as with @cmd{INSERT}.
 307
 308 @node INSERT
 309 @section INSERT
 310 @vindex INSERT
 311
 312 @display
 313      INSERT [FILE=]'@var{file_name}'
 314         [CD=@{NO,YES@}]
 315         [ERROR=@{CONTINUE,STOP@}]
 316         [SYNTAX=@{BATCH,INTERACTIVE@}]
 317         [ENCODING=@{LOCALE, '@var{charset_name}'@}].
 318 @end display
 319
 320 @cmd{INSERT} is similar to @cmd{INCLUDE} (@pxref{INCLUDE})
 321 but somewhat more flexible.
 322 It causes the command processor to read a file as if it were embedded in the
 323 current command file.
 324
 325 If @subcmd{CD=YES} is specified, then before including the file, the
 326 current directory becomes the directory of the included
 327 file.
 328 The default setting is @samp{CD=NO}.
 329 Note that this directory remains current until it is
 330 changed explicitly (with the @cmd{CD} command, or a subsequent
 331 @cmd{INSERT} command with the @samp{CD=YES} option).
 332 It does not revert to its original setting even after the included
 333 file is finished processing.
 334
 335 If @subcmd{ERROR=STOP} is specified, errors encountered in the
 336 inserted file causes processing to immediately cease.
 337 Otherwise processing continues at the next command.
 338 The default setting is @subcmd{ERROR=CONTINUE}.
 339
 340 If @subcmd{SYNTAX=INTERACTIVE} is specified then the syntax contained in
 341 the included file must conform to interactive syntax
 342 conventions. @xref{Syntax Variants}.
 343 The default setting is @subcmd{SYNTAX=BATCH}.
 344
 345 @subcmd{ENCODING} optionally specifies the character set used by the included
 346 file.  Its argument, which is not case-sensitive, must be in one of
 347 the following forms:
 348
 349 @table @asis
 350 @item @subcmd{LOCALE}
 351 The encoding used by the system locale, or as overridden by the
 352 @cmd{SET} command (@pxref{SET}).  On GNU/Linux and other Unix-like systems,
 353 environment variables, @i{e.g.}@: @env{LANG} or @env{LC_ALL}, determine the
 354 system locale.
 355
 356 @item @var{charset_name}
 357 One of the character set names listed by @acronym{IANA} at
 358 @uref{http://www.iana.org/assignments/character-sets}.  Some examples
 359 are @code{ASCII} (United States), @code{ISO-8859-1} (western Europe),
 360 @code{EUC-JP} (Japan), and @code{windows-1252} (Windows).  Not all
 361 systems support all character sets.
 362
 363 @item @code{Auto,@var{encoding}}
 364 Automatically detects whether a syntax file is encoded in an Unicode
 365 encoding such as UTF-8, UTF-16, or UTF-32.  If it is not, then @pspp{}
 366 generally assumes that the file is encoded in @var{encoding} (an @acronym{IANA}
 367 character set name).  However, if @var{encoding} is UTF-8, and the
 368 syntax file is not valid UTF-8, @pspp{} instead assumes that the file
 369 is encoded in @code{windows-1252}.
 370
 371 For best results, @var{encoding} should be an @acronym{ASCII}-compatible
 372 encoding (the most common locale encodings are all @acronym{ASCII}-compatible),
 373 because encodings that are not @acronym{ASCII} compatible cannot be
 374 automatically distinguished from UTF-8.
 375
 376 @item @code{Auto}
 377 @item @code{Auto,Locale}
 378 Automatic detection, as above, with the default encoding taken from
 379 the system locale or the setting on @subcmd{SET LOCALE}.
 380 @end table
 381
 382 When ENCODING is not specified, the default is taken from the
 383 @option{--syntax-encoding} command option, if it was specified, and
 384 otherwise it is @code{Auto}.
 385
 386 @node OUTPUT
 387 @section OUTPUT
 388 @vindex OUTPUT
 389 @cindex precision, of output
 390 @cindex decimal places
 391
 392 @display
 393 OUTPUT MODIFY
 394        /SELECT TABLES
 395        /TABLECELLS SELECT = [ @var{class}... ]
 396                    FORMAT = @var{fmt_spec}.
 397 @end display
 398 @note{In the above synopsis the characters @samp{[} and @samp{]} are literals.
 399 They must appear in the syntax to be interpreted.}
 400
 401 @cmd{OUTPUT} changes the appearance of the tables in which results are
 402 printed. In particular, it can be used to set the format and precision
 403 to which results are displayed.
 404
 405 After running this command, the default table appearance parameters
 406 will have been modified and  each new output table generated uses
 407 the new parameters.
 408
 409 Following @code{/TABLECELLS SELECT =} a list of cell classes must
 410 appear, enclosed in square brackets.  This list determines the classes
 411 of values should be selected for modification. Each class can be:
 412
 413 @table @asis
 414 @item RESIDUAL
 415 Residual values.  Default: @t{F40.2}.
 416
 417 @item CORRELATION
 418 Correlations.  Default: @t{F40.3}.
 419
 420 @item PERCENT
 421 Percentages.  Default: @t{PCT40.1}.
 422
 423 @item SIGNIFICANCE
 424 Significance of tests (p-values).  Default: @t{F40.3}.
 425
 426 @item COUNT
 427 Counts or sums of weights.  For a weighted data set, the default is
 428 the weight variable's print format.  For an unweighted data set, the
 429 default is F40.0.
 430 @end table
 431
 432 For most other numeric values that appear in tables, @code{SET FORMAT}
 433 may be used to specify the format (@pxref{SET FORMAT}).
 434
 435 The value of @var{fmt_spec} must be a valid output format (@pxref{Input and Output Formats}).
 436 Note that not all possible formats are meaningful for all classes.
 437
 438 @node PERMISSIONS
 439 @section PERMISSIONS
 440 @vindex PERMISSIONS
 441 @cindex mode
 442 @cindex file mode
 443 @cindex changing file permissions
 444
 445 @display
 446 PERMISSIONS
 447         FILE='@var{file_name}'
 448         /PERMISSIONS = @{READONLY,WRITEABLE@}.
 449 @end display
 450
 451 @cmd{PERMISSIONS} changes the permissions of a file.
 452 There is one mandatory subcommand which specifies the permissions to
 453 which the file should be changed.
 454 If you set a file's  permission  to @subcmd{READONLY}, then the file
 455 will become unwritable either by you or anyone else on the system.
 456 If you set the permission to @subcmd{WRITEABLE}, then the file becomes
 457 writeable by you; the permissions afforded to others are unchanged.
 458 This command cannot be used if the @subcmd{SAFER} (@pxref{SET})
 459 setting is active.
 460
 461
 462 @node PRESERVE and RESTORE
 463 @section PRESERVE and RESTORE
 464 @vindex PRESERVE
 465 @vindex RESTORE
 466
 467 @display
 468 PRESERVE.
 469 @dots{}
 470 RESTORE.
 471 @end display
 472
 473 @cmd{PRESERVE} saves all of the settings that @cmd{SET} (@pxref{SET})
 474 can adjust.  A later @cmd{RESTORE} command restores those settings.
 475
 476 @cmd{PRESERVE} can be nested up to five levels deep.
 477
 478 @node SET
 479 @section SET
 480 @vindex SET
 481
 482 @display
 483 SET
 484
 485 (data input)
 486         /BLANKS=@{SYSMIS,'.',number@}
 487         /DECIMAL=@{DOT,COMMA@}
 488         /FORMAT=@var{fmt_spec}
 489         /EPOCH=@{AUTOMATIC,@var{year}@}
 490         /RIB=@{NATIVE,MSBFIRST,LSBFIRST,VAX@}
 491         /RRB=@{NATIVE,ISL,ISB,IDL,IDB,VF,VD,VG,ZS,ZL@}
 492
 493 (interaction)
 494         /MXERRS=@var{max_errs}
 495         /MXWARNS=@var{max_warnings}
 496         /WORKSPACE=@var{workspace_size}
 497
 498 (syntax execution)
 499         /LOCALE='@var{locale}'
 500         /MXLOOPS=@var{max_loops}
 501         /SEED=@{RANDOM,@var{seed_value}@}
 502         /UNDEFINED=@{WARN,NOWARN@}
 503         /FUZZBITS=@var{fuzzbits}
 504         /SCALEMIN=@var{count}
 505
 506 (data output)
 507         /CC@{A,B,C,D,E@}=@{'@var{npre},@var{pre},@var{suf},@var{nsuf}','@var{npre}.@var{pre}.@var{suf}.@var{nsuf}'@}
 508         /DECIMAL=@{DOT,COMMA@}
 509         /FORMAT=@var{fmt_spec}
 510         /LEADZERO=@{ON,OFF@}
 511         /MDISPLAY=@{TEXT,TABLES@}
 512         /SMALL=@var{number}
 513         /SUMMARY=@{NONE,@var{comment}@}
 514         /WIB=@{NATIVE,MSBFIRST,LSBFIRST,VAX@}
 515         /WRB=@{NATIVE,ISL,ISB,IDL,IDB,VF,VD,VG,ZS,ZL@}
 516
 517 (output routing)
 518         /ERRORS=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}
 519         /MESSAGES=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}
 520         /PRINTBACK=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}
 521         /RESULTS=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}
 522
 523 (output driver options)
 524         /HEADERS=@{NO,YES,BLANK@}
 525         /LENGTH=@{NONE,@var{n_lines}@}
 526         /WIDTH=@{NARROW,WIDTH,@var{n_characters}@}
 527         /TNUMBERS=@{VALUES,LABELS,BOTH@}
 528         /TVARS=@{NAMES,LABELS,BOTH@}
 529         /TLOOK=@{NONE,@var{file}@}
 530
 531 (logging)
 532         /JOURNAL=@{ON,OFF@} ['@var{file_name}']
 533
 534 (system files)
 535         /SCOMPRESSION=@{ON,OFF@}
 536
 537 (miscellaneous)
 538         /SAFER=ON
 539         /LOCALE='@var{string}'
 540
 541 (macros)
 542         /MEXPAND=@{ON,OFF@}
 543         /MPRINT=@{ON,OFF@}
 544         /MITERATE=@var{number}
 545         /MNEST=@var{number}
 546
 547 (settings not yet implemented, but accepted and ignored)
 548         /BASETEXTDIRECTION=@{AUTOMATIC,RIGHTTOLEFT,LEFTTORIGHT@}
 549         /BLOCK='@var{c}'
 550         /BOX=@{'@var{xxx}','@var{xxxxxxxxxxx}'@}
 551         /CACHE=@{ON,OFF@}
 552         /CELLSBREAK=@var{number}
 553         /COMPRESSION=@{ON,OFF@}
 554         /CMPTRANS=@{ON,OFF@}
 555         /HEADER=@{NO,YES,BLANK@}
 556 @end display
 557
 558 @cmd{SET} allows the user to adjust several parameters relating to
 559 @pspp{}'s execution.  Since there are many subcommands to this command, its
 560 subcommands are examined in groups.
 561
 562 For subcommands that take boolean values, @subcmd{ON} and @subcmd{YES} are synonymous,
 563 as are @subcmd{OFF} and @subcmd{NO}, when used as subcommand values.
 564
 565 The data input subcommands affect the way that data is read from data
 566 files.  The data input subcommands are
 567
 568 @table @asis
 569 @item BLANKS
 570 @anchor{SET BLANKS}
 571 This is the value assigned to an item data item that is empty or
 572 contains only white space.  An argument of SYSMIS or '.'  causes the
 573 system-missing value to be assigned to null items.  This is the
 574 default.  Any real value may be assigned.
 575
 576 @item DECIMAL
 577 @anchor{SET DECIMAL}
 578 This value may be set to @subcmd{DOT} or @subcmd{COMMA}.
 579 Setting it to @subcmd{DOT} causes the decimal point character to be
 580 @samp{.} and the grouping character to be @samp{,}.
 581 Setting it to @subcmd{COMMA}
 582 causes the decimal point character to be @samp{,} and the grouping
 583 character to be @samp{.}.
 584 If the setting is @subcmd{COMMA}, then @samp{,} is not treated
 585 as a field separator in the @cmd{DATA LIST} command (@pxref{DATA LIST}).
 586 The default value is determined from the system locale.
 587
 588 @item FORMAT
 589 @anchor{SET FORMAT}
 590 Allows the default numeric input/output format to be specified.  The
 591 default is F8.2.  @xref{Input and Output Formats}.
 592
 593 @item EPOCH
 594 @anchor{SET EPOCH}
 595 Specifies the range of years used when a 2-digit year is read from a
 596 data file or used in a date construction expression (@pxref{Date
 597 Construction}).  If a 4-digit year is specified for the epoch, then
 598 2-digit years are interpreted starting from that year, known as the
 599 epoch.  If @subcmd{AUTOMATIC} (the default) is specified, then the epoch begins
 600 69 years before the current date.
 601
 602 @item RIB
 603 @anchor{SET RIB}
 604
 605 @pspp{} extension to set the byte ordering (endianness) used for reading
 606 data in IB or PIB format (@pxref{Binary and Hexadecimal Numeric
 607 Formats}).  In @subcmd{MSBFIRST} ordering, the most-significant byte appears at
 608 the left end of a IB or PIB field.  In @subcmd{LSBFIRST} ordering, the
 609 least-significant byte appears at the left end.  @subcmd{VAX} ordering is like
 610 @subcmd{MSBFIRST}, except that each pair of bytes is in reverse order.  @subcmd{NATIVE},
 611 the default, is equivalent to @subcmd{MSBFIRST} or @subcmd{LSBFIRST} depending on the
 612 native format of the machine running @pspp{}.
 613
 614 @item RRB
 615 @anchor{SET RRB}
 616
 617 @pspp{} extension to set the floating-point format used for reading data in
 618 RB format (@pxref{Binary and Hexadecimal Numeric Formats}).  The
 619 possibilities are:
 620
 621 @table @asis
 622 @item NATIVE
 623 The native format of the machine running @pspp{}.  Equivalent to either IDL
 624 or IDB.
 625
 626 @item ISL
 627 32-bit IEEE 754 single-precision floating point, in little-endian byte
 628 order.
 629
 630 @item ISB
 631 32-bit IEEE 754 single-precision floating point, in big-endian byte
 632 order.
 633
 634 @item IDL
 635 64-bit IEEE 754 double-precision floating point, in little-endian byte
 636 order.
 637
 638 @item IDB
 639 64-bit IEEE 754 double-precision floating point, in big-endian byte
 640 order.
 641
 642 @item VF
 643 32-bit VAX F format, in VAX-endian byte order.
 644
 645 @item VD
 646 64-bit VAX D format, in VAX-endian byte order.
 647
 648 @item VG
 649 64-bit VAX G format, in VAX-endian byte order.
 650
 651 @item ZS
 652 32-bit IBM Z architecture short format hexadecimal floating point, in
 653 big-endian byte order.
 654
 655 @item ZL
 656 64-bit IBM Z architecture long format hexadecimal floating point, in
 657 big-endian byte order.
 658
 659 Z architecture also supports IEEE 754 floating point.  The ZS and ZL
 660 formats are only for use with very old input files.
 661 @end table
 662 The default is NATIVE.
 663 @end table
 664
 665 Interaction subcommands affect the way that @pspp{} interacts with an
 666 online user.  The interaction subcommands are
 667
 668 @table @asis
 669 @item MXERRS
 670 The maximum number of errors before @pspp{} halts processing of the current
 671 command file.  The default is 50.
 672
 673 @item MXWARNS
 674 The maximum number of warnings + errors before @pspp{} halts processing the
 675 current command file.
 676 The special value of zero means that all warning situations should be ignored.
 677 No warnings are issued, except a single initial warning advising you
 678 that warnings will not be given.
 679 The default value is 100.
 680 @end table
 681
 682 Syntax execution subcommands control the way that @pspp{} commands
 683 execute.  The syntax execution subcommands are
 684
 685 @table @asis
 686 @item LOCALE
 687 Overrides the system locale for the purpose of reading and writing
 688 syntax and data files.  The argument should be a locale name in the
 689 general form @code{@var{language}_@var{country}.@var{encoding}}, where @var{language}
 690 and @var{country} are 2-character language and country abbreviations,
 691 respectively, and @var{encoding} is an @acronym{IANA} character set name.
 692 Example locales are @code{en_US.UTF-8} (UTF-8 encoded English as
 693 spoken in the United States) and @code{ja_JP.EUC-JP} (EUC-JP encoded
 694 Japanese as spoken in Japan).
 695
 696 @item MXLOOPS
 697 @anchor{SET MXLOOPS}
 698
 699 The maximum number of iterations for an uncontrolled loop
 700 (@pxref{LOOP}), and for any loop in the matrix language (@pxref{Matrix
 701 LOOP and BREAK Commands}).  The default @var{max_loops} is 40.
 702
 703 @item SEED
 704 @anchor{SET SEED}
 705 The initial pseudo-random number seed.  Set it to a real number or to
 706 RANDOM, to obtain an initial seed from the current time of day.
 707
 708 @item UNDEFINED
 709 Currently not used.
 710
 711 @item FUZZBITS
 712 @anchor{SET FUZZBITS}
 713 The maximum number of bits of errors in the least-significant places
 714 to accept for rounding up a value that is almost halfway between two
 715 possibilities for rounding with the RND operator (@pxref{Miscellaneous
 716 Mathematics}).  The default @var{fuzzbits} is 6.
 717
 718 @item SCALEMIN
 719 @anchor{SET SCALEMIN}
 720 The minimum number of distinct valid values for @pspp{} to assume that
 721 a variable has a scale measurement level.  @xref{Measurement Level}.
 722
 723 @item WORKSPACE
 724 The maximum amount of memory (in kilobytes) that @pspp{} uses to
 725 store data being processed.  If memory in excess of the workspace size
 726 is required, then @pspp{} starts to use temporary files to store
 727 the data.   Setting a higher value means that procedures
 728 run faster, but may cause other applications to run slower.
 729 On platforms without virtual memory management, setting a very large
 730 workspace may cause @pspp{} to abort.
 731 @cindex workspace
 732 @cindex memory, amount used to store cases
 733 @end table
 734
 735 Data output subcommands affect the format of output data.  These
 736 subcommands are
 737
 738 @table @asis
 739 @item CCA
 740 @itemx CCB
 741 @itemx CCC
 742 @itemx CCD
 743 @itemx CCE
 744 @anchor{CCx Settings}
 745
 746 Set up custom currency formats.  @xref{Custom Currency Formats}, for
 747 details.
 748
 749 @item DECIMAL
 750 The default @subcmd{DOT} setting causes the decimal point character to be
 751 @samp{.}.  A setting of @subcmd{COMMA} causes the decimal point character to be
 752 @samp{,}.
 753
 754 @item FORMAT
 755 Allows the default numeric input/output format to be specified.  The
 756 default is F8.2.  @xref{Input and Output Formats}.
 757
 758 @item LEADZERO
 759 @anchor{SET LEADZERO}
 760
 761 Controls whether numbers with magnitude less than one are displayed
 762 with a zero before the decimal point.  For example, with @code{SET
 763 LEADZERO=OFF}, which is the default, one-half is shown as 0.5, and
 764 with @code{SET LEADZERO=ON}, it is shown as .5.  This setting affects
 765 only the @code{F}, @code{COMMA}, and @code{DOT} formats.
 766
 767 @item MDISPLAY
 768 @anchor{SET MDISPLAY}
 769
 770 Controls how the @code{PRINT} command within
 771 @code{MATRIX}@dots{}@code{END MATRIX} outputs matrices.  With the
 772 default @subcmd{TEXT}, @code{PRINT} outputs matrices as text.  Change
 773 this setting to @code{TABLES} to instead output matrices as pivot
 774 tables.  @xref{Matrix PRINT Command}, for more information.
 775
 776 @item SMALL
 777 This controls how @pspp{} formats small numbers in pivot tables, in
 778 cases where @pspp{} does not otherwise have a well-defined format for
 779 the numbers.  When such a number has a magnitude less than the value
 780 set here, @pspp{} formats the number in scientific notation;
 781 otherwise, it formats it in standard notation.  The default is 0.0001.
 782 Set a value of 0 to disable scientific notation.
 783
 784 @item SUMMARY
 785 The @subcmd{SUMMARY} option sets the comment string which will appear in all
 786 generated tables until the next @subcmd{SUMMARY} is issued.  If the special
 787 value @subcmd{NONE} is specified, then no comment will appear.
 788 These comment strings can be seen in the graphical user interface by placing
 789 the pointer over the table.
 790 If @var{comment} contains any of the following substrings, they will be
 791 subsituted as follows:
 792 @table @code
 793 @item \n
 794 A line break.
 795 @item )DATE
 796 The current date in the form @samp{dd-mmm-yyyy}
 797 @item )ADATE
 798 The current date in the form @samp{mm/dd/yyyy}
 799 @item )SDATE
 800 The current date in the form @samp{yyyy/mm/dd}
 801 @item )EDATE
 802 The current date in the form @samp{dd.mm.yyyy}
 803 @item )TIME
 804 The current 12 hour clock time in the form @samp{hh:mm:ss}
 805 @item )ETIME
 806 The current 24 hour clock time in the form @samp{hh:mm:ss}
 807 @end table
 808
 809 @item WIB
 810 @anchor{SET WIB}
 811
 812 @pspp{} extension to set the byte ordering (endianness) used for writing
 813 data in IB or PIB format (@pxref{Binary and Hexadecimal Numeric
 814 Formats}).  In @subcmd{MSBFIRST} ordering, the most-significant byte appears at
 815 the left end of a IB or PIB field.  In @subcmd{LSBFIRST} ordering, the
 816 least-significant byte appears at the left end.  @subcmd{VAX} ordering is like
 817 @subcmd{MSBFIRST}, except that each pair of bytes is in reverse order.  @subcmd{NATIVE},
 818 the default, is equivalent to @subcmd{MSBFIRST} or @subcmd{LSBFIRST} depending on the
 819 native format of the machine running @pspp{}.
 820
 821 @item WRB
 822 @anchor{SET WRB}
 823
 824 @pspp{} extension to set the floating-point format used for writing data in
 825 RB format (@pxref{Binary and Hexadecimal Numeric Formats}).  The choices
 826 are the same as @subcmd{SET RIB}.  The default is @subcmd{NATIVE}.
 827 @end table
 828
 829 In the @pspp{} text-based interface, the output routing subcommands
 830 affect where output is sent.  The following values are allowed for
 831 each of these subcommands:
 832
 833 @table @asis
 834 @item OFF
 835 @item NONE
 836 Discard this kind of output.
 837
 838 @item TERMINAL
 839 Write this output to the terminal, but not to listing files and other
 840 output devices.
 841
 842 @item LISTING
 843 Write this output to listing files and other output devices, but not
 844 to the terminal.
 845
 846 @item ON
 847 @itemx BOTH
 848 Write this type of output to all output devices.
 849 @end table
 850
 851 These output routing subcommands are:
 852
 853 @table @asis
 854 @item ERRORS
 855 Applies to error and warning messages.  The default is @subcmd{BOTH}.
 856
 857 @item MESSAGES
 858 Applies to notes.  The default is @subcmd{BOTH}.
 859
 860 @item PRINTBACK
 861 Determines whether the syntax used for input is printed back as part
 862 of the output.  The default is @subcmd{NONE}.
 863
 864 @item RESULTS
 865 Applies to everything not in one of the above categories, such as the
 866 results of statistical procedures.  The default is @subcmd{BOTH}.
 867 @end table
 868
 869 These subcommands have no effect on output in the @pspp{} GUI
 870 environment.
 871
 872 Output driver option subcommands affect output drivers' settings.  These
 873 subcommands are
 874
 875 @table @asis
 876 @item HEADERS
 877 @itemx LENGTH
 878 @itemx WIDTH
 879 @itemx TNUMBERS
 880 The @subcmd{TNUMBERS} option sets the way in which values are displayed in output tables.
 881 The valid settings are @subcmd{VALUES}, @subcmd{LABELS} and @subcmd{BOTH}.
 882 If @subcmd{TNUMBERS} is set to @subcmd{VALUES}, then all values are displayed with their literal value
 883 (which for a numeric value is a number and for a string value an alphanumeric string).
 884 If @subcmd{TNUMBERS} is set to @subcmd{LABELS}, then values are displayed using their assigned labels if any.
 885 (@xref{VALUE LABELS}.)
 886 If the value has no label, then the literal value is used for display.
 887 If @subcmd{TNUMBERS} is set to @subcmd{BOTH}, then values are displayed with both their label
 888 (if any) and their literal value in parentheses.
 889 @item TVARS
 890 @anchor{SET TVARS}
 891 The @subcmd{TVARS} option sets the way in which variables are displayed in output tables.
 892 The valid settings are @subcmd{NAMES}, @subcmd{LABELS} and @subcmd{BOTH}.
 893 If @subcmd{TVARS} is set to @subcmd{NAMES}, then all variables are displayed using their names.
 894 If @subcmd{TVARS} is set to @subcmd{LABELS}, then variables are displayed using their label if one
 895 has been set.  If no label has been set, then the name is used.
 896 (@xref{VARIABLE LABELS}.)
 897 If @subcmd{TVARS} is set to @subcmd{BOTH}, then variables are displayed with both their label
 898 (if any) and their name in parentheses.
 899 @item TLOOK
 900 The @subcmd{TLOOK} option sets the style used for subsequent table
 901 output.  Specifying @subcmd{NONE} makes @pspp{} use the default
 902 built-in style.  Otherwise, specifying @var{file} makes @pspp{} search
 903 for an @file{.stt} or @file{.tlo} file in the same way as specifying
 904 @option{--table-look=@var{file}} the @pspp{} command line (@pxref{Main
 905 Options}).
 906 @end table
 907
 908 @cindex headers
 909 @cindex length
 910 @cindex pager
 911 @cindex width
 912 @cindex tnumbers
 913
 914 These subcommands affect journaling, also called logging.  When
 915 journaling is enabled, @pspp{} writes the commands that it executes,
 916 plus any errors or other diagostics that it outputs, to a text file,
 917 called the @dfn{journal} file.
 918
 919 @pspp{} enables journaling by default when it runs interactively in a
 920 terminal or in the PSPPIRE GUI.  In the GUI, use @clicksequence{Edit
 921 @click{} Options@dots{}} to view or override the default location or
 922 to disable journaling.  From syntax, use @code{SHOW JOURNAL} to see
 923 the journal's location and whether it is enabled.
 924
 925 @table @asis
 926 @item JOURNAL
 927 @itemx LOG
 928 Specify @subcmd{ON} to enable the journal and @subcmd{OFF} to disable
 929 it.  Specify a file name to set the name of the journal file.
 930 @end table
 931
 932 System file subcommands affect the default format of system files
 933 produced by @pspp{}.  These subcommands are
 934
 935 @table @asis
 936 @item SCOMPRESSION
 937 Whether system files created by @cmd{SAVE} or @cmd{XSAVE} are
 938 compressed by default.  The default is @subcmd{ON}.
 939 @end table
 940
 941 Security subcommands affect the operations that commands are allowed to
 942 perform.  The security subcommands are
 943
 944 @table @asis
 945 @item SAFER
 946 Setting this option disables the following operations:
 947
 948 @itemize @bullet
 949 @item
 950 The @cmd{ERASE} command.
 951 @item
 952 The @cmd{HOST} command.
 953 @item
 954 The @cmd{PERMISSIONS} command.
 955 @item
 956 Pipes (file names beginning or ending with @samp{|}).
 957 @end itemize
 958
 959 Be aware that this setting does not guarantee safety (commands can still
 960 overwrite files, for instance) but it is an improvement.
 961 When set, this setting cannot be reset during the same session, for
 962 obvious security reasons.
 963
 964 @item LOCALE
 965 @cindex locale
 966 @cindex encoding, characters
 967 This item is used to set the default character encoding.
 968 The encoding may be specified either as an encoding name or alias
 969 (see @url{http://www.iana.org/assignments/character-sets}), or
 970 as a locale name.
 971 If given as a locale name, only the character encoding of the
 972 locale is relevant.
 973
 974 System files written by @pspp{} use this encoding.
 975 System files read by @pspp{}, for which the encoding is unknown, are
 976 interpreted using this encoding.
 977
 978 The full list of valid encodings and locale names/alias are operating system
 979 dependent.
 980 The following are all examples of acceptable syntax on common GNU/Linux
 981 systems.
 982 @example
 983 SET LOCALE='iso-8859-1'.
 984
 985 SET LOCALE='ru_RU.cp1251'.
 986
 987 SET LOCALE='japanese'.
 988 @end example
 989
 990 Contrary to intuition, this command does not affect any aspect
 991 of the system's locale.
 992 @end table
 993
 994 The following subcommands affect the interpretation of macros.
 995
 996 @table @asis
 997 @item MEXPAND
 998 @anchor{SET MEXPAND}
 999 Controls whether macros are expanded.  The default is ON.
1000
1001 @item MPRINT
1002 @anchor{SET MPRINT}
1003 Controls whether the expansion of macros is included in output.  This
1004 is separate from whether command syntax in general is included in
1005 output.  The default is OFF.
1006
1007 @item MITERATE
1008 @anchor{SET MITERATE}
1009 Limits the number of iterations executed in @code{!DO} loops within
1010 macros.  This does not affect other language constructs such as
1011 @cmd{LOOP}.  This must be set to a positive integer.  The default is
1012 1000.
1013
1014 @item MNEST
1015 @anchor{SET MNEST}
1016 Limits the number of levels of nested macro expansions.  This must be
1017 set to a positive integer.  The default is 50.
1018 @end table
1019
1020 The following subcommands are not yet implemented, but PSPP accepts
1021 them and ignores the settings.
1022
1023 @table @asis
1024 @item BASETEXTDIRECTION
1025 @itemx BLOCK
1026 @itemx BOX
1027 @itemx CACHE
1028 @itemx CELLSBREAK
1029 @itemx COMPRESSION
1030 @itemx CMPTRANS
1031 @itemx HEADER
1032 @end table
1033
1034 @node SHOW
1035 @section SHOW
1036 @vindex SHOW
1037
1038 @display
1039 SHOW
1040         [ALL]
1041         [BLANKS]
1042         [CC]
1043         [CCA]
1044         [CCB]
1045         [CCC]
1046         [CCD]
1047         [CCE]
1048         [COPYING]
1049         [DECIMAL]
1050         [DIRECTORY]
1051         [ENVIRONMENT]
1052         [FORMAT]
1053         [FUZZBITS]
1054         [LENGTH]
1055         [MEXPAND]
1056         [MPRINT]
1057         [MITERATE]
1058         [MNEST]
1059         [MXERRS]
1060         [MXLOOPS]
1061         [MXWARNS]
1062         [N]
1063         [SCOMPRESSION]
1064         [SYSTEM]
1065         [TEMPDIR]
1066         [UNDEFINED]
1067         [VERSION]
1068         [WARRANTY]
1069         [WEIGHT]
1070         [WIDTH]
1071 @end display
1072
1073 @cmd{SHOW} can be used to display the current state of @pspp{}'s execution
1074 parameters.  Parameters that can be changed using @cmd{SET}
1075 (@pxref{SET}), can be examined using @cmd{SHOW} using the subcommand
1076 with the same name.  @cmd{SHOW} supports the following additional
1077 subcommands:
1078
1079 @table @asis
1080 @item @subcmd{ALL}
1081 Show all settings.
1082 @item @subcmd{CC}
1083 Show all custom currency settings (@subcmd{CCA} through @subcmd{CCE}).
1084 @item @subcmd{DIRECTORY}
1085 Shows the current working directory.
1086 @item @subcmd{ENVIRONMENT}
1087 Shows the operating system details.
1088 @item @subcmd{N}
1089 Reports the number of cases in the active dataset.  The reported number is not
1090 weighted.  If no dataset is defined, then @samp{Unknown} is reported.
1091 @item @subcmd{SYSTEM}
1092 Shows information about how PSPP was built.  This information is
1093 useful in bug reports.  @xref{Bugs}, for details.
1094 @item @subcmd{TEMPDIR}
1095 Shows the path of the directory where temporary files are stored.
1096 @item @subcmd{VERSION}
1097 Shows the version of this installation of @pspp{}.
1098 @item @subcmd{WARRANTY}
1099 Show details of the lack of warranty for @pspp{}.
1100 @item @subcmd{COPYING} / @subcmd{LICENSE}
1101 Display the terms of @pspp{}'s copyright licence (@pxref{License}).
1102 @end table
1103
1104 Specifying @cmd{SHOW} without any subcommands is equivalent to @subcmd{SHOW ALL}.
1105
1106 @node SUBTITLE
1107 @section SUBTITLE
1108 @vindex SUBTITLE
1109
1110 @display
1111 SUBTITLE '@var{subtitle_string}'.
1112   or
1113 SUBTITLE @var{subtitle_string}.
1114 @end display
1115
1116 @cmd{SUBTITLE} provides a subtitle to a particular @pspp{}
1117 run.  This subtitle appears at the top of each output page below the
1118 title, if headers are enabled on the output device.
1119
1120 Specify a subtitle as a string in quotes.  The alternate syntax that did
1121 not require quotes is now obsolete.  If it is used then the subtitle is
1122 converted to all uppercase.
1123
1124 @node TITLE
1125 @section TITLE
1126 @vindex TITLE
1127
1128 @display
1129 TITLE '@var{title_string}'.
1130   or
1131 TITLE @var{title_string}.
1132 @end display
1133
1134 @cmd{TITLE} provides a title to a particular @pspp{} run.
1135 This title appears at the top of each output page, if headers are enabled
1136 on the output device.
1137
1138 Specify a title as a string in quotes.  The alternate syntax that did
1139 not require quotes is now obsolete.  If it is used then the title is
1140 converted to all uppercase.