doc/utilities.texi

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