doc/invoking.texi

   1 @node Invocation, Language, License, Top
   2 @chapter Invoking PSPP
   3 @cindex invocation
   4 @cindex PSPP, invoking
   5
   6 @cindex command line, options
   7 @cindex options, command-line
   8 @example
   9 pspp [ -B @var{dir} | --config-dir=@var{dir} ] [ -o @var{device} | --device=@var{device} ]
  10        [ -d @var{var}[=@var{value}] | --define=@var{var}[=@var{value}] ] [-u @var{var} | --undef=@var{var} ]
  11        [ -f @var{file} | --out-file=@var{file} ] [ -p | --pipe ] [ -I- | --no-include ]
  12        [ -I @var{dir} | --include=@var{dir} ] [ -i | --interactive ]
  13        [ -n | --edit | --dry-run | --just-print | --recon ]
  14        [ -r | --no-statrc ] [ -h | --help ] [ -l | --list ]
  15        [ -c @var{command} | --command @var{command} ] [ -s | --safer ]
  16        [ --testing-mode ] [ -V | --version ] [ -v | --verbose ]
  17        [ @var{key}=@var{value} ] @var{file}@enddots{}
  18 @end example
  19
  20 @menu
  21 * Non-option Arguments::        Specifying syntax files and output devices.
  22 * Configuration Options::       Change the configuration for the current run.
  23 * Input and output options::    Controlling input and output files.
  24 * Language control options::    Language variants.
  25 * Informational options::       Helpful information about PSPP.
  26 @end menu
  27
  28 @node Non-option Arguments, Configuration Options, Invocation, Invocation
  29 @section Non-option Arguments
  30
  31 Syntax files and output device substitutions can be specified on
  32 PSPP's command line:
  33
  34 @table @code
  35 @item @var{file}
  36
  37 A file by itself on the command line will be executed as a syntax file.
  38 PSPP terminates after the syntax file runs, unless the @code{-i} or
  39 @code{--interactive} option is given (@pxref{Language control options}).
  40
  41 @item @var{file1} @var{file2}
  42
  43 When two or more filenames are given on the command line, the first
  44 syntax file is executed, then PSPP's dictionary is cleared, then the second
  45 syntax file is executed.
  46
  47 @item @var{file1} + @var{file2}
  48
  49 If syntax files' names are delimited by a plus sign (@samp{+}), then the
  50 dictionary is not cleared between their executions, as if they were
  51 concatenated together into a single file.
  52
  53 @item @var{key}=@var{value}
  54
  55 Defines an output device macro @var{key} to expand to @var{value},
  56 overriding any macro having the same @var{key} defined in the device
  57 configuration file.  @xref{Macro definitions}.
  58
  59 @end table
  60
  61 There is one other way to specify a syntax file, if your operating
  62 system supports it.  If you have a syntax file @file{foobar.stat}, put
  63 the notation
  64
  65 @example
  66 #! /usr/local/bin/pspp
  67 @end example
  68
  69 at the top, and mark the file as executable with @code{chmod +x
  70 foobar.stat}.  (If PSPP is not installed in @file{/usr/local/bin},
  71 then insert its actual installation directory into the syntax file
  72 instead.)  Now you should be able to invoke the syntax file just by
  73 typing its name.  You can include any options on the command line as
  74 usual.  PSPP entirely ignores any lines beginning with @samp{#!}.
  75
  76 @node Configuration Options, Input and output options, Non-option Arguments, Invocation
  77 @section Configuration Options
  78
  79 Configuration options are used to change PSPP's configuration for the
  80 current run.  The configuration options are:
  81
  82 @table @code
  83 @item -a @{compatible|enhanced@}
  84 @itemx --algorithm=@{compatible|enhanced@}
  85
  86 If you chose @code{compatible}, then PSPP will use the same  algorithms
  87 as used by some proprietary statistical analysis packages.
  88 This is not recommended, as  these algorithms are inferior and in some cases
  89 compeletely broken.
  90 The default setting is @code{enhanced}.
  91 Certain commands have subcommands which allow you to override this setting on
  92 a per command basis.
  93
  94 @item -B @var{dir}
  95 @itemx --config-dir=@var{dir}
  96
  97 Sets the configuration directory to @var{dir}.  @xref{File locations}.
  98
  99 @item -o @var{device}
 100 @itemx --device=@var{device}
 101
 102 Selects the output device with name @var{device}.  If this option is
 103 given more than once, then all devices mentioned are selected.  This
 104 option disables all devices besides those mentioned on the command line.
 105
 106 @item -d @var{var}[=@var{value}]
 107 @itemx --define=@var{var}[=@var{value}]
 108
 109 Defines an `environment variable' named @var{var} having the optional
 110 value @var{value} specified.  @xref{Variable values}.
 111
 112 @item -u @var{var}
 113 @itemx --undef=@var{var}
 114
 115 Undefines the `environment variable' named @var{var}.  @xref{Variable
 116 values}.
 117 @end table
 118
 119 @node Input and output options, Language control options, Configuration Options, Invocation
 120 @section Input and output options
 121
 122 Input and output options affect how PSPP reads input and writes
 123 output.  These are the input and output options:
 124
 125 @table @code
 126 @item -f @var{file}
 127 @itemx --out-file=@var{file}
 128
 129 This overrides the output file name for devices designated as listing
 130 devices.  If a file named @var{file} already exists, it is overwritten.
 131
 132 @item -p
 133 @itemx --pipe
 134
 135 Allows PSPP to be used as a filter by causing the syntax file to be
 136 read from stdin and output to be written to stdout.  Conflicts with the
 137 @code{-f @var{file}} and @code{--file=@var{file}} options.
 138
 139 @item -I-
 140 @itemx --no-include
 141
 142 Clears all directories from the include path.  This includes all
 143 directories put in the include path by default.  @xref{Miscellaneous
 144 configuring}.
 145
 146 @item -I @var{dir}
 147 @itemx --include=@var{dir}
 148
 149 Appends directory @var{dir} to the path that is searched for include
 150 files in PSPP syntax files.
 151
 152 @item -c @var{command}
 153 @itemx --command=@var{command}
 154
 155 Execute literal command @var{command}.  The command is executed before
 156 startup syntax files, if any.
 157
 158 @item --testing-mode
 159
 160 Invoke heuristics to assist with testing PSPP.  For use by @code{make
 161 check} and similar scripts.
 162 @end table
 163
 164 @node Language control options, Informational options, Input and output options, Invocation
 165 @section Language control options
 166
 167 Language control options control how PSPP syntax files are parsed and
 168 interpreted.  The available language control options are:
 169
 170 @table @code
 171 @item -i
 172 @itemx --interactive
 173
 174 When a syntax file is specified on the command line, PSPP normally
 175 terminates after processing it.  Giving this option will cause PSPP to
 176 bring up a command prompt after processing the syntax file.
 177
 178 In addition, this forces syntax files to be interpreted in interactive
 179 mode, rather than the default batch mode.  @xref{Tokenizing lines}, for
 180 information on the differences between batch mode and interactive mode
 181 command interpretation.
 182
 183 @item -n
 184 @itemx --edit
 185 @itemx --dry-run
 186 @itemx --just-print
 187 @itemx --recon
 188
 189 Only the syntax of any syntax file specified or of commands entered at
 190 the command line is checked.  Transformations are not performed and
 191 procedures are not executed.  Not yet implemented.
 192
 193 @item -r
 194 @itemx --no-statrc
 195
 196 Prevents the execution of the PSPP startup syntax file.  Not yet
 197 implemented, as startup syntax files aren't, either.
 198
 199 @item -s
 200 @itemx --safer
 201
 202 Disables certain unsafe operations.  This includes the ERASE and
 203 HOST commands, as well as use of pipes as input and output files.
 204 @end table
 205
 206 @node Informational options,  , Language control options, Invocation
 207 @section Informational options
 208
 209 Informational options cause information about PSPP to be written to
 210 the terminal.  Here are the available options:
 211
 212 @table @code
 213 @item -h
 214 @item --help
 215
 216 Prints a message describing PSPP command-line syntax and the available
 217 device driver classes, then terminates.
 218
 219 @item -l
 220 @item --list
 221
 222 Lists the available device driver classes, then terminates.
 223
 224 @item -x @{compatible|enhanced@}
 225 @itemx --syntax=@{compatible|enhanced@}
 226
 227 If you chose @code{compatible}, then PSPP will only accept command syntax that
 228 is compatible with the proprietary program SPSS.
 229 If you choose @code{enhanced} then additional syntax will be available.
 230 The default is @code{enhanced}.
 231
 232
 233 @item -V
 234 @item --version
 235
 236 Prints a brief message listing PSPP's version, warranties you don't
 237 have, copying conditions and copyright, and e-mail address for bug
 238 reports, then terminates.
 239
 240 @item -v
 241 @item --verbose
 242
 243 Increments PSPP's verbosity level.  Higher verbosity levels cause
 244 PSPP to display greater amounts of information about what it is
 245 doing.  Often useful for debugging PSPP's configuration.
 246
 247 This option can be given multiple times to set the verbosity level to
 248 that value.  The default verbosity level is 0, in which no informational
 249 messages will be displayed.
 250
 251 Higher verbosity levels cause messages to be displayed when the
 252 corresponding events take place.
 253
 254 @table @asis
 255 @item 1
 256
 257 Driver and subsystem initializations.
 258
 259 @item 2
 260
 261 Completion of driver initializations.  Beginning of driver closings.
 262
 263 @item 3
 264
 265 Completion of driver closings.
 266
 267 @item 4
 268
 269 Files searched for; success of searches.
 270
 271 @item 5
 272
 273 Individual directories included in file searches.
 274 @end table
 275
 276 Each verbosity level also includes messages from lower verbosity levels.
 277
 278 @end table
 279 @setfilename ignored