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