doc/files.texi

   1 @node System and Portable Files
   2 @chapter System Files and Portable Files
   3
   4 The commands in this chapter read, write, and examine system files and
   5 portable files.
   6
   7 @menu
   8 * APPLY DICTIONARY::            Apply system file dictionary to active file.
   9 * EXPORT::                      Write to a portable file.
  10 * GET::                         Read from a system file.
  11 * IMPORT::                      Read from a portable file.
  12 * MATCH FILES::                 Merge system files.
  13 * SAVE::                        Write to a system file.
  14 * SYSFILE INFO::                Display system file dictionary.
  15 * XEXPORT::                     Write to a portable file, as a transformation.
  16 * XSAVE::                       Write to a system file, as a transformation.
  17 @end menu
  18
  19 @node APPLY DICTIONARY
  20 @section APPLY DICTIONARY
  21 @vindex APPLY DICTIONARY
  22
  23 @display
  24 APPLY DICTIONARY FROM=@{'file-name',file_handle@}.
  25 @end display
  26
  27 @cmd{APPLY DICTIONARY} applies the variable labels, value labels,
  28 and missing values taken from a file to corresponding
  29 variables in the active file.  In some cases it also updates the
  30 weighting variable.
  31
  32 Specify a system file, portable file, or scratch file with a file name
  33 string or as a file handle (@pxref{File Handles}).  The dictionary in the
  34 file will be read, but it will not replace the active file dictionary.
  35 The file's data will not be read.
  36
  37 Only variables with names that exist in both the active file and the
  38 system file are considered.  Variables with the same name but different
  39 types (numeric, string) will cause an error message.  Otherwise, the
  40 system file variables' attributes will replace those in their matching
  41 active file variables, as described below.
  42
  43 If a system file variable has a variable label, then it will replace the
  44 active file variable's variable label.  If the system file variable does
  45 not have a variable label, then the active file variable's variable
  46 label, if any, will be retained.
  47
  48 If the active file variable is numeric or short string, then value
  49 labels and missing values, if any, will be copied to the active file
  50 variable.  If the system file variable does not have value labels or
  51 missing values, then those in the active file variable, if any, will not
  52 be disturbed.
  53
  54 Finally, weighting of the active file is updated (@pxref{WEIGHT}).  If
  55 the active file has a weighting variable, and the system file does not,
  56 or if the weighting variable in the system file does not exist in the
  57 active file, then the active file weighting variable, if any, is
  58 retained.  Otherwise, the weighting variable in the system file becomes
  59 the active file weighting variable.
  60
  61 @cmd{APPLY DICTIONARY} takes effect immediately.  It does not read the
  62 active
  63 file.  The system file is not modified.
  64
  65 @node EXPORT
  66 @section EXPORT
  67 @vindex EXPORT
  68
  69 @display
  70 EXPORT
  71         /OUTFILE='file-name'
  72         /UNSELECTED=@{RETAIN,DELETE@}
  73         /DIGITS=n
  74         /DROP=var_list
  75         /KEEP=var_list
  76         /RENAME=(src_names=target_names)@dots{}
  77         /TYPE=@{COMM,TAPE@}
  78         /MAP
  79 @end display
  80
  81 The @cmd{EXPORT} procedure writes the active file dictionary and data to a
  82 specified portable file or scratch file.
  83
  84 By default, cases excluded with FILTER are written to the
  85 file.  These can be excluded by specifying DELETE on the UNSELECTED
  86 subcommand.  Specifying RETAIN makes the default explicit.
  87
  88 Portable files express real numbers in base 30.  Integers are always
  89 expressed to the maximum precision needed to make them exact.
  90 Non-integers are, by default, expressed to the machine's maximum
  91 natural precision (approximately 15 decimal digits on many machines).
  92 If many numbers require this many digits, the portable file may
  93 significantly increase in size.  As an alternative, the DIGITS
  94 subcommand may be used to specify the number of decimal digits of
  95 precision to write.  DIGITS applies only to non-integers.
  96
  97 The OUTFILE subcommand, which is the only required subcommand, specifies
  98 the portable file or scratch file to be written as a file name string or
  99 a file handle (@pxref{File Handles}).
 100
 101 DROP, KEEP, and RENAME follow the same format as the SAVE procedure
 102 (@pxref{SAVE}).
 103
 104 The TYPE subcommand specifies the character set for use in the
 105 portable file.  Its value is currently not used.
 106
 107 The MAP subcommand is currently ignored.
 108
 109 @cmd{EXPORT} is a procedure.  It causes the active file to be read.
 110
 111 @node GET
 112 @section GET
 113 @vindex GET
 114
 115 @display
 116 GET
 117         /FILE=@{'file-name',file_handle@}
 118         /DROP=var_list
 119         /KEEP=var_list
 120         /RENAME=(src_names=target_names)@dots{}
 121 @end display
 122
 123 @cmd{GET} clears the current dictionary and active file and
 124 replaces them with the dictionary and data from a specified file.
 125
 126 The FILE subcommand is the only required subcommand.  Specify the system
 127 file, portable file, or scratch file to be read as a string file name or
 128 a file handle (@pxref{File Handles}).
 129
 130 By default, all the variables in a file are read.  The DROP
 131 subcommand can be used to specify a list of variables that are not to be
 132 read.  By contrast, the KEEP subcommand can be used to specify variable
 133 that are to be read, with all other variables not read.
 134
 135 Normally variables in a file retain the names that they were
 136 saved under.  Use the RENAME subcommand to change these names.  Specify,
 137 within parentheses, a list of variable names followed by an equals sign
 138 (@samp{=}) and the names that they should be renamed to.  Multiple
 139 parenthesized groups of variable names can be included on a single
 140 RENAME subcommand.  Variables' names may be swapped using a RENAME
 141 subcommand of the form @samp{/RENAME=(A B=B A)}.
 142
 143 Alternate syntax for the RENAME subcommand allows the parentheses to be
 144 eliminated.  When this is done, only a single variable may be renamed at
 145 once.  For instance, @samp{/RENAME=A=B}.  This alternate syntax is
 146 deprecated.
 147
 148 DROP, KEEP, and RENAME are executed in left-to-right order.
 149 Each may be present any number of times.  @cmd{GET} never modifies a
 150 file on disk.  Only the active file read from the file
 151 is affected by these subcommands.
 152
 153 @cmd{GET} does not cause the data to be read, only the dictionary.  The data
 154 is read later, when a procedure is executed.
 155
 156 Use of @cmd{GET} to read a portable file or scratch file is a PSPP
 157 extension.
 158
 159 @node IMPORT
 160 @section IMPORT
 161 @vindex IMPORT
 162
 163 @display
 164 IMPORT
 165         /FILE='file-name'
 166         /TYPE=@{COMM,TAPE@}
 167         /DROP=var_list
 168         /KEEP=var_list
 169         /RENAME=(src_names=target_names)@dots{}
 170 @end display
 171
 172 The @cmd{IMPORT} transformation clears the active file dictionary and
 173 data and
 174 replaces them with a dictionary and data from a system, portable file,
 175 or scratch file.
 176
 177 The FILE subcommand, which is the only required subcommand, specifies
 178 the portable file to be read as a file name string or a file handle
 179 (@pxref{File Handles}).
 180
 181 The TYPE subcommand is currently not used.
 182
 183 DROP, KEEP, and RENAME follow the syntax used by @cmd{GET} (@pxref{GET}).
 184
 185 @cmd{IMPORT} does not cause the data to be read, only the dictionary.  The
 186 data is read later, when a procedure is executed.
 187
 188 Use of @cmd{IMPORT} to read a system file or scratch file is a PSPP
 189 extension.
 190
 191 @node MATCH FILES
 192 @section MATCH FILES
 193 @vindex MATCH FILES
 194
 195 @display
 196 MATCH FILES
 197         /@{FILE,TABLE@}=@{*,'file-name'@}
 198         /RENAME=(src_names=target_names)@dots{}
 199         /IN=var_name
 200
 201         /BY=var_list
 202         /DROP=var_list
 203         /KEEP=var_list
 204         /FIRST=var_name
 205         /LAST=var_name
 206         /MAP
 207 @end display
 208
 209 @cmd{MATCH FILES} merges one or more system, portable, or scratch files,
 210 optionally
 211 including the active file.  Cases with the same values for BY
 212 variables are combined into a single case.  Cases with different
 213 values are output in order.  Thus, multiple sorted files are
 214 combined into a single sorted file based on the value of the BY
 215 variables.  The results of the merge become the new active file.
 216
 217 Specify FILE with a system, portable, or scratch file as a file name
 218 string or file handle
 219 (@pxref{File Handles}), or with an asterisk (@samp{*}) to
 220 indicate the current active file.  The files specified on FILE are
 221 merged together based on the BY variables, or combined case-by-case if
 222 BY is not specified.
 223
 224 Specify TABLE with a file to use it as a @dfn{table
 225 lookup file}.  Cases in table lookup files are not used up after
 226 they've been used once.  This means that data in table lookup files can
 227 correspond to any number of cases in FILE files.  Table lookup files
 228 correspond to lookup tables in traditional relational database systems.
 229 If a table lookup file contains more than one case with a given set of
 230 BY variables, only the first case is used.
 231
 232 Any number of FILE and TABLE subcommands may be specified.
 233 Ordinarily, at least two FILE subcommands, or one FILE and at least
 234 one TABLE, should be specified.  Each instance of FILE or TABLE can be
 235 followed by any sequence of RENAME subcommands.  These have the same
 236 form and meaning as the corresponding subcommands of @cmd{GET}
 237 (@pxref{GET}), but apply only to variables in the given file.
 238
 239 Each FILE or TABLE may optionally be followed by an IN subcommand,
 240 which creates a numeric variable with the specified name and format
 241 F1.0.  The IN variable takes value 1 in a case if the given file
 242 contributed a row to the merged file, 0 otherwise.  The DROP, KEEP,
 243 and RENAME subcommands do not affect IN variables.
 244
 245 When more than one FILE or TABLE contains a variable with a given
 246 name, those variables must all have the same type (numeric or string)
 247 and, for string variables, the same width.  This rules applies to
 248 variable names after renaming with RENAME; thus, RENAME can be used to
 249 resolve conflicts.
 250
 251 FILE and TABLE must be specified at the beginning of the command, with
 252 any RENAME or IN specifications immediately after the corresponding
 253 FILE or TABLE.  These subcommands are followed by BY, DROP, KEEP,
 254 FIRST, LAST, and MAP.
 255
 256 The BY subcommand specifies a list of variables that are used to match
 257 cases from each of the files.  When TABLE or IN is used, BY is
 258 required; otherwise, it is optional.  When BY is specified, all the
 259 files named on FILE and TABLE subcommands must be sorted in ascending
 260 order of the BY variables.  Variables belonging to files that are not
 261 present for the current case are set to the system-missing value for
 262 numeric variables or spaces for string variables.
 263
 264 The DROP and KEEP subcommands allow variables to be dropped from or
 265 reordered within the new active file.  These subcommands have the same
 266 form and meaning as the corresponding subcommands of @cmd{GET}
 267 (@pxref{GET}).  They apply to the new active file as a whole, not to
 268 individual input files.  The variable names specified on DROP and KEEP
 269 are those after any renaming with RENAME.
 270
 271 The optional FIRST and LAST subcommands name variables that @cmd{MATCH
 272 FILES} adds to the active file.  The new variables are numeric with
 273 print and write format F1.0.  The value of the FIRST variable is 1 in
 274 the first case with a given set of values for the BY variables, and 0
 275 in other cases.  Similarly, the LAST variable is 1 in the last case
 276 with a given of BY values, and 0 in other cases.
 277
 278 @cmd{MATCH FILES} may not be specified following @cmd{TEMPORARY}
 279 (@pxref{TEMPORARY}) if the active file is used as an input source.
 280
 281 Use of portable or scratch files on @cmd{MATCH FILES} is a PSPP
 282 extension.
 283
 284 @node SAVE
 285 @section SAVE
 286 @vindex SAVE
 287
 288 @display
 289 SAVE
 290         /OUTFILE=@{'file-name',file_handle@}
 291         /UNSELECTED=@{RETAIN,DELETE@}
 292         /@{COMPRESSED,UNCOMPRESSED@}
 293         /PERMISSIONS=@{WRITEABLE,READONLY@}
 294         /DROP=var_list
 295         /KEEP=var_list
 296         /VERSION=version
 297         /RENAME=(src_names=target_names)@dots{}
 298         /NAMES
 299         /MAP
 300 @end display
 301
 302 The @cmd{SAVE} procedure causes the dictionary and data in the active
 303 file to
 304 be written to a system file or scratch file.
 305
 306 OUTFILE is the only required subcommand.  Specify the system file or
 307 scratch file to be written as a string file name or a file handle
 308 (@pxref{File Handles}).
 309
 310 By default, cases excluded with FILTER are written to the system file.
 311 These can be excluded by specifying DELETE on the UNSELECTED
 312 subcommand.  Specifying RETAIN makes the default explicit.
 313
 314 The COMPRESS and UNCOMPRESS subcommand determine whether the saved
 315 system file is compressed.  By default, system files are compressed.
 316 This default can be changed with the SET command (@pxref{SET}).
 317
 318 The PERMISSIONS subcommand specifies permissions for the new system
 319 file.  WRITEABLE, the default, creates the file with read and write
 320 permission.  READONLY creates the file for read-only access.
 321
 322 By default, all the variables in the active file dictionary are written
 323 to the system file.  The DROP subcommand can be used to specify a list
 324 of variables not to be written.  In contrast, KEEP specifies variables
 325 to be written, with all variables not specified not written.
 326
 327 Normally variables are saved to a system file under the same names they
 328 have in the active file.  Use the RENAME subcommand to change these names.
 329 Specify, within parentheses, a list of variable names followed by an
 330 equals sign (@samp{=}) and the names that they should be renamed to.
 331 Multiple parenthesized groups of variable names can be included on a
 332 single RENAME subcommand.  Variables' names may be swapped using a
 333 RENAME subcommand of the form @samp{/RENAME=(A B=B A)}.
 334
 335 Alternate syntax for the RENAME subcommand allows the parentheses to be
 336 eliminated.  When this is done, only a single variable may be renamed at
 337 once.  For instance, @samp{/RENAME=A=B}.  This alternate syntax is
 338 deprecated.
 339
 340 DROP, KEEP, and RENAME are performed in left-to-right order.  They
 341 each may be present any number of times.  @cmd{SAVE} never modifies
 342 the active file.  DROP, KEEP, and RENAME only affect the system file
 343 written to disk.
 344
 345 The VERSION subcommand specifies the version of the file format. Valid
 346 versions are 2 and 3.  The default version is 3.  In version 2 system
 347 files, variable names longer than 8 bytes will be truncated.  The two
 348 versions are otherwise identical.
 349
 350 The NAMES and MAP subcommands are currently ignored.
 351
 352 @cmd{SAVE} causes the data to be read.  It is a procedure.
 353
 354 @node SYSFILE INFO
 355 @section SYSFILE INFO
 356 @vindex SYSFILE INFO
 357
 358 @display
 359 SYSFILE INFO FILE='file-name'.
 360 @end display
 361
 362 @cmd{SYSFILE INFO} reads the dictionary in a system file and
 363 displays the information in its dictionary.
 364
 365 Specify a file name or file handle.  @cmd{SYSFILE INFO} reads that file as
 366 a system file and displays information on its dictionary.
 367
 368 @cmd{SYSFILE INFO} does not affect the current active file.
 369
 370 @node XEXPORT
 371 @section XEXPORT
 372 @vindex XEXPORT
 373
 374 @display
 375 EXPORT
 376         /OUTFILE='file-name'
 377         /DIGITS=n
 378         /DROP=var_list
 379         /KEEP=var_list
 380         /RENAME=(src_names=target_names)@dots{}
 381         /TYPE=@{COMM,TAPE@}
 382         /MAP
 383 @end display
 384
 385 The @cmd{EXPORT} transformation writes the active file dictionary and
 386 data to a specified portable file.
 387
 388 This transformation is a PSPP extension.
 389
 390 It is similar to the @cmd{EXPORT} procedure, with two differences:
 391
 392 @itemize
 393 @item
 394 @cmd{XEXPORT} is a transformation, not a procedure.  It is executed when
 395 the data is read by a procedure or procedure-like command.
 396
 397 @item
 398 @cmd{XEXPORT} does not support the UNSELECTED subcommand.
 399 @end itemize
 400
 401 @xref{EXPORT}, for more information.
 402
 403 @node XSAVE
 404 @section XSAVE
 405 @vindex XSAVE
 406
 407 @display
 408 XSAVE
 409         /OUTFILE='file-name'
 410         /@{COMPRESSED,UNCOMPRESSED@}
 411         /PERMISSIONS=@{WRITEABLE,READONLY@}
 412         /DROP=var_list
 413         /KEEP=var_list
 414         /VERSION=version
 415         /RENAME=(src_names=target_names)@dots{}
 416         /NAMES
 417         /MAP
 418 @end display
 419
 420 The @cmd{XSAVE} transformation writes the active file dictionary and
 421 data to a system file or scratch file.  It is similar to the @cmd{SAVE}
 422 procedure, with two differences:
 423
 424 @itemize
 425 @item
 426 @cmd{XSAVE} is a transformation, not a procedure.  It is executed when
 427 the data is read by a procedure or procedure-like command.
 428
 429 @item
 430 @cmd{XSAVE} does not support the UNSELECTED subcommand.
 431 @end itemize
 432
 433 @xref{SAVE}, for more information.
 434 @setfilename ignored