doc/files.texi

   1 @node System and Portable Files, Variable Attributes, Data Input and Output, Top
   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 * XSAVE::                       Write to a system file, as a transform.
  16 @end menu
  17
  18 @node APPLY DICTIONARY, EXPORT, System and Portable Files, System and Portable Files
  19 @section APPLY DICTIONARY
  20 @vindex APPLY DICTIONARY
  21
  22 @display
  23 APPLY DICTIONARY FROM='filename'.
  24 @end display
  25
  26 @cmd{APPLY DICTIONARY} applies the variable labels, value labels,
  27 and missing values from variables in a system file to corresponding
  28 variables in the active file.  In some cases it also updates the
  29 weighting variable.
  30
  31 Specify a system file with a file name string or as a file handle
  32 (@pxref{FILE HANDLE}).  The dictionary in the system file will be read,
  33 but it will not replace the active file dictionary.  The system file's
  34 data will not be read.
  35
  36 Only variables with names that exist in both the active file and the
  37 system file are considered.  Variables with the same name but different
  38 types (numeric, string) will cause an error message.  Otherwise, the
  39 system file variables' attributes will replace those in their matching
  40 active file variables, as described below.
  41
  42 If a system file variable has a variable label, then it will replace the
  43 active file variable's variable label.  If the system file variable does
  44 not have a variable label, then the active file variable's variable
  45 label, if any, will be retained.
  46
  47 If the active file variable is numeric or short string, then value
  48 labels and missing values, if any, will be copied to the active file
  49 variable.  If the system file variable does not have value labels or
  50 missing values, then those in the active file variable, if any, will not
  51 be disturbed.
  52
  53 Finally, weighting of the active file is updated (@pxref{WEIGHT}).  If
  54 the active file has a weighting variable, and the system file does not,
  55 or if the weighting variable in the system file does not exist in the
  56 active file, then the active file weighting variable, if any, is
  57 retained.  Otherwise, the weighting variable in the system file becomes
  58 the active file weighting variable.
  59
  60 @cmd{APPLY DICTIONARY} takes effect immediately.  It does not read the
  61 active
  62 file.  The system file is not modified.
  63
  64 @node EXPORT, GET, APPLY DICTIONARY, System and Portable Files
  65 @section EXPORT
  66 @vindex EXPORT
  67
  68 @display
  69 EXPORT
  70         /OUTFILE='filename'
  71         /DROP=var_list
  72         /KEEP=var_list
  73         /RENAME=(src_names=target_names)@dots{}
  74 @end display
  75
  76 The @cmd{EXPORT} procedure writes the active file dictionary and data to a
  77 specified portable file.
  78
  79 The OUTFILE subcommand, which is the only required subcommand, specifies
  80 the portable file to be written as a file name string or a file handle
  81 (@pxref{FILE HANDLE}).
  82
  83 DROP, KEEP, and RENAME follow the same format as the SAVE procedure
  84 (@pxref{SAVE}).
  85
  86 @cmd{EXPORT} is a procedure.  It causes the active file to be read.
  87
  88 @node GET, IMPORT, EXPORT, System and Portable Files
  89 @section GET
  90 @vindex GET
  91
  92 @display
  93 GET
  94         /FILE='filename'
  95         /DROP=var_list
  96         /KEEP=var_list
  97         /RENAME=(src_names=target_names)@dots{}
  98 @end display
  99
 100 @cmd{GET} clears the current dictionary and active file and
 101 replaces them with the dictionary and data from a specified system file.
 102
 103 The FILE subcommand is the only required subcommand.  Specify the system
 104 file to be read as a string file name or a file handle (@pxref{FILE
 105 HANDLE}).
 106
 107 By default, all the variables in a system file are read.  The DROP
 108 subcommand can be used to specify a list of variables that are not to be
 109 read.  By contrast, the KEEP subcommand can be used to specify variable
 110 that are to be read, with all other variables not read.
 111
 112 Normally variables in a system file retain the names that they were
 113 saved under.  Use the RENAME subcommand to change these names.  Specify,
 114 within parentheses, a list of variable names followed by an equals sign
 115 (@samp{=}) and the names that they should be renamed to.  Multiple
 116 parenthesized groups of variable names can be included on a single
 117 RENAME subcommand.  Variables' names may be swapped using a RENAME
 118 subcommand of the form @samp{/RENAME=(A B=B A)}.
 119
 120 Alternate syntax for the RENAME subcommand allows the parentheses to be
 121 eliminated.  When this is done, only a single variable may be renamed at
 122 once.  For instance, @samp{/RENAME=A=B}.  This alternate syntax is
 123 deprecated.
 124
 125 DROP, KEEP, and RENAME are performed in left-to-right order.  They
 126 each may be present any number of times.  @cmd{GET} never modifies a
 127 system file on disk.  Only the active file read from the system file
 128 is affected by these subcommands.
 129
 130 @cmd{GET} does not cause the data to be read, only the dictionary.  The data
 131 is read later, when a procedure is executed.
 132
 133 @node IMPORT, MATCH FILES, GET, System and Portable Files
 134 @section IMPORT
 135 @vindex IMPORT
 136
 137 @display
 138 IMPORT
 139         /FILE='filename'
 140         /TYPE=@{COMM,TAPE@}
 141         /DROP=var_list
 142         /KEEP=var_list
 143         /RENAME=(src_names=target_names)@dots{}
 144 @end display
 145
 146 The @cmd{IMPORT} transformation clears the active file dictionary and
 147 data and
 148 replaces them with a dictionary and data from a portable file on disk.
 149
 150 The FILE subcommand, which is the only required subcommand, specifies
 151 the portable file to be read as a file name string or a file handle
 152 (@pxref{FILE HANDLE}).
 153
 154 The TYPE subcommand is currently not used.
 155
 156 DROP, KEEP, and RENAME follow the syntax used by @cmd{GET} (@pxref{GET}).
 157
 158 @cmd{IMPORT} does not cause the data to be read, only the dictionary.  The
 159 data is read later, when a procedure is executed.
 160
 161 @node MATCH FILES, SAVE, IMPORT, System and Portable Files
 162 @section MATCH FILES
 163 @vindex MATCH FILES
 164
 165 @display
 166 MATCH FILES
 167         /BY var_list
 168         /@{FILE,TABLE@}=@{*,'filename'@}
 169         /DROP=var_list
 170         /KEEP=var_list
 171         /RENAME=(src_names=target_names)@dots{}
 172         /IN=var_name
 173         /FIRST=var_name
 174         /LAST=var_name
 175         /MAP
 176 @end display
 177
 178 @cmd{MATCH FILES} merges one or more system files, optionally
 179 including the active file.  Records with the same values for BY
 180 variables are combined into a single record.  Records with different
 181 values are output in order.  Thus, multiple sorted system files are
 182 combined into a single sorted system file based on the value of the BY
 183 variables.  The results of the merge become the new active file.
 184
 185 The BY subcommand specifies a list of variables that are used to match
 186 records from each of the system files.  Variables specified must exist
 187 in all the files specified on FILE and TABLE.  BY should usually be
 188 specified.  If TABLE is used then BY is required.
 189
 190 Specify FILE with a system file as a file name string or file handle
 191 (@pxref{FILE HANDLE}), or with an asterisk (@samp{*}) to
 192 indicate the current active file.  The files specified on FILE are
 193 merged together based on the BY variables, or combined case-by-case if
 194 BY is not specified.  Normally at least two FILE subcommands should be
 195 specified.
 196
 197 Specify TABLE with a system file to use it as a @dfn{table
 198 lookup file}.  Records in table lookup files are not used up after
 199 they've been used once.  This means that data in table lookup files can
 200 correspond to any number of records in FILE files.  Table lookup files
 201 correspond to lookup tables in traditional relational database systems.
 202 It is incorrect to have records with duplicate BY values in table lookup
 203 files.
 204
 205 Any number of FILE and TABLE subcommands may be specified.  Each
 206 instance of FILE or TABLE can be followed by DROP, KEEP, and/or RENAME
 207 subcommands.  These take the same form as the corresponding subcommands
 208 of @cmd{GET} (@pxref{GET}), and perform the same functions.
 209
 210 Variables belonging to files that are not present for the current case
 211 are set to the system-missing value for numeric variables or spaces for
 212 string variables.
 213
 214 IN, FIRST, LAST, and MAP are currently not used.
 215
 216 @cmd{MATCH FILES} may not be specified following @cmd{TEMPORARY}
 217 (@pxref{TEMPORARY}) if the active file is used as an input source.
 218
 219 @node SAVE, SYSFILE INFO, MATCH FILES, System and Portable Files
 220 @section SAVE
 221 @vindex SAVE
 222
 223 @display
 224 SAVE
 225         /OUTFILE='filename'
 226         /@{COMPRESSED,UNCOMPRESSED@}
 227         /DROP=var_list
 228         /KEEP=var_list
 229         /VERSION=version
 230         /RENAME=(src_names=target_names)@dots{}
 231 @end display
 232
 233 The @cmd{SAVE} procedure causes the dictionary and data in the active
 234 file to
 235 be written to a system file.
 236
 237 FILE is the only required subcommand.  Specify the system
 238 file to be written as a string file name or a file handle (@pxref{FILE
 239 HANDLE}).
 240
 241 The COMPRESS and UNCOMPRESS subcommand determine whether the saved
 242 system file is compressed.  By default, system files are compressed.
 243 This default can be changed with the SET command (@pxref{SET}).
 244
 245 By default, all the variables in the active file dictionary are written
 246 to the system file.  The DROP subcommand can be used to specify a list
 247 of variables not to be written.  In contrast, KEEP specifies variables
 248 to be written, with all variables not specified not written.
 249
 250 Normally variables are saved to a system file under the same names they
 251 have in the active file.  Use the RENAME subcommand to change these names.
 252 Specify, within parentheses, a list of variable names followed by an
 253 equals sign (@samp{=}) and the names that they should be renamed to.
 254 Multiple parenthesized groups of variable names can be included on a
 255 single RENAME subcommand.  Variables' names may be swapped using a
 256 RENAME subcommand of the form @samp{/RENAME=(A B=B A)}.
 257
 258 Alternate syntax for the RENAME subcommand allows the parentheses to be
 259 eliminated.  When this is done, only a single variable may be renamed at
 260 once.  For instance, @samp{/RENAME=A=B}.  This alternate syntax is
 261 deprecated.
 262
 263 DROP, KEEP, and RENAME are performed in left-to-right order.  They
 264 each may be present any number of times.  @cmd{SAVE} never modifies
 265 the active file.  DROP, KEEP, and RENAME only affect the system file
 266 written to disk.
 267
 268 The VERSION subcommand specifies the version of the file format. Valid
 269 versions are '3' and '3x'.  Version 3x system files are identical to
 270 version 3 files, except that variable names greater than 8 bytes will
 271 be truncated.  The default version is 3.  The VERSION subcommand is
 272 optional.  There is no need ever to use it.
 273
 274 @cmd{SAVE} causes the data to be read.  It is a procedure.
 275
 276 @node SYSFILE INFO, XSAVE, SAVE, System and Portable Files
 277 @section SYSFILE INFO
 278 @vindex SYSFILE INFO
 279
 280 @display
 281 SYSFILE INFO FILE='filename'.
 282 @end display
 283
 284 @cmd{SYSFILE INFO} reads the dictionary in a system file and
 285 displays the information in its dictionary.
 286
 287 Specify a file name or file handle.  @cmd{SYSFILE INFO} reads that file as
 288 a system file and displays information on its dictionary.
 289
 290 @cmd{SYSFILE INFO} does not affect the current active file.
 291
 292 @node XSAVE,  , SYSFILE INFO, System and Portable Files
 293 @section XSAVE
 294 @vindex XSAVE
 295
 296 @display
 297 XSAVE
 298         /FILE='filename'
 299         /@{COMPRESSED,UNCOMPRESSED@}
 300         /DROP=var_list
 301         /KEEP=var_list
 302         /RENAME=(src_names=target_names)@dots{}
 303 @end display
 304
 305 The @cmd{XSAVE} transformation writes the active file dictionary and
 306 data to a
 307 system file stored on disk.
 308
 309 @cmd{XSAVE} is a transformation, not a procedure.  It is executed when the
 310 data is read by a procedure or procedure-like command.  In all other
 311 respects, @cmd{XSAVE} is identical to @cmd{SAVE}.  @xref{SAVE}, for
 312 more information on syntax and usage.
 313 @setfilename ignored