1 @c PSPP - a program for statistical analysis.
2 @c Copyright (C) 2017, 2020 Free Software Foundation, Inc.
3 @c Permission is granted to copy, distribute and/or modify this document
4 @c under the terms of the GNU Free Documentation License, Version 1.3
5 @c or any later version published by the Free Software Foundation;
6 @c with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
7 @c A copy of the license is included in the section entitled "GNU
8 @c Free Documentation License".
10 @node Invoking pspp-convert
11 @chapter Invoking @command{pspp-convert}
13 @cindex @command{pspp-convert}
15 @command{pspp-convert} is a command-line utility accompanying
16 @pspp{}. It reads an SPSS or SPSS/PC+ system file or SPSS portable
17 file or encrypted SPSS syntax file @var{input} and
18 writes a copy of it to another @var{output} in a different format.
22 @t{pspp-convert} [@var{options}] @var{input} @var{output}
24 @t{pspp-convert -@w{-}help}
26 @t{pspp-convert -@w{-}version}
29 The format of @var{input} is automatically detected, when possible.
30 The character encoding of old SPSS system files cannot always be
31 guessed correctly, and SPSS/PC+ system files do not include any
32 indication of their encoding. Use @code{-e @var{encoding}} to specify
33 the encoding in this case.
35 By default, the intended format for @var{output} is inferred based on its
41 Comma-separated value. Each value is formatted according to its
42 variable's print format. The first line in the file contains variable
53 SPSS syntax file. (Only encrypted syntax files may be converted to
57 @command{pspp-convert} can convert most input formats to most output
58 formats. Encrypted SPSS file formats are exceptions: if the input
59 file is in an encrypted format, then the output file will be the same
60 format (decrypted). To decrypt such a file, specify the encrypted
61 file as @var{input}. The output will be the equivalent plaintext
62 file. Options for the output format are ignored in this case.
64 The password for encrypted files can be specified a few different
65 ways. If the password is known, use the @option{-p} option
66 (documented below) or allow @command{pspp-convert} to prompt for it.
67 If the password is unknown, use the @option{-a} and @option{-l}
68 options to specify how to search for it, or @option{--password-list}
69 to specify a file of passwords to try.
71 Use @code{-O @var{format}} to override the inferred format or to
72 specify the format for unrecognized extensions.
74 @command{pspp-convert} accepts the following general options:
77 @item @option{-O @var{format}}
78 @itemx @option{--output-format=@var{format}}
79 Sets the output format, where @var{format} is one of the extensions
80 listed above, @i{e.g.}: @option{-O csv}. Use @option{--help} to list
81 the supported output formats.
83 @item -c @var{maxcases}
84 @itemx --cases=@var{maxcases}
85 By default, all cases are copied from @var{input} to @var{output}.
86 Specifying this option to limit the number of cases written to
87 @var{output} to @var{maxcases}.
89 @item -e @var{charset}
90 @itemx --encoding=@var{charset}
91 Overrides the encoding in which character strings in @var{input} are
92 interpreted. This option is necessary because old SPSS system files,
93 and SPSS/PC+ system files, do not self-identify their encoding.
95 @item -k @var{variable}@dots{}
96 @itemx --keep=@var{variable}@dots{}
97 By default, @command{pspp-convert} includes all the variables from the
98 input file. Use this option to list specific variables to include;
99 any variables not listed will be dropped. The variables in the output
100 file will also be reordered into the given order. The variable list
101 may use @code{TO} in the same way as in PSPP syntax, @i{e.g.}@: if the
102 dictionary contains consecutive variables @code{a}, @code{b},
103 @code{c}, and @code{d}, then @option{--keep='a to d'} will include all
104 of them (and no others).
106 @item -d @var{variable}@dots{}
107 @itemx --drop=@var{variable}@dots{}
108 Drops the specified variables from the output.
110 When @option{--keep} and @option{--drop} are used together,
111 @option{--keep} is processed first.
115 Prints a usage message on stdout and exits.
119 Prints version information on stdout and exits.
122 The following options affect CSV output:
126 By default, @command{pspp-convert} writes user-missing values to CSV
127 output files as their regular values. With this option,
128 @command{pspp-convert} recodes them to system-missing values (which
129 are written as a single space).
132 By default, @command{pspp-convert} writes the variable names as the
133 first line of output. With this option, @command{pspp-convert} omits
137 By default, @command{pspp-convert} writes variables' values to CSV
138 output files. With this option, @command{pspp-convert} writes value
141 @item --print-formats
142 By default, @command{pspp-convert} writes numeric variables as plain
143 numbers. This option makes @command{pspp-convert} honor variables'
146 @item --decimal=@var{decimal}
147 This option sets the character used as a decimal point in output. The
150 @item --delimiter=@var{delimiter}
151 This option sets the character used to separate fields in output. The
152 default is @samp{,}, unless the decimal point is @samp{,}, in which
153 case @samp{;} is used.
155 @item --qualifier=@var{qualifier}
156 The option sets the character used to quote fields that contain the
157 delimiter. The default is @samp{"}.
160 The following options specify how to obtain the password for encrypted
164 @item -p @var{password}
165 @item --password=@var{password}
166 Specifies the password to use to decrypt an encrypted SPSS system file
167 or syntax file. If this option is not specified,
168 @command{pspp-convert} will prompt interactively for the password as
171 Be aware that command-line options, including passwords, may be
172 visible to other users on multiuser systems.
174 When used with @option{-a} (or @option{--password-alphabet}) and
175 @option{-l} (or @option{--password-length}), this option specifies the
176 starting point for the search. This can be used to restart a search
177 that was interrupted.
179 @item -a @var{alphabet}
180 @item --password-alphabet=@var{alphabet}
181 Specifies the alphabet of symbols over which to search for an
182 encrypted file's password. @var{alphabet} may include individual
183 characters and ranges delimited by @samp{-}. For example, @option{-a
184 a-z} searches lowercase letters, @option{-a A-Z0-9} searches uppercase
185 letters and digits, and @option{-a ' -~'} searches all printable ASCII
188 @item -l @var{max-length}
189 @item --password-length=@var{max-length}
190 Specifies the maximum length of the passwords to try.
192 @item --password-list=@var{file}
193 Specifies a file to read containing a list of passwords to try, one
194 per line. If @var{file} is @file{-}, reads from stdin.