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