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