doc/data-file-format.texi

   1 @node Data File Format, q2c Input Format, Portable File Format, Top
   2 @appendix Data File Format
   3
   4 PSPP necessarily uses the same format for system files as do the
   5 products with which it is compatible.  This chapter is a description of
   6 that format.
   7
   8 There are three data types used in system files: 32-bit integers, 64-bit
   9 floating points, and 1-byte characters.  In this document these will
  10 simply be referred to as @code{int32}, @code{flt64}, and @code{char},
  11 the names that are used in the PSPP source code.  Every field of type
  12 @code{int32} or @code{flt64} is aligned on a 32-bit boundary.
  13
  14 The endianness of data in PSPP system files is not specified.  System
  15 files output on a computer of a particular endianness will have the
  16 endianness of that computer.  However, PSPP can read files of either
  17 endianness, regardless of its host computer's endianness.  PSPP
  18 translates endianness for both integer and floating point numbers.
  19
  20 Floating point formats are also not specified.  PSPP does not
  21 translate between floating point formats.  This is unlikely to be a
  22 problem as all modern computer architectures use IEEE 754 format for
  23 floating point representation.
  24
  25 The PSPP system-missing value is represented by the largest possible
  26 negative number in the floating point format; in C, this is most likely
  27 @code{-DBL_MAX}.  There are two other important values used in missing
  28 values: @code{HIGHEST} and @code{LOWEST}.  These are represented by the
  29 largest possible positive number (probably @code{DBL_MAX}) and the
  30 second-largest negative number.  The latter must be determined in a
  31 system-dependent manner; in IEEE 754 format it is represented by value
  32 @code{0xffeffffffffffffe}.
  33
  34 System files are divided into records.  Each record begins with an
  35 @code{int32} giving a numeric record type.  Individual record types are
  36 described below:
  37
  38 @menu
  39 * File Header Record::
  40 * Variable Record::
  41 * Value Label Record::
  42 * Value Label Variable Record::
  43 * Document Record::
  44 * Machine int32 Info Record::
  45 * Machine flt64 Info Record::
  46 * Miscellaneous Informational Records::
  47 * Dictionary Termination Record::
  48 * Data Record::
  49 @end menu
  50
  51 @node File Header Record, Variable Record, Data File Format, Data File Format
  52 @section File Header Record
  53
  54 The file header is always the first record in the file.
  55
  56 @example
  57 struct sysfile_header
  58   @{
  59     char                rec_type[4];
  60     char                prod_name[60];
  61     int32               layout_code;
  62     int32               case_size;
  63     int32               compressed;
  64     int32               weight_index;
  65     int32               ncases;
  66     flt64               bias;
  67     char                creation_date[9];
  68     char                creation_time[8];
  69     char                file_label[64];
  70     char                padding[3];
  71   @};
  72 @end example
  73
  74 @table @code
  75 @item char rec_type[4];
  76 Record type code.  Always set to @samp{$FL2}.  This is the only record
  77 for which the record type is not of type @code{int32}.
  78
  79 @item char prod_name[60];
  80 Product identification string.  This always begins with the characters
  81 @samp{@@(#) SPSS DATA FILE}.  PSPP uses the remaining characters to
  82 give its version and the operating system name; for example, @samp{GNU
  83 pspp 0.1.4 - sparc-sun-solaris2.5.2}.  The string is truncated if it
  84 would be longer than 60 characters; otherwise it is padded on the right
  85 with spaces.
  86
  87 @item int32 layout_code;
  88 Always set to 2.  PSPP reads this value to determine the
  89 file's endianness.
  90
  91 @item int32 case_size;
  92 Number of data elements per case.  This is the number of variables,
  93 except that long string variables add extra data elements (one for every
  94 8 characters after the first 8).
  95
  96 @item int32 compressed;
  97 Set to 1 if the data in the file is compressed, 0 otherwise.
  98
  99 @item int32 weight_index;
 100 If one of the variables in the data set is used as a weighting variable,
 101 set to the index of that variable.  Otherwise, set to 0.
 102
 103 @item int32 ncases;
 104 Set to the number of cases in the file if it is known, or -1 otherwise.
 105
 106 In the general case it is not possible to determine the number of cases
 107 that will be output to a system file at the time that the header is
 108 written.  The way that this is dealt with is by writing the entire
 109 system file, including the header, then seeking back to the beginning of
 110 the file and writing just the @code{ncases} field.  For `files' in which
 111 this is not valid, the seek operation fails.  In this case,
 112 @code{ncases} remains -1.
 113
 114 @item flt64 bias;
 115 Compression bias.  Always set to 100.  The significance of this value is
 116 that only numbers between @code{(1 - bias)} and @code{(251 - bias)} can
 117 be compressed.
 118
 119 @item char creation_date[9];
 120 Set to the date of creation of the system file, in @samp{dd mmm yy}
 121 format, with the month as standard English abbreviations, using an
 122 initial capital letter and following with lowercase.  If the date is not
 123 available then this field is arbitrarily set to @samp{01 Jan 70}.
 124
 125 @item char creation_time[8];
 126 Set to the time of creation of the system file, in @samp{hh:mm:ss}
 127 format and using 24-hour time.  If the time is not available then this
 128 field is arbitrarily set to @samp{00:00:00}.
 129
 130 @item char file_label[64];
 131 Set the the file label declared by the user, if any.  Padded on the
 132 right with spaces.
 133
 134 @item char padding[3];
 135 Ignored padding bytes to make the structure a multiple of 32 bits in
 136 length.  Set to zeros.
 137 @end table
 138
 139 @node Variable Record, Value Label Record, File Header Record, Data File Format
 140 @section Variable Record
 141
 142 Immediately following the header must come the variable records.  There
 143 must be one variable record for every variable and every 8 characters in
 144 a long string beyond the first 8; i.e., there must be exactly as many
 145 variable records as the value specified for @code{case_size} in the file
 146 header record.
 147
 148 @example
 149 struct sysfile_variable
 150   @{
 151     int32               rec_type;
 152     int32               type;
 153     int32               has_var_label;
 154     int32               n_missing_values;
 155     int32               print;
 156     int32               write;
 157     char                name[8];
 158
 159     /* The following two fields are present
 160        only if has_var_label is 1. */
 161     int32               label_len;
 162     char                label[/* variable length */];
 163
 164     /* The following field is present only
 165        if n_missing_values is not 0. */
 166     flt64               missing_values[/* variable length*/];
 167   @};
 168 @end example
 169
 170 @table @code
 171 @item int32 rec_type;
 172 Record type code.  Always set to 2.
 173
 174 @item int32 type;
 175 Variable type code.  Set to 0 for a numeric variable.  For a short
 176 string variable or the first part of a long string variable, this is set
 177 to the width of the string.  For the second and subsequent parts of a
 178 long string variable, set to -1, and the remaining fields in the
 179 structure are ignored.
 180
 181 @item int32 has_var_label;
 182 If this variable has a variable label, set to 1; otherwise, set to 0.
 183
 184 @item int32 n_missing_values;
 185 If the variable has no missing values, set to 0.  If the variable has
 186 one, two, or three discrete missing values, set to 1, 2, or 3,
 187 respectively.  If the variable has a range for missing variables, set to
 188 -2; if the variable has a range for missing variables plus a single
 189 discrete value, set to -3.
 190
 191 @item int32 print;
 192 Print format for this variable.  See below.
 193
 194 @item int32 write;
 195 Write format for this variable.  See below.
 196
 197 @item char name[8];
 198 Variable name.  The variable name must begin with a capital letter or
 199 the at-sign (@samp{@@}).  Subsequent characters may also be octothorpes
 200 (@samp{#}), dollar signs (@samp{$}), underscores (@samp{_}), or full
 201 stops (@samp{.}).  The variable name is padded on the right with spaces.
 202
 203 @item int32 label_len;
 204 This field is present only if @code{has_var_label} is set to 1.  It is
 205 set to the length, in characters, of the variable label, which must be a
 206 number between 0 and 120.
 207
 208 @item char label[/* variable length */];
 209 This field is present only if @code{has_var_label} is set to 1.  It has
 210 length @code{label_len}, rounded up to the nearest multiple of 32 bits.
 211 The first @code{label_len} characters are the variable's variable label.
 212
 213 @item flt64 missing_values[/* variable length */];
 214 This field is present only if @code{n_missing_values} is not 0.  It has
 215 the same number of elements as the absolute value of
 216 @code{n_missing_values}.  For discrete missing values, each element
 217 represents one missing value.  When a range is present, the first
 218 element denotes the minimum value in the range, and the second element
 219 denotes the maximum value in the range.  When a range plus a value are
 220 present, the third element denotes the additional discrete missing
 221 value.  HIGHEST and LOWEST are indicated as described in the chapter
 222 introduction.
 223 @end table
 224
 225 The @code{print} and @code{write} members of sysfile_variable are output
 226 formats coded into @code{int32} types.  The LSB (least-significant byte)
 227 of the @code{int32} represents the number of decimal places, and the
 228 next two bytes in order of increasing significance represent field width
 229 and format type, respectively.  The MSB (most-significant byte) is not
 230 used and should be set to zero.
 231
 232 Format types are defined as follows:
 233 @table @asis
 234 @item 0
 235 Not used.
 236 @item 1
 237 @code{A}
 238 @item 2
 239 @code{AHEX}
 240 @item 3
 241 @code{COMMA}
 242 @item 4
 243 @code{DOLLAR}
 244 @item 5
 245 @code{F}
 246 @item 6
 247 @code{IB}
 248 @item 7
 249 @code{PIBHEX}
 250 @item 8
 251 @code{P}
 252 @item 9
 253 @code{PIB}
 254 @item 10
 255 @code{PK}
 256 @item 11
 257 @code{RB}
 258 @item 12
 259 @code{RBHEX}
 260 @item 13
 261 Not used.
 262 @item 14
 263 Not used.
 264 @item 15
 265 @code{Z}
 266 @item 16
 267 @code{N}
 268 @item 17
 269 @code{E}
 270 @item 18
 271 Not used.
 272 @item 19
 273 Not used.
 274 @item 20
 275 @code{DATE}
 276 @item 21
 277 @code{TIME}
 278 @item 22
 279 @code{DATETIME}
 280 @item 23
 281 @code{ADATE}
 282 @item 24
 283 @code{JDATE}
 284 @item 25
 285 @code{DTIME}
 286 @item 26
 287 @code{WKDAY}
 288 @item 27
 289 @code{MONTH}
 290 @item 28
 291 @code{MOYR}
 292 @item 29
 293 @code{QYR}
 294 @item 30
 295 @code{WKYR}
 296 @item 31
 297 @code{PCT}
 298 @item 32
 299 @code{DOT}
 300 @item 33
 301 @code{CCA}
 302 @item 34
 303 @code{CCB}
 304 @item 35
 305 @code{CCC}
 306 @item 36
 307 @code{CCD}
 308 @item 37
 309 @code{CCE}
 310 @item 38
 311 @code{EDATE}
 312 @item 39
 313 @code{SDATE}
 314 @end table
 315
 316 @node Value Label Record, Value Label Variable Record, Variable Record, Data File Format
 317 @section Value Label Record
 318
 319 Value label records must follow the variable records and must precede
 320 the header termination record.  Other than this, they may appear
 321 anywhere in the system file.  Every value label record must be
 322 immediately followed by a label variable record, described below.
 323
 324 Value label records begin with @code{rec_type}, an @code{int32} value
 325 set to the record type of 3.  This is followed by @code{count}, an
 326 @code{int32} value set to the number of value labels present in this
 327 record.
 328
 329 These two fields are followed by a series of @code{count} tuples.  Each
 330 tuple is divided into two fields, the value and the label.  The first of
 331 these, the value, is composed of a 64-bit value, which is either a
 332 @code{flt64} value or up to 8 characters (padded on the right to 8
 333 bytes) denoting a short string value.  Whether the value is a
 334 @code{flt64} or a character string is not defined inside the value label
 335 record.
 336
 337 The second field in the tuple, the label, has variable length.  The
 338 first @code{char} is a count of the number of characters in the value
 339 label.  The remainder of the field is the label itself.  The field is
 340 padded on the right to a multiple of 64 bits in length.
 341
 342 @node Value Label Variable Record, Document Record, Value Label Record, Data File Format
 343 @section Value Label Variable Record
 344
 345 Every value label variable record must be immediately preceded by a
 346 value label record, described above.
 347
 348 @example
 349 struct sysfile_value_label_variable
 350   @{
 351      int32              rec_type;
 352      int32              count;
 353      int32              vars[/* variable length */];
 354   @};
 355 @end example
 356
 357 @table @code
 358 @item int32 rec_type;
 359 Record type.  Always set to 4.
 360
 361 @item int32 count;
 362 Number of variables that the associated value labels from the value
 363 label record are to be applied.
 364
 365 @item int32 vars[/* variable length];
 366 A list of variables to which to apply the value labels.  There are
 367 @code{count} elements.
 368 @end table
 369
 370 @node Document Record, Machine int32 Info Record, Value Label Variable Record, Data File Format
 371 @section Document Record
 372
 373 There must be no more than one document record per system file.
 374 Document records must follow the variable records and precede the
 375 dictionary termination record.
 376
 377 @example
 378 struct sysfile_document
 379   @{
 380     int32               rec_type;
 381     int32               n_lines;
 382     char                lines[/* variable length */][80];
 383   @};
 384 @end example
 385
 386 @table @code
 387 @item int32 rec_type;
 388 Record type.  Always set to 6.
 389
 390 @item int32 n_lines;
 391 Number of lines of documents present.
 392
 393 @item char lines[/* variable length */][80];
 394 Document lines.  The number of elements is defined by @code{n_lines}.
 395 Lines shorter than 80 characters are padded on the right with spaces.
 396 @end table
 397
 398 @node Machine int32 Info Record, Machine flt64 Info Record, Document Record, Data File Format
 399 @section Machine @code{int32} Info Record
 400
 401 There must be no more than one machine @code{int32} info record per
 402 system file.  Machine @code{int32} info records must follow the variable
 403 records and precede the dictionary termination record.
 404
 405 @example
 406 struct sysfile_machine_int32_info
 407   @{
 408     /* Header. */
 409     int32               rec_type;
 410     int32               subtype;
 411     int32               size;
 412     int32               count;
 413
 414     /* Data. */
 415     int32               version_major;
 416     int32               version_minor;
 417     int32               version_revision;
 418     int32               machine_code;
 419     int32               floating_point_rep;
 420     int32               compression_code;
 421     int32               endianness;
 422     int32               character_code;
 423   @};
 424 @end example
 425
 426 @table @code
 427 @item int32 rec_type;
 428 Record type.  Always set to 7.
 429
 430 @item int32 subtype;
 431 Record subtype.  Always set to 3.
 432
 433 @item int32 size;
 434 Size of each piece of data in the data part, in bytes.  Always set to 4.
 435
 436 @item int32 count;
 437 Number of pieces of data in the data part.  Always set to 8.
 438
 439 @item int32 version_major;
 440 PSPP major version number.  In version @var{x}.@var{y}.@var{z}, this
 441 is @var{x}.
 442
 443 @item int32 version_minor;
 444 PSPP minor version number.  In version @var{x}.@var{y}.@var{z}, this
 445 is @var{y}.
 446
 447 @item int32 version_revision;
 448 PSPP version revision number.  In version @var{x}.@var{y}.@var{z},
 449 this is @var{z}.
 450
 451 @item int32 machine_code;
 452 Machine code.  PSPP always set this field to value to -1, but other
 453 values may appear.
 454
 455 @item int32 floating_point_rep;
 456 Floating point representation code.  For IEEE 754 systems this is 1.
 457 IBM 370 sets this to 2, and DEC VAX E to 3.
 458
 459 @item int32 compression_code;
 460 Compression code.  Always set to 1.
 461
 462 @item int32 endianness;
 463 Machine endianness.  1 indicates big-endian, 2 indicates little-endian.
 464
 465 @item int32 character_code;
 466 Character code.  1 indicates EBCDIC, 2 indicates 7-bit ASCII, 3
 467 indicates 8-bit ASCII, 4 indicates DEC Kanji.
 468 @end table
 469
 470 @node Machine flt64 Info Record, Miscellaneous Informational Records, Machine int32 Info Record, Data File Format
 471 @section Machine @code{flt64} Info Record
 472
 473 There must be no more than one machine @code{flt64} info record per
 474 system file.  Machine @code{flt64} info records must follow the variable
 475 records and precede the dictionary termination record.
 476
 477 @example
 478 struct sysfile_machine_flt64_info
 479   @{
 480     /* Header. */
 481     int32               rec_type;
 482     int32               subtype;
 483     int32               size;
 484     int32               count;
 485
 486     /* Data. */
 487     flt64               sysmis;
 488     flt64               highest;
 489     flt64               lowest;
 490   @};
 491 @end example
 492
 493 @table @code
 494 @item int32 rec_type;
 495 Record type.  Always set to 7.
 496
 497 @item int32 subtype;
 498 Record subtype.  Always set to 4.
 499
 500 @item int32 size;
 501 Size of each piece of data in the data part, in bytes.  Always set to 4.
 502
 503 @item int32 count;
 504 Number of pieces of data in the data part.  Always set to 3.
 505
 506 @item flt64 sysmis;
 507 The system missing value.
 508
 509 @item flt64 highest;
 510 The value used for HIGHEST in missing values.
 511
 512 @item flt64 lowest;
 513 The value used for LOWEST in missing values.
 514 @end table
 515
 516 @node Miscellaneous Informational Records, Dictionary Termination Record, Machine flt64 Info Record, Data File Format
 517 @section Miscellaneous Informational Records
 518
 519 Miscellaneous informational records must follow the variable records and
 520 precede the dictionary termination record.
 521
 522 Miscellaneous informational records are ignored by PSPP when reading
 523 system files.  They are not written by PSPP when writing system files.
 524
 525 @example
 526 struct sysfile_misc_info
 527   @{
 528     /* Header. */
 529     int32               rec_type;
 530     int32               subtype;
 531     int32               size;
 532     int32               count;
 533
 534     /* Data. */
 535     char                data[/* variable length */];
 536   @};
 537 @end example
 538
 539 @table @code
 540 @item int32 rec_type;
 541 Record type.  Always set to 7.
 542
 543 @item int32 subtype;
 544 Record subtype.  May take any value.  According to Aapi
 545 H@"am@"al@"ainen, value 5 indicates a set of grouped variables and 6
 546 indicates date info (probably related to USE).
 547
 548 @item int32 size;
 549 Size of each piece of data in the data part.  Should have the value 4 or
 550 8, for @code{int32} and @code{flt64}, respectively.
 551
 552 @item int32 count;
 553 Number of pieces of data in the data part.
 554
 555 @item char data[/* variable length */];
 556 Arbitrary data.  There must be @code{size} times @code{count} bytes of
 557 data.
 558 @end table
 559
 560 @node Dictionary Termination Record, Data Record, Miscellaneous Informational Records, Data File Format
 561 @section Dictionary Termination Record
 562
 563 The dictionary termination record must follow all other records, except
 564 for the actual cases, which it must precede.  There must be exactly one
 565 dictionary termination record in every system file.
 566
 567 @example
 568 struct sysfile_dict_term
 569   @{
 570     int32               rec_type;
 571     int32               filler;
 572   @};
 573 @end example
 574
 575 @table @code
 576 @item int32 rec_type;
 577 Record type.  Always set to 999.
 578
 579 @item int32 filler;
 580 Ignored padding.  Should be set to 0.
 581 @end table
 582
 583 @node Data Record,  , Dictionary Termination Record, Data File Format
 584 @section Data Record
 585
 586 Data records must follow all other records in the data file.  There must
 587 be at least one data record in every system file.
 588
 589 The format of data records varies depending on whether the data is
 590 compressed.  Regardless, the data is arranged in a series of 8-byte
 591 elements.
 592
 593 When data is not compressed, Every case is composed of @code{case_size}
 594 of these 8-byte elements, where @code{case_size} comes from the file
 595 header record (@pxref{File Header Record}).  Each element corresponds to
 596 the variable declared in the respective variable record (@pxref{Variable
 597 Record}).  Numeric values are given in @code{flt64} format; string
 598 values are literal characters string, padded on the right when
 599 necessary.
 600
 601 Compressed data is arranged in the following manner: the first 8-byte
 602 element in the data section is divided into a series of 1-byte command
 603 codes.  These codes have meanings as described below:
 604
 605 @table @asis
 606 @item 0
 607 Ignored.  If the program writing the system file accumulates compressed
 608 data in blocks of fixed length, 0 bytes can be used to pad out extra
 609 bytes remaining at the end of a fixed-size block.
 610
 611 @item 1 through 251
 612 These values indicate that the corresponding numeric variable has the
 613 value @code{(@var{code} - @var{bias})} for the case being read, where
 614 @var{code} is the value of the compression code and @var{bias} is the
 615 variable @code{compression_bias} from the file header.  For example,
 616 code 105 with bias 100.0 (the normal value) indicates a numeric variable
 617 of value 5.
 618
 619 @item 252
 620 End of file.  This code may or may not appear at the end of the data
 621 stream.  PSPP always outputs this code but its use is not required.
 622
 623 @item 253
 624 This value indicates that the numeric or string value is not
 625 compressible.  The value is stored in the 8-byte element following the
 626 current block of command bytes.  If this value appears twice in a block
 627 of command bytes, then it indicates the second element following the
 628 command bytes, and so on.
 629
 630 @item 254
 631 Used to indicate a string value that is all spaces.
 632
 633 @item 255
 634 Used to indicate the system-missing value.
 635 @end table
 636
 637 When the end of the first 8-byte element of command bytes is reached,
 638 any blocks of non-compressible values are skipped, and the next element
 639 of command bytes is read and interpreted, until the end of the file is
 640 reached.
 641 @setfilename ignored