1 @node Portable File Format, Data File Format, Configuration, Top
2 @appendix Portable File Format
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.
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.
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::
24 * Value Label Records::
25 * Portable File Data::
28 @node Portable File Characters, Portable File Structure, Portable File Format, Portable File Format
29 @section Portable File Characters
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.
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}.)
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
48 @node Portable File Structure, Portable File Header, Portable File Characters, Portable File Format
49 @section Portable File Structure
51 Every portable file consists of the following records, in sequence:
59 Version and date info.
62 Product identification.
65 Subproduct identification (optional).
71 Case weight variable (optional).
74 Variables. Each variable record may optionally be followed by a
75 missing value record and a variable label record.
78 Value labels (optional).
84 Most records are identified by a single-character tag code. The file
85 header and version info record do not have a tag.
87 Other than these single-character codes, there are three types of fields
88 in a portable file: floating-point, integer, and string. Floating-point
89 fields have the following format:
94 Zero or more leading spaces.
97 Optional asterisk (@samp{*}), which indicates a missing value. The
98 asterisk must be followed by a single character, generally a period
99 (@samp{.}), but it appears that other characters may also be possible.
100 This completes the specification of a missing value.
103 Optional minus sign (@samp{-}) to indicate a negative number.
106 A whole number, consisting of one or more base-30 digits: @samp{0}
107 through @samp{9} plus capital letters @samp{A} through @samp{T}.
110 Optional fraction, consisting of a radix point (@samp{.}) followed by
111 one or more base-30 digits.
114 Optional exponent, consisting of a plus or minus sign (@samp{+} or
115 @samp{-}) followed by one or more base-30 digits.
118 A forward slash (@samp{/}).
121 Integer fields take a form identical to floating-point fields, but they
122 may not contain a fraction.
124 String fields take the form of a integer field having value @var{n},
125 followed by exactly @var{n} characters, which are the string content.
127 @node Portable File Header, Version and Date Info Record, Portable File Structure, Portable File Format
128 @section Portable File Header
130 Every portable file begins with a 464-byte header, consisting of a
131 200-byte collection of vanity splash strings, followed by a 256-byte
132 character set translation table, followed by an 8-byte tag string.
134 The 200-byte segment is divided into five 40-byte sections, each of
135 which represents the string @code{@var{charset} SPSS PORT FILE} in a
136 different character set encoding, where @var{charset} is the name of
137 the character set used in the file, e.g.@: @code{ASCII} or
138 @code{EBCDIC}. Each string is padded on the right with spaces in its
139 respective character set.
141 It appears that these strings exist only to inform those who might view
142 the file on a screen, and that they are not parsed by SPSS products.
143 Thus, they can be safely ignored. For those interested, the strings are
144 supposed to be in the following character sets, in the specified order:
145 EBCDIC, 7-bit ASCII, CDC 6-bit ASCII, 6-bit ASCII, Honeywell 6-bit
148 The 256-byte segment describes a mapping from the character set used in
149 the portable file to an arbitrary character set having characters at the
155 Control characters. Not important enough to describe in full here.
163 Digits @samp{0} through @samp{9}.
167 Capital letters @samp{A} through @samp{Z}.
171 Lowercase letters @samp{a} through @samp{z}.
187 Symbols @code{&[]!$*);^-/}
191 Broken vertical pipe.
195 Symbols @code{,%_>}?@code{`:} @c @code{?} is an inverted question mark
199 British pound symbol.
203 Symbols @code{@@'="}.
207 Less than or equal symbol.
239 Lower left corner box draw.
243 Upper left corner box draw.
247 Greater than or equal symbol.
251 Superscript @samp{0} through @samp{9}.
255 Lower right corner box draw.
259 Upper right corner box draw.
271 Superscript @samp{(}.
275 Superscript @samp{)}.
279 Horizontal dagger (?).
283 Symbols @samp{@{@}\}.
290 Centered dot, or bullet.
297 Symbols that are not defined in a particular character set are set to
298 the same value as symbol 64; i.e., to @samp{0}.
300 The 8-byte tag string consists of the exact characters @code{SPSSPORT}
301 in the portable file's character set, which can be used to verify that
302 the file is indeed a portable file.
304 @node Version and Date Info Record, Identification Records, Portable File Header, Portable File Format
305 @section Version and Date Info Record
307 This record does not have a tag code. It has the following structure:
311 A single character identifying the file format version. The letter A
312 represents version 0, and so on.
315 An 8-character string field giving the file creation date in the format
319 A 6-character string field giving the file creation time in the format
323 @node Identification Records, Variable Count Record, Version and Date Info Record, Portable File Format
324 @section Identification Records
326 The product identification record has tag code @samp{1}. It consists of
327 a single string field giving the name of the product that wrote the
330 The subproduct identification record has tag code @samp{3}. It
331 consists of a single string field giving additional information on the
332 product that wrote the portable file.
334 @node Variable Count Record, Case Weight Variable Record, Identification Records, Portable File Format
335 @section Variable Count Record
337 The variable count record has tag code @samp{4}. It consists of two
338 integer fields. The first contains the number of variables in the file
339 dictionary. The purpose of the second is unknown; it contains the value
340 161 in all portable files examined so far.
342 @node Case Weight Variable Record, Variable Records, Variable Count Record, Portable File Format
343 @section Case Weight Variable Record
345 The case weight variable record is optional. If it is present, it
346 indicates the variable used for weighting cases; if it is absent,
347 cases are unweighted. It has tag code @samp{6}. It consists of a
348 single string field that names the weighting variable.
350 @node Variable Records, Value Label Records, Case Weight Variable Record, Portable File Format
351 @section Variable Records
353 Each variable record represents a single variable. Variable records
354 have tag code @samp{7}. They have the following structure:
359 Width (integer). This is 0 for a numeric variable, and a number between 1
360 and 255 for a string variable.
363 Name (string). 1--8 characters long. Must be in all capitals.
366 Print format. This is a set of three integer fields:
371 Format type (@pxref{Variable Record}).
377 Number of decimal places. 1--40.
381 Write format. Same structure as the print format described above.
384 Each variable record can optionally be followed by a missing value
385 record, which has tag code @samp{8}. A missing value record has one
386 field, the missing value itself (a floating-point or string, as
387 appropriate). Up to three of these missing value records can be used.
389 There is also a record for missing value ranges, which has tag code
390 @samp{B}. It is followed by two fields representing the range, which
391 are floating-point or string as appropriate. If a missing value range
392 is present, it may be followed by a single missing value record.
394 Tag codes @samp{9} and @samp{A} represent @code{LO THRU @var{x}} and
395 @code{@var{x} THRU HI} ranges, respectively. Each is followed by a
396 single field representing @var{x}. If one of the ranges is present, it
397 may be followed by a single missing value record.
399 In addition, each variable record can optionally be followed by a
400 variable label record, which has tag code @samp{C}. A variable label
401 record has one field, the variable label itself (string).
403 @node Value Label Records, Portable File Data, Variable Records, Portable File Format
404 @section Value Label Records
406 Value label records have tag code @samp{D}. They have the following
411 Variable count (integer).
414 List of variables (strings). The variable count specifies the number in
415 the list. Variables are specified by their names. All variables must
416 be of the same type (numeric or string).
419 Label count (integer).
422 List of (value, label) tuples. The label count specifies the number of
423 tuples. Each tuple consists of a value, which is numeric or string as
424 appropriate to the variables, followed by a label (string).
427 @node Portable File Data, , Value Label Records, Portable File Format
428 @section Portable File Data
430 The data record has tag code @samp{F}. There is only one tag for all
431 the data; thus, all the data must follow the dictionary. The data is
432 terminated by the end-of-file marker @samp{Z}, which is not valid as the
433 beginning of a data element.
435 Data elements are output in the same order as the variable records
436 describing them. String variables are output as string fields, and
437 numeric variables are output as floating-point fields.