3321390edf6dd76d09617111e82db679edf93623
[pspp-builds.git] / 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         /RENAME=(src_names=target_names)@dots{}
230 @end display
231
232 The @cmd{SAVE} procedure causes the dictionary and data in the active
233 file to
234 be written to a system file.
235
236 FILE is the only required subcommand.  Specify the system
237 file to be written as a string file name or a file handle (@pxref{FILE
238 HANDLE}).
239
240 The COMPRESS and UNCOMPRESS subcommand determine whether the saved
241 system file is compressed.  By default, system files are compressed.
242 This default can be changed with the SET command (@pxref{SET}).
243
244 By default, all the variables in the active file dictionary are written
245 to the system file.  The DROP subcommand can be used to specify a list
246 of variables not to be written.  In contrast, KEEP specifies variables
247 to be written, with all variables not specified not written.
248
249 Normally variables are saved to a system file under the same names they
250 have in the active file.  Use the RENAME subcommand to change these names.
251 Specify, within parentheses, a list of variable names followed by an
252 equals sign (@samp{=}) and the names that they should be renamed to.
253 Multiple parenthesized groups of variable names can be included on a
254 single RENAME subcommand.  Variables' names may be swapped using a
255 RENAME subcommand of the form @samp{/RENAME=(A B=B A)}.
256
257 Alternate syntax for the RENAME subcommand allows the parentheses to be
258 eliminated.  When this is done, only a single variable may be renamed at
259 once.  For instance, @samp{/RENAME=A=B}.  This alternate syntax is
260 deprecated.
261
262 DROP, KEEP, and RENAME are performed in left-to-right order.  They
263 each may be present any number of times.  @cmd{SAVE} never modifies
264 the active file.  DROP, KEEP, and RENAME only affect the system file
265 written to disk.
266
267 @cmd{SAVE} causes the data to be read.  It is a procedure.
268
269 @node SYSFILE INFO, XSAVE, SAVE, System and Portable Files
270 @section SYSFILE INFO
271 @vindex SYSFILE INFO
272
273 @display 
274 SYSFILE INFO FILE='filename'.
275 @end display
276
277 @cmd{SYSFILE INFO} reads the dictionary in a system file and
278 displays the information in its dictionary.
279
280 Specify a file name or file handle.  @cmd{SYSFILE INFO} reads that file as
281 a system file and displays information on its dictionary.
282
283 @cmd{SYSFILE INFO} does not affect the current active file.
284
285 @node XSAVE,  , SYSFILE INFO, System and Portable Files
286 @section XSAVE
287 @vindex XSAVE
288
289 @display
290 XSAVE
291         /FILE='filename'
292         /@{COMPRESSED,UNCOMPRESSED@}
293         /DROP=var_list
294         /KEEP=var_list
295         /RENAME=(src_names=target_names)@dots{}
296 @end display
297
298 The @cmd{XSAVE} transformation writes the active file dictionary and
299 data to a
300 system file stored on disk.
301
302 @cmd{XSAVE} is a transformation, not a procedure.  It is executed when the
303 data is read by a procedure or procedure-like command.  In all other
304 respects, @cmd{XSAVE} is identical to @cmd{SAVE}.  @xref{SAVE}, for
305 more information on syntax and usage.
306 @setfilename ignored