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