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