doc/utilities.texi

   1 @node Utilities
   2 @chapter Utilities
   3
   4 Commands that don't fit any other category are placed here.
   5
   6 Most of these commands are not affected by commands like @cmd{IF} and
   7 @cmd{LOOP}:
   8 they take effect only once, unconditionally, at the time that they are
   9 encountered in the input.
  10
  11 @menu
  12 * ADD DOCUMENT::                Add documentary text to the active file.
  13 * CD::                          Change the current directory.
  14 * COMMENT::                     Document your syntax file.
  15 * DOCUMENT::                    Document the active file.
  16 * DISPLAY DOCUMENTS::           Display active file documents.
  17 * DISPLAY FILE LABEL::          Display the active file label.
  18 * DROP DOCUMENTS::              Remove documents from the active file.
  19 * ECHO::                        Write a string to the output stream.
  20 * ERASE::                       Erase a file.
  21 * EXECUTE::                     Execute pending transformations.
  22 * FILE LABEL::                  Set the active file's label.
  23 * FINISH::                      Terminate the PSPP session.
  24 * HOST::                        Temporarily return to the operating system.
  25 * INCLUDE::                     Include a file within the current one.
  26 * PERMISSIONS::                 Change permissions on a file.
  27 * SET::                         Adjust PSPP runtime parameters.
  28 * SHOW::                        Display runtime parameters.
  29 * SUBTITLE::                    Provide a document subtitle.
  30 * TITLE::                       Provide a document title.
  31 @end menu
  32
  33 @node ADD DOCUMENT
  34 @comment  node-name,  next,  previous,  up
  35 @section ADD DOCUMENT
  36 @vindex  ADD DOCUMENT
  37
  38 @display
  39 ADD DOCUMENT
  40     'line one' 'line two' @dots{} 'last line' .
  41 @end display
  42
  43
  44 @cmd{ADD DOCUMENT} adds one or more lines of descriptive commentary to
  45 the active file.  Documents added in this way are saved to system files.
  46 They can be viewed using @cmd{SYSFILE INFO} or @cmd{DISPLAY
  47 DOCUMENTS}.  They can be removed from the active file with @cmd{DROP
  48 DOCUMENTS}.
  49
  50 Each line of documentary text must be enclosed in quotation marks, and
  51 may not be more than 80 bytes long. @xref{DOCUMENT}.
  52
  53 @node CD
  54 @section CD
  55 @vindex CD
  56 @cindex directory
  57 @cindex changing directory
  58
  59 @display
  60 CD 'new directory' .
  61 @end display
  62
  63 @cmd{CD} changes the current directory.  The new directory will become that specified by the command.
  64
  65 @node COMMENT
  66 @section COMMENT
  67 @vindex COMMENT
  68 @vindex *
  69
  70 @display
  71 Two possibles syntaxes:
  72         COMMENT comment text @dots{} .
  73         *comment text @dots{} .
  74 @end display
  75
  76 @cmd{COMMENT} is ignored.  It is used to provide information to
  77 the author and other readers of the PSPP syntax file.
  78
  79 @cmd{COMMENT} can extend over any number of lines.  Don't forget to
  80 terminate it with a dot or a blank line.
  81
  82
  83
  84 @node DOCUMENT
  85 @section DOCUMENT
  86 @vindex DOCUMENT
  87
  88 @display
  89 DOCUMENT @var{documentary_text}.
  90 @end display
  91
  92 @cmd{DOCUMENT} adds one or more lines of descriptive commentary to the
  93 active file.  Documents added in this way are saved to system files.
  94 They can be viewed using @cmd{SYSFILE INFO} or @cmd{DISPLAY
  95 DOCUMENTS}.  They can be removed from the active file with @cmd{DROP
  96 DOCUMENTS}.
  97
  98 Specify the @var{documentary text} following the DOCUMENT keyword.
  99 It is interpreted literally --- any quotes or other punctuation marks
 100 will be included in the file.
 101 You can extend the documentary text over as many lines as necessary.
 102 Lines are truncated at 80 bytes.  Don't forget to terminate
 103 the command with a dot or a blank line. @xref{ADD DOCUMENT}.
 104
 105 @node DISPLAY DOCUMENTS
 106 @section DISPLAY DOCUMENTS
 107 @vindex DISPLAY DOCUMENTS
 108
 109 @display
 110 DISPLAY DOCUMENTS.
 111 @end display
 112
 113 @cmd{DISPLAY DOCUMENTS} displays the documents in the active file.  Each
 114 document is preceded by a line giving the time and date that it was
 115 added.  @xref{DOCUMENT}.
 116
 117 @node DISPLAY FILE LABEL
 118 @section DISPLAY FILE LABEL
 119 @vindex DISPLAY FILE LABEL
 120
 121 @display
 122 DISPLAY FILE LABEL.
 123 @end display
 124
 125 @cmd{DISPLAY FILE LABEL} displays the file label contained in the
 126 active file,
 127 if any.  @xref{FILE LABEL}.
 128
 129 This command is a PSPP extension.
 130
 131 @node DROP DOCUMENTS
 132 @section DROP DOCUMENTS
 133 @vindex DROP DOCUMENTS
 134
 135 @display
 136 DROP DOCUMENTS.
 137 @end display
 138
 139 @cmd{DROP DOCUMENTS} removes all documents from the active file.
 140 New documents can be added with @cmd{DOCUMENT} (@pxref{DOCUMENT}).
 141
 142 @cmd{DROP DOCUMENTS} changes only the active file.  It does not modify any
 143 system files stored on disk.
 144
 145 @node ECHO
 146 @section ECHO
 147 @vindex ECHO
 148
 149 @display
 150 ECHO 'arbitrary text' .
 151 @end display
 152
 153 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}).
 154
 155 @node ERASE
 156 @comment  node-name,  next,  previous,  up
 157 @section ERASE
 158 @vindex ERASE
 159
 160 @display
 161 ERASE FILE file_name.
 162 @end display
 163
 164 @cmd{ERASE FILE} deletes a file from the local filesystem.
 165 file_name must be quoted.
 166 This command cannot be used if the SAFER setting is active.
 167
 168
 169 @node EXECUTE
 170 @section EXECUTE
 171 @vindex EXECUTE
 172
 173 @display
 174 EXECUTE.
 175 @end display
 176
 177 @cmd{EXECUTE} causes the active file to be read and all pending
 178 transformations to be executed.
 179
 180 @node FILE LABEL
 181 @section FILE LABEL
 182 @vindex FILE LABEL
 183
 184 @display
 185 FILE LABEL file_label.
 186 @end display
 187
 188 @cmd{FILE LABEL} provides a title for the active file.  This
 189 title will be saved into system files and portable files that are
 190 created during this PSPP run.
 191
 192 file_label need not be quoted.  If quotes are
 193 included, they become part of the file label.
 194
 195 @node FINISH
 196 @section FINISH
 197 @vindex FINISH
 198
 199 @display
 200 FINISH.
 201 @end display
 202
 203 @cmd{FINISH} terminates the current PSPP session and returns
 204 control to the operating system.
 205
 206 @node HOST
 207 @comment  node-name,  next,  previous,  up
 208 @section HOST
 209 @vindex HOST
 210
 211 @display
 212 HOST.
 213 @end display
 214
 215 @cmd{HOST} suspends the current PSPP session and temporarily returns control
 216 to the operating system.
 217 This command cannot be used if the SAFER setting is active.
 218
 219
 220 @node INCLUDE
 221 @section INCLUDE
 222 @vindex INCLUDE
 223 @vindex @@
 224
 225 @display
 226 Two possible syntaxes:
 227         INCLUDE 'file-name'.
 228         @@file-name.
 229 @end display
 230
 231 @cmd{INCLUDE} causes the PSPP command processor to read an
 232 additional command file as if it were included bodily in the current
 233 command file.
 234
 235 Include files may be nested to any depth, up to the limit of available
 236 memory.
 237
 238 @node PERMISSIONS
 239 @comment  node-name,  next,  previous,  up
 240 @section PERMISSIONS
 241 @vindex PERMISSIONS
 242 @cindex mode
 243 @cindex file mode
 244 @cindex changing file permissions
 245
 246 @display
 247 PERMISSIONS
 248         FILE='file-name'
 249         /PERMISSIONS = @{READONLY,WRITEABLE@}.
 250 @end display
 251
 252 @cmd{PERMISSIONS} changes the permissions of a file.
 253 There is one mandatory subcommand which specifies the permissions to
 254 which the file should be changed.
 255 If you set a file's  permission  to READONLY, then the file will become
 256 unwritable either by you or anyone else on the system.
 257 If you set the permission to WRITEABLE, then the file will become
 258 writeable by you; the permissions afforded to others will be
 259 unchanged.
 260 This command cannot be used if the SAFER setting is active.
 261
 262
 263 @node SET
 264 @section SET
 265 @vindex SET
 266
 267 @display
 268 SET
 269
 270 (data input)
 271         /BLANKS=@{SYSMIS,'.',number@}
 272         /DECIMAL=@{DOT,COMMA@}
 273         /FORMAT=fmt_spec
 274         /EPOCH=@{AUTOMATIC,year@}
 275         /RIB=@{NATIVE,MSBFIRST,LSBFIRST,VAX@}
 276         /RRB=@{NATIVE,ISL,ISB,IDL,IDB,VF,VD,VG,ZS,ZL@}
 277
 278 (program input)
 279         /ENDCMD='.'
 280         /NULLINE=@{ON,OFF@}
 281
 282 (interaction)
 283         /CPROMPT='cprompt_string'
 284         /DPROMPT='dprompt_string'
 285         /ERRORBREAK=@{OFF,ON@}
 286         /MXERRS=max_errs
 287         /MXWARNS=max_warnings
 288         /PROMPT='prompt'
 289
 290 (program execution)
 291         /MEXPAND=@{ON,OFF@}
 292         /MITERATE=max_iterations
 293         /MNEST=max_nest
 294         /MPRINT=@{ON,OFF@}
 295         /MXLOOPS=max_loops
 296         /SEED=@{RANDOM,seed_value@}
 297         /UNDEFINED=@{WARN,NOWARN@}
 298
 299 (data output)
 300         /CC@{A,B,C,D,E@}=@{'npre,pre,suf,nsuf','npre.pre.suf.nsuf'@}
 301         /DECIMAL=@{DOT,COMMA@}
 302         /FORMAT=fmt_spec
 303         /WIB=@{NATIVE,MSBFIRST,LSBFIRST,VAX@}
 304         /WRB=@{NATIVE,ISL,ISB,IDL,IDB,VF,VD,VG,ZS,ZL@}
 305
 306 (output routing)
 307         /ECHO=@{ON,OFF@}
 308         /ERRORS=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}
 309         /INCLUDE=@{ON,OFF@}
 310         /MESSAGES=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}
 311         /PRINTBACK=@{ON,OFF@}
 312         /RESULTS=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}
 313
 314 (output driver options)
 315         /HEADERS=@{NO,YES,BLANK@}
 316         /LENGTH=@{NONE,length_in_lines@}
 317         /LISTING=@{ON,OFF,'file-name'@}
 318         /MORE=@{ON,OFF@}
 319         /WIDTH=@{NARROW,WIDTH,n_characters@}
 320
 321 (logging)
 322         /JOURNAL=@{ON,OFF@} ['file-name']
 323
 324 (system files)
 325         /COMPRESSION=@{ON,OFF@}
 326         /SCOMPRESSION=@{ON,OFF@}
 327
 328 (security)
 329         /SAFER=ON
 330
 331 (obsolete settings accepted for compatibility, but ignored)
 332         /BOXSTRING=@{'xxx','xxxxxxxxxxx'@}
 333         /CASE=@{UPPER,UPLOW@}
 334         /CPI=cpi_value
 335         /DISK=@{ON,OFF@}
 336         /HIGHRES=@{ON,OFF@}
 337         /HISTOGRAM='c'
 338         /LOWRES=@{AUTO,ON,OFF@}
 339         /LPI=lpi_value
 340         /MENUS=@{STANDARD,EXTENDED@}
 341         /MXMEMORY=max_memory
 342         /SCRIPTTAB='c'
 343         /TB1=@{'xxx','xxxxxxxxxxx'@}
 344         /TBFONTS='string'
 345         /WORKSPACE=workspace_size
 346         /XSORT=@{YES,NO@}
 347 @end display
 348
 349 @cmd{SET} allows the user to adjust several parameters relating to
 350 PSPP's execution.  Since there are many subcommands to this command, its
 351 subcommands will be examined in groups.
 352
 353 On subcommands that take boolean values, ON and YES are synonym, and
 354 as are OFF and NO, when used as subcommand values.
 355
 356 The data input subcommands affect the way that data is read from data
 357 files.  The data input subcommands are
 358
 359 @table @asis
 360 @item BLANKS
 361 This is the value assigned to an item data item that is empty or
 362 contains only white space.  An argument of SYSMIS or '.' will cause the
 363 system-missing value to be assigned to null items.  This is the
 364 default.  Any real value may be assigned.
 365
 366 @item DECIMAL
 367 @anchor{SET DECIMAL}
 368 The default DOT setting causes the decimal point character to be
 369 @samp{.} and the grouping character to be @samp{,}.  A setting of COMMA
 370 causes the decimal point character to be @samp{,} and the grouping
 371 character to be @samp{.}.
 372
 373 @item FORMAT
 374 Allows the default numeric input/output format to be specified.  The
 375 default is F8.2.  @xref{Input and Output Formats}.
 376
 377 @item EPOCH
 378 @anchor{SET EPOCH}
 379 Specifies the range of years used when a 2-digit year is read from a
 380 data file or used in a date construction expression (@pxref{Date
 381 Construction}).  If a 4-digit year is specified for the epoch, then
 382 2-digit years are interpreted starting from that year, known as the
 383 epoch.  If AUTOMATIC (the default) is specified, then the epoch begins
 384 69 years before the current date.
 385
 386 @item RIB
 387 @anchor{SET RIB}
 388
 389 PSPP extension to set the byte ordering (endianness) used for reading
 390 data in IB or PIB format (@pxref{Binary and Hexadecimal Numeric
 391 Formats}).  In MSBFIRST ordering, the most-significant byte appears at
 392 the left end of a IB or PIB field.  In LSBFIRST ordering, the
 393 least-significant byte appears at the left end.  VAX ordering is like
 394 MSBFIRST, except that each pair of bytes is in reverse order.  NATIVE,
 395 the default, is equivalent to MSBFIRST or LSBFIRST depending on the
 396 native format of the machine running PSPP.
 397
 398 @item RRB
 399 @anchor{SET RRB}
 400
 401 PSPP extension to set the floating-point format used for reading data in
 402 RB format (@pxref{Binary and Hexadecimal Numeric Formats}).  The
 403 possibilities are:
 404
 405 @table @asis
 406 @item NATIVE
 407 The native format of the machine running PSPP.  Equivalent to either IDL
 408 or IDB.
 409
 410 @item ISL
 411 32-bit IEEE 754 single-precision floating point, in little-endian byte
 412 order.
 413
 414 @item ISB
 415 32-bit IEEE 754 single-precision floating point, in big-endian byte
 416 order.
 417
 418 @item IDL
 419 64-bit IEEE 754 double-precision floating point, in little-endian byte
 420 order.
 421
 422 @item IDB
 423 64-bit IEEE 754 double-precision floating point, in big-endian byte
 424 order.
 425
 426 @item VF
 427 32-bit VAX F format, in VAX-endian byte order.
 428
 429 @item VD
 430 64-bit VAX D format, in VAX-endian byte order.
 431
 432 @item VG
 433 64-bit VAX G format, in VAX-endian byte order.
 434
 435 @item ZS
 436 32-bit IBM Z architecture short format hexadecimal floating point, in
 437 big-endian byte order.
 438
 439 @item ZL
 440 64-bit IBM Z architecture long format hexadecimal floating point, in
 441 big-endian byte order.
 442
 443 Z architecture also supports IEEE 754 floating point.  The ZS and ZL
 444 formats are only for use with very old input files.
 445 @end table
 446 The default is NATIVE.
 447 @end table
 448
 449 Program input subcommands affect the way that programs are parsed when
 450 they are typed interactively or run from a command file.  They are
 451
 452 @table @asis
 453 @item ENDCMD
 454 This is a single character indicating the end of a command.  The default
 455 is @samp{.}.  Don't change this.
 456
 457 @item NULLINE
 458 Whether a blank line is interpreted as ending the current command.  The
 459 default is ON.
 460 @end table
 461
 462 Interaction subcommands affect the way that PSPP interacts with an
 463 online user.  The interaction subcommands are
 464
 465 @table @asis
 466 @item CPROMPT
 467 The command continuation prompt.  The default is @samp{    > }.
 468
 469 @item DPROMPT
 470 Prompt used when expecting data input within @cmd{BEGIN DATA} (@pxref{BEGIN
 471 DATA}).  The default is @samp{data> }.
 472
 473 @item ERRORBREAK
 474 Whether an error causes PSPP to stop processing the current command
 475 file after finishing the current command.  The default is OFF.
 476
 477 @item MXERRS
 478 The maximum number of errors before PSPP halts processing of the current
 479 command file.  The default is 50.
 480
 481 @item MXWARNS
 482 The maximum number of warnings + errors before PSPP halts processing the
 483 current command file.  The default is 100.
 484
 485 @item PROMPT
 486 The command prompt.  The default is @samp{PSPP> }.
 487 @end table
 488
 489 Program execution subcommands control the way that PSPP commands
 490 execute.  The program execution subcommands are
 491
 492 @table @asis
 493 @item MEXPAND
 494 @itemx MITERATE
 495 @itemx MNEST
 496 @itemx MPRINT
 497 Currently not used.
 498
 499 @item MXLOOPS
 500 The maximum number of iterations for an uncontrolled loop (@pxref{LOOP}).
 501
 502 @item SEED
 503 The initial pseudo-random number seed.  Set to a real number or to
 504 RANDOM, which will obtain an initial seed from the current time of day.
 505
 506 @item UNDEFINED
 507 Currently not used.
 508 @end table
 509
 510 Data output subcommands affect the format of output data.  These
 511 subcommands are
 512
 513 @table @asis
 514 @item CCA
 515 @itemx CCB
 516 @itemx CCC
 517 @itemx CCD
 518 @itemx CCE
 519 @anchor{CCx Settings}
 520
 521 Set up custom currency formats.  @xref{Custom Currency Formats}, for
 522 details.
 523
 524 @item DECIMAL
 525 The default DOT setting causes the decimal point character to be
 526 @samp{.}.  A setting of COMMA causes the decimal point character to be
 527 @samp{,}.
 528
 529 @item FORMAT
 530 Allows the default numeric input/output format to be specified.  The
 531 default is F8.2.  @xref{Input and Output Formats}.
 532
 533 @item WIB
 534 @anchor{SET WIB}
 535
 536 PSPP extension to set the byte ordering (endianness) used for writing
 537 data in IB or PIB format (@pxref{Binary and Hexadecimal Numeric
 538 Formats}).  In MSBFIRST ordering, the most-significant byte appears at
 539 the left end of a IB or PIB field.  In LSBFIRST ordering, the
 540 least-significant byte appears at the left end.  VAX ordering is like
 541 MSBFIRST, except that each pair of bytes is in reverse order.  NATIVE,
 542 the default, is equivalent to MSBFIRST or LSBFIRST depending on the
 543 native format of the machine running PSPP.
 544
 545 @item WRB
 546 @anchor{SET WRB}
 547
 548 PSPP extension to set the floating-point format used for writing data in
 549 RB format (@pxref{Binary and Hexadecimal Numeric Formats}).  The choices
 550 are the same as SET RIB.  The default is NATIVE.
 551 @end table
 552
 553 Output routing subcommands affect where the output of transformations
 554 and procedures is sent.  These subcommands are
 555
 556 @table @asis
 557 @item ECHO
 558
 559 If turned on, commands are written to the listing file as they are read
 560 from command files.  The default is OFF.
 561
 562 @itemx ERRORS
 563 @itemx INCLUDE
 564 @itemx MESSAGES
 565 @item PRINTBACK
 566 @item RESULTS
 567 Currently not used.
 568 @end table
 569
 570 Output driver option subcommands affect output drivers' settings.  These
 571 subcommands are
 572
 573 @table @asis
 574 @item HEADERS
 575 @itemx LENGTH
 576 @itemx LISTING
 577 @itemx MORE
 578 @itemx PAGER
 579 @itemx WIDTH
 580 @end table
 581
 582 @cindex headers
 583 @cindex length
 584 @cindex listing
 585 @cindex more
 586 @cindex pager
 587 @cindex width
 588
 589
 590 Logging subcommands affect logging of commands executed to external
 591 files.  These subcommands are
 592
 593 @table @asis
 594 @item JOURNAL
 595 @item LOG
 596 Not currently used.
 597 @end table
 598
 599 System file subcommands affect the default format of system files
 600 produced by PSPP.  These subcommands are
 601
 602 @table @asis
 603 @item COMPRESSION
 604 Not currently used.
 605
 606 @item SCOMPRESSION
 607 Whether system files created by @cmd{SAVE} or @cmd{XSAVE} are
 608 compressed by default.  The default is ON.
 609 @end table
 610
 611 Security subcommands affect the operations that commands are allowed to
 612 perform.  The security subcommands are
 613
 614 @table @asis
 615 @item SAFER
 616 Setting this option disables the following operations:
 617
 618 @itemize @bullet
 619 @item
 620 The ERASE command.
 621 @item
 622 The HOST command.
 623 @item
 624 The PERMISSIONS command.
 625 @item
 626 Pipes (file names beginning or ending with @samp{|}).
 627 @end itemize
 628
 629 Be aware that this setting does not guarantee safety (commands can still
 630 overwrite files, for instance) but it is an improvement.
 631 When set, this setting cannot be reset during the same session, for
 632 obvious security reasons.
 633 @end table
 634
 635 @node SHOW
 636 @comment  node-name,  next,  previous,  up
 637 @section SHOW
 638 @vindex SHOW
 639
 640 @display
 641 SHOW
 642         [ALL]
 643         [BLANKS]
 644         [CC]
 645         [CCA]
 646         [CCB]
 647         [CCC]
 648         [CCD]
 649         [CCE]
 650         [COPYING]
 651         [DECIMALS]
 652         [ENDCMD]
 653         [FORMAT]
 654         [LENGTH]
 655         [MXERRS]
 656         [MXLOOPS]
 657         [MXWARNS]
 658         [SCOMPRESSION]
 659         [UNDEFINED]
 660         [WARRANTY]
 661         [WEIGHT]
 662         [WIDTH]
 663 @end display
 664
 665 @cmd{SHOW} can be used to display the current state of PSPP's execution
 666 parameters.  Parameters that can be changed using @cmd{SET}
 667 (@pxref{SET}), can be examined using @cmd{SHOW} using the subcommand
 668 with the same name.  @code{SHOW} supports the following additional
 669 subcommands:
 670
 671 @table @code
 672 @item ALL
 673 Show all settings.
 674 @item CC
 675 Show all custom currency settings (CCA through CCE).
 676 @item WARRANTY
 677 Show details of the lack of warranty for PSPP.
 678 @item COPYING
 679 Display the terms of PSPP's copyright licence (@pxref{License}).
 680 @end table
 681
 682 Specifying @cmd{SHOW} without any subcommands is equivalent to SHOW ALL.
 683
 684 @node SUBTITLE
 685 @section SUBTITLE
 686 @vindex SUBTITLE
 687
 688 @display
 689 SUBTITLE 'subtitle_string'.
 690   or
 691 SUBTITLE subtitle_string.
 692 @end display
 693
 694 @cmd{SUBTITLE} provides a subtitle to a particular PSPP
 695 run.  This subtitle appears at the top of each output page below the
 696 title, if headers are enabled on the output device.
 697
 698 Specify a subtitle as a string in quotes.  The alternate syntax that did
 699 not require quotes is now obsolete.  If it is used then the subtitle is
 700 converted to all uppercase.
 701
 702 @node TITLE
 703 @section TITLE
 704 @vindex TITLE
 705
 706 @display
 707 TITLE 'title_string'.
 708   or
 709 TITLE title_string.
 710 @end display
 711
 712 @cmd{TITLE} provides a title to a particular PSPP run.
 713 This title appears at the top of each output page, if headers are enabled
 714 on the output device.
 715
 716 Specify a title as a string in quotes.  The alternate syntax that did
 717 not require quotes is now obsolete.  If it is used then the title is
 718 converted to all uppercase.
 719 @setfilename ignored