VARIABLE ROLE: Document the format and add a test.
[pspp] / doc / dev / portable-file-format.texi
1 @node Portable File Format
2 @appendix Portable File Format
3
4 These days, most computers use the same internal data formats for
5 integer and floating-point data, if one ignores little differences like
6 big- versus little-endian byte ordering.  However, occasionally it is
7 necessary to exchange data between systems with incompatible data
8 formats.  This is what portable files are designed to do.
9
10 @strong{Please note:} This information is gleaned from examination of
11 ASCII-formatted portable files only, so some of it may be incorrect
12 for portable files formatted in EBCDIC or other character sets.
13
14 @menu
15 * Portable File Characters::
16 * Portable File Structure::
17 * Portable File Header::
18 * Version and Date Info Record::
19 * Identification Records::
20 * Variable Count Record::
21 * Precision Record::
22 * Case Weight Variable Record::
23 * Variable Records::
24 * Value Label Records::
25 * Portable File Document Record::
26 * Portable File Data::
27 @end menu
28
29 @node Portable File Characters
30 @section Portable File Characters
31
32 Portable files are arranged as a series of lines of 80
33 characters each.  Each line is terminated by a carriage-return,
34 line-feed sequence (``new-lines'').  New-lines are only used to avoid
35 line length limits imposed by some OSes; they are not meaningful.
36
37 Most lines in portable files are exactly 80 characters long.  The only
38 exception is a line that ends in one or more spaces, in which the
39 spaces may optionally be omitted.  Thus, a portable file reader must
40 act as though a line shorter than 80 characters is padded to that
41 length with spaces.
42
43 The file must be terminated with a @samp{Z} character.  In addition, if
44 the final line in the file does not have exactly 80 characters, then it
45 is padded on the right with @samp{Z} characters.  (The file contents may
46 be in any character set; the file contains a description of its own
47 character set, as explained in the next section.  Therefore, the
48 @samp{Z} character is not necessarily an ASCII @samp{Z}.)
49
50 For the rest of the description of the portable file format, new-lines
51 and the trailing @samp{Z}s will be ignored, as if they did not exist,
52 because they are not an important part of understanding the file
53 contents.
54
55 @node Portable File Structure
56 @section Portable File Structure
57
58 Every portable file consists of the following records, in sequence:
59
60 @itemize @bullet
61
62 @item
63 File header.
64
65 @item
66 Version and date info.
67
68 @item
69 Product identification.
70
71 @item
72 Author identification (optional).
73
74 @item
75 Subproduct identification (optional).
76
77 @item
78 Variable count.
79
80 @item
81 Case weight variable (optional).
82
83 @item
84 Variables.  Each variable record may optionally be followed by a
85 missing value record and a variable label record.
86
87 @item
88 Value labels (optional).
89
90 @item
91 Documents (optional).
92
93 @item
94 Data.
95 @end itemize
96
97 Most records are identified by a single-character tag code.  The file
98 header and version info record do not have a tag.
99
100 Other than these single-character codes, there are three types of fields
101 in a portable file: floating-point, integer, and string.  Floating-point
102 fields have the following format:
103
104 @itemize @bullet
105
106 @item
107 Zero or more leading spaces.
108
109 @item
110 Optional asterisk (@samp{*}), which indicates a missing value.  The
111 asterisk must be followed by a single character, generally a period
112 (@samp{.}), but it appears that other characters may also be possible.
113 This completes the specification of a missing value.
114
115 @item
116 Optional minus sign (@samp{-}) to indicate a negative number.
117
118 @item
119 A whole number, consisting of one or more base-30 digits: @samp{0}
120 through @samp{9} plus capital letters @samp{A} through @samp{T}.
121
122 @item
123 Optional fraction, consisting of a radix point (@samp{.}) followed by
124 one or more base-30 digits.
125
126 @item
127 Optional exponent, consisting of a plus or minus sign (@samp{+} or
128 @samp{-}) followed by one or more base-30 digits.
129
130 @item
131 A forward slash (@samp{/}).
132 @end itemize
133
134 Integer fields take a form identical to floating-point fields, but they
135 may not contain a fraction.
136
137 String fields take the form of a integer field having value @var{n},
138 followed by exactly @var{n} characters, which are the string content.
139
140 @node Portable File Header
141 @section Portable File Header
142
143 Every portable file begins with a 464-byte header, consisting of a
144 200-byte collection of vanity splash strings, followed by a 256-byte
145 character set translation table, followed by an 8-byte tag string.
146
147 The 200-byte segment is divided into five 40-byte sections, each of
148 which represents the string @code{@var{charset} SPSS PORT FILE} in a
149 different character set encoding, where @var{charset} is the name of
150 the character set used in the file, e.g.@: @code{ASCII} or
151 @code{EBCDIC}.  Each string is padded on the right with spaces in its
152 respective character set.
153
154 It appears that these strings exist only to inform those who might view
155 the file on a screen, and that they are not parsed by SPSS products.
156 Thus, they can be safely ignored.  For those interested, the strings are
157 supposed to be in the following character sets, in the specified order:
158 EBCDIC, 7-bit ASCII, CDC 6-bit ASCII, 6-bit ASCII, Honeywell 6-bit
159 ASCII.
160
161 The 256-byte segment describes a mapping from the character set used in
162 the portable file to an arbitrary character set having characters at the
163 following positions:
164
165 @table @asis
166 @item 0--60
167
168 Control characters.  Not important enough to describe in full here.
169
170 @item 61--63
171
172 Reserved.
173
174 @item 64--73
175
176 Digits @samp{0} through @samp{9}.
177
178 @item 74--99
179
180 Capital letters @samp{A} through @samp{Z}.
181
182 @item 100--125
183
184 Lowercase letters @samp{a} through @samp{z}.
185
186 @item 126
187
188 Space.
189
190 @item 127--130
191
192 Symbols @code{.<(+}
193
194 @item 131
195
196 Solid vertical pipe.
197
198 @item 132--142
199
200 Symbols @code{&[]!$*);^-/}
201
202 @item 143
203
204 Broken vertical pipe.
205
206 @item 144--150
207
208 Symbols @code{,%_>}?@code{`:}   @c @code{?} is an inverted question mark
209
210 @item 151
211
212 British pound symbol.
213
214 @item 152--155
215
216 Symbols @code{@@'="}.
217
218 @item 156
219
220 Less than or equal symbol.
221
222 @item 157
223
224 Empty box.
225
226 @item 158
227
228 Plus or minus.
229
230 @item 159
231
232 Filled box.
233
234 @item 160
235
236 Degree symbol.
237
238 @item 161
239
240 Dagger.
241
242 @item 162
243
244 Symbol @samp{~}.
245
246 @item 163
247
248 En dash.
249
250 @item 164
251
252 Lower left corner box draw.
253
254 @item 165
255
256 Upper left corner box draw.
257
258 @item 166
259
260 Greater than or equal symbol.
261
262 @item 167--176
263
264 Superscript @samp{0} through @samp{9}.
265
266 @item 177
267
268 Lower right corner box draw.
269
270 @item 178
271
272 Upper right corner box draw.
273
274 @item 179
275
276 Not equal symbol.
277
278 @item 180
279
280 Em dash.
281
282 @item 181
283
284 Superscript @samp{(}.
285
286 @item 182
287
288 Superscript @samp{)}.
289
290 @item 183
291
292 Horizontal dagger (?).
293
294 @item 184--186
295
296 Symbols @samp{@{@}\}.
297 @item 187
298
299 Cents symbol.
300
301 @item 188
302
303 Centered dot, or bullet.
304
305 @item 189--255
306
307 Reserved.
308 @end table
309
310 Symbols that are not defined in a particular character set are set to
311 the same value as symbol 64; i.e., to @samp{0}.
312
313 The 8-byte tag string consists of the exact characters @code{SPSSPORT}
314 in the portable file's character set, which can be used to verify that
315 the file is indeed a portable file.
316
317 @node Version and Date Info Record
318 @section Version and Date Info Record
319
320 This record does not have a tag code.  It has the following structure:
321
322 @itemize @bullet
323 @item
324 A single character identifying the file format version.  The letter A
325 represents version 0, and so on.
326
327 @item
328 An 8-character string field giving the file creation date in the format
329 YYYYMMDD.
330
331 @item
332 A 6-character string field giving the file creation time in the format
333 HHMMSS.
334 @end itemize
335
336 @node Identification Records
337 @section Identification Records
338
339 The product identification record has tag code @samp{1}.  It consists of
340 a single string field giving the name of the product that wrote the
341 portable file.
342
343 The author identification record has tag code @samp{2}.  It is
344 optional.  If present, it consists of a single string field giving the
345 name of the person who caused the portable file to be written.
346
347 The subproduct identification record has tag code @samp{3}.  It is
348 optional.  If present, it consists of a single string field giving
349 additional information on the product that wrote the portable file.
350
351 @node Variable Count Record
352 @section Variable Count Record
353
354 The variable count record has tag code @samp{4}.  It consists of a
355 single integer field giving the number of variables in the file
356 dictionary.
357
358 @node Precision Record
359 @section Precision Record
360
361 The precision record has tag code @samp{5}.  It consists of a single
362 integer field specifying the maximum number of base-30 digits used in
363 data in the file.
364
365 @node Case Weight Variable Record
366 @section Case Weight Variable Record
367
368 The case weight variable record is optional.  If it is present, it
369 indicates the variable used for weighting cases; if it is absent,
370 cases are unweighted.  It has tag code @samp{6}.  It consists of a
371 single string field that names the weighting variable.
372
373 @node Variable Records
374 @section Variable Records
375
376 Each variable record represents a single variable.  Variable records
377 have tag code @samp{7}.  They have the following structure:
378
379 @itemize @bullet
380
381 @item
382 Width (integer).  This is 0 for a numeric variable, and a number between 1
383 and 255 for a string variable.
384
385 @item
386 Name (string).  1--8 characters long.  Must be in all capitals.
387
388 A few portable files that contain duplicate variable names have been
389 spotted in the wild.  PSPP handles these by renaming the duplicates
390 with numeric extensions: @code{@var{var}_1}, @code{@var{var}_2}, and
391 so on.
392
393 @item
394 Print format.  This is a set of three integer fields:
395
396 @itemize @minus
397
398 @item
399 Format type (@pxref{Variable Record}).
400
401 @item
402 Format width.  1--40.
403
404 @item
405 Number of decimal places.  1--40.
406 @end itemize
407
408 A few portable files with invalid format types or formats that are not
409 of the appropriate width for their variables have been spotted in the
410 wild.  PSPP assigns a default F or A format to a variable with an
411 invalid format.
412
413 @item
414 Write format.  Same structure as the print format described above.
415 @end itemize
416
417 Each variable record can optionally be followed by a missing value
418 record, which has tag code @samp{8}.  A missing value record has one
419 field, the missing value itself (a floating-point or string, as
420 appropriate).  Up to three of these missing value records can be used.
421
422 There is also a record for missing value ranges, which has tag code
423 @samp{B}.  It is followed by two fields representing the range, which
424 are floating-point or string as appropriate.  If a missing value range
425 is present, it may be followed by a single missing value record.
426
427 Tag codes @samp{9} and @samp{A} represent @code{LO THRU @var{x}} and
428 @code{@var{x} THRU HI} ranges, respectively.  Each is followed by a
429 single field representing @var{x}.  If one of the ranges is present, it
430 may be followed by a single missing value record.
431
432 In addition, each variable record can optionally be followed by a
433 variable label record, which has tag code @samp{C}.  A variable label
434 record has one field, the variable label itself (string).
435
436 @node Value Label Records
437 @section Value Label Records
438
439 Value label records have tag code @samp{D}.  They have the following
440 format:
441
442 @itemize @bullet
443 @item
444 Variable count (integer).
445
446 @item
447 List of variables (strings).  The variable count specifies the number in
448 the list.  Variables are specified by their names.  All variables must
449 be of the same type (numeric or string), but string variables do not
450 necessarily have the same width.
451
452 @item
453 Label count (integer).
454
455 @item
456 List of (value, label) tuples.  The label count specifies the number of
457 tuples.  Each tuple consists of a value, which is numeric or string as
458 appropriate to the variables, followed by a label (string).
459 @end itemize
460
461 A few portable files that specify duplicate value labels, that is, two
462 different labels for a single value of a single variable, have been
463 spotted in the wild.  PSPP uses the last value label specified in
464 these cases.
465
466 @node Portable File Document Record
467 @section Document Record
468
469 One document record may optionally follow the value label record.  The
470 document record consists of tag code @samp{E}, following by the number
471 of document lines as an integer, followed by that number of strings,
472 each of which represents one document line.  Document lines must be 80
473 bytes long or shorter.
474
475 @node Portable File Data
476 @section Portable File Data
477
478 The data record has tag code @samp{F}.  There is only one tag for all
479 the data; thus, all the data must follow the dictionary.  The data is
480 terminated by the end-of-file marker @samp{Z}, which is not valid as the
481 beginning of a data element.
482
483 Data elements are output in the same order as the variable records
484 describing them.  String variables are output as string fields, and
485 numeric variables are output as floating-point fields.
486 @setfilename ignored