utilities/pspp-convert.1

   1 .\" -*- nroff -*-
   2 .\" Copyright (C) 2020  Free Software Foundation
   3
   4 .\" This program is free software: you can redistribute it and/or modify
   5 .\" it under the terms of the GNU General Public License as published by
   6 .\" the Free Software Foundation, either version 3 of the License, or
   7 .\" (at your option) any later version.
   8
   9 .\" This program is distributed in the hope that it will be useful,
  10 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12 .\" GNU General Public License for more details.
  13
  14 .\" You should have received a copy of the GNU General Public License
  15 .\" along with this program.  If not, see <http://www.gnu.org/licenses/>.
  16 .de IQ
  17 .  br
  18 .  ns
  19 .  IP "\\$1"
  20 ..
  21 .TH pspp\-convert 1 "October 2013" "PSPP" "PSPP Manual"
  22 .
  23 .SH NAME
  24 pspp\-convert \- convert SPSS data files to other formats
  25 .
  26 .SH SYNOPSIS
  27 \fBpspp\-convert\fR [\fIoptions\fR] \fIinput\fR \fIoutput\fR
  28 .br
  29 \fBpspp\-convert \-\-help\fR | \fB\-h\fR
  30 .br
  31 \fBpspp\-convert \-\-version\fR | \fB\-v\fR
  32 .
  33 .SH DESCRIPTION
  34 The \fBpspp\-convert\fR program reads \fIinput\fR, which may be an
  35 SPSS system file, an SPSS/PC+ system file, an SPSS portable file,
  36 or an encrypted SPSS syntax file,
  37 and writes it to \fIoutput\fR, performing format conversion as
  38 necessary.
  39 .PP
  40 The format of \fIinput\fR is automatically detected, when possible.
  41 The character encoding of old SPSS system files cannot always be
  42 guessed correctly, and SPSS/PC+ system files do not include any
  43 indication of their encoding.  Use \fB\-e \fIencoding\fR to specify
  44 the encoding in this case.
  45 .PP
  46 By default, the intended format for \fIoutput\fR is inferred from its
  47 extension:
  48 .
  49 .IP \fBcsv\fR
  50 .IQ \fBtxt\fR
  51 Comma-separated value.  Each value is formatted according to its
  52 variable's print format.  The first line in the file contains variable
  53 names.
  54 .
  55 .IP \fBsav\fR
  56 .IQ \fBsys\fR
  57 SPSS system file.
  58 .
  59 .IP \fBpor\fR
  60 SPSS portable file.
  61 .
  62 .IP \fBsps\fR
  63 SPSS syntax file.  (Only encrypted syntax files may be converted to
  64 this format.)
  65 .
  66 .PP
  67 Use \fB\-O \fIextension\fR to override the inferred format or to
  68 specify the format for unrecognized extensions.
  69 .
  70 .PP
  71 \fBpspp\-convert\fR can convert most input formats to most output
  72 formats.  Encrypted SPSS file formats are exceptions: if the input
  73 file is in an encrypted format, then the output file will be the same
  74 format (decrypted).  Options for the output format are ignored in this
  75 case.
  76 .
  77 .SH "OPTIONS"
  78 .SS "General Options"
  79 .
  80 .IP "\fB\-O format\fR"
  81 .IQ "\fB\-\-output\-format=\fIformat\fR"
  82 Specifies the desired output format.  \fIformat\fR must be one of the
  83 extensions listed above, e.g. \fB\-O csv\fR requests comma-separated
  84 value output.
  85 .
  86 .IP "\fB\-c \fImaxcases\fR"
  87 .IQ "\fB\-\-cases=\fImaxcases\fR"
  88 By default, all cases are copied from \fIinput\fR to \fIoutput\fR.
  89 Specifying this option to limit the number of cases written to
  90 \fIoutput\fR to \fImaxcases\fR.
  91 .
  92 .IP "\fB\-e \fIcharset\fR"
  93 .IQ "\fB\-\-encoding=\fIcharset\fR"
  94 Overrides the encoding in which character strings in \fIinput\fR are
  95 interpreted.  This option is necessary because old SPSS system files
  96 do not self-identify their encoding.
  97 .
  98 .IP "\fB\-k \fIvar\fR..."
  99 .IQ "\fB\-\-keep=\fIvar\fR..."
 100 Drops all variables except those listed as \fIvar\fR, and reorders the
 101 remaining variables into the specified order.
 102 .
 103 .IP "\fB\-d \fIvar\fR..."
 104 .IQ "\fB\-\-drop=\fIvar\fR..."
 105 Drops each \fIvar\fR listed from the output.
 106 .
 107 .SS "CSV Output Options"
 108 .PP
 109 These options affect only output to \fB.csv\fR and \fB.txt\fR files.
 110 .IP "\fB\-\-labels\fR"
 111 By default, \fBpspp\-convert\fR writes variables' values to the output.
 112 With this option, \fBpspp\-convert\fR writes value labels.
 113 .IP "\fB\-\-no\-var\-names\fR"
 114 By default, \fRpspp\-convert\fR\fR writes the variable names as the
 115 first line of output.  With this option, \fBpspp\-convert\fR omits
 116 this line.
 117 .IP "\fB\-\-recode\fR"
 118 By default, \fBpspp\-convert\fR writes user-missing values as their
 119 regular values.  With this option, \fBpspp\-convert\fR recodes them to
 120 system-missing values (which are written as a single space).
 121
 122 .IP "\fB\-\-print\-formats\fR"
 123 By default, \fBpspp\-convert\fR writes numeric variables as plain
 124 numbers.  This option makes \fBpspp\-convert\fR honor variables'
 125 print formats.
 126
 127 .IP "\fB\-\-decimal=\fIdecimal\fR"
 128 This option sets the character used as a decimal point in output.  The
 129 default is a period (\fB.\fR).
 130
 131 .IP "\fB\-\-delimiter=\fIdelimiter\fR"
 132 This option sets the character used to separate fields in output.  The
 133 default is a comma (\fB,\fR), unless the decimal point is a comma, in
 134 which case a semicolon (\fB;\fR) is used.
 135
 136 .IP "\fB\-\-qualifier=\fIqualifier\fR"
 137 The option sets the character used to quote fields that contain the
 138 delimiter.  The default is a double quote (\fB\(dq\fR).
 139 .
 140 .SS "Password Options"
 141 When the input file is encrypted, \fBpspp\-convert\fR needs to obtain
 142 a password to decrypt it.  To do so, the user may specify the password
 143 with \fB\-p\fR (or \fB\-\-password\fR), or the name of a file containing a
 144 list of possible passwords with \fB\-\-password\-list\fR, or an
 145 alphabet of possible passwords to try along with a maximum length with
 146 \fB\-a\fR (or \fB\-\-password\-alphabet\fR) and \fB\-l\fR (or
 147 \-\-password\-length\fR).  If none of these options is used,
 148 \fBpspp\-convert\fR prompts for the password.  The password options
 149 are:
 150 .
 151 .IP "\fB\-p \fIpassword\fR"
 152 .IQ "\fB\-\-password=\fIpassword\fR"
 153 Specifies the password to use to decrypt the input file.
 154 .
 155 .IP
 156 On multiuser systems, this option may not be safe because other users
 157 may be able to see the password in process listings.
 158 .
 159 .IP "\fB\-a \fIalphabet \fB\-l \fImax-length\fR"
 160 .IQ "\fB\-\-password-alphabet=\fIalphabet\ \fB\-\-password-length=\fImax-length\fR"
 161 These options are an alternative to \fB\-p\fR or \fB\-\-password\fR.
 162 They direct \fBpspp\-convert\fR to search for the correct password
 163 from the set of all passwords of symbols from \fIalphabet\fR (which
 164 may contain character ranges specified with \fB-\fR) and no more than
 165 \fImax-length\fR symbols long.  For example, \fB\-a a-z \-l 5\fR
 166 checks all possible lowercase alphabetic passwords no more than 5
 167 characters long.
 168 .IP
 169 When these options are used, \fB\-p\fR may additionally specify a
 170 starting point for the search.
 171 .
 172 .IP "\fB\-\-password\-list=\fIfile\fR"
 173 Specifies a file to read containing a list of passwords to try, one
 174 per line.  If \fIfile\fR is \fB\-\fR, reads from stdin.
 175 .
 176 .SS "Other Options"
 177 .IP "\fB\-h\fR"
 178 .IQ "\fB\-\-help\fR"
 179 Prints a usage message on stdout and exits.
 180 .
 181 .IP "\fB\-v\fR"
 182 .IQ "\fB\-\-version\fR"
 183 Prints version information on stdout and exits.
 184 .
 185 .SH "AUTHORS"
 186 Ben Pfaff.
 187 .
 188 .SH "SEE ALSO"
 189 .
 190 .BR pspp\-output (1),
 191 .BR pspp (1),
 192 .BR psppire (1).