gtk.h wrapper: Added *_set_realized and set_mapped
[pspp] / doc / dev / system-file-format.texi
1 @node System File Format
2 @appendix System File Format
3
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.
7
8 System files use four data types: 8-bit characters, 32-bit integers,
9 64-bit integers, 
10 and 64-bit floating points, called here @code{char}, @code{int32},
11 @code{int64}, and
12 @code{flt64}, respectively.  Data is not necessarily aligned on a word
13 or double-word boundary: the long variable name record (@pxref{Long
14 Variable Names Record}) and very long string records (@pxref{Very Long
15 String Record}) have arbitrary byte length and can therefore cause all
16 data coming after them in the file to be misaligned.
17
18 Integer data in system files may be big-endian or little-endian.  A
19 reader may detect the endianness of a system file by examining
20 @code{layout_code} in the file header record
21 (@pxref{layout_code,,@code{layout_code}}).
22
23 Floating-point data in system files may nominally be in IEEE 754, IBM,
24 or VAX formats.  A reader may detect the floating-point format in use
25 by examining @code{bias} in the file header record
26 (@pxref{bias,,@code{bias}}).
27
28 PSPP detects big-endian and little-endian integer formats in system
29 files and translates as necessary.  PSPP also detects the
30 floating-point format in use, as well as the endianness of IEEE 754
31 floating-point numbers, and translates as needed.  However, only IEEE
32 754 numbers with the same endianness as integer data in the same file
33 has actually been observed in system files, and it is likely that
34 other formats are obsolete or were never used.
35
36 The PSPP system-missing value is represented by the largest possible
37 negative number in the floating point format (@code{-DBL_MAX}).  Two
38 other values are important for use as missing values: @code{HIGHEST},
39 represented by the largest possible positive number (@code{DBL_MAX}),
40 and @code{LOWEST}, represented by the second-largest negative number
41 (in IEEE 754 format, @code{0xffeffffffffffffe}).
42
43 System files are divided into records, each of which begins with a
44 4-byte record type, usually regarded as an @code{int32}.
45
46 The records must appear in the following order:
47
48 @itemize @bullet
49 @item
50 File header record.
51
52 @item
53 Variable records.
54
55 @item
56 All pairs of value labels records and value label variables records,
57 if present.
58
59 @item
60 Document record, if present.
61
62 @item
63 Extension (type 7) records, in ascending numerical order of their
64 subtypes.
65
66 @item
67 Dictionary termination record.
68
69 @item
70 Data record.
71 @end itemize
72
73 Each type of record is described separately below.
74
75 @menu
76 * File Header Record::
77 * Variable Record::
78 * Value Labels Records::
79 * Document Record::
80 * Machine Integer Info Record::
81 * Machine Floating-Point Info Record::
82 * Multiple Response Sets Records::
83 * Variable Display Parameter Record::
84 * Long Variable Names Record::
85 * Very Long String Record::
86 * Character Encoding Record::
87 * Long String Value Labels Record::
88 * Data File and Variable Attributes Records::
89 * Extended Number of Cases Record::
90 * Miscellaneous Informational Records::
91 * Dictionary Termination Record::
92 * Data Record::
93 @end menu
94
95 @node File Header Record
96 @section File Header Record
97
98 The file header is always the first record in the file.  It has the
99 following format:
100
101 @example
102 char                rec_type[4];
103 char                prod_name[60];
104 int32               layout_code;
105 int32               nominal_case_size;
106 int32               compressed;
107 int32               weight_index;
108 int32               ncases;
109 flt64               bias;
110 char                creation_date[9];
111 char                creation_time[8];
112 char                file_label[64];
113 char                padding[3];
114 @end example
115
116 @table @code
117 @item char rec_type[4];
118 Record type code, set to @samp{$FL2}, that is, either @code{24 46 4c
119 32} if the file uses an ASCII-based character encoding, or @code{5b c6
120 d3 f2} if the file uses an EBCDIC-based character encoding.
121
122 @item char prod_name[60];
123 Product identification string.  This always begins with the characters
124 @samp{@@(#) SPSS DATA FILE}.  PSPP uses the remaining characters to
125 give its version and the operating system name; for example, @samp{GNU
126 pspp 0.1.4 - sparc-sun-solaris2.5.2}.  The string is truncated if it
127 would be longer than 60 characters; otherwise it is padded on the right
128 with spaces.
129
130 @anchor{layout_code}
131 @item int32 layout_code;
132 Normally set to 2, although a few system files have been spotted in
133 the wild with a value of 3 here.  PSPP use this value to determine the
134 file's integer endianness (@pxref{System File Format}).
135
136 @item int32 nominal_case_size;
137 Number of data elements per case.  This is the number of variables,
138 except that long string variables add extra data elements (one for every
139 8 characters after the first 8).  However, string variables do not
140 contribute to this value beyond the first 255 bytes.   Further, system
141 files written by some systems set this value to -1.  In general, it is
142 unsafe for systems reading system files to rely upon this value.
143
144 @item int32 compressed;
145 Set to 1 if the data in the file is compressed, 0 otherwise.
146
147 @item int32 weight_index;
148 If one of the variables in the data set is used as a weighting
149 variable, set to the dictionary index of that variable, plus 1
150 (@pxref{Dictionary Index}).  Otherwise, set to 0.
151
152 @item int32 ncases;
153 Set to the number of cases in the file if it is known, or -1 otherwise.
154
155 In the general case it is not possible to determine the number of cases
156 that will be output to a system file at the time that the header is
157 written.  The way that this is dealt with is by writing the entire
158 system file, including the header, then seeking back to the beginning of
159 the file and writing just the @code{ncases} field.  For files in which
160 this is not valid, the seek operation fails.  In this case,
161 @code{ncases} remains -1.
162
163 @anchor{bias}
164 @item flt64 bias;
165 Compression bias, ordinarily set to 100.  Only integers between
166 @code{1 - bias} and @code{251 - bias} can be compressed.
167
168 By assuming that its value is 100, PSPP uses @code{bias} to determine
169 the file's floating-point format and endianness (@pxref{System File
170 Format}).  If the compression bias is not 100, PSPP cannot auto-detect
171 the floating-point format and assumes that it is IEEE 754 format with
172 the same endianness as the system file's integers, which is correct
173 for all known system files.
174
175 @item char creation_date[9];
176 Date of creation of the system file, in @samp{dd mmm yy}
177 format, with the month as standard English abbreviations, using an
178 initial capital letter and following with lowercase.  If the date is not
179 available then this field is arbitrarily set to @samp{01 Jan 70}.
180
181 @item char creation_time[8];
182 Time of creation of the system file, in @samp{hh:mm:ss}
183 format and using 24-hour time.  If the time is not available then this
184 field is arbitrarily set to @samp{00:00:00}.
185
186 @item char file_label[64];
187 File label declared by the user, if any (@pxref{FILE LABEL,,,pspp,
188 PSPP Users Guide}).  Padded on the right with spaces.
189
190 @item char padding[3];
191 Ignored padding bytes to make the structure a multiple of 32 bits in
192 length.  Set to zeros.
193 @end table
194
195 @node Variable Record
196 @section Variable Record
197
198 There must be one variable record for each numeric variable and each
199 string variable with width 8 bytes or less.  String variables wider
200 than 8 bytes have one variable record for each 8 bytes, rounding up.
201 The first variable record for a long string specifies the variable's
202 correct dictionary information.  Subsequent variable records for a
203 long string are filled with dummy information: a type of -1, no
204 variable label or missing values, print and write formats that are
205 ignored, and an empty string as name.  A few system files have been
206 encountered that include a variable label on dummy variable records,
207 so readers should take care to parse dummy variable records in the
208 same way as other variable records.
209
210 @anchor{Dictionary Index}
211 The @dfn{dictionary index} of a variable is its offset in the set of
212 variable records, including dummy variable records for long string
213 variables.  The first variable record has a dictionary index of 0, the
214 second has a dictionary index of 1, and so on.
215
216 The system file format does not directly support string variables
217 wider than 255 bytes.  Such very long string variables are represented
218 by a number of narrower string variables.  @xref{Very Long String
219 Record}, for details.
220
221 @example
222 int32               rec_type;
223 int32               type;
224 int32               has_var_label;
225 int32               n_missing_values;
226 int32               print;
227 int32               write;
228 char                name[8];
229
230 /* @r{Present only if @code{has_var_label} is 1.} */
231 int32               label_len;
232 char                label[];
233
234 /* @r{Present only if @code{n_missing_values} is nonzero}. */
235 flt64               missing_values[];
236 @end example
237
238 @table @code
239 @item int32 rec_type;
240 Record type code.  Always set to 2.
241
242 @item int32 type;
243 Variable type code.  Set to 0 for a numeric variable.  For a short
244 string variable or the first part of a long string variable, this is set
245 to the width of the string.  For the second and subsequent parts of a
246 long string variable, set to -1, and the remaining fields in the
247 structure are ignored.
248
249 @item int32 has_var_label;
250 If this variable has a variable label, set to 1; otherwise, set to 0.
251
252 @item int32 n_missing_values;
253 If the variable has no missing values, set to 0.  If the variable has
254 one, two, or three discrete missing values, set to 1, 2, or 3,
255 respectively.  If the variable has a range for missing variables, set to
256 -2; if the variable has a range for missing variables plus a single
257 discrete value, set to -3.
258
259 @item int32 print;
260 Print format for this variable.  See below.
261
262 @item int32 write;
263 Write format for this variable.  See below.
264
265 @item char name[8];
266 Variable name.  The variable name must begin with a capital letter or
267 the at-sign (@samp{@@}).  Subsequent characters may also be digits, octothorpes
268 (@samp{#}), dollar signs (@samp{$}), underscores (@samp{_}), or full
269 stops (@samp{.}).  The variable name is padded on the right with spaces.
270
271 @item int32 label_len;
272 This field is present only if @code{has_var_label} is set to 1.  It is
273 set to the length, in characters, of the variable label.  The
274 documented maximum length varies from 120 to 255 based on SPSS
275 version, but some files have been seen with longer labels.  PSPP
276 accepts longer labels and truncates them to 255 bytes on input.
277
278 @item char label[];
279 This field is present only if @code{has_var_label} is set to 1.  It has
280 length @code{label_len}, rounded up to the nearest multiple of 32 bits.
281 The first @code{label_len} characters are the variable's variable label.
282
283 @item flt64 missing_values[];
284 This field is present only if @code{n_missing_values} is nonzero.  It
285 has the same number of 8-byte elements as the absolute value of
286 @code{n_missing_values}.  Each element is interpreted as a number for
287 numeric variables (with HIGHEST and LOWEST indicated as described in
288 the chapter introduction).  For string variables of width less than 8
289 bytes, elements are right-padded with spaces; for string variables
290 wider than 8 bytes, only the first 8 bytes of each missing value are
291 specified, with the remainder implicitly all spaces.
292
293 For discrete missing values, each element represents one missing
294 value.  When a range is present, the first element denotes the minimum
295 value in the range, and the second element denotes the maximum value
296 in the range.  When a range plus a value are present, the third
297 element denotes the additional discrete missing value.
298 @end table
299
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.
306
307 Format types are defined as follows:
308
309 @quotation
310 @multitable {Value} {@code{DATETIME}}
311 @headitem Value
312 @tab Meaning
313 @item 0
314 @tab Not used.
315 @item 1
316 @tab @code{A}
317 @item 2
318 @tab @code{AHEX}
319 @item 3
320 @tab @code{COMMA}
321 @item 4
322 @tab @code{DOLLAR}
323 @item 5
324 @tab @code{F}
325 @item 6
326 @tab @code{IB}
327 @item 7
328 @tab @code{PIBHEX}
329 @item 8
330 @tab @code{P}
331 @item 9
332 @tab @code{PIB}
333 @item 10
334 @tab @code{PK}
335 @item 11
336 @tab @code{RB}
337 @item 12
338 @tab @code{RBHEX}
339 @item 13
340 @tab Not used.
341 @item 14
342 @tab Not used.
343 @item 15
344 @tab @code{Z}
345 @item 16
346 @tab @code{N}
347 @item 17
348 @tab @code{E}
349 @item 18
350 @tab Not used.
351 @item 19
352 @tab Not used.
353 @item 20
354 @tab @code{DATE}
355 @item 21
356 @tab @code{TIME}
357 @item 22
358 @tab @code{DATETIME}
359 @item 23
360 @tab @code{ADATE}
361 @item 24
362 @tab @code{JDATE}
363 @item 25
364 @tab @code{DTIME}
365 @item 26
366 @tab @code{WKDAY}
367 @item 27
368 @tab @code{MONTH}
369 @item 28
370 @tab @code{MOYR}
371 @item 29
372 @tab @code{QYR}
373 @item 30
374 @tab @code{WKYR}
375 @item 31
376 @tab @code{PCT}
377 @item 32
378 @tab @code{DOT}
379 @item 33
380 @tab @code{CCA}
381 @item 34
382 @tab @code{CCB}
383 @item 35
384 @tab @code{CCC}
385 @item 36
386 @tab @code{CCD}
387 @item 37
388 @tab @code{CCE}
389 @item 38
390 @tab @code{EDATE}
391 @item 39
392 @tab @code{SDATE}
393 @end multitable
394 @end quotation
395
396 A few system files have been observed in the wild with invalid
397 @code{write} fields, in particular with value 0.  Readers should
398 probably treat invalid @code{print} or @code{write} fields as some
399 default format.
400
401 @node Value Labels Records
402 @section Value Labels Records
403
404 The value label records documented in this section are used for
405 numeric and short string variables only.  Long string variables may
406 have value labels, but their value labels are recorded using a
407 different record type (@pxref{Long String Value Labels Record}).
408
409 The value label record has the following format:
410
411 @example
412 int32               rec_type;
413 int32               label_count;
414
415 /* @r{Repeated @code{label_cnt} times}. */
416 char                value[8];
417 char                label_len;
418 char                label[];
419 @end example
420
421 @table @code
422 @item int32 rec_type;
423 Record type.  Always set to 3.
424
425 @item int32 label_count;
426 Number of value labels present in this record.
427 @end table
428
429 The remaining fields are repeated @code{count} times.  Each
430 repetition specifies one value label.
431
432 @table @code
433 @item char value[8];
434 A numeric value or a short string value padded as necessary to 8 bytes
435 in length.  Its type and width cannot be determined until the
436 following value label variables record (see below) is read.
437
438 @item char label_len;
439 The label's length, in bytes.  The documented maximum length varies
440 from 60 to 120 based on SPSS version.  PSPP supports value labels up
441 to 255 bytes long.
442
443 @item char label[];
444 @code{label_len} bytes of the actual label, followed by up to 7 bytes
445 of padding to bring @code{label} and @code{label_len} together to a
446 multiple of 8 bytes in length.
447 @end table
448
449 The value label record is always immediately followed by a value label
450 variables record with the following format:
451
452 @example
453 int32               rec_type;
454 int32               var_count;
455 int32               vars[];
456 @end example
457
458 @table @code
459 @item int32 rec_type;
460 Record type.  Always set to 4.
461
462 @item int32 var_count;
463 Number of variables that the associated value labels from the value
464 label record are to be applied.
465
466 @item int32 vars[];
467 A list of dictionary indexes of variables to which to apply the value
468 labels (@pxref{Dictionary Index}).  There are @code{var_count}
469 elements.
470
471 String variables wider than 8 bytes may not be specified in this list.
472 @end table
473
474 @node Document Record
475 @section Document Record
476
477 The document record, if present, has the following format:
478
479 @example
480 int32               rec_type;
481 int32               n_lines;
482 char                lines[][80];
483 @end example
484
485 @table @code
486 @item int32 rec_type;
487 Record type.  Always set to 6.
488
489 @item int32 n_lines;
490 Number of lines of documents present.
491
492 @item char lines[][80];
493 Document lines.  The number of elements is defined by @code{n_lines}.
494 Lines shorter than 80 characters are padded on the right with spaces.
495 @end table
496
497 @node Machine Integer Info Record
498 @section Machine Integer Info Record
499
500 The integer info record, if present, has the following format:
501
502 @example
503 /* @r{Header.} */
504 int32               rec_type;
505 int32               subtype;
506 int32               size;
507 int32               count;
508
509 /* @r{Data.} */
510 int32               version_major;
511 int32               version_minor;
512 int32               version_revision;
513 int32               machine_code;
514 int32               floating_point_rep;
515 int32               compression_code;
516 int32               endianness;
517 int32               character_code;
518 @end example
519
520 @table @code
521 @item int32 rec_type;
522 Record type.  Always set to 7.
523
524 @item int32 subtype;
525 Record subtype.  Always set to 3.
526
527 @item int32 size;
528 Size of each piece of data in the data part, in bytes.  Always set to 4.
529
530 @item int32 count;
531 Number of pieces of data in the data part.  Always set to 8.
532
533 @item int32 version_major;
534 PSPP major version number.  In version @var{x}.@var{y}.@var{z}, this
535 is @var{x}.
536
537 @item int32 version_minor;
538 PSPP minor version number.  In version @var{x}.@var{y}.@var{z}, this
539 is @var{y}.
540
541 @item int32 version_revision;
542 PSPP version revision number.  In version @var{x}.@var{y}.@var{z},
543 this is @var{z}.
544
545 @item int32 machine_code;
546 Machine code.  PSPP always set this field to value to -1, but other
547 values may appear.
548
549 @item int32 floating_point_rep;
550 Floating point representation code.  For IEEE 754 systems this is 1.
551 IBM 370 sets this to 2, and DEC VAX E to 3.
552
553 @item int32 compression_code;
554 Compression code.  Always set to 1.
555
556 @item int32 endianness;
557 Machine endianness.  1 indicates big-endian, 2 indicates little-endian.
558
559 @item int32 character_code;
560 @anchor{character-code} Character code.  The following values have
561 been actually observed in system files:
562
563 @table @asis
564 @item 1
565 EBCDIC.
566
567 @item 2
568 7-bit ASCII.
569
570 @item 1250
571 The @code{windows-1250} code page for Central European and Eastern
572 European languages.
573
574 @item 1252
575 The @code{windows-1252} code page for Western European languages.
576
577 @item 28591
578 ISO 8859-1.
579
580 @item 65001
581 UTF-8.
582 @end table
583
584 The following additional values are known to be defined:
585
586 @table @asis
587 @item 3
588 8-bit ``ASCII''.
589
590 @item 4
591 DEC Kanji.
592 @end table
593
594 Other Windows code page numbers are known to be generally valid.
595
596 Old versions of SPSS for Unix and Windows always wrote value 2 in this
597 field, regardless of the encoding in use.  Newer versions also write
598 the character encoding as a string (see @ref{Character Encoding
599 Record}).
600 @end table
601
602 @node Machine Floating-Point Info Record
603 @section Machine Floating-Point Info Record
604
605 The floating-point info record, if present, has the following format:
606
607 @example
608 /* @r{Header.} */
609 int32               rec_type;
610 int32               subtype;
611 int32               size;
612 int32               count;
613
614 /* @r{Data.} */
615 flt64               sysmis;
616 flt64               highest;
617 flt64               lowest;
618 @end example
619
620 @table @code
621 @item int32 rec_type;
622 Record type.  Always set to 7.
623
624 @item int32 subtype;
625 Record subtype.  Always set to 4.
626
627 @item int32 size;
628 Size of each piece of data in the data part, in bytes.  Always set to 8.
629
630 @item int32 count;
631 Number of pieces of data in the data part.  Always set to 3.
632
633 @item flt64 sysmis;
634 The system missing value.
635
636 @item flt64 highest;
637 The value used for HIGHEST in missing values.
638
639 @item flt64 lowest;
640 The value used for LOWEST in missing values.
641 @end table
642
643 @node Multiple Response Sets Records
644 @section Multiple Response Sets Records
645
646 The system file format has two different types of records that
647 represent multiple response sets (@pxref{MRSETS,,,pspp, PSPP Users
648 Guide}).  The first type of record describes multiple response sets
649 that can be understood by SPSS before version 14.  The second type of
650 record, with a closely related format, is used for multiple dichotomy
651 sets that use the CATEGORYLABELS=COUNTEDVALUES feature added in
652 version 14.
653
654 @example
655 /* @r{Header.} */
656 int32               rec_type;
657 int32               subtype;
658 int32               size;
659 int32               count;
660
661 /* @r{Exactly @code{count} bytes of data.} */
662 char                mrsets[];
663 @end example
664
665 @table @code
666 @item int32 rec_type;
667 Record type.  Always set to 7.
668
669 @item int32 subtype;
670 Record subtype.  Set to 7 for records that describe multiple response
671 sets understood by SPSS before version 14, or to 19 for records that
672 describe dichotomy sets that use the CATEGORYLABELS=COUNTEDVALUES
673 feature added in version 14.
674
675 @item int32 size;
676 The size of each element in the @code{mrsets} member. Always set to 1.
677
678 @item int32 count;
679 The total number of bytes in @code{mrsets}.
680
681 @item char mrsets[];
682 A series of multiple response sets, each of which consists of the
683 following:
684
685 @itemize @bullet
686 @item
687 The set's name (an identifier that begins with @samp{$}), in mixed
688 upper and lower case.
689
690 @item
691 An equals sign (@samp{=}).
692
693 @item
694 @samp{C} for a multiple category set, @samp{D} for a multiple
695 dichotomy set with CATEGORYLABELS=VARLABELS, or @samp{E} for a
696 multiple dichotomy set with CATEGORYLABELS=COUNTEDVALUES.
697
698 @item
699 For a multiple dichotomy set with CATEGORYLABELS=COUNTEDVALUES, a
700 space, followed by a number expressed as decimal digits, followed by a
701 space.  If LABELSOURCE=VARLABEL was specified on MRSETS, then the
702 number is 11; otherwise it is 1.@footnote{This part of the format may
703 not be fully understood, because only a single example of each
704 possibility has been examined.}
705
706 @item
707 For either kind of multiple dichotomy set, the counted value, as a
708 positive integer count specified as decimal digits, followed by a
709 space, followed by as many string bytes as specified in the count.  If
710 the set contains numeric variables, the string consists of the counted
711 integer value expressed as decimal digits.  If the set contains string
712 variables, the string contains the counted string value.  Either way,
713 the string may be padded on the right with spaces (older versions of
714 SPSS seem to always pad to a width of 8 bytes; newer versions don't).
715
716 @item
717 A space.
718
719 @item
720 The multiple response set's label, using the same format as for the
721 counted value for multiple dichotomy sets.  A string of length 0 means
722 that the set does not have a label.  A string of length 0 is also
723 written if LABELSOURCE=VARLABEL was specified.
724
725 @item
726 A space.
727
728 @item
729 The short names of the variables in the set, converted to lowercase,
730 each separated from the previous by a single space.
731
732 @item
733 A line feed (byte 0x0a).
734 @end itemize
735 @end table
736
737 Example: Given appropriate variable definitions, consider the
738 following MRSETS command:
739
740 @example
741 MRSETS /MCGROUP NAME=$a LABEL='my mcgroup' VARIABLES=a b c
742        /MDGROUP NAME=$b VARIABLES=g e f d VALUE=55
743        /MDGROUP NAME=$c LABEL='mdgroup #2' VARIABLES=h i j VALUE='Yes'
744        /MDGROUP NAME=$d LABEL='third mdgroup' CATEGORYLABELS=COUNTEDVALUES
745         VARIABLES=k l m VALUE=34
746        /MDGROUP NAME=$e CATEGORYLABELS=COUNTEDVALUES LABELSOURCE=VARLABEL
747         VARIABLES=n o p VALUE='choice'.
748 @end example
749
750 The above would generate the following multiple response set record of
751 subtype 7:
752
753 @example
754 $a=C 10 my mcgroup a b c
755 $b=D2 55 0  g e f d
756 $c=D3 Yes 10 mdgroup #2 h i j
757 @end example
758
759 It would also generate the following multiple response set record with
760 subtype 19:
761
762 @example
763 $d=E 1 2 34 13 third mdgroup k l m
764 $e=E 11 6 choice 0  n o p
765 @end example
766
767 @node Variable Display Parameter Record
768 @section Variable Display Parameter Record
769
770 The variable display parameter record, if present, has the following
771 format:
772
773 @example
774 /* @r{Header.} */
775 int32               rec_type;
776 int32               subtype;
777 int32               size;
778 int32               count;
779
780 /* @r{Repeated @code{count} times}. */
781 int32               measure;
782 int32               width;           /* @r{Not always present.} */
783 int32               alignment;
784 @end example
785
786 @table @code
787 @item int32 rec_type;
788 Record type.  Always set to 7.
789
790 @item int32 subtype;
791 Record subtype.  Always set to 11.
792
793 @item int32 size;
794 The size of @code{int32}.  Always set to 4.
795
796 @item int32 count;
797 The number of sets of variable display parameters (ordinarily the
798 number of variables in the dictionary), times 2 or 3.
799 @end table
800
801 The remaining members are repeated @code{count} times, in the same
802 order as the variable records.  No element corresponds to variable
803 records that continue long string variables.  The meanings of these
804 members are as follows:
805
806 @table @code
807 @item int32 measure;
808 The measurement type of the variable:
809 @table @asis
810 @item 1
811 Nominal Scale
812 @item 2
813 Ordinal Scale
814 @item 3
815 Continuous Scale
816 @end table
817
818 SPSS 14 sometimes writes a @code{measure} of 0 for string variables.
819 PSPP interprets this as nominal scale.
820
821 @item int32 width;
822 The width of the display column for the variable in characters.
823
824 This field is present if @var{count} is 3 times the number of
825 variables in the dictionary.  It is omitted if @var{count} is 2 times
826 the number of variables.
827
828 @item int32 alignment;
829 The alignment of the variable for display purposes:
830
831 @table @asis
832 @item 0
833 Left aligned
834 @item 1
835 Right aligned
836 @item 2
837 Centre aligned
838 @end table
839 @end table
840
841 @node Long Variable Names Record
842 @section Long Variable Names Record
843
844 If present, the long variable names record has the following format:
845
846 @example
847 /* @r{Header.} */
848 int32               rec_type;
849 int32               subtype;
850 int32               size;
851 int32               count;
852
853 /* @r{Exactly @code{count} bytes of data.} */
854 char                var_name_pairs[];
855 @end example
856
857 @table @code
858 @item int32 rec_type;
859 Record type.  Always set to 7.
860
861 @item int32 subtype;
862 Record subtype.  Always set to 13.
863
864 @item int32 size;
865 The size of each element in the @code{var_name_pairs} member. Always set to 1.
866
867 @item int32 count;
868 The total number of bytes in @code{var_name_pairs}.
869
870 @item char var_name_pairs[];
871 A list of @var{key}--@var{value} tuples, where @var{key} is the name
872 of a variable, and @var{value} is its long variable name.
873 The @var{key} field is at most 8 bytes long and must match the
874 name of a variable which appears in the variable record (@pxref{Variable
875 Record}).
876 The @var{value} field is at most 64 bytes long.
877 The @var{key} and @var{value} fields are separated by a @samp{=} byte.
878 Each tuple is separated by a byte whose value is 09.  There is no
879 trailing separator following the last tuple.
880 The total length is @code{count} bytes.
881 @end table
882
883 @node Very Long String Record
884 @section Very Long String Record
885
886 Old versions of SPSS limited string variables to a width of 255 bytes.
887 For backward compatibility with these older versions, the system file
888 format represents a string longer than 255 bytes, called a @dfn{very
889 long string}, as a collection of strings no longer than 255 bytes
890 each.  The strings concatenated to make a very long string are called
891 its @dfn{segments}; for consistency, variables other than very long
892 strings are considered to have a single segment.
893
894 A very long string with a width of @var{w} has @var{n} =
895 (@var{w} + 251) / 252 segments, that is, one segment for every
896 252 bytes of width, rounding up.  It would be logical, then, for each
897 of the segments except the last to have a width of 252 and the last
898 segment to have the remainder, but this is not the case.  In fact,
899 each segment except the last has a width of 255 bytes.  The last
900 segment has width @var{w} - (@var{n} - 1) * 252; some versions
901 of SPSS make it slightly wider, but not wide enough to make the last
902 segment require another 8 bytes of data.
903
904 Data is packed tightly into segments of a very long string, 255 bytes
905 per segment.  Because 255 bytes of segment data are allocated for
906 every 252 bytes of the very long string's width (approximately), some
907 unused space is left over at the end of the allocated segments.  Data
908 in unused space is ignored.
909
910 Example: Consider a very long string of width 20,000.  Such a very
911 long string has 20,000 / 252 = 80 (rounding up) segments.  The first
912 79 segments have width 255; the last segment has width 20,000 - 79 *
913 252 = 92 or slightly wider (up to 96 bytes, the next multiple of 8).
914 The very long string's data is actually stored in the 19,890 bytes in
915 the first 78 segments, plus the first 110 bytes of the 79th segment
916 (19,890 + 110 = 20,000).  The remaining 145 bytes of the 79th segment
917 and all 92 bytes of the 80th segment are unused.
918
919 The very long string record explains how to stitch together segments
920 to obtain very long string data.  For each of the very long string
921 variables in the dictionary, it specifies the name of its first
922 segment's variable and the very long string variable's actual width.
923 The remaining segments immediately follow the named variable in the
924 system file's dictionary.
925
926 The very long string record, which is present only if the system file
927 contains very long string variables, has the following format:
928
929 @example
930 /* @r{Header.} */
931 int32               rec_type;
932 int32               subtype;
933 int32               size;
934 int32               count;
935
936 /* @r{Exactly @code{count} bytes of data.} */
937 char                string_lengths[];
938 @end example
939
940 @table @code
941 @item int32 rec_type;
942 Record type.  Always set to 7.
943
944 @item int32 subtype;
945 Record subtype.  Always set to 14.
946
947 @item int32 size;
948 The size of each element in the @code{string_lengths} member. Always set to 1.
949
950 @item int32 count;
951 The total number of bytes in @code{string_lengths}.
952
953 @item char string_lengths[];
954 A list of @var{key}--@var{value} tuples, where @var{key} is the name
955 of a variable, and @var{value} is its length.
956 The @var{key} field is at most 8 bytes long and must match the
957 name of a variable which appears in the variable record (@pxref{Variable
958 Record}).
959 The @var{value} field is exactly 5 bytes long. It is a zero-padded,
960 ASCII-encoded string that is the length of the variable.
961 The @var{key} and @var{value} fields are separated by a @samp{=} byte.
962 Tuples are delimited by a two-byte sequence @{00, 09@}.
963 After the last tuple, there may be a single byte 00, or @{00, 09@}.
964 The total length is @code{count} bytes.
965 @end table
966
967 @node Character Encoding Record
968 @section Character Encoding Record
969
970 This record, if present, indicates the character encoding for string data,
971 long variable names, variable labels, value labels and other strings in the
972 file.
973
974 @example
975 /* @r{Header.} */
976 int32               rec_type;
977 int32               subtype;
978 int32               size;
979 int32               count;
980
981 /* @r{Exactly @code{count} bytes of data.} */
982 char                encoding[];
983 @end example
984
985 @table @code
986 @item int32 rec_type;
987 Record type.  Always set to 7.
988
989 @item int32 subtype;
990 Record subtype.  Always set to 20.
991
992 @item int32 size;
993 The size of each element in the @code{encoding} member. Always set to 1.
994
995 @item int32 count;
996 The total number of bytes in @code{encoding}.
997
998 @item char encoding[];
999 The name of the character encoding.  Normally this will be an official
1000 IANA character set name or alias.
1001 See @url{http://www.iana.org/assignments/character-sets}.
1002 Character set names are not case-sensitive, but SPSS appears to write
1003 them in all-uppercase.
1004 @end table
1005
1006 This record is not present in files generated by older software.  See
1007 also the @code{character_code} field in the machine integer info
1008 record (@pxref{character-code}).
1009
1010 When the character encoding record and the machine integer info record
1011 are both present, all system files observed in practice indicate the
1012 same character encoding, e.g.@: 1252 as @code{character_code} and
1013 @code{windows-1252} as @code{encoding}, 65001 and @code{UTF-8}, etc.
1014
1015 If, for testing purposes, a file is crafted with different
1016 @code{character_code} and @code{encoding}, it seems that
1017 @code{character_code} controls the encoding for all strings in the
1018 system file before the dictionary termination record, including
1019 strings in data (e.g.@: string missing values), and @code{encoding}
1020 controls the encoding for strings following the dictionary termination
1021 record.
1022
1023 @node Long String Value Labels Record
1024 @section Long String Value Labels Record
1025
1026 This record, if present, specifies value labels for long string
1027 variables.
1028
1029 @example
1030 /* @r{Header.} */
1031 int32               rec_type;
1032 int32               subtype;
1033 int32               size;
1034 int32               count;
1035
1036 /* @r{Repeated up to exactly @code{count} bytes.} */
1037 int32               var_name_len;
1038 char                var_name[];
1039 int32               var_width;
1040 int32               n_labels;
1041 long_string_label   labels[];
1042 @end example
1043
1044 @table @code
1045 @item int32 rec_type;
1046 Record type.  Always set to 7.
1047
1048 @item int32 subtype;
1049 Record subtype.  Always set to 21.
1050
1051 @item int32 size;
1052 Always set to 1.
1053
1054 @item int32 count;
1055 The number of bytes following the header until the next header.
1056
1057 @item int32 var_name_len;
1058 @itemx char var_name[];
1059 The number of bytes in the name of the variable that has long string
1060 value labels, plus the variable name itself, which consists of exactly
1061 @code{var_name_len} bytes.  The variable name is not padded to any
1062 particular boundary, nor is it null-terminated.
1063
1064 @item int32 var_width;
1065 The width of the variable, in bytes, which will be between 9 and
1066 32767.
1067
1068 @item int32 n_labels;
1069 @itemx long_string_label labels[];
1070 The long string labels themselves.  The @code{labels} array contains
1071 exactly @code{n_labels} elements, each of which has the following
1072 substructure:
1073
1074 @example
1075 int32               value_len;
1076 char                value[];
1077 int32               label_len;
1078 char                label[];
1079 @end example
1080
1081 @table @code
1082 @item int32 value_len;
1083 @itemx char value[];
1084 The string value being labeled.  @code{value_len} is the number of
1085 bytes in @code{value}; it is equal to @code{var_width}.  The
1086 @code{value} array is not padded or null-terminated.
1087
1088 @item int32 label_len;
1089 @itemx char label[];
1090 The label for the string value.  @code{label_len}, which must be
1091 between 0 and 120, is the number of bytes in @code{label}.  The
1092 @code{label} array is not padded or null-terminated.
1093 @end table
1094 @end table
1095
1096 @node Data File and Variable Attributes Records
1097 @section Data File and Variable Attributes Records
1098
1099 The data file and variable attributes records represent custom
1100 attributes for the system file or for individual variables in the
1101 system file, as defined on the DATAFILE ATTRIBUTE (@pxref{DATAFILE
1102 ATTRIBUTE,,,pspp, PSPP Users Guide}) and VARIABLE ATTRIBUTE commands
1103 (@pxref{VARIABLE ATTRIBUTE,,,pspp, PSPP Users Guide}), respectively.
1104
1105 @example
1106 /* @r{Header.} */
1107 int32               rec_type;
1108 int32               subtype;
1109 int32               size;
1110 int32               count;
1111
1112 /* @r{Exactly @code{count} bytes of data.} */
1113 char                attributes[];
1114 @end example
1115
1116 @table @code
1117 @item int32 rec_type;
1118 Record type.  Always set to 7.
1119
1120 @item int32 subtype;
1121 Record subtype.  Always set to 17 for a data file attribute record or
1122 to 18 for a variable attributes record.
1123
1124 @item int32 size;
1125 The size of each element in the @code{attributes} member. Always set to 1.
1126
1127 @item int32 count;
1128 The total number of bytes in @code{attributes}.
1129
1130 @item char attributes[];
1131 The attributes, in a text-based format.
1132
1133 In record type 17, this field contains a single attribute set.  An
1134 attribute set is a sequence of one or more attributes concatenated
1135 together.  Each attribute consists of a name, which has the same
1136 syntax as a variable name, followed by, inside parentheses, a sequence
1137 of one or more values.  Each value consists of a string enclosed in
1138 single quotes (@code{'}) followed by a line feed (byte 0x0a).  A value
1139 may contain single quote characters, which are not themselves escaped
1140 or quoted or required to be present in pairs.  There is no apparent
1141 way to embed a line feed in a value.  There is no distinction between
1142 an attribute with a single value and an attribute array with one
1143 element.
1144
1145 In record type 18, this field contains a sequence of one or more
1146 variable attribute sets.  If more than one variable attribute set is
1147 present, each one after the first is delimited from the previous by
1148 @code{/}.  Each variable attribute set consists of a long
1149 variable name,
1150 followed by @code{:}, followed by an attribute set with the same
1151 syntax as on record type 17.
1152
1153 The total length is @code{count} bytes.
1154 @end table
1155
1156 @subheading Example
1157
1158 A system file produced with the following VARIABLE ATTRIBUTE commands
1159 in effect:
1160
1161 @example
1162 VARIABLE ATTRIBUTE VARIABLES=dummy ATTRIBUTE=fred[1]('23') fred[2]('34').
1163 VARIABLE ATTRIBUTE VARIABLES=dummy ATTRIBUTE=bert('123').
1164 @end example
1165
1166 @noindent
1167 will contain a variable attribute record with the following contents:
1168
1169 @example
1170 00000000  07 00 00 00 12 00 00 00  01 00 00 00 22 00 00 00  |............"...|
1171 00000010  64 75 6d 6d 79 3a 66 72  65 64 28 27 32 33 27 0a  |dummy:fred('23'.|
1172 00000020  27 33 34 27 0a 29 62 65  72 74 28 27 31 32 33 27  |'34'.)bert('123'|
1173 00000030  0a 29                                             |.)              |
1174 @end example
1175
1176 @node Extended Number of Cases Record
1177 @section Extended Number of Cases Record
1178
1179 The file header record expresses the number of cases in the system
1180 file as an int32 (@pxref{File Header Record}).  This record allows the
1181 number of cases in the system file to be expressed as a 64-bit number.
1182
1183 @example
1184 int32               rec_type;
1185 int32               subtype;
1186 int32               size;
1187 int32               count;
1188 int64               unknown;
1189 int64               ncases64;
1190 @end example
1191
1192 @table @code
1193 @item int32 rec_type;
1194 Record type.  Always set to 7.
1195
1196 @item int32 subtype;
1197 Record subtype.  Always set to 16.
1198
1199 @item int32 size;
1200 Size of each element.  Always set to 8.
1201
1202 @item int32 count;
1203 Number of pieces of data in the data part.  Alway set to 2.
1204
1205 @item int64 unknown;
1206 Meaning unknown.  Always set to 1.
1207
1208 @item int64 ncases64;
1209 Number of cases in the file as a 64-bit integer.  Presumably this
1210 could be -1 to indicate that the number of cases is unknown, for the
1211 same reason as @code{ncases} in the file header record, but this has
1212 not been observed in the wild.
1213 @end table
1214
1215 @node Miscellaneous Informational Records
1216 @section Miscellaneous Informational Records
1217
1218 Some specific types of miscellaneous informational records are
1219 documented here, but others are known to exist.  PSPP ignores unknown
1220 miscellaneous informational records when reading system files.
1221
1222 @example
1223 /* @r{Header.} */
1224 int32               rec_type;
1225 int32               subtype;
1226 int32               size;
1227 int32               count;
1228
1229 /* @r{Exactly @code{size * count} bytes of data.} */
1230 char                data[];
1231 @end example
1232
1233 @table @code
1234 @item int32 rec_type;
1235 Record type.  Always set to 7.
1236
1237 @item int32 subtype;
1238 Record subtype.  May take any value.  According to Aapi
1239 H@"am@"al@"ainen, value 5 indicates a set of grouped variables and 6
1240 indicates date info (probably related to USE).
1241
1242 @item int32 size;
1243 Size of each piece of data in the data part.  Should have the value 1,
1244 4, or 8, for @code{char}, @code{int32}, and @code{flt64} format data,
1245 respectively.
1246
1247 @item int32 count;
1248 Number of pieces of data in the data part.
1249
1250 @item char data[];
1251 Arbitrary data.  There must be @code{size} times @code{count} bytes of
1252 data.
1253 @end table
1254
1255 @node Dictionary Termination Record
1256 @section Dictionary Termination Record
1257
1258 The dictionary termination record separates all other records from the
1259 data records.
1260
1261 @example
1262 int32               rec_type;
1263 int32               filler;
1264 @end example
1265
1266 @table @code
1267 @item int32 rec_type;
1268 Record type.  Always set to 999.
1269
1270 @item int32 filler;
1271 Ignored padding.  Should be set to 0.
1272 @end table
1273
1274 @node Data Record
1275 @section Data Record
1276
1277 Data records must follow all other records in the system file.  There must
1278 be at least one data record in every system file.
1279
1280 The format of data records varies depending on whether the data is
1281 compressed.  Regardless, the data is arranged in a series of 8-byte
1282 elements.
1283
1284 When data is not compressed,
1285 each element corresponds to
1286 the variable declared in the respective variable record (@pxref{Variable
1287 Record}).  Numeric values are given in @code{flt64} format; string
1288 values are literal characters string, padded on the right when
1289 necessary to fill out 8-byte units.
1290
1291 Compressed data is arranged in the following manner: the first 8 bytes
1292 in the data section is divided into a series of 1-byte command
1293 codes.  These codes have meanings as described below:
1294
1295 @table @asis
1296 @item 0
1297 Ignored.  If the program writing the system file accumulates compressed
1298 data in blocks of fixed length, 0 bytes can be used to pad out extra
1299 bytes remaining at the end of a fixed-size block.
1300
1301 @item 1 through 251
1302 A number with
1303 value @var{code} - @var{bias}, where
1304 @var{code} is the value of the compression code and @var{bias} is the
1305 variable @code{bias} from the file header.  For example,
1306 code 105 with bias 100.0 (the normal value) indicates a numeric variable
1307 of value 5.
1308 One file has been seen written by SPSS 14 that contained such a code
1309 in a @emph{string} field with the value 0 (after the bias is
1310 subtracted) as a way of encoding null bytes.
1311
1312 @item 252
1313 End of file.  This code may or may not appear at the end of the data
1314 stream.  PSPP always outputs this code but its use is not required.
1315
1316 @item 253
1317 A numeric or string value that is not
1318 compressible.  The value is stored in the 8 bytes following the
1319 current block of command bytes.  If this value appears twice in a block
1320 of command bytes, then it indicates the second group of 8 bytes following the
1321 command bytes, and so on.
1322
1323 @item 254
1324 An 8-byte string value that is all spaces.
1325
1326 @item 255
1327 The system-missing value.
1328 @end table
1329
1330 When the end of the an 8-byte group of command bytes is reached, any
1331 blocks of non-compressible values indicated by code 253 are skipped,
1332 and the next element of command bytes is read and interpreted, until
1333 the end of the file or a code with value 252 is reached.
1334 @setfilename ignored