1 @node System and Portable Files, Variable Attributes, Data Input and Output, Top
2 @chapter System Files and Portable Files
4 The commands in this chapter read, write, and examine system files and
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.
19 @node APPLY DICTIONARY
20 @section APPLY DICTIONARY
21 @vindex APPLY DICTIONARY
24 APPLY DICTIONARY FROM='filename'.
27 @cmd{APPLY DICTIONARY} applies the variable labels, value labels,
28 and missing values from variables in a system file to corresponding
29 variables in the active file. In some cases it also updates the
32 Specify a system file with a file name string or as a file handle
33 (@pxref{FILE HANDLE}). The dictionary in the system file will be read,
34 but it will not replace the active file dictionary. The system file's
35 data will not be read.
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.
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.
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
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.
61 @cmd{APPLY DICTIONARY} takes effect immediately. It does not read the
63 file. The system file is not modified.
72 /UNSELECTED=@{RETAIN,DELETE@}
76 /RENAME=(src_names=target_names)@dots{}
81 The @cmd{EXPORT} procedure writes the active file dictionary and data to a
82 specified portable file.
84 By default, cases excluded with FILTER are written to the portable
85 file. These can be excluded by specifying DELETE on the UNSELECTED
86 subcommand. Specifying RETAIN makes the default explicit.
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.
97 The OUTFILE subcommand, which is the only required subcommand, specifies
98 the portable file to be written as a file name string or a file handle
99 (@pxref{FILE HANDLE}).
101 DROP, KEEP, and RENAME follow the same format as the SAVE procedure
104 The TYPE subcommand specifies the character set for use in the
105 portable file. Its value is currently not used.
107 The MAP subcommand is currently ignored.
109 @cmd{EXPORT} is a procedure. It causes the active file to be read.
120 /RENAME=(src_names=target_names)@dots{}
123 @cmd{GET} clears the current dictionary and active file and
124 replaces them with the dictionary and data from a specified system file.
126 The FILE subcommand is the only required subcommand. Specify the system
127 file to be read as a string file name or a file handle (@pxref{FILE
130 By default, all the variables in a system 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.
135 Normally variables in a system 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)}.
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
148 DROP, KEEP, and RENAME are performed in left-to-right order. They
149 each may be present any number of times. @cmd{GET} never modifies a
150 system file on disk. Only the active file read from the system file
151 is affected by these subcommands.
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.
166 /RENAME=(src_names=target_names)@dots{}
169 The @cmd{IMPORT} transformation clears the active file dictionary and
171 replaces them with a dictionary and data from a portable file on disk.
173 The FILE subcommand, which is the only required subcommand, specifies
174 the portable file to be read as a file name string or a file handle
175 (@pxref{FILE HANDLE}).
177 The TYPE subcommand is currently not used.
179 DROP, KEEP, and RENAME follow the syntax used by @cmd{GET} (@pxref{GET}).
181 @cmd{IMPORT} does not cause the data to be read, only the dictionary. The
182 data is read later, when a procedure is executed.
190 /@{FILE,TABLE@}=@{*,'filename'@}
193 /RENAME=(src_names=target_names)@dots{}
202 @cmd{MATCH FILES} merges one or more system files, optionally
203 including the active file. Records with the same values for BY
204 variables are combined into a single record. Records with different
205 values are output in order. Thus, multiple sorted system files are
206 combined into a single sorted system file based on the value of the BY
207 variables. The results of the merge become the new active file.
209 The BY subcommand specifies a list of variables that are used to match
210 records from each of the system files. Variables specified must exist
211 in all the files specified on FILE and TABLE. BY should usually be
212 specified. If TABLE or IN is used then BY is required.
214 Specify FILE with a system file as a file name string or file handle
215 (@pxref{FILE HANDLE}), or with an asterisk (@samp{*}) to
216 indicate the current active file. The files specified on FILE are
217 merged together based on the BY variables, or combined case-by-case if
218 BY is not specified. Normally at least two FILE subcommands should be
221 Specify TABLE with a system file to use it as a @dfn{table
222 lookup file}. Records in table lookup files are not used up after
223 they've been used once. This means that data in table lookup files can
224 correspond to any number of records in FILE files. Table lookup files
225 correspond to lookup tables in traditional relational database systems.
226 It is incorrect to have records with duplicate BY values in table lookup
229 Any number of FILE and TABLE subcommands may be specified. Each
230 instance of FILE or TABLE can be followed by any sequence of DROP,
231 KEEP, or RENAME subcommands. These have the same form and meaning as
232 the corresponding subcommands of @cmd{GET} (@pxref{GET}), but apply
233 only to variables in the given file.
235 Each FILE or TABLE may optionally be followed by an IN subcommand,
236 which creates a numeric variable with the specified name and format
237 F1.0. The IN variable takes value 1 in a case if the given file
238 contributed a row to the merged file, 0 otherwise. The DROP, KEEP,
239 and RENAME subcommands do not affect IN variables.
241 Variables belonging to files that are not present for the current case
242 are set to the system-missing value for numeric variables or spaces for
245 FIRST, LAST, and MAP are currently ignored.
247 @cmd{MATCH FILES} may not be specified following @cmd{TEMPORARY}
248 (@pxref{TEMPORARY}) if the active file is used as an input source.
257 /UNSELECTED=@{RETAIN,DELETE@}
258 /@{COMPRESSED,UNCOMPRESSED@}
259 /PERMISSIONS=@{WRITEABLE,READONLY@}
263 /RENAME=(src_names=target_names)@dots{}
268 The @cmd{SAVE} procedure causes the dictionary and data in the active
270 be written to a system file.
272 OUTFILE is the only required subcommand. Specify the system
273 file to be written as a string file name or a file handle (@pxref{FILE
276 By default, cases excluded with FILTER are written to the system file.
277 These can be excluded by specifying DELETE on the UNSELECTED
278 subcommand. Specifying RETAIN makes the default explicit.
280 The COMPRESS and UNCOMPRESS subcommand determine whether the saved
281 system file is compressed. By default, system files are compressed.
282 This default can be changed with the SET command (@pxref{SET}).
284 The PERMISSIONS subcommand specifies permissions for the new system
285 file. WRITEABLE, the default, creates the file with read and write
286 permission. READONLY creates the file for read-only access.
288 By default, all the variables in the active file dictionary are written
289 to the system file. The DROP subcommand can be used to specify a list
290 of variables not to be written. In contrast, KEEP specifies variables
291 to be written, with all variables not specified not written.
293 Normally variables are saved to a system file under the same names they
294 have in the active file. Use the RENAME subcommand to change these names.
295 Specify, within parentheses, a list of variable names followed by an
296 equals sign (@samp{=}) and the names that they should be renamed to.
297 Multiple parenthesized groups of variable names can be included on a
298 single RENAME subcommand. Variables' names may be swapped using a
299 RENAME subcommand of the form @samp{/RENAME=(A B=B A)}.
301 Alternate syntax for the RENAME subcommand allows the parentheses to be
302 eliminated. When this is done, only a single variable may be renamed at
303 once. For instance, @samp{/RENAME=A=B}. This alternate syntax is
306 DROP, KEEP, and RENAME are performed in left-to-right order. They
307 each may be present any number of times. @cmd{SAVE} never modifies
308 the active file. DROP, KEEP, and RENAME only affect the system file
311 The VERSION subcommand specifies the version of the file format. Valid
312 versions are 2 and 3. The default version is 3. In version 2 system
313 files, variable names longer than 8 bytes will be truncated. The two
314 versions are otherwise identical.
316 The NAMES and MAP subcommands are currently ignored.
318 @cmd{SAVE} causes the data to be read. It is a procedure.
321 @section SYSFILE INFO
325 SYSFILE INFO FILE='filename'.
328 @cmd{SYSFILE INFO} reads the dictionary in a system file and
329 displays the information in its dictionary.
331 Specify a file name or file handle. @cmd{SYSFILE INFO} reads that file as
332 a system file and displays information on its dictionary.
334 @cmd{SYSFILE INFO} does not affect the current active file.
346 /RENAME=(src_names=target_names)@dots{}
351 The @cmd{EXPORT} transformation writes the active file dictionary and
352 data to a specified portable file.
354 This transformation is a PSPP extension.
356 It is similar to the @cmd{EXPORT} procedure, with two differences:
360 @cmd{XEXPORT} is a transformation, not a procedure. It is executed when
361 the data is read by a procedure or procedure-like command.
364 @cmd{XEXPORT} does not support the UNSELECTED subcommand.
367 @xref{EXPORT}, for more information.
369 @node XSAVE, , XEXPORT, System and Portable Files
376 /@{COMPRESSED,UNCOMPRESSED@}
377 /PERMISSIONS=@{WRITEABLE,READONLY@}
381 /RENAME=(src_names=target_names)@dots{}
386 The @cmd{XSAVE} transformation writes the active file dictionary and
387 data to a system file stored on disk. It is similar to the @cmd{SAVE}
388 procedure, with two differences:
392 @cmd{XSAVE} is a transformation, not a procedure. It is executed when
393 the data is read by a procedure or procedure-like command.
396 @cmd{XSAVE} does not support the UNSELECTED subcommand.
399 @xref{SAVE}, for more information.