1 @node System File Format
2 @appendix System File Format
4 A system file encapsulates a set of cases and dictionary information
5 that describes how they may be interpreted. This chapter describes
6 the format of a system file.
8 System files use three data types: 8-bit characters, 32-bit integers,
9 and 64-bit floating points, called here @code{char}, @code{int32}, and
10 @code{flt64}, respectively. Data is not necessarily aligned on a word
11 or double-word boundary: the long variable name record (@pxref{Long
12 Variable Names Record}) and very long string records (@pxref{Very Long
13 String Record}) have arbitrary byte length and can therefore cause all
14 data coming after them in the file to be misaligned.
16 Integer data in system files may be big-endian or little-endian. A
17 reader may detect the endianness of a system file by examining
18 @code{layout_code} in the file header record
19 (@pxref{layout_code,,@code{layout_code}}).
21 Floating-point data in system files may nominally be in IEEE 754, IBM,
22 or VAX formats. A reader may detect the floating-point format in use
23 by examining @code{bias} in the file header record
24 (@pxref{bias,,@code{bias}}).
26 PSPP detects big-endian and little-endian integer formats in system
27 files and translates as necessary. PSPP also detects the
28 floating-point format in use, as well as the endianness of IEEE 754
29 floating-point numbers, and translates as needed. However, only IEEE
30 754 numbers with the same endianness as integer data in the same file
31 has actually been observed in system files, and it is likely that
32 other formats are obsolete or were never used.
34 The PSPP system-missing value is represented by the largest possible
35 negative number in the floating point format (@code{-DBL_MAX}). Two
36 other values are important for use as missing values: @code{HIGHEST},
37 represented by the largest possible positive number (@code{DBL_MAX}),
38 and @code{LOWEST}, represented by the second-largest negative number
39 (in IEEE 754 format, @code{0xffeffffffffffffe}).
41 System files are divided into records, each of which begins with a
42 4-byte record type, usually regarded as an @code{int32}.
44 The records must appear in the following order:
54 All pairs of value labels records and value label variables records,
58 Document record, if present.
61 Any of the following records, if present, in any order:
65 Machine integer info record.
68 Machine floating-point info record.
71 Variable display parameter record.
74 Long variable names record.
77 Miscellaneous informational records.
81 Dictionary termination record.
87 Each type of record is described separately below.
90 * File Header Record::
92 * Value Labels Records::
94 * Machine Integer Info Record::
95 * Machine Floating-Point Info Record::
96 * Variable Display Parameter Record::
97 * Long Variable Names Record::
98 * Very Long String Record::
99 * Miscellaneous Informational Records::
100 * Dictionary Termination Record::
104 @node File Header Record
105 @section File Header Record
107 The file header is always the first record in the file. It has the
114 int32 nominal_case_size;
119 char creation_date[9];
120 char creation_time[8];
126 @item char rec_type[4];
127 Record type code, set to @samp{$FL2}.
129 @item char prod_name[60];
130 Product identification string. This always begins with the characters
131 @samp{@@(#) SPSS DATA FILE}. PSPP uses the remaining characters to
132 give its version and the operating system name; for example, @samp{GNU
133 pspp 0.1.4 - sparc-sun-solaris2.5.2}. The string is truncated if it
134 would be longer than 60 characters; otherwise it is padded on the right
138 @item int32 layout_code;
139 Normally set to 2, although a few system files have been spotted in
140 the wild with a value of 3 here. PSPP use this value to determine the
141 file's integer endianness (@pxref{System File Format}).
143 @item int32 nominal_case_size;
144 Number of data elements per case. This is the number of variables,
145 except that long string variables add extra data elements (one for every
146 8 characters after the first 8). However, string variables do not
147 contribute to this value beyond the first 255 bytes. Further, system
148 files written by some systems set this value to -1. In general, it is
149 unsafe for systems reading system files to rely upon this value.
151 @item int32 compressed;
152 Set to 1 if the data in the file is compressed, 0 otherwise.
154 @item int32 weight_index;
155 If one of the variables in the data set is used as a weighting
156 variable, set to the dictionary index of that variable, plus 1
157 (@pxref{Dictionary Index}). Otherwise, set to 0.
160 Set to the number of cases in the file if it is known, or -1 otherwise.
162 In the general case it is not possible to determine the number of cases
163 that will be output to a system file at the time that the header is
164 written. The way that this is dealt with is by writing the entire
165 system file, including the header, then seeking back to the beginning of
166 the file and writing just the @code{ncases} field. For `files' in which
167 this is not valid, the seek operation fails. In this case,
168 @code{ncases} remains -1.
172 Compression bias, ordinarily set to 100. Only integers between
173 @code{1 - bias} and @code{251 - bias} can be compressed.
175 By assuming that its value is 100, PSPP uses @code{bias} to determine
176 the file's floating-point format and endianness (@pxref{System File
177 Format}). If the compression bias is not 100, PSPP cannot auto-detect
178 the floating-point format and assumes that it is IEEE 754 format with
179 the same endianness as the system file's integers, which is correct
180 for all known system files.
182 @item char creation_date[9];
183 Date of creation of the system file, in @samp{dd mmm yy}
184 format, with the month as standard English abbreviations, using an
185 initial capital letter and following with lowercase. If the date is not
186 available then this field is arbitrarily set to @samp{01 Jan 70}.
188 @item char creation_time[8];
189 Time of creation of the system file, in @samp{hh:mm:ss}
190 format and using 24-hour time. If the time is not available then this
191 field is arbitrarily set to @samp{00:00:00}.
193 @item char file_label[64];
194 File label declared by the user, if any (@pxref{FILE LABEL}).
195 Padded on the right with spaces.
197 @item char padding[3];
198 Ignored padding bytes to make the structure a multiple of 32 bits in
199 length. Set to zeros.
202 @node Variable Record
203 @section Variable Record
205 There must be one variable record for each numeric variable and each
206 string variable with width 8 bytes or less. String variables wider
207 than 8 bytes have one variable record for each 8 bytes, rounding up.
208 The first variable record for a long string specifies the variable's
209 correct dictionary information. Subsequent variable records for a
210 long string are filled with dummy information: a type of -1, no
211 variable label or missing values, print and write formats that are
212 ignored, and an empty string as name. A few system files have been
213 encountered that include a variable label on dummy variable records,
214 so readers should take care to parse dummy variable records in the
215 same way as other variable records.
217 @anchor{Dictionary Index}
218 The @dfn{dictionary index} of a variable is its offset in the set of
219 variable records, including dummy variable records for long string
220 variables. The first variable record has a dictionary index of 0, the
221 second has a dictionary index of 1, and so on.
223 The system file format does not directly support string variables
224 wider than 255 bytes. Such very long string variables are represented
225 by a number of narrower string variables. @xref{Very Long String
226 Record}, for details.
232 int32 n_missing_values;
237 /* @r{Present only if @code{has_var_label} is 1.} */
241 /* @r{Present only if @code{n_missing_values} is nonzero}. */
242 flt64 missing_values[];
246 @item int32 rec_type;
247 Record type code. Always set to 2.
250 Variable type code. Set to 0 for a numeric variable. For a short
251 string variable or the first part of a long string variable, this is set
252 to the width of the string. For the second and subsequent parts of a
253 long string variable, set to -1, and the remaining fields in the
254 structure are ignored.
256 @item int32 has_var_label;
257 If this variable has a variable label, set to 1; otherwise, set to 0.
259 @item int32 n_missing_values;
260 If the variable has no missing values, set to 0. If the variable has
261 one, two, or three discrete missing values, set to 1, 2, or 3,
262 respectively. If the variable has a range for missing variables, set to
263 -2; if the variable has a range for missing variables plus a single
264 discrete value, set to -3.
267 Print format for this variable. See below.
270 Write format for this variable. See below.
273 Variable name. The variable name must begin with a capital letter or
274 the at-sign (@samp{@@}). Subsequent characters may also be digits, octothorpes
275 (@samp{#}), dollar signs (@samp{$}), underscores (@samp{_}), or full
276 stops (@samp{.}). The variable name is padded on the right with spaces.
278 @item int32 label_len;
279 This field is present only if @code{has_var_label} is set to 1. It is
280 set to the length, in characters, of the variable label, which must be a
281 number between 0 and 120.
284 This field is present only if @code{has_var_label} is set to 1. It has
285 length @code{label_len}, rounded up to the nearest multiple of 32 bits.
286 The first @code{label_len} characters are the variable's variable label.
288 @item flt64 missing_values[];
289 This field is present only if @code{n_missing_values} is not 0. It has
290 the same number of elements as the absolute value of
291 @code{n_missing_values}. For discrete missing values, each element
292 represents one missing value. When a range is present, the first
293 element denotes the minimum value in the range, and the second element
294 denotes the maximum value in the range. When a range plus a value are
295 present, the third element denotes the additional discrete missing
296 value. HIGHEST and LOWEST are indicated as described in the chapter
300 The @code{print} and @code{write} members of sysfile_variable are output
301 formats coded into @code{int32} types. The least-significant byte
302 of the @code{int32} represents the number of decimal places, and the
303 next two bytes in order of increasing significance represent field width
304 and format type, respectively. The most-significant byte is not
305 used and should be set to zero.
307 Format types are defined as follows:
310 @multitable {Value} {@code{DATETIME}}
396 @node Value Labels Records
397 @section Value Labels Records
399 The value label record has the following format:
405 /* @r{Repeated @code{label_cnt} times}. */
412 @item int32 rec_type;
413 Record type. Always set to 3.
415 @item int32 label_count;
416 Number of value labels present in this record.
419 The remaining fields are repeated @code{count} times. Each
420 repetition specifies one value label.
424 A numeric value or a short string value padded as necessary to 8 bytes
425 in length. Its type and width cannot be determined until the
426 following value label variables record (see below) is read.
428 @item char label_len;
429 The label's length, in bytes.
432 @code{label_len} bytes of the actual label, followed by up to 7 bytes
433 of padding to bring @code{label} and @code{label_len} together to a
434 multiple of 8 bytes in length.
437 The value label record is always immediately followed by a value label
438 variables record with the following format:
447 @item int32 rec_type;
448 Record type. Always set to 4.
450 @item int32 var_count;
451 Number of variables that the associated value labels from the value
452 label record are to be applied.
455 A list of dictionary indexes of variables to which to apply the value
456 labels (@pxref{Dictionary Index}). There are @code{var_count}
459 String variables wider than 8 bytes may not have value labels.
462 @node Document Record
463 @section Document Record
465 The document record, if present, has the following format:
474 @item int32 rec_type;
475 Record type. Always set to 6.
478 Number of lines of documents present.
480 @item char lines[][80];
481 Document lines. The number of elements is defined by @code{n_lines}.
482 Lines shorter than 80 characters are padded on the right with spaces.
485 @node Machine Integer Info Record
486 @section Machine Integer Info Record
488 The integer info record, if present, has the following format:
500 int32 version_revision;
502 int32 floating_point_rep;
503 int32 compression_code;
505 int32 character_code;
509 @item int32 rec_type;
510 Record type. Always set to 7.
513 Record subtype. Always set to 3.
516 Size of each piece of data in the data part, in bytes. Always set to 4.
519 Number of pieces of data in the data part. Always set to 8.
521 @item int32 version_major;
522 PSPP major version number. In version @var{x}.@var{y}.@var{z}, this
525 @item int32 version_minor;
526 PSPP minor version number. In version @var{x}.@var{y}.@var{z}, this
529 @item int32 version_revision;
530 PSPP version revision number. In version @var{x}.@var{y}.@var{z},
533 @item int32 machine_code;
534 Machine code. PSPP always set this field to value to -1, but other
537 @item int32 floating_point_rep;
538 Floating point representation code. For IEEE 754 systems this is 1.
539 IBM 370 sets this to 2, and DEC VAX E to 3.
541 @item int32 compression_code;
542 Compression code. Always set to 1.
544 @item int32 endianness;
545 Machine endianness. 1 indicates big-endian, 2 indicates little-endian.
547 @item int32 character_code;
548 Character code. 1 indicates EBCDIC, 2 indicates 7-bit ASCII, 3
549 indicates 8-bit ASCII, 4 indicates DEC Kanji.
550 Windows code page numbers are also valid.
553 @node Machine Floating-Point Info Record
554 @section Machine Floating-Point Info Record
556 The floating-point info record, if present, has the following format:
572 @item int32 rec_type;
573 Record type. Always set to 7.
576 Record subtype. Always set to 4.
579 Size of each piece of data in the data part, in bytes. Always set to 8.
582 Number of pieces of data in the data part. Always set to 3.
585 The system missing value.
588 The value used for HIGHEST in missing values.
591 The value used for LOWEST in missing values.
594 @node Variable Display Parameter Record
595 @section Variable Display Parameter Record
597 The variable display parameter record, if present, has the following
607 /* @r{Repeated @code{count} times}. */
614 @item int32 rec_type;
615 Record type. Always set to 7.
618 Record subtype. Always set to 11.
621 The size of @code{int32}. Always set to 4.
624 The number of sets of variable display parameters (ordinarily the
625 number of variables in the dictionary), times 3.
628 The remaining members are repeated @code{count} times, in the same
629 order as the variable records. No element corresponds to variable
630 records that continue long string variables. The meanings of these
631 members are as follows:
635 The measurement type of the variable:
645 SPSS 14 sometimes writes a @code{measure} of 0. PSPP interprets this
649 The width of the display column for the variable in characters.
651 @item int32 alignment;
652 The alignment of the variable for display purposes:
664 @node Long Variable Names Record
665 @section Long Variable Names Record
667 If present, the long variable names record has the following format:
676 /* @r{Exactly @code{count} bytes of data.} */
677 char var_name_pairs[];
681 @item int32 rec_type;
682 Record type. Always set to 7.
685 Record subtype. Always set to 13.
688 The size of each element in the @code{var_name_pairs} member. Always set to 1.
691 The total number of bytes in @code{var_name_pairs}.
693 @item char var_name_pairs[];
694 A list of @var{key}--@var{value} tuples, where @var{key} is the name
695 of a variable, and @var{value} is its long variable name.
696 The @var{key} field is at most 8 bytes long and must match the
697 name of a variable which appears in the variable record (@pxref{Variable
699 The @var{value} field is at most 64 bytes long.
700 The @var{key} and @var{value} fields are separated by a @samp{=} byte.
701 Each tuple is separated by a byte whose value is 09. There is no
702 trailing separator following the last tuple.
703 The total length is @code{count} bytes.
706 @node Very Long String Record
707 @section Very Long String Record
709 Old versions of SPSS limited string variables to a width of 255 bytes.
710 For backward compatibility with these older versions, the system file
711 format represents a string longer than 255 bytes, called a @dfn{very
712 long string}, as a collection of strings no longer than 255 bytes
713 each. The strings concatenated to make a very long string are called
714 its @dfn{segments}; for consistency, variables other than very long
715 strings are considered to have a single segment.
717 A very long string with a width of @var{w} has @var{n} =
718 (@var{w} + 251) / 252 segments, that is, one segment for every
719 252 bytes of width, rounding up. It would be logical, then, for each
720 of the segments except the last to have a width of 252 and the last
721 segment to have the remainder, but this is not the case. In fact,
722 each segment except the last has a width of 255 bytes. The last
723 segment has width @var{w} - (@var{n} - 1) * 252; some versions
724 of SPSS make it slightly wider, but not wide enough to make the last
725 segment require another 8 bytes of data.
727 Data is packed tightly into segments of a very long string, 255 bytes
728 per segment. Because 255 bytes of segment data are allocated for
729 every 252 bytes of the very long string's width (approximately), some
730 unused space is left over at the end of the allocated segments. Data
731 in unused space is ignored.
733 Example: Consider a very long string of width 20,000. Such a very
734 long string has 20,000 / 252 = 80 (rounding up) segments. The first
735 79 segments have width 255; the last segment has width 20,000 - 79 *
736 252 = 92 or slightly wider (up to 96 bytes, the next multiple of 8).
737 The very long string's data is actually stored in the 19,890 bytes in
738 the first 78 segments, plus the first 110 bytes of the 79th segment
739 (19,890 + 110 = 20,000). The remaining 145 bytes of the 79th segment
740 and all 92 bytes of the 80th segment are unused.
742 The very long string record explains how to stitch together segments
743 to obtain very long string data. For each of the very long string
744 variables in the dictionary, it specifies the name of its first
745 segment's variable and the very long string variable's actual width.
746 The remaining segments immediately follow the named variable in the
747 system file's dictionary.
749 The very long string record, which is present only if the system file
750 contains very long string variables, has the following format:
759 /* @r{Exactly @code{count} bytes of data.} */
760 char string_lengths[];
764 @item int32 rec_type;
765 Record type. Always set to 7.
768 Record subtype. Always set to 14.
771 The size of each element in the @code{string_lengths} member. Always set to 1.
774 The total number of bytes in @code{string_lengths}.
776 @item char string_lengths[];
777 A list of @var{key}--@var{value} tuples, where @var{key} is the name
778 of a variable, and @var{value} is its length.
779 The @var{key} field is at most 8 bytes long and must match the
780 name of a variable which appears in the variable record (@pxref{Variable
782 The @var{value} field is exactly 5 bytes long. It is a zero-padded,
783 ASCII-encoded string that is the length of the variable.
784 The @var{key} and @var{value} fields are separated by a @samp{=} byte.
785 Tuples are delimited by a two-byte sequence @{00, 09@}.
786 After the last tuple, there may be a single byte 00, or @{00, 09@}.
787 The total length is @code{count} bytes.
790 @node Miscellaneous Informational Records
791 @section Miscellaneous Informational Records
793 Some specific types of miscellaneous informational records are
794 documented here, but others are known to exist. PSPP ignores unknown
795 miscellaneous informational records when reading system files.
804 /* @r{Exactly @code{size * count} bytes of data.} */
809 @item int32 rec_type;
810 Record type. Always set to 7.
813 Record subtype. May take any value. According to Aapi
814 H@"am@"al@"ainen, value 5 indicates a set of grouped variables and 6
815 indicates date info (probably related to USE).
818 Size of each piece of data in the data part. Should have the value 1,
819 4, or 8, for @code{char}, @code{int32}, and @code{flt64} format data,
823 Number of pieces of data in the data part.
826 Arbitrary data. There must be @code{size} times @code{count} bytes of
830 @node Dictionary Termination Record
831 @section Dictionary Termination Record
833 The dictionary termination record separates all other records from the
842 @item int32 rec_type;
843 Record type. Always set to 999.
846 Ignored padding. Should be set to 0.
852 Data records must follow all other records in the system file. There must
853 be at least one data record in every system file.
855 The format of data records varies depending on whether the data is
856 compressed. Regardless, the data is arranged in a series of 8-byte
859 When data is not compressed,
860 each element corresponds to
861 the variable declared in the respective variable record (@pxref{Variable
862 Record}). Numeric values are given in @code{flt64} format; string
863 values are literal characters string, padded on the right when
864 necessary to fill out 8-byte units.
866 Compressed data is arranged in the following manner: the first 8 bytes
867 in the data section is divided into a series of 1-byte command
868 codes. These codes have meanings as described below:
872 Ignored. If the program writing the system file accumulates compressed
873 data in blocks of fixed length, 0 bytes can be used to pad out extra
874 bytes remaining at the end of a fixed-size block.
878 value @var{code} - @var{bias}, where
879 @var{code} is the value of the compression code and @var{bias} is the
880 variable @code{bias} from the file header. For example,
881 code 105 with bias 100.0 (the normal value) indicates a numeric variable
885 End of file. This code may or may not appear at the end of the data
886 stream. PSPP always outputs this code but its use is not required.
889 A numeric or string value that is not
890 compressible. The value is stored in the 8 bytes following the
891 current block of command bytes. If this value appears twice in a block
892 of command bytes, then it indicates the second group of 8 bytes following the
893 command bytes, and so on.
896 An 8-byte string value that is all spaces.
899 The system-missing value.
902 When the end of the an 8-byte group of command bytes is reached, any
903 blocks of non-compressible values indicated by code 253 are skipped,
904 and the next element of command bytes is read and interpreted, until
905 the end of the file or a code with value 252 is reached.