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