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