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 @node DROP DOCUMENTS, ECHO, 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 @node ECHO, ERASE, DROP DOCUMENTS, Utilities
 106 @section ECHO
 107 @vindex ECHO
 108
 109 @display
 110 ECHO 'arbitrary text' .
 111 @end display
 112
 113 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}).
 114
 115 @node ERASE, EXECUTE, ECHO, Utilities
 116 @comment  node-name,  next,  previous,  up
 117 @section ERASE
 118 @vindex ERASE
 119
 120 @display
 121 ERASE FILE file_name.
 122 @end display
 123
 124 @cmd{ERASE FILE} deletes a file from the local filesystem.
 125 file_name must be quoted.
 126 This command cannot be used if the SAFER setting is active.
 127
 128
 129 @node EXECUTE, FILE LABEL, ERASE, Utilities
 130 @section EXECUTE
 131 @vindex EXECUTE
 132
 133 @display
 134 EXECUTE.
 135 @end display
 136
 137 @cmd{EXECUTE} causes the active file to be read and all pending
 138 transformations to be executed.
 139
 140 @node FILE LABEL, FINISH, EXECUTE, Utilities
 141 @section FILE LABEL
 142 @vindex FILE LABEL
 143
 144 @display
 145 FILE LABEL file_label.
 146 @end display
 147
 148 @cmd{FILE LABEL} provides a title for the active file.  This
 149 title will be saved into system files and portable files that are
 150 created during this PSPP run.
 151
 152 file_label need not be quoted.  If quotes are
 153 included, they become part of the file label.
 154
 155 @node FINISH, HOST, FILE LABEL, Utilities
 156 @section FINISH
 157 @vindex FINISH
 158
 159 @display
 160 FINISH.
 161 @end display
 162
 163 @cmd{FINISH} terminates the current PSPP session and returns
 164 control to the operating system.
 165
 166 @node HOST, INCLUDE, FINISH, Utilities
 167 @comment  node-name,  next,  previous,  up
 168 @section HOST
 169 @vindex HOST
 170
 171 @display
 172 HOST.
 173 @end display
 174
 175 @cmd{HOST} suspends the current PSPP session and temporarily returns control
 176 to the operating system.
 177 This command cannot be used if the SAFER setting is active.
 178
 179
 180 @node INCLUDE, PERMISSIONS, HOST, Utilities
 181 @section INCLUDE
 182 @vindex INCLUDE
 183 @vindex @@
 184
 185 @display
 186 Two possible syntaxes:
 187         INCLUDE 'filename'.
 188         @@filename.
 189 @end display
 190
 191 @cmd{INCLUDE} causes the PSPP command processor to read an
 192 additional command file as if it were included bodily in the current
 193 command file.
 194
 195 Include files may be nested to any depth, up to the limit of available
 196 memory.
 197
 198 @node PERMISSIONS, SET, INCLUDE, Utilities
 199 @comment  node-name,  next,  previous,  up
 200 @section PERMISSIONS
 201 @vindex PERMISSIONS
 202 @cindex mode
 203 @cindex file mode
 204 @cindex changing file permissions
 205
 206 @display
 207 PERMISSIONS
 208         FILE='filename'
 209         /PERMISSIONS = @{READONLY,WRITEABLE@}.
 210 @end display
 211
 212 @cmd{PERMISSIONS} changes the permissions of a file.
 213 There is one mandatory subcommand which specifies the permissions to
 214 which the file should be changed.
 215 If you set a file's  permission  to READONLY, then the file will become
 216 unwritable either by you or anyone else on the system.
 217 If you set the permission to WRITEABLE, then the file will become
 218 writeable by you; the permissions afforded to others will be
 219 unchanged.
 220 This command cannot be used if the SAFER setting is active.
 221
 222
 223 @node SET, SHOW, PERMISSIONS, Utilities
 224 @section SET
 225 @vindex SET
 226
 227 @display
 228 SET
 229
 230 (data input)
 231         /BLANKS=@{SYSMIS,'.',number@}
 232         /DECIMAL=@{DOT,COMMA@}
 233         /FORMAT=fmt_spec
 234         /EPOCH=@{AUTOMATIC,year@}
 235
 236 (program input)
 237         /ENDCMD='.'
 238         /NULLINE=@{ON,OFF@}
 239
 240 (interaction)
 241         /CPROMPT='cprompt_string'
 242         /DPROMPT='dprompt_string'
 243         /ERRORBREAK=@{OFF,ON@}
 244         /MXERRS=max_errs
 245         /MXWARNS=max_warnings
 246         /PROMPT='prompt'
 247
 248 (program execution)
 249         /MEXPAND=@{ON,OFF@}
 250         /MITERATE=max_iterations
 251         /MNEST=max_nest
 252         /MPRINT=@{ON,OFF@}
 253         /MXLOOPS=max_loops
 254         /SEED=@{RANDOM,seed_value@}
 255         /UNDEFINED=@{WARN,NOWARN@}
 256
 257 (data output)
 258         /CC@{A,B,C,D,E@}=@{'npre,pre,suf,nsuf','npre.pre.suf.nsuf'@}
 259         /DECIMAL=@{DOT,COMMA@}
 260         /FORMAT=fmt_spec
 261
 262 (output routing)
 263         /ECHO=@{ON,OFF@}
 264         /ERRORS=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}
 265         /INCLUDE=@{ON,OFF@}
 266         /MESSAGES=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}
 267         /PRINTBACK=@{ON,OFF@}
 268         /RESULTS=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}
 269
 270 (output driver options)
 271         /HEADERS=@{NO,YES,BLANK@}
 272         /LENGTH=@{NONE,length_in_lines@}
 273         /LISTING=@{ON,OFF,filename@}
 274         /MORE=@{ON,OFF@}
 275         /WIDTH=@{NARROW,WIDTH,n_characters@}
 276
 277 (logging)
 278         /JOURNAL=@{ON,OFF@} [filename]
 279
 280 (system files)
 281         /COMPRESSION=@{ON,OFF@}
 282         /SCOMPRESSION=@{ON,OFF@}
 283
 284 (security)
 285         /SAFER=ON
 286
 287 (obsolete settings accepted for compatibility, but ignored)
 288         /BOXSTRING=@{'xxx','xxxxxxxxxxx'@}
 289         /CASE=@{UPPER,UPLOW@}
 290         /CPI=cpi_value
 291         /DISK=@{ON,OFF@}
 292         /HIGHRES=@{ON,OFF@}
 293         /HISTOGRAM='c'
 294         /LOWRES=@{AUTO,ON,OFF@}
 295         /LPI=lpi_value
 296         /MENUS=@{STANDARD,EXTENDED@}
 297         /MXMEMORY=max_memory
 298         /SCRIPTTAB='c'
 299         /TB1=@{'xxx','xxxxxxxxxxx'@}
 300         /TBFONTS='string'
 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 white space.  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
 331 @item EPOCH
 332 @anchor{SET EPOCH}
 333 Specifies the range of years used when a 2-digit year is read from a
 334 data file or used in a date construction expression (@pxref{Date
 335 Construction}).  If a 4-digit year is specified, then 2-digit years
 336 are interpreted starting from that year, known as the epoch.  If
 337 AUTOMATIC (the default) is specified, then the epoch begins 69 years
 338 before the current date.
 339 @end table
 340
 341 Program input subcommands affect the way that programs are parsed when
 342 they are typed interactively or run from a command file.  They are
 343
 344 @table @asis
 345 @item ENDCMD
 346 This is a single character indicating the end of a command.  The default
 347 is @samp{.}.  Don't change this.
 348
 349 @item NULLINE
 350 Whether a blank line is interpreted as ending the current command.  The
 351 default is ON.
 352 @end table
 353
 354 Interaction subcommands affect the way that PSPP interacts with an
 355 online user.  The interaction subcommands are
 356
 357 @table @asis
 358 @item CPROMPT
 359 The command continuation prompt.  The default is @samp{    > }.
 360
 361 @item DPROMPT
 362 Prompt used when expecting data input within @cmd{BEGIN DATA} (@pxref{BEGIN
 363 DATA}).  The default is @samp{data> }.
 364
 365 @item ERRORBREAK
 366 Whether an error causes PSPP to stop processing the current command
 367 file after finishing the current command.  The default is OFF.
 368
 369 @item MXERRS
 370 The maximum number of errors before PSPP halts processing of the current
 371 command file.  The default is 50.
 372
 373 @item MXWARNS
 374 The maximum number of warnings + errors before PSPP halts processing the
 375 current command file.  The default is 100.
 376
 377 @item PROMPT
 378 The command prompt.  The default is @samp{PSPP> }.
 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 driver option subcommands affect output drivers' settings.  These
 452 subcommands are
 453
 454 @table @asis
 455 @item HEADERS
 456 @itemx LENGTH
 457 @itemx LISTING
 458 @itemx MORE
 459 @itemx PAGER
 460 @itemx WIDTH
 461 @end table
 462
 463 @cindex headers
 464 @cindex length
 465 @cindex listing
 466 @cindex more
 467 @cindex pager
 468 @cindex width
 469
 470
 471 Logging subcommands affect logging of commands executed to external
 472 files.  These subcommands are
 473
 474 @table @asis
 475 @item JOURNAL
 476 @item LOG
 477 Not currently used.
 478 @end table
 479
 480 System file subcommands affect the default format of system files
 481 produced by PSPP.  These subcommands are
 482
 483 @table @asis
 484 @item COMPRESSION
 485 Not currently used.
 486
 487 @item SCOMPRESSION
 488 Whether system files created by @cmd{SAVE} or @cmd{XSAVE} are
 489 compressed by default.  The default is ON.
 490 @end table
 491
 492 Security subcommands affect the operations that commands are allowed to
 493 perform.  The security subcommands are
 494
 495 @table @asis
 496 @item SAFER
 497 Setting this option disables the following operations:
 498
 499 @itemize @bullet
 500 @item
 501 The ERASE command.
 502 @item
 503 The HOST command.
 504 @item
 505 The PERMISSIONS command.
 506 @item
 507 Pipe filenames (filenames beginning or ending with @samp{|}).
 508 @end itemize
 509
 510 Be aware that this setting does not guarantee safety (commands can still
 511 overwrite files, for instance) but it is an improvement.
 512 When set, this setting cannot be reset during the same session, for
 513 obvious security reasons.
 514 @end table
 515
 516 @node SHOW, SUBTITLE, SET, Utilities
 517 @comment  node-name,  next,  previous,  up
 518 @section SHOW
 519 @vindex SHOW
 520
 521 @display
 522 SHOW
 523         [ALL]
 524         [BLANKS]
 525         [CC]
 526         [CCA]
 527         [CCB]
 528         [CCC]
 529         [CCD]
 530         [CCE]
 531         [COPYING]
 532         [DECIMALS]
 533         [ENDCMD]
 534         [FORMAT]
 535         [LENGTH]
 536         [MXERRS]
 537         [MXLOOPS]
 538         [MXWARNS]
 539         [SCOMPRESSION]
 540         [UNDEFINED]
 541         [WARRANTY]
 542         [WEIGHT]
 543         [WIDTH]
 544 @end display
 545
 546 @cmd{SHOW} can be used to display the current state of PSPP's execution
 547 parameters.  Parameters that can be changed using @cmd{SET}
 548 (@pxref{SET}), can be examined using @cmd{SHOW} using the subcommand
 549 with the same name.  @code{SHOW} supports the following additional
 550 subcommands:
 551
 552 @table @code
 553 @item ALL
 554 Show all settings.
 555 @item CC
 556 Show all custom currency settings (CCA through CCE).
 557 @item WARRANTY
 558 Show details of the lack of warranty for PSPP.
 559 @item COPYING
 560 Display the terms of PSPP's copyright licence (@pxref{License}).
 561 @end table
 562
 563 Specifying @cmd{SHOW} without any subcommands is equivalent to SHOW ALL.
 564
 565 @node SUBTITLE, TITLE, SHOW, Utilities
 566 @section SUBTITLE
 567 @vindex SUBTITLE
 568
 569 @display
 570 SUBTITLE 'subtitle_string'.
 571   or
 572 SUBTITLE subtitle_string.
 573 @end display
 574
 575 @cmd{SUBTITLE} provides a subtitle to a particular PSPP
 576 run.  This subtitle appears at the top of each output page below the
 577 title, if headers are enabled on the output device.
 578
 579 Specify a subtitle as a string in quotes.  The alternate syntax that did
 580 not require quotes is now obsolete.  If it is used then the subtitle is
 581 converted to all uppercase.
 582
 583 @node TITLE,  , SUBTITLE, Utilities
 584 @section TITLE
 585 @vindex TITLE
 586
 587 @display
 588 TITLE 'title_string'.
 589   or
 590 TITLE title_string.
 591 @end display
 592
 593 @cmd{TITLE} provides a title to a particular PSPP run.
 594 This title appears at the top of each output page, if headers are enabled
 595 on the output device.
 596
 597 Specify a title as a string in quotes.  The alternate syntax that did
 598 not require quotes is now obsolete.  If it is used then the title is
 599 converted to all uppercase.
 600 @setfilename ignored