@c PSPP - a program for statistical analysis.
@c Copyright (C) 2017, 2020 Free Software Foundation, Inc.
@c Permission is granted to copy, distribute and/or modify this document
@c under the terms of the GNU Free Documentation License, Version 1.3
@c or any later version published by the Free Software Foundation;
@c with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
@c A copy of the license is included in the section entitled "GNU
@c Free Documentation License".
@c
@node Invoking pspp-convert
@chapter Invoking @command{pspp-convert}
@cindex Invocation
@cindex @command{pspp-convert}

@command{pspp-convert} is a command-line utility accompanying
@pspp{}. It reads an SPSS or SPSS/PC+ system file or SPSS portable
file or encrypted SPSS syntax file @var{input} and
writes a copy of it to another @var{output} in a different format.
Synopsis:

@display
@t{pspp-convert} [@var{options}] @var{input} @var{output}

@t{pspp-convert -@w{-}help}

@t{pspp-convert -@w{-}version}
@end display

The format of @var{input} is automatically detected, when possible.
The character encoding of old SPSS system files cannot always be
guessed correctly, and SPSS/PC+ system files do not include any
indication of their encoding.  Use @code{-e @var{encoding}} to specify
the encoding in this case.

By default, the intended format for @var{output} is inferred based on its
extension:

@table @code
@item csv
@itemx txt
Comma-separated value.  Each value is formatted according to its
variable's print format.  The first line in the file contains variable
names.

@item sav
@item sys
SPSS system file.

@item por
SPSS portable file.

@item sps
SPSS syntax file.  (Only encrypted syntax files may be converted to
this format.)
@end table

@command{pspp-convert} can convert most input formats to most output
formats.  Encrypted SPSS file formats are exceptions: if the input
file is in an encrypted format, then the output file will be the same
format (decrypted).  To decrypt such a file, specify the encrypted
file as @var{input}.  The output will be the equivalent plaintext
file.  Options for the output format are ignored in this case.

The password for encrypted files can be specified a few different
ways.  If the password is known, use the @option{-p} option
(documented below) or allow @command{pspp-convert} to prompt for it.
If the password is unknown, use the @option{-a} and @option{-l}
options to specify how to search for it, or @option{--password-list}
to specify a file of passwords to try.

Use @code{-O @var{format}} to override the inferred format or to
specify the format for unrecognized extensions.

@command{pspp-convert} accepts the following general options:

@table @option
@item @option{-O @var{format}}
@itemx @option{--output-format=@var{format}}
Sets the output format, where @var{format} is one of the extensions
listed above, @i{e.g.}: @option{-O csv}.  Use @option{--help} to list
the supported output formats.

@item -c @var{maxcases}
@itemx --cases=@var{maxcases}
By default, all cases are copied from @var{input} to @var{output}.
Specifying this option to limit the number of cases written to
@var{output} to @var{maxcases}.

@item -e @var{charset}
@itemx --encoding=@var{charset}
Overrides the encoding in which character strings in @var{input} are
interpreted.  This option is necessary because old SPSS system files,
and SPSS/PC+ system files, do not self-identify their encoding.

@item -k @var{variable}@dots{}
@itemx --keep=@var{variable}@dots{}
By default, @command{pspp-convert} includes all the variables from the
input file.  Use this option to list specific variables to include;
any variables not listed will be dropped.  The variables in the output
file will also be reordered into the given order.  The variable list
may use @code{TO} in the same way as in PSPP syntax, @i{e.g.}@: if the
dictionary contains consecutive variables @code{a}, @code{b},
@code{c}, and @code{d}, then @option{--keep='a to d'} will include all
of them (and no others).

@item -d @var{variable}@dots{}
@itemx --drop=@var{variable}@dots{}
Drops the specified variables from the output.

When @option{--keep} and @option{--drop} are used together,
@option{--keep} is processed first.

@item -h
@itemx --help
Prints a usage message on stdout and exits.

@item -v
@itemx --version
Prints version information on stdout and exits.
@end table

The following options affect CSV output:

@table @option
@item --recode
By default, @command{pspp-convert} writes user-missing values to CSV
output files as their regular values.  With this option,
@command{pspp-convert} recodes them to system-missing values (which
are written as a single space).

@item --no-var-names
By default, @command{pspp-convert} writes the variable names as the
first line of output.  With this option, @command{pspp-convert} omits
this line.

@item --labels
By default, @command{pspp-convert} writes variables' values to CSV
output files.  With this option, @command{pspp-convert} writes value
labels.

@item --print-formats
By default, @command{pspp-convert} writes numeric variables as plain
numbers.  This option makes @command{pspp-convert} honor variables'
print formats.

@item --decimal=@var{decimal}
This option sets the character used as a decimal point in output.  The
default is @samp{.}.

@item --delimiter=@var{delimiter}
This option sets the character used to separate fields in output.  The
default is @samp{,}, unless the decimal point is @samp{,}, in which
case @samp{;} is used.

@item --qualifier=@var{qualifier}
The option sets the character used to quote fields that contain the
delimiter.  The default is @samp{"}.
@end table

The following options specify how to obtain the password for encrypted
files:

@table @option
@item -p @var{password}
@item --password=@var{password}
Specifies the password to use to decrypt an encrypted SPSS system file
or syntax file.  If this option is not specified,
@command{pspp-convert} will prompt interactively for the password as
necessary.

Be aware that command-line options, including passwords, may be
visible to other users on multiuser systems.

When used with @option{-a} (or @option{--password-alphabet}) and
@option{-l} (or @option{--password-length}), this option specifies the
starting point for the search.  This can be used to restart a search
that was interrupted.

@item -a @var{alphabet}
@item --password-alphabet=@var{alphabet}
Specifies the alphabet of symbols over which to search for an
encrypted file's password.  @var{alphabet} may include individual
characters and ranges delimited by @samp{-}.  For example, @option{-a
a-z} searches lowercase letters, @option{-a A-Z0-9} searches uppercase
letters and digits, and @option{-a ' -~'} searches all printable ASCII
characters.

@item -l @var{max-length}
@item --password-length=@var{max-length}
Specifies the maximum length of the passwords to try.

@item --password-list=@var{file}
Specifies a file to read containing a list of passwords to try, one
per line.  If @var{file} is @file{-}, reads from stdin.
@end table
