1 @node Data File Format, q2c Input Format, Portable File Format, Top
2 @appendix Data File Format
4 PSPP necessarily uses the same format for system files as do the
5 products with which it is compatible. This chapter is a description of
8 There are three data types used in system files: 32-bit integers, 64-bit
9 floating points, and 1-byte characters. In this document these will
10 simply be referred to as @code{int32}, @code{flt64}, and @code{char},
11 the names that are used in the PSPP source code. Every field of type
12 @code{int32} or @code{flt64} is aligned on a 32-bit boundary.
14 The endianness of data in PSPP system files is not specified. System
15 files output on a computer of a particular endianness will have the
16 endianness of that computer. However, PSPP can read files of either
17 endianness, regardless of its host computer's endianness. PSPP
18 translates endianness for both integer and floating point numbers.
20 Floating point formats are also not specified. PSPP does not
21 translate between floating point formats. This is unlikely to be a
22 problem as all modern computer architectures use IEEE 754 format for
23 floating point representation.
25 The PSPP system-missing value is represented by the largest possible
26 negative number in the floating point format; in C, this is most likely
27 @code{-DBL_MAX}. There are two other important values used in missing
28 values: @code{HIGHEST} and @code{LOWEST}. These are represented by the
29 largest possible positive number (probably @code{DBL_MAX}) and the
30 second-largest negative number. The latter must be determined in a
31 system-dependent manner; in IEEE 754 format it is represented by value
32 @code{0xffeffffffffffffe}.
34 System files are divided into records. Each record begins with an
35 @code{int32} giving a numeric record type. Individual record types are
39 * File Header Record::
41 * Value Label Record::
42 * Value Label Variable Record::
44 * Machine int32 Info Record::
45 * Machine flt64 Info Record::
46 * Auxilliary Variable Parameter Record::
47 * Long Variable Names Record::
48 * Miscellaneous Informational Records::
49 * Dictionary Termination Record::
53 @node File Header Record, Variable Record, Data File Format, Data File Format
54 @section File Header Record
56 The file header is always the first record in the file.
69 char creation_date[9];
70 char creation_time[8];
77 @item char rec_type[4];
78 Record type code. Always set to @samp{$FL2}. This is the only record
79 for which the record type is not of type @code{int32}.
81 @item char prod_name[60];
82 Product identification string. This always begins with the characters
83 @samp{@@(#) SPSS DATA FILE}. PSPP uses the remaining characters to
84 give its version and the operating system name; for example, @samp{GNU
85 pspp 0.1.4 - sparc-sun-solaris2.5.2}. The string is truncated if it
86 would be longer than 60 characters; otherwise it is padded on the right
89 @item int32 layout_code;
90 Always set to 2. PSPP reads this value to determine the
93 @item int32 case_size;
94 Number of data elements per case. This is the number of variables,
95 except that long string variables add extra data elements (one for every
96 8 characters after the first 8).
98 @item int32 compressed;
99 Set to 1 if the data in the file is compressed, 0 otherwise.
101 @item int32 weight_index;
102 If one of the variables in the data set is used as a weighting variable,
103 set to the index of that variable. Otherwise, set to 0.
106 Set to the number of cases in the file if it is known, or -1 otherwise.
108 In the general case it is not possible to determine the number of cases
109 that will be output to a system file at the time that the header is
110 written. The way that this is dealt with is by writing the entire
111 system file, including the header, then seeking back to the beginning of
112 the file and writing just the @code{ncases} field. For `files' in which
113 this is not valid, the seek operation fails. In this case,
114 @code{ncases} remains -1.
117 Compression bias. Always set to 100. The significance of this value is
118 that only numbers between @code{(1 - bias)} and @code{(251 - bias)} can
121 @item char creation_date[9];
122 Set to the date of creation of the system file, in @samp{dd mmm yy}
123 format, with the month as standard English abbreviations, using an
124 initial capital letter and following with lowercase. If the date is not
125 available then this field is arbitrarily set to @samp{01 Jan 70}.
127 @item char creation_time[8];
128 Set to the time of creation of the system file, in @samp{hh:mm:ss}
129 format and using 24-hour time. If the time is not available then this
130 field is arbitrarily set to @samp{00:00:00}.
132 @item char file_label[64];
133 Set the the file label declared by the user, if any. Padded on the
136 @item char padding[3];
137 Ignored padding bytes to make the structure a multiple of 32 bits in
138 length. Set to zeros.
141 @node Variable Record, Value Label Record, File Header Record, Data File Format
142 @section Variable Record
144 Immediately following the header must come the variable records. There
145 must be one variable record for every variable and every 8 characters in
146 a long string beyond the first 8; i.e., there must be exactly as many
147 variable records as the value specified for @code{case_size} in the file
151 struct sysfile_variable
156 int32 n_missing_values;
161 /* The following two fields are present
162 only if has_var_label is 1. */
164 char label[/* variable length */];
166 /* The following field is present only
167 if n_missing_values is not 0. */
168 flt64 missing_values[/* variable length*/];
173 @item int32 rec_type;
174 Record type code. Always set to 2.
177 Variable type code. Set to 0 for a numeric variable. For a short
178 string variable or the first part of a long string variable, this is set
179 to the width of the string. For the second and subsequent parts of a
180 long string variable, set to -1, and the remaining fields in the
181 structure are ignored.
183 @item int32 has_var_label;
184 If this variable has a variable label, set to 1; otherwise, set to 0.
186 @item int32 n_missing_values;
187 If the variable has no missing values, set to 0. If the variable has
188 one, two, or three discrete missing values, set to 1, 2, or 3,
189 respectively. If the variable has a range for missing variables, set to
190 -2; if the variable has a range for missing variables plus a single
191 discrete value, set to -3.
194 Print format for this variable. See below.
197 Write format for this variable. See below.
200 Variable name. The variable name must begin with a capital letter or
201 the at-sign (@samp{@@}). Subsequent characters may also be octothorpes
202 (@samp{#}), dollar signs (@samp{$}), underscores (@samp{_}), or full
203 stops (@samp{.}). The variable name is padded on the right with spaces.
205 @item int32 label_len;
206 This field is present only if @code{has_var_label} is set to 1. It is
207 set to the length, in characters, of the variable label, which must be a
208 number between 0 and 120.
210 @item char label[/* variable length */];
211 This field is present only if @code{has_var_label} is set to 1. It has
212 length @code{label_len}, rounded up to the nearest multiple of 32 bits.
213 The first @code{label_len} characters are the variable's variable label.
215 @item flt64 missing_values[/* variable length */];
216 This field is present only if @code{n_missing_values} is not 0. It has
217 the same number of elements as the absolute value of
218 @code{n_missing_values}. For discrete missing values, each element
219 represents one missing value. When a range is present, the first
220 element denotes the minimum value in the range, and the second element
221 denotes the maximum value in the range. When a range plus a value are
222 present, the third element denotes the additional discrete missing
223 value. HIGHEST and LOWEST are indicated as described in the chapter
227 The @code{print} and @code{write} members of sysfile_variable are output
228 formats coded into @code{int32} types. The LSB (least-significant byte)
229 of the @code{int32} represents the number of decimal places, and the
230 next two bytes in order of increasing significance represent field width
231 and format type, respectively. The MSB (most-significant byte) is not
232 used and should be set to zero.
234 Format types are defined as follows:
318 @node Value Label Record, Value Label Variable Record, Variable Record, Data File Format
319 @section Value Label Record
321 Value label records must follow the variable records and must precede
322 the header termination record. Other than this, they may appear
323 anywhere in the system file. Every value label record must be
324 immediately followed by a label variable record, described below.
326 Value label records begin with @code{rec_type}, an @code{int32} value
327 set to the record type of 3. This is followed by @code{count}, an
328 @code{int32} value set to the number of value labels present in this
331 These two fields are followed by a series of @code{count} tuples. Each
332 tuple is divided into two fields, the value and the label. The first of
333 these, the value, is composed of a 64-bit value, which is either a
334 @code{flt64} value or up to 8 characters (padded on the right to 8
335 bytes) denoting a short string value. Whether the value is a
336 @code{flt64} or a character string is not defined inside the value label
339 The second field in the tuple, the label, has variable length. The
340 first @code{char} is a count of the number of characters in the value
341 label. The remainder of the field is the label itself. The field is
342 padded on the right to a multiple of 64 bits in length.
344 @node Value Label Variable Record, Document Record, Value Label Record, Data File Format
345 @section Value Label Variable Record
347 Every value label variable record must be immediately preceded by a
348 value label record, described above.
351 struct sysfile_value_label_variable
355 int32 vars[/* variable length */];
360 @item int32 rec_type;
361 Record type. Always set to 4.
364 Number of variables that the associated value labels from the value
365 label record are to be applied.
367 @item int32 vars[/* variable length];
368 A list of variables to which to apply the value labels. There are
369 @code{count} elements.
372 @node Document Record, Machine int32 Info Record, Value Label Variable Record, Data File Format
373 @section Document Record
375 There must be no more than one document record per system file.
376 Document records must follow the variable records and precede the
377 dictionary termination record.
380 struct sysfile_document
384 char lines[/* variable length */][80];
389 @item int32 rec_type;
390 Record type. Always set to 6.
393 Number of lines of documents present.
395 @item char lines[/* variable length */][80];
396 Document lines. The number of elements is defined by @code{n_lines}.
397 Lines shorter than 80 characters are padded on the right with spaces.
400 @node Machine int32 Info Record, Machine flt64 Info Record, Document Record, Data File Format
401 @section Machine @code{int32} Info Record
403 There must be no more than one machine @code{int32} info record per
404 system file. Machine @code{int32} info records must follow the variable
405 records and precede the dictionary termination record.
408 struct sysfile_machine_int32_info
419 int32 version_revision;
421 int32 floating_point_rep;
422 int32 compression_code;
424 int32 character_code;
429 @item int32 rec_type;
430 Record type. Always set to 7.
433 Record subtype. Always set to 3.
436 Size of each piece of data in the data part, in bytes. Always set to 4.
439 Number of pieces of data in the data part. Always set to 8.
441 @item int32 version_major;
442 PSPP major version number. In version @var{x}.@var{y}.@var{z}, this
445 @item int32 version_minor;
446 PSPP minor version number. In version @var{x}.@var{y}.@var{z}, this
449 @item int32 version_revision;
450 PSPP version revision number. In version @var{x}.@var{y}.@var{z},
453 @item int32 machine_code;
454 Machine code. PSPP always set this field to value to -1, but other
457 @item int32 floating_point_rep;
458 Floating point representation code. For IEEE 754 systems this is 1.
459 IBM 370 sets this to 2, and DEC VAX E to 3.
461 @item int32 compression_code;
462 Compression code. Always set to 1.
464 @item int32 endianness;
465 Machine endianness. 1 indicates big-endian, 2 indicates little-endian.
467 @item int32 character_code;
468 Character code. 1 indicates EBCDIC, 2 indicates 7-bit ASCII, 3
469 indicates 8-bit ASCII, 4 indicates DEC Kanji.
472 @node Machine flt64 Info Record, Auxilliary Variable Parameter Record, Machine int32 Info Record, Data File Format
473 @section Machine @code{flt64} Info Record
475 There must be no more than one machine @code{flt64} info record per
476 system file. Machine @code{flt64} info records must follow the variable
477 records and precede the dictionary termination record.
480 struct sysfile_machine_flt64_info
496 @item int32 rec_type;
497 Record type. Always set to 7.
500 Record subtype. Always set to 4.
503 Size of each piece of data in the data part, in bytes. Always set to 4.
506 Number of pieces of data in the data part. Always set to 3.
509 The system missing value.
512 The value used for HIGHEST in missing values.
515 The value used for LOWEST in missing values.
518 @node Auxilliary Variable Parameter Record, Long Variable Names Record, Machine flt64 Info Record, Data File Format
519 @section Auxilliary Variable Parameter Record
521 There must be no more than one auxilliary variable parameter record per
522 system file. This record must follow the variable
523 records and precede the dictionary termination record.
526 struct sysfile_aux_var_parameter
535 struct aux_params aux_params[/* variable length */];
540 @item int32 rec_type;
541 Record type. Always set to 7.
544 Record subtype. Always set to 11.
547 The size @code{int32}. Always set to 4.
550 The total number of bytes in @code{aux_params} divided by 3.
552 @item struct aux_params aux_params[];
553 An array of @code{struct aux_params}. The order of the elements corresponds
554 to the order of the variables in the Variable Records. The @code{struct aux_params} type is defined as follows:
567 The measurement type of the variable:
578 The width of the display column for the variable in characters.
580 @item int32 alignment
581 The alignment of the variable for display purposes:
600 @node Long Variable Names Record, Miscellaneous Informational Records, Auxilliary Variable Parameter Record, Data File Format
601 @section Long Variable Names Record
603 There must be no more than one long variable names record per
604 system file. This record must follow the variable
605 records and precede the dictionary termination record.
608 struct sysfile_long_variable_names
617 char var_name_pairs[/* variable length */];
622 @item int32 rec_type;
623 Record type. Always set to 7.
626 Record subtype. Always set to 13.
629 The size of each element in the @code{var_name_pairs} member. Always set to 1.
632 The total number of bytes in @code{var_name_pairs}.
634 @item char var_name_pairs[/* variable length];
635 A list of @var{key}--@var{value} tuples, where @var{key} is the name
636 of a variable, and @var{value} is its long variable name.
637 The @var{key} field is at most 8 bytes long and must match the
638 name of a variable which appears in the variable record @xref{Variable Record}.
639 The @var{value} field is at most 64 bytes long.
640 The @var{key} and @var{value} fields are separated by a @samp{=} byte.
641 Each tuple is separated by a byte whose value is 09. There is no
642 trailing separator following the last tuple.
643 The total length is @code{count} bytes.
647 @node Miscellaneous Informational Records, Dictionary Termination Record, Long Variable Names Record, Data File Format
648 @section Miscellaneous Informational Records
650 Miscellaneous informational records must follow the variable records and
651 precede the dictionary termination record.
653 Miscellaneous informational records are ignored by PSPP when reading
654 system files. They are not written by PSPP when writing system files.
657 struct sysfile_misc_info
666 char data[/* variable length */];
671 @item int32 rec_type;
672 Record type. Always set to 7.
675 Record subtype. May take any value. According to Aapi
676 H@"am@"al@"ainen, value 5 indicates a set of grouped variables and 6
677 indicates date info (probably related to USE).
680 Size of each piece of data in the data part. Should have the value 4 or
681 8, for @code{int32} and @code{flt64}, respectively.
684 Number of pieces of data in the data part.
686 @item char data[/* variable length */];
687 Arbitrary data. There must be @code{size} times @code{count} bytes of
691 @node Dictionary Termination Record, Data Record, Miscellaneous Informational Records, Data File Format
692 @section Dictionary Termination Record
694 The dictionary termination record must follow all other records, except
695 for the actual cases, which it must precede. There must be exactly one
696 dictionary termination record in every system file.
699 struct sysfile_dict_term
707 @item int32 rec_type;
708 Record type. Always set to 999.
711 Ignored padding. Should be set to 0.
714 @node Data Record, , Dictionary Termination Record, Data File Format
717 Data records must follow all other records in the data file. There must
718 be at least one data record in every system file.
720 The format of data records varies depending on whether the data is
721 compressed. Regardless, the data is arranged in a series of 8-byte
724 When data is not compressed, Every case is composed of @code{case_size}
725 of these 8-byte elements, where @code{case_size} comes from the file
726 header record (@pxref{File Header Record}). Each element corresponds to
727 the variable declared in the respective variable record (@pxref{Variable
728 Record}). Numeric values are given in @code{flt64} format; string
729 values are literal characters string, padded on the right when
732 Compressed data is arranged in the following manner: the first 8-byte
733 element in the data section is divided into a series of 1-byte command
734 codes. These codes have meanings as described below:
738 Ignored. If the program writing the system file accumulates compressed
739 data in blocks of fixed length, 0 bytes can be used to pad out extra
740 bytes remaining at the end of a fixed-size block.
743 These values indicate that the corresponding numeric variable has the
744 value @code{(@var{code} - @var{bias})} for the case being read, where
745 @var{code} is the value of the compression code and @var{bias} is the
746 variable @code{compression_bias} from the file header. For example,
747 code 105 with bias 100.0 (the normal value) indicates a numeric variable
751 End of file. This code may or may not appear at the end of the data
752 stream. PSPP always outputs this code but its use is not required.
755 This value indicates that the numeric or string value is not
756 compressible. The value is stored in the 8-byte element following the
757 current block of command bytes. If this value appears twice in a block
758 of command bytes, then it indicates the second element following the
759 command bytes, and so on.
762 Used to indicate a string value that is all spaces.
765 Used to indicate the system-missing value.
768 When the end of the first 8-byte element of command bytes is reached,
769 any blocks of non-compressible values are skipped, and the next element
770 of command bytes is read and interpreted, until the end of the file is