doc/invoking.texi

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