doc/data-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 three data types: 8-bit characters, 32-bit integers,
   9 and 64-bit floating points, called here @code{char}, @code{int32}, and
  10 @code{flt64}, respectively.  Data is not necessarily aligned on a word
  11 or double-word boundary: the long variable name record (@pxref{Long
  12 Variable Names Record}) and very long string records (@pxref{Very Long
  13 String Record}) have arbitrary byte length and can therefore cause all
  14 data coming after them in the file to be misaligned.
  15
  16 Integer data in system files may be big-endian or little-endian.  A
  17 reader may detect the endianness of a system file by examining
  18 @code{layout_code} in the file header record
  19 (@pxref{layout_code,,@code{layout_code}}).
  20
  21 Floating-point data in system files may nominally be in IEEE 754, IBM,
  22 or VAX formats.  A reader may detect the floating-point format in use
  23 by examining @code{bias} in the file header record
  24 (@pxref{bias,,@code{bias}}).
  25
  26 PSPP detects big-endian and little-endian integer formats in system
  27 files and translates as necessary.  PSPP also detects the
  28 floating-point format in use, as well as the endianness of IEEE 754
  29 floating-point numbers, and translates as needed.  However, only IEEE
  30 754 numbers with the same endianness as integer data in the same file
  31 has actually been observed in system files, and it is likely that
  32 other formats are obsolete or were never used.
  33
  34 The PSPP system-missing value is represented by the largest possible
  35 negative number in the floating point format (@code{-DBL_MAX}).  Two
  36 other values are important for use as missing values: @code{HIGHEST},
  37 represented by the largest possible positive number (@code{DBL_MAX}),
  38 and @code{LOWEST}, represented by the second-largest negative number
  39 (in IEEE 754 format, @code{0xffeffffffffffffe}).
  40
  41 System files are divided into records, each of which begins with a
  42 4-byte record type, usually regarded as an @code{int32}.
  43
  44 The records must appear in the following order:
  45
  46 @itemize @bullet
  47 @item
  48 File header record.
  49
  50 @item
  51 Variable records.
  52
  53 @item
  54 All pairs of value labels records and value label variables records,
  55 if present.
  56
  57 @item
  58 Document record, if present.
  59
  60 @item
  61 Any of the following records, if present, in any order:
  62
  63 @itemize @minus
  64 @item
  65 Machine integer info record.
  66
  67 @item
  68 Machine floating-point info record.
  69
  70 @item
  71 Variable display parameter record.
  72
  73 @item
  74 Long variable names record.
  75
  76 @item
  77 Miscellaneous informational records.
  78 @end itemize
  79
  80 @item
  81 Dictionary termination record.
  82
  83 @item
  84 Data record.
  85 @end itemize
  86
  87 Each type of record is described separately below.
  88
  89 @menu
  90 * File Header Record::
  91 * Variable Record::
  92 * Value Labels Records::
  93 * Document Record::
  94 * Machine Integer Info Record::
  95 * Machine Floating-Point Info Record::
  96 * Variable Display Parameter Record::
  97 * Long Variable Names Record::
  98 * Very Long String Record::
  99 * Miscellaneous Informational Records::
 100 * Dictionary Termination Record::
 101 * Data Record::
 102 @end menu
 103
 104 @node File Header Record
 105 @section File Header Record
 106
 107 The file header is always the first record in the file.  It has the
 108 following format:
 109
 110 @example
 111 char                rec_type[4];
 112 char                prod_name[60];
 113 int32               layout_code;
 114 int32               nominal_case_size;
 115 int32               compressed;
 116 int32               weight_index;
 117 int32               ncases;
 118 flt64               bias;
 119 char                creation_date[9];
 120 char                creation_time[8];
 121 char                file_label[64];
 122 char                padding[3];
 123 @end example
 124
 125 @table @code
 126 @item char rec_type[4];
 127 Record type code, set to @samp{$FL2}.
 128
 129 @item char prod_name[60];
 130 Product identification string.  This always begins with the characters
 131 @samp{@@(#) SPSS DATA FILE}.  PSPP uses the remaining characters to
 132 give its version and the operating system name; for example, @samp{GNU
 133 pspp 0.1.4 - sparc-sun-solaris2.5.2}.  The string is truncated if it
 134 would be longer than 60 characters; otherwise it is padded on the right
 135 with spaces.
 136
 137 @anchor{layout_code}
 138 @item int32 layout_code;
 139 Normally set to 2, although a few system files have been spotted in
 140 the wild with a value of 3 here.  PSPP use this value to determine the
 141 file's integer endianness (@pxref{System File Format}).
 142
 143 @item int32 nominal_case_size;
 144 Number of data elements per case.  This is the number of variables,
 145 except that long string variables add extra data elements (one for every
 146 8 characters after the first 8).  However, string variables do not
 147 contribute to this value beyond the first 255 bytes.   Further, system
 148 files written by some systems set this value to -1.  In general, it is
 149 unsafe for systems reading system files to rely upon this value.
 150
 151 @item int32 compressed;
 152 Set to 1 if the data in the file is compressed, 0 otherwise.
 153
 154 @item int32 weight_index;
 155 If one of the variables in the data set is used as a weighting
 156 variable, set to the dictionary index of that variable, plus 1
 157 (@pxref{Dictionary Index}).  Otherwise, set to 0.
 158
 159 @item int32 ncases;
 160 Set to the number of cases in the file if it is known, or -1 otherwise.
 161
 162 In the general case it is not possible to determine the number of cases
 163 that will be output to a system file at the time that the header is
 164 written.  The way that this is dealt with is by writing the entire
 165 system file, including the header, then seeking back to the beginning of
 166 the file and writing just the @code{ncases} field.  For `files' in which
 167 this is not valid, the seek operation fails.  In this case,
 168 @code{ncases} remains -1.
 169
 170 @anchor{bias}
 171 @item flt64 bias;
 172 Compression bias, ordinarily set to 100.  Only integers between
 173 @code{1 - bias} and @code{251 - bias} can be compressed.
 174
 175 By assuming that its value is 100, PSPP uses @code{bias} to determine
 176 the file's floating-point format and endianness (@pxref{System File
 177 Format}).  If the compression bias is not 100, PSPP cannot auto-detect
 178 the floating-point format and assumes that it is IEEE 754 format with
 179 the same endianness as the system file's integers, which is correct
 180 for all known system files.
 181
 182 @item char creation_date[9];
 183 Date of creation of the system file, in @samp{dd mmm yy}
 184 format, with the month as standard English abbreviations, using an
 185 initial capital letter and following with lowercase.  If the date is not
 186 available then this field is arbitrarily set to @samp{01 Jan 70}.
 187
 188 @item char creation_time[8];
 189 Time of creation of the system file, in @samp{hh:mm:ss}
 190 format and using 24-hour time.  If the time is not available then this
 191 field is arbitrarily set to @samp{00:00:00}.
 192
 193 @item char file_label[64];
 194 File label declared by the user, if any (@pxref{FILE LABEL}).
 195 Padded on the right with spaces.
 196
 197 @item char padding[3];
 198 Ignored padding bytes to make the structure a multiple of 32 bits in
 199 length.  Set to zeros.
 200 @end table
 201
 202 @node Variable Record
 203 @section Variable Record
 204
 205 There must be one variable record for each numeric variable and each
 206 string variable with width 8 bytes or less.  String variables wider
 207 than 8 bytes have one variable record for each 8 bytes, rounding up.
 208 The first variable record for a long string specifies the variable's
 209 correct dictionary information.  Subsequent variable records for a
 210 long string are filled with dummy information: a type of -1, no
 211 variable label or missing values, print and write formats that are
 212 ignored, and an empty string as name.  A few system files have been
 213 encountered that include a variable label on dummy variable records,
 214 so readers should take care to parse dummy variable records in the
 215 same way as other variable records.
 216
 217 @anchor{Dictionary Index}
 218 The @dfn{dictionary index} of a variable is its offset in the set of
 219 variable records, including dummy variable records for long string
 220 variables.  The first variable record has a dictionary index of 0, the
 221 second has a dictionary index of 1, and so on.
 222
 223 The system file format does not directly support string variables
 224 wider than 255 bytes.  Such very long string variables are represented
 225 by a number of narrower string variables.  @xref{Very Long String
 226 Record}, for details.
 227
 228 @example
 229 int32               rec_type;
 230 int32               type;
 231 int32               has_var_label;
 232 int32               n_missing_values;
 233 int32               print;
 234 int32               write;
 235 char                name[8];
 236
 237 /* @r{Present only if @code{has_var_label} is 1.} */
 238 int32               label_len;
 239 char                label[];
 240
 241 /* @r{Present only if @code{n_missing_values} is nonzero}. */
 242 flt64               missing_values[];
 243 @end example
 244
 245 @table @code
 246 @item int32 rec_type;
 247 Record type code.  Always set to 2.
 248
 249 @item int32 type;
 250 Variable type code.  Set to 0 for a numeric variable.  For a short
 251 string variable or the first part of a long string variable, this is set
 252 to the width of the string.  For the second and subsequent parts of a
 253 long string variable, set to -1, and the remaining fields in the
 254 structure are ignored.
 255
 256 @item int32 has_var_label;
 257 If this variable has a variable label, set to 1; otherwise, set to 0.
 258
 259 @item int32 n_missing_values;
 260 If the variable has no missing values, set to 0.  If the variable has
 261 one, two, or three discrete missing values, set to 1, 2, or 3,
 262 respectively.  If the variable has a range for missing variables, set to
 263 -2; if the variable has a range for missing variables plus a single
 264 discrete value, set to -3.
 265
 266 @item int32 print;
 267 Print format for this variable.  See below.
 268
 269 @item int32 write;
 270 Write format for this variable.  See below.
 271
 272 @item char name[8];
 273 Variable name.  The variable name must begin with a capital letter or
 274 the at-sign (@samp{@@}).  Subsequent characters may also be digits, octothorpes
 275 (@samp{#}), dollar signs (@samp{$}), underscores (@samp{_}), or full
 276 stops (@samp{.}).  The variable name is padded on the right with spaces.
 277
 278 @item int32 label_len;
 279 This field is present only if @code{has_var_label} is set to 1.  It is
 280 set to the length, in characters, of the variable label, which must be a
 281 number between 0 and 120.
 282
 283 @item char label[];
 284 This field is present only if @code{has_var_label} is set to 1.  It has
 285 length @code{label_len}, rounded up to the nearest multiple of 32 bits.
 286 The first @code{label_len} characters are the variable's variable label.
 287
 288 @item flt64 missing_values[];
 289 This field is present only if @code{n_missing_values} is not 0.  It has
 290 the same number of elements as the absolute value of
 291 @code{n_missing_values}.  For discrete missing values, each element
 292 represents one missing value.  When a range is present, the first
 293 element denotes the minimum value in the range, and the second element
 294 denotes the maximum value in the range.  When a range plus a value are
 295 present, the third element denotes the additional discrete missing
 296 value.  HIGHEST and LOWEST are indicated as described in the chapter
 297 introduction.
 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 @node Value Labels Records
 397 @section Value Labels Records
 398
 399 The value label record has the following format:
 400
 401 @example
 402 int32               rec_type;
 403 int32               label_count;
 404
 405 /* @r{Repeated @code{label_cnt} times}. */
 406 char                value[8];
 407 char                label_len;
 408 char                label[];
 409 @end example
 410
 411 @table @code
 412 @item int32 rec_type;
 413 Record type.  Always set to 3.
 414
 415 @item int32 label_count;
 416 Number of value labels present in this record.
 417 @end table
 418
 419 The remaining fields are repeated @code{count} times.  Each
 420 repetition specifies one value label.
 421
 422 @table @code
 423 @item char value[8];
 424 A numeric value or a short string value padded as necessary to 8 bytes
 425 in length.  Its type and width cannot be determined until the
 426 following value label variables record (see below) is read.
 427
 428 @item char label_len;
 429 The label's length, in bytes.
 430
 431 @item char label[];
 432 @code{label_len} bytes of the actual label, followed by up to 7 bytes
 433 of padding to bring @code{label} and @code{label_len} together to a
 434 multiple of 8 bytes in length.
 435 @end table
 436
 437 The value label record is always immediately followed by a value label
 438 variables record with the following format:
 439
 440 @example
 441 int32               rec_type;
 442 int32               var_count;
 443 int32               vars[];
 444 @end example
 445
 446 @table @code
 447 @item int32 rec_type;
 448 Record type.  Always set to 4.
 449
 450 @item int32 var_count;
 451 Number of variables that the associated value labels from the value
 452 label record are to be applied.
 453
 454 @item int32 vars[];
 455 A list of dictionary indexes of variables to which to apply the value
 456 labels (@pxref{Dictionary Index}).  There are @code{var_count}
 457 elements.
 458
 459 String variables wider than 8 bytes may not have value labels.
 460 @end table
 461
 462 @node Document Record
 463 @section Document Record
 464
 465 The document record, if present, has the following format:
 466
 467 @example
 468 int32               rec_type;
 469 int32               n_lines;
 470 char                lines[][80];
 471 @end example
 472
 473 @table @code
 474 @item int32 rec_type;
 475 Record type.  Always set to 6.
 476
 477 @item int32 n_lines;
 478 Number of lines of documents present.
 479
 480 @item char lines[][80];
 481 Document lines.  The number of elements is defined by @code{n_lines}.
 482 Lines shorter than 80 characters are padded on the right with spaces.
 483 @end table
 484
 485 @node Machine Integer Info Record
 486 @section Machine Integer Info Record
 487
 488 The integer info record, if present, has the following format:
 489
 490 @example
 491 /* @r{Header.} */
 492 int32               rec_type;
 493 int32               subtype;
 494 int32               size;
 495 int32               count;
 496
 497 /* @r{Data.} */
 498 int32               version_major;
 499 int32               version_minor;
 500 int32               version_revision;
 501 int32               machine_code;
 502 int32               floating_point_rep;
 503 int32               compression_code;
 504 int32               endianness;
 505 int32               character_code;
 506 @end example
 507
 508 @table @code
 509 @item int32 rec_type;
 510 Record type.  Always set to 7.
 511
 512 @item int32 subtype;
 513 Record subtype.  Always set to 3.
 514
 515 @item int32 size;
 516 Size of each piece of data in the data part, in bytes.  Always set to 4.
 517
 518 @item int32 count;
 519 Number of pieces of data in the data part.  Always set to 8.
 520
 521 @item int32 version_major;
 522 PSPP major version number.  In version @var{x}.@var{y}.@var{z}, this
 523 is @var{x}.
 524
 525 @item int32 version_minor;
 526 PSPP minor version number.  In version @var{x}.@var{y}.@var{z}, this
 527 is @var{y}.
 528
 529 @item int32 version_revision;
 530 PSPP version revision number.  In version @var{x}.@var{y}.@var{z},
 531 this is @var{z}.
 532
 533 @item int32 machine_code;
 534 Machine code.  PSPP always set this field to value to -1, but other
 535 values may appear.
 536
 537 @item int32 floating_point_rep;
 538 Floating point representation code.  For IEEE 754 systems this is 1.
 539 IBM 370 sets this to 2, and DEC VAX E to 3.
 540
 541 @item int32 compression_code;
 542 Compression code.  Always set to 1.
 543
 544 @item int32 endianness;
 545 Machine endianness.  1 indicates big-endian, 2 indicates little-endian.
 546
 547 @item int32 character_code;
 548 Character code.  1 indicates EBCDIC, 2 indicates 7-bit ASCII, 3
 549 indicates 8-bit ASCII, 4 indicates DEC Kanji.
 550 Windows code page numbers are also valid.
 551 @end table
 552
 553 @node Machine Floating-Point Info Record
 554 @section Machine Floating-Point Info Record
 555
 556 The floating-point info record, if present, has the following format:
 557
 558 @example
 559 /* @r{Header.} */
 560 int32               rec_type;
 561 int32               subtype;
 562 int32               size;
 563 int32               count;
 564
 565 /* @r{Data.} */
 566 flt64               sysmis;
 567 flt64               highest;
 568 flt64               lowest;
 569 @end example
 570
 571 @table @code
 572 @item int32 rec_type;
 573 Record type.  Always set to 7.
 574
 575 @item int32 subtype;
 576 Record subtype.  Always set to 4.
 577
 578 @item int32 size;
 579 Size of each piece of data in the data part, in bytes.  Always set to 8.
 580
 581 @item int32 count;
 582 Number of pieces of data in the data part.  Always set to 3.
 583
 584 @item flt64 sysmis;
 585 The system missing value.
 586
 587 @item flt64 highest;
 588 The value used for HIGHEST in missing values.
 589
 590 @item flt64 lowest;
 591 The value used for LOWEST in missing values.
 592 @end table
 593
 594 @node Variable Display Parameter Record
 595 @section Variable Display Parameter Record
 596
 597 The variable display parameter record, if present, has the following
 598 format:
 599
 600 @example
 601 /* @r{Header.} */
 602 int32               rec_type;
 603 int32               subtype;
 604 int32               size;
 605 int32               count;
 606
 607 /* @r{Repeated @code{count} times}. */
 608 int32               measure;
 609 int32               width;
 610 int32               alignment;
 611 @end example
 612
 613 @table @code
 614 @item int32 rec_type;
 615 Record type.  Always set to 7.
 616
 617 @item int32 subtype;
 618 Record subtype.  Always set to 11.
 619
 620 @item int32 size;
 621 The size of @code{int32}.  Always set to 4.
 622
 623 @item int32 count;
 624 The number of sets of variable display parameters (ordinarily the
 625 number of variables in the dictionary), times 3.
 626 @end table
 627
 628 The remaining members are repeated @code{count} times, in the same
 629 order as the variable records.  No element corresponds to variable
 630 records that continue long string variables.  The meanings of these
 631 members are as follows:
 632
 633 @table @code
 634 @item int32 measure;
 635 The measurement type of the variable:
 636 @table @asis
 637 @item 1
 638 Nominal Scale
 639 @item 2
 640 Ordinal Scale
 641 @item 3
 642 Continuous Scale
 643 @end table
 644
 645 SPSS 14 sometimes writes a @code{measure} of 0.  PSPP interprets this
 646 as nominal scale.
 647
 648 @item int32 width;
 649 The width of the display column for the variable in characters.
 650
 651 @item int32 alignment;
 652 The alignment of the variable for display purposes:
 653
 654 @table @asis
 655 @item 0
 656 Left aligned
 657 @item 1
 658 Right aligned
 659 @item 2
 660 Centre aligned
 661 @end table
 662 @end table
 663
 664 @node Long Variable Names Record
 665 @section Long Variable Names Record
 666
 667 If present, the long variable names record has the following format:
 668
 669 @example
 670 /* @r{Header.} */
 671 int32               rec_type;
 672 int32               subtype;
 673 int32               size;
 674 int32               count;
 675
 676 /* @r{Exactly @code{count} bytes of data.} */
 677 char                var_name_pairs[];
 678 @end example
 679
 680 @table @code
 681 @item int32 rec_type;
 682 Record type.  Always set to 7.
 683
 684 @item int32 subtype;
 685 Record subtype.  Always set to 13.
 686
 687 @item int32 size;
 688 The size of each element in the @code{var_name_pairs} member. Always set to 1.
 689
 690 @item int32 count;
 691 The total number of bytes in @code{var_name_pairs}.
 692
 693 @item char var_name_pairs[];
 694 A list of @var{key}--@var{value} tuples, where @var{key} is the name
 695 of a variable, and @var{value} is its long variable name.
 696 The @var{key} field is at most 8 bytes long and must match the
 697 name of a variable which appears in the variable record (@pxref{Variable
 698 Record}).
 699 The @var{value} field is at most 64 bytes long.
 700 The @var{key} and @var{value} fields are separated by a @samp{=} byte.
 701 Each tuple is separated by a byte whose value is 09.  There is no
 702 trailing separator following the last tuple.
 703 The total length is @code{count} bytes.
 704 @end table
 705
 706 @node Very Long String Record
 707 @section Very Long String Record
 708
 709 Old versions of SPSS limited string variables to a width of 255 bytes.
 710 For backward compatibility with these older versions, the system file
 711 format represents a string longer than 255 bytes, called a @dfn{very
 712 long string}, as a collection of strings no longer than 255 bytes
 713 each.  The strings concatenated to make a very long string are called
 714 its @dfn{segments}; for consistency, variables other than very long
 715 strings are considered to have a single segment.
 716
 717 A very long string with a width of @var{w} has @var{n} =
 718 (@var{w} + 251) / 252 segments, that is, one segment for every
 719 252 bytes of width, rounding up.  It would be logical, then, for each
 720 of the segments except the last to have a width of 252 and the last
 721 segment to have the remainder, but this is not the case.  In fact,
 722 each segment except the last has a width of 255 bytes.  The last
 723 segment has width @var{w} - (@var{n} - 1) * 252; some versions
 724 of SPSS make it slightly wider, but not wide enough to make the last
 725 segment require another 8 bytes of data.
 726
 727 Data is packed tightly into segments of a very long string, 255 bytes
 728 per segment.  Because 255 bytes of segment data are allocated for
 729 every 252 bytes of the very long string's width (approximately), some
 730 unused space is left over at the end of the allocated segments.  Data
 731 in unused space is ignored.
 732
 733 Example: Consider a very long string of width 20,000.  Such a very
 734 long string has 20,000 / 252 = 80 (rounding up) segments.  The first
 735 79 segments have width 255; the last segment has width 20,000 - 79 *
 736 252 = 92 or slightly wider (up to 96 bytes, the next multiple of 8).
 737 The very long string's data is actually stored in the 19,890 bytes in
 738 the first 78 segments, plus the first 110 bytes of the 79th segment
 739 (19,890 + 110 = 20,000).  The remaining 145 bytes of the 79th segment
 740 and all 92 bytes of the 80th segment are unused.
 741
 742 The very long string record explains how to stitch together segments
 743 to obtain very long string data.  For each of the very long string
 744 variables in the dictionary, it specifies the name of its first
 745 segment's variable and the very long string variable's actual width.
 746 The remaining segments immediately follow the named variable in the
 747 system file's dictionary.
 748
 749 The very long string record, which is present only if the system file
 750 contains very long string variables, has the following format:
 751
 752 @example
 753 /* @r{Header.} */
 754 int32               rec_type;
 755 int32               subtype;
 756 int32               size;
 757 int32               count;
 758
 759 /* @r{Exactly @code{count} bytes of data.} */
 760 char                string_lengths[];
 761 @end example
 762
 763 @table @code
 764 @item int32 rec_type;
 765 Record type.  Always set to 7.
 766
 767 @item int32 subtype;
 768 Record subtype.  Always set to 14.
 769
 770 @item int32 size;
 771 The size of each element in the @code{string_lengths} member. Always set to 1.
 772
 773 @item int32 count;
 774 The total number of bytes in @code{string_lengths}.
 775
 776 @item char string_lengths[];
 777 A list of @var{key}--@var{value} tuples, where @var{key} is the name
 778 of a variable, and @var{value} is its length.
 779 The @var{key} field is at most 8 bytes long and must match the
 780 name of a variable which appears in the variable record (@pxref{Variable
 781 Record}).
 782 The @var{value} field is exactly 5 bytes long. It is a zero-padded,
 783 ASCII-encoded string that is the length of the variable.
 784 The @var{key} and @var{value} fields are separated by a @samp{=} byte.
 785 Tuples are delimited by a two-byte sequence @{00, 09@}.
 786 After the last tuple, there may be a single byte 00, or @{00, 09@}.
 787 The total length is @code{count} bytes.
 788 @end table
 789
 790 @node Miscellaneous Informational Records
 791 @section Miscellaneous Informational Records
 792
 793 Some specific types of miscellaneous informational records are
 794 documented here, but others are known to exist.  PSPP ignores unknown
 795 miscellaneous informational records when reading system files.
 796
 797 @example
 798 /* @r{Header.} */
 799 int32               rec_type;
 800 int32               subtype;
 801 int32               size;
 802 int32               count;
 803
 804 /* @r{Exactly @code{size * count} bytes of data.} */
 805 char                data[];
 806 @end example
 807
 808 @table @code
 809 @item int32 rec_type;
 810 Record type.  Always set to 7.
 811
 812 @item int32 subtype;
 813 Record subtype.  May take any value.  According to Aapi
 814 H@"am@"al@"ainen, value 5 indicates a set of grouped variables and 6
 815 indicates date info (probably related to USE).
 816
 817 @item int32 size;
 818 Size of each piece of data in the data part.  Should have the value 1,
 819 4, or 8, for @code{char}, @code{int32}, and @code{flt64} format data,
 820 respectively.
 821
 822 @item int32 count;
 823 Number of pieces of data in the data part.
 824
 825 @item char data[];
 826 Arbitrary data.  There must be @code{size} times @code{count} bytes of
 827 data.
 828 @end table
 829
 830 @node Dictionary Termination Record
 831 @section Dictionary Termination Record
 832
 833 The dictionary termination record separates all other records from the
 834 data records.
 835
 836 @example
 837 int32               rec_type;
 838 int32               filler;
 839 @end example
 840
 841 @table @code
 842 @item int32 rec_type;
 843 Record type.  Always set to 999.
 844
 845 @item int32 filler;
 846 Ignored padding.  Should be set to 0.
 847 @end table
 848
 849 @node Data Record
 850 @section Data Record
 851
 852 Data records must follow all other records in the system file.  There must
 853 be at least one data record in every system file.
 854
 855 The format of data records varies depending on whether the data is
 856 compressed.  Regardless, the data is arranged in a series of 8-byte
 857 elements.
 858
 859 When data is not compressed,
 860 each element corresponds to
 861 the variable declared in the respective variable record (@pxref{Variable
 862 Record}).  Numeric values are given in @code{flt64} format; string
 863 values are literal characters string, padded on the right when
 864 necessary to fill out 8-byte units.
 865
 866 Compressed data is arranged in the following manner: the first 8 bytes
 867 in the data section is divided into a series of 1-byte command
 868 codes.  These codes have meanings as described below:
 869
 870 @table @asis
 871 @item 0
 872 Ignored.  If the program writing the system file accumulates compressed
 873 data in blocks of fixed length, 0 bytes can be used to pad out extra
 874 bytes remaining at the end of a fixed-size block.
 875
 876 @item 1 through 251
 877 A number with
 878 value @var{code} - @var{bias}, where
 879 @var{code} is the value of the compression code and @var{bias} is the
 880 variable @code{bias} from the file header.  For example,
 881 code 105 with bias 100.0 (the normal value) indicates a numeric variable
 882 of value 5.
 883
 884 @item 252
 885 End of file.  This code may or may not appear at the end of the data
 886 stream.  PSPP always outputs this code but its use is not required.
 887
 888 @item 253
 889 A numeric or string value that is not
 890 compressible.  The value is stored in the 8 bytes following the
 891 current block of command bytes.  If this value appears twice in a block
 892 of command bytes, then it indicates the second group of 8 bytes following the
 893 command bytes, and so on.
 894
 895 @item 254
 896 An 8-byte string value that is all spaces.
 897
 898 @item 255
 899 The system-missing value.
 900 @end table
 901
 902 When the end of the an 8-byte group of command bytes is reached, any
 903 blocks of non-compressible values indicated by code 253 are skipped,
 904 and the next element of command bytes is read and interpreted, until
 905 the end of the file or a code with value 252 is reached.
 906 @setfilename ignored