LIST: Remove WEIGHT subcommand.
[pspp-builds.git] / doc / data-io.texi
1 @node Data Input and Output
2 @chapter Data Input and Output
3 @cindex input
4 @cindex output
5 @cindex data
6 @cindex cases
7 @cindex observations
8
9 Data are the focus of the PSPP language.  
10 Each datum  belongs to a @dfn{case} (also called an @dfn{observation}).
11 Each case represents an individual or ``experimental unit''.
12 For example, in the results of a survey, the names of the respondents,
13 their sex, age, etc.@: and their responses are all data and the data
14 pertaining to single respondent is a case.
15 This chapter examines
16 the PSPP commands for defining variables and reading and writing data.
17 There are alternative commands to  read data from predefined sources
18 such as system files or databases (@xref{GET, GET DATA}.)
19
20 @quotation Note
21 These commands tell PSPP how to read data, but the data will not
22 actually be read until a procedure is executed.
23 @end quotation
24
25 @menu
26 * BEGIN DATA::                  Embed data within a syntax file.
27 * CLOSE FILE HANDLE::           Close a file handle.
28 * DATAFILE ATTRIBUTE::          Set custom attributes on data files.
29 * DATA LIST::                   Fundamental data reading command.
30 * END CASE::                    Output the current case.
31 * END FILE::                    Terminate the current input program.
32 * FILE HANDLE::                 Support for special file formats.
33 * INPUT PROGRAM::               Support for complex input programs.
34 * LIST::                        List cases in the active file.
35 * NEW FILE::                    Clear the active file and dictionary.
36 * PRINT::                       Display values in print formats.
37 * PRINT EJECT::                 Eject the current page then print.
38 * PRINT SPACE::                 Print blank lines.
39 * REREAD::                      Take another look at the previous input line.
40 * REPEATING DATA::              Multiple cases on a single line.
41 * WRITE::                       Display values in write formats.
42 @end menu
43
44 @node BEGIN DATA
45 @section BEGIN DATA
46 @vindex BEGIN DATA
47 @vindex END DATA
48 @cindex Embedding data in syntax files
49 @cindex Data, embedding in syntax files
50
51 @display
52 BEGIN DATA.
53 @dots{}
54 END DATA.
55 @end display
56
57 @cmd{BEGIN DATA} and @cmd{END DATA} can be used to embed raw ASCII
58 data in a PSPP syntax file.  @cmd{DATA LIST} or another input
59 procedure must be used before @cmd{BEGIN DATA} (@pxref{DATA LIST}).
60 @cmd{BEGIN DATA} and @cmd{END DATA} must be used together.  @cmd{END
61 DATA} must appear by itself on a single line, with no leading
62 white space and exactly one space between the words @code{END} and
63 @code{DATA}, like this:
64
65 @example
66 END DATA.
67 @end example
68
69 @node CLOSE FILE HANDLE
70 @section CLOSE FILE HANDLE
71
72 @display
73 CLOSE FILE HANDLE handle_name.
74 @end display
75
76 @cmd{CLOSE FILE HANDLE} disassociates the name of a file handle with a
77 given file.  The only specification is the name of the handle to close.
78 Afterward
79 @cmd{FILE HANDLE}.
80
81 If the file handle name refers to a scratch file, then the storage
82 associated with the scratch file in memory or on disk will be freed.
83 If the scratch file is in use, e.g.@: it has been specified on a
84 @cmd{GET} command whose execution has not completed, then freeing is
85 delayed until it is no longer in use.
86
87 The file named INLINE, which represents data entered between @cmd{BEGIN
88 DATA} and @cmd{END DATA}, cannot be closed.  Attempts to close it with
89 @cmd{CLOSE FILE HANDLE} have no effect.
90
91 @cmd{CLOSE FILE HANDLE} is a PSPP extension.
92
93 @node DATAFILE ATTRIBUTE
94 @section DATAFILE ATTRIBUTE
95 @vindex DATAFILE ATTRIBUTE
96
97 @display
98 DATAFILE ATTRIBUTE
99          ATTRIBUTE=name('value') [name('value')]@dots{}
100          ATTRIBUTE=name@b{[}index@b{]}('value') [name@b{[}index@b{]}('value')]@dots{}
101          DELETE=name [name]@dots{}
102          DELETE=name@b{[}index@b{]} [name@b{[}index@b{]}]@dots{}
103 @end display
104
105 @cmd{DATAFILE ATTRIBUTE} adds, modifies, or removes user-defined
106 attributes associated with the active file.  Custom data file
107 attributes are not interpreted by PSPP, but they are saved as part of
108 system files and may be used by other software that reads them.
109
110 Use the ATTRIBUTE subcommand to add or modify a custom data file
111 attribute.  Specify the name of the attribute as an identifier
112 (@pxref{Tokens}), followed by the desired value, in parentheses, as a
113 quoted string.  Attribute names that begin with @code{$} are reserved
114 for PSPP's internal use, and attribute names that begin with @code{@@}
115 or @code{$@@} are not displayed by most PSPP commands that display
116 other attributes.  Other attribute names are not treated specially.
117
118 Attributes may also be organized into arrays.  To assign to an array
119 element, add an integer array index enclosed in square brackets
120 (@code{[} and @code{]}) between the attribute name and value.  Array
121 indexes start at 1, not 0.  An attribute array that has a single
122 element (number 1) is not distinguished from a non-array attribute.
123
124 Use the DELETE subcommand to delete an attribute.  Specify an
125 attribute name by itself to delete an entire attribute, including all
126 array elements for attribute arrays.  Specify an attribute name
127 followed by an array index in square brackets to delete a single
128 element of an attribute array.  In the latter case, all the array
129 elements numbered higher than the deleted element are shifted down,
130 filling the vacated position.
131
132 To associate custom attributes with particular variables, instead of
133 with the entire active file, use @cmd{VARIABLE ATTRIBUTE} (@pxref{VARIABLE ATTRIBUTE}) instead.
134
135 @cmd{DATAFILE ATTRIBUTE} takes effect immediately.  It is not affected
136 by conditional and looping structures such as @cmd{DO IF} or
137 @cmd{LOOP}.
138
139 @node DATA LIST
140 @section DATA LIST
141 @vindex DATA LIST
142 @cindex reading data from a file
143 @cindex data, reading from a file
144 @cindex data, embedding in syntax files
145 @cindex embedding data in syntax files
146
147 Used to read text or binary data, @cmd{DATA LIST} is the most
148 fundamental data-reading command.  Even the more sophisticated input
149 methods use @cmd{DATA LIST} commands as a building block.
150 Understanding @cmd{DATA LIST} is important to understanding how to use
151 PSPP to read your data files.
152
153 There are two major variants of @cmd{DATA LIST}, which are fixed
154 format and free format.  In addition, free format has a minor variant,
155 list format, which is discussed in terms of its differences from vanilla
156 free format.
157
158 Each form of @cmd{DATA LIST} is described in detail below.
159
160 @xref{GET DATA}, for a command that offers a few enhancements over
161 DATA LIST and that may be substituted for DATA LIST in many
162 situations.
163
164 @menu
165 * DATA LIST FIXED::             Fixed columnar locations for data.
166 * DATA LIST FREE::              Any spacing you like.
167 * DATA LIST LIST::              Each case must be on a single line.
168 @end menu
169
170 @node DATA LIST FIXED
171 @subsection DATA LIST FIXED
172 @vindex DATA LIST FIXED
173 @cindex reading fixed-format data
174 @cindex fixed-format data, reading
175 @cindex data, fixed-format, reading
176 @cindex embedding fixed-format data
177
178 @display
179 DATA LIST [FIXED]
180         @{TABLE,NOTABLE@}
181         [FILE='file-name' [ENCODING='encoding']]
182         [RECORDS=record_count]
183         [END=end_var]
184         [SKIP=record_count]
185         /[line_no] var_spec@dots{}
186
187 where each var_spec takes one of the forms
188         var_list start-end [type_spec]
189         var_list (fortran_spec)
190 @end display
191
192 @cmd{DATA LIST FIXED} is used to read data files that have values at fixed
193 positions on each line of single-line or multiline records.  The
194 keyword FIXED is optional.
195
196 The FILE subcommand must be used if input is to be taken from an
197 external file.  It may be used to specify a file name as a string or a
198 file handle (@pxref{File Handles}).  If the FILE subcommand is not used,
199 then input is assumed to be specified within the command file using
200 @cmd{BEGIN DATA}@dots{}@cmd{END DATA} (@pxref{BEGIN DATA}).
201 The ENCODING subcommand may only be used if the FILE subcommand is also used.
202 It specifies the character encoding of the file.
203
204 The optional RECORDS subcommand, which takes a single integer as an
205 argument, is used to specify the number of lines per record.  If RECORDS
206 is not specified, then the number of lines per record is calculated from
207 the list of variable specifications later in @cmd{DATA LIST}.
208
209 The END subcommand is only useful in conjunction with @cmd{INPUT
210 PROGRAM}.  @xref{INPUT PROGRAM}, for details.
211
212 The optional SKIP subcommand specifies a number of records to skip at
213 the beginning of an input file.  It can be used to skip over a row
214 that contains variable names, for example.
215
216 @cmd{DATA LIST} can optionally output a table describing how the data file
217 will be read.  The TABLE subcommand enables this output, and NOTABLE
218 disables it.  The default is to output the table.
219
220 The list of variables to be read from the data list must come last.
221 Each line in the data record is introduced by a slash (@samp{/}).
222 Optionally, a line number may follow the slash.  Following, any number
223 of variable specifications may be present.
224
225 Each variable specification consists of a list of variable names
226 followed by a description of their location on the input line.  Sets of
227 variables may be specified using the @code{DATA LIST} TO convention
228 (@pxref{Sets of
229 Variables}).  There are two ways to specify the location of the variable
230 on the line: columnar style and FORTRAN style.
231
232 In columnar style, the starting column and ending column for the field
233 are specified after the variable name, separated by a dash (@samp{-}).
234 For instance, the third through fifth columns on a line would be
235 specified @samp{3-5}.  By default, variables are considered to be in
236 @samp{F} format (@pxref{Input and Output Formats}).  (This default can be
237 changed; see @ref{SET} for more information.)
238
239 In columnar style, to use a variable format other than the default,
240 specify the format type in parentheses after the column numbers.  For
241 instance, for alphanumeric @samp{A} format, use @samp{(A)}.  
242
243 In addition, implied decimal places can be specified in parentheses
244 after the column numbers.  As an example, suppose that a data file has a
245 field in which the characters @samp{1234} should be interpreted as
246 having the value 12.34.  Then this field has two implied decimal places,
247 and the corresponding specification would be @samp{(2)}.  If a field
248 that has implied decimal places contains a decimal point, then the
249 implied decimal places are not applied.
250
251 Changing the variable format and adding implied decimal places can be
252 done together; for instance, @samp{(N,5)}.
253
254 When using columnar style, the input and output width of each variable is
255 computed from the field width.  The field width must be evenly divisible
256 into the number of variables specified.
257
258 FORTRAN style is an altogether different approach to specifying field
259 locations.  With this approach, a list of variable input format
260 specifications, separated by commas, are placed after the variable names
261 inside parentheses.  Each format specifier advances as many characters
262 into the input line as it uses.
263
264 Implied decimal places also exist in FORTRAN style.  A format
265 specification with @var{d} decimal places also has @var{d} implied
266 decimal places.
267
268 In addition to the standard format specifiers (@pxref{Input and Output
269 Formats}), FORTRAN style defines some extensions:
270
271 @table @asis
272 @item @code{X}
273 Advance the current column on this line by one character position.
274
275 @item @code{T}@var{x}
276 Set the current column on this line to column @var{x}, with column
277 numbers considered to begin with 1 at the left margin.
278
279 @item @code{NEWREC}@var{x}
280 Skip forward @var{x} lines in the current record, resetting the active
281 column to the left margin.
282
283 @item Repeat count
284 Any format specifier may be preceded by a number.  This causes the
285 action of that format specifier to be repeated the specified number of
286 times.
287
288 @item (@var{spec1}, @dots{}, @var{specN})
289 Group the given specifiers together.  This is most useful when preceded
290 by a repeat count.  Groups may be nested arbitrarily.
291 @end table
292
293 FORTRAN and columnar styles may be freely intermixed.  Columnar style
294 leaves the active column immediately after the ending column
295 specified.  Record motion using @code{NEWREC} in FORTRAN style also
296 applies to later FORTRAN and columnar specifiers.
297  
298 @menu
299 * DATA LIST FIXED Examples::    Examples of DATA LIST FIXED.
300 @end menu
301
302 @node DATA LIST FIXED Examples
303 @unnumberedsubsubsec Examples
304
305 @enumerate
306 @item
307 @example
308 DATA LIST TABLE /NAME 1-10 (A) INFO1 TO INFO3 12-17 (1).
309
310 BEGIN DATA.
311 John Smith 102311
312 Bob Arnold 122015
313 Bill Yates  918 6
314 END DATA.
315 @end example
316
317 Defines the following variables:
318
319 @itemize @bullet
320 @item
321 @code{NAME}, a 10-character-wide string variable, in columns 1
322 through 10.
323
324 @item
325 @code{INFO1}, a numeric variable, in columns 12 through 13.
326
327 @item
328 @code{INFO2}, a numeric variable, in columns 14 through 15.
329
330 @item
331 @code{INFO3}, a numeric variable, in columns 16 through 17.
332 @end itemize
333
334 The @code{BEGIN DATA}/@code{END DATA} commands cause three cases to be
335 defined:
336
337 @example
338 Case   NAME         INFO1   INFO2   INFO3
339    1   John Smith     10      23      11
340    2   Bob Arnold     12      20      15
341    3   Bill Yates      9      18       6
342 @end example
343
344 The @code{TABLE} keyword causes PSPP to print out a table
345 describing the four variables defined.
346
347 @item
348 @example
349 DAT LIS FIL="survey.dat"
350         /ID 1-5 NAME 7-36 (A) SURNAME 38-67 (A) MINITIAL 69 (A)
351         /Q01 TO Q50 7-56
352         /.
353 @end example
354
355 Defines the following variables:
356
357 @itemize @bullet
358 @item
359 @code{ID}, a numeric variable, in columns 1-5 of the first record.
360
361 @item
362 @code{NAME}, a 30-character string variable, in columns 7-36 of the
363 first record.
364
365 @item
366 @code{SURNAME}, a 30-character string variable, in columns 38-67 of
367 the first record.
368
369 @item
370 @code{MINITIAL}, a 1-character string variable, in column 69 of
371 the first record.
372
373 @item
374 Fifty variables @code{Q01}, @code{Q02}, @code{Q03}, @dots{}, @code{Q49},
375 @code{Q50}, all numeric, @code{Q01} in column 7, @code{Q02} in column 8,
376 @dots{}, @code{Q49} in column 55, @code{Q50} in column 56, all in the second
377 record.
378 @end itemize
379
380 Cases are separated by a blank record.
381
382 Data is read from file @file{survey.dat} in the current directory.
383
384 This example shows keywords abbreviated to their first 3 letters.
385
386 @end enumerate
387
388 @node DATA LIST FREE
389 @subsection DATA LIST FREE
390 @vindex DATA LIST FREE
391
392 @display
393 DATA LIST FREE
394         [(@{TAB,'c'@}, @dots{})]
395         [@{NOTABLE,TABLE@}]
396         [FILE='file-name' [ENCODING='encoding']]
397         [SKIP=record_cnt]
398         /var_spec@dots{}
399
400 where each var_spec takes one of the forms
401         var_list [(type_spec)]
402         var_list *
403 @end display
404
405 In free format, the input data is, by default, structured as a series
406 of fields separated by spaces, tabs, commas, or line breaks.  Each
407 field's content may be unquoted, or it may be quoted with a pairs of
408 apostrophes (@samp{'}) or double quotes (@samp{"}).  Unquoted white
409 space separates fields but is not part of any field.  Any mix of
410 spaces, tabs, and line breaks is equivalent to a single space for the
411 purpose of separating fields, but consecutive commas will skip a
412 field.
413
414 Alternatively, delimiters can be specified explicitly, as a
415 parenthesized, comma-separated list of single-character strings
416 immediately following FREE.  The word TAB may also be used to specify
417 a tab character as a delimiter.  When delimiters are specified
418 explicitly, only the given characters, plus line breaks, separate
419 fields.  Furthermore, leading spaces at the beginnings of fields are
420 not trimmed, consecutive delimiters define empty fields, and no form
421 of quoting is allowed.
422
423 The NOTABLE and TABLE subcommands are as in @cmd{DATA LIST FIXED} above.
424 NOTABLE is the default.
425
426 The FILE and SKIP subcommands are as in @cmd{DATA LIST FIXED} above.
427
428 The variables to be parsed are given as a single list of variable names.
429 This list must be introduced by a single slash (@samp{/}).  The set of
430 variable names may contain format specifications in parentheses
431 (@pxref{Input and Output Formats}).  Format specifications apply to all
432 variables back to the previous parenthesized format specification.  
433
434 In addition, an asterisk may be used to indicate that all variables
435 preceding it are to have input/output format @samp{F8.0}.
436
437 Specified field widths are ignored on input, although all normal limits
438 on field width apply, but they are honored on output.
439
440 @node DATA LIST LIST
441 @subsection DATA LIST LIST
442 @vindex DATA LIST LIST
443
444 @display
445 DATA LIST LIST
446         [(@{TAB,'c'@}, @dots{})]
447         [@{NOTABLE,TABLE@}]
448         [FILE='file-name' [ENCODING='encoding']]
449         [SKIP=record_count]
450         /var_spec@dots{}
451
452 where each var_spec takes one of the forms
453         var_list [(type_spec)]
454         var_list *
455 @end display
456
457 With one exception, @cmd{DATA LIST LIST} is syntactically and
458 semantically equivalent to @cmd{DATA LIST FREE}.  The exception is
459 that each input line is expected to correspond to exactly one input
460 record.  If more or fewer fields are found on an input line than
461 expected, an appropriate diagnostic is issued.
462
463 @node END CASE
464 @section END CASE
465 @vindex END CASE
466
467 @display
468 END CASE.
469 @end display
470
471 @cmd{END CASE} is used only within @cmd{INPUT PROGRAM} to output the
472 current case.  @xref{INPUT PROGRAM}, for details.
473
474 @node END FILE
475 @section END FILE
476 @vindex END FILE
477
478 @display
479 END FILE.
480 @end display
481
482 @cmd{END FILE} is used only within @cmd{INPUT PROGRAM} to terminate
483 the current input program.  @xref{INPUT PROGRAM}.
484
485 @node FILE HANDLE
486 @section FILE HANDLE
487 @vindex FILE HANDLE
488
489 @display
490 For text files:
491         FILE HANDLE handle_name
492                 /NAME='file-name'
493                 [/MODE=CHARACTER]
494                 /TABWIDTH=tab_width
495
496 For binary files in native encoding with fixed-length records:
497         FILE HANDLE handle_name
498                 /NAME='file-name'
499                 /MODE=IMAGE
500                 [/LRECL=rec_len]
501
502 For binary files in native encoding with variable-length records:
503         FILE HANDLE handle_name
504                 /NAME='file-name'
505                 /MODE=BINARY
506                 [/LRECL=rec_len]
507
508 For binary files encoded in EBCDIC:
509         FILE HANDLE handle_name
510                 /NAME='file-name'
511                 /MODE=360
512                 /RECFORM=@{FIXED,VARIABLE,SPANNED@}
513                 [/LRECL=rec_len]
514
515 To explicitly declare a scratch handle:
516         FILE HANDLE handle_name
517                 /MODE=SCRATCH
518 @end display
519
520 Use @cmd{FILE HANDLE} to associate a file handle name with a file and
521 its attributes, so that later commands can refer to the file by its
522 handle name.  Names of text files can be specified directly on
523 commands that access files, so that @cmd{FILE HANDLE} is only needed when a
524 file is not an ordinary file containing lines of text.  However,
525 @cmd{FILE HANDLE} may be used even for text files, and it may be
526 easier to specify a file's name once and later refer to it by an
527 abstract handle.
528
529 Specify the file handle name as the identifier immediately following the
530 @cmd{FILE HANDLE} command name.  The identifier INLINE is reserved for
531 representing data embedded in the syntax file (@pxref{BEGIN DATA}) The
532 file handle name must not already have been used in a previous
533 invocation of @cmd{FILE HANDLE}, unless it has been closed by an
534 intervening command (@pxref{CLOSE FILE HANDLE}).
535
536 The effect and syntax of FILE HANDLE depends on the selected MODE:
537
538 @itemize
539 @item
540 In CHARACTER mode, the default, the data file is read as a text file,
541 according to the local system's conventions, and each text line is
542 read as one record.
543
544 In CHARACTER mode only, tabs are expanded to spaces by input programs,
545 except by @cmd{DATA LIST FREE} with explicitly specified delimiters.
546 Each tab is 4 characters wide by default, but TABWIDTH (a PSPP
547 extension) may be used to specify an alternate width.  Use a TABWIDTH
548 of 0 to suppress tab expansion.
549
550 @item
551 In IMAGE mode, the data file is treated as a series of fixed-length
552 binary records.  LRECL should be used to specify the record length in
553 bytes, with a default of 1024.  On input, it is an error if an IMAGE
554 file's length is not a integer multiple of the record length.  On
555 output, each record is padded with spaces or truncated, if necessary,
556 to make it exactly the correct length.
557
558 @item
559 In BINARY mode, the data file is treated as a series of
560 variable-length binary records.  LRECL may be specified, but its value
561 is ignored.  The data for each record is both preceded and followed by
562 a 32-bit signed integer in little-endian byte order that specifies the
563 length of the record.  (This redundancy permits records in these
564 files to be efficiently read in reverse order, although PSPP always
565 reads them in forward order.)  The length does not include either
566 integer.
567
568 @item
569 Mode 360 reads and writes files in formats first used for tapes in the
570 1960s on IBM mainframe operating systems and still supported today by
571 the modern successors of those operating systems.  For more
572 information, see @cite{OS/400 Tape and Diskette Device Programming},
573 available on IBM's website.
574
575 Alphanumeric data in mode 360 files are encoded in EBCDIC.  PSPP
576 translates EBCDIC to or from the host's native format as necessary on
577 input or output, using an ASCII/EBCDIC translation that is one-to-one,
578 so that a ``round trip'' from ASCII to EBCDIC back to ASCII, or vice
579 versa, always yields exactly the original data.
580
581 The RECFORM subcommand is required in mode 360.  The precise file
582 format depends on its setting:
583
584 @table @asis
585 @item F
586 @itemx FIXED
587 This record format is equivalent to IMAGE mode, except for EBCDIC
588 translation.
589
590 IBM documentation calls this @code{*F} (fixed-length, deblocked)
591 format.
592
593 @item V
594 @itemx VARIABLE
595 The file comprises a sequence of zero or more variable-length blocks.
596 Each block begins with a 4-byte @dfn{block descriptor word} (BDW).
597 The first two bytes of the BDW are an unsigned integer in big-endian
598 byte order that specifies the length of the block, including the BDW
599 itself.  The other two bytes of the BDW are ignored on input and
600 written as zeros on output.
601
602 Following the BDW, the remainder of each block is a sequence of one or
603 more variable-length records, each of which in turn begins with a
604 4-byte @dfn{record descriptor word} (RDW) that has the same format as
605 the BDW.  Following the RDW, the remainder of each record is the
606 record data.
607
608 The maximum length of a record in VARIABLE mode is 65,527 bytes:
609 65,535 bytes (the maximum value of a 16-bit unsigned integer), minus 4
610 bytes for the BDW, minus 4 bytes for the RDW.
611
612 In mode VARIABLE, LRECL specifies a maximum, not a fixed, record
613 length, in bytes.  The default is 8,192.
614
615 IBM documentation calls this @code{*VB} (variable-length, blocked,
616 unspanned) format.
617
618 @item VS
619 @itemx SPANNED
620 The file format is like that of VARIABLE mode, except that logical
621 records may be split among multiple physical records (called
622 @dfn{segments}) or blocks.  In SPANNED mode, the third byte of each
623 RDW is called the segment control character (SCC).  Odd SCC values
624 cause the segment to be appended to a record buffer maintained in
625 memory; even values also append the segment and then flush its
626 contents to the input procedure.  Canonically, SCC value 0 designates
627 a record not spanned among multiple segments, and values 1 through 3
628 designate the first segment, the last segment, or an intermediate
629 segment, respectively, within a multi-segment record.  The record
630 buffer is also flushed at end of file regardless of the final record's
631 SCC.
632
633 The maximum length of a logical record in VARIABLE mode is limited
634 only by memory available to PSPP.  Segments are limited to 65,527
635 bytes, as in VARIABLE mode.
636
637 This format is similar to what IBM documentation call @code{*VS}
638 (variable-length, deblocked, spanned) format.
639 @end table
640
641 In mode 360, fields of type A that extend beyond the end of a record
642 read from disk are padded with spaces in the host's native character
643 set, which are then translated from EBCDIC to the native character
644 set.  Thus, when the host's native character set is based on ASCII,
645 these fields are effectively padded with character @code{X'80'}.  This
646 wart is implemented for compatibility.
647
648 @item
649 SCRATCH mode is a PSPP extension that designates the file handle as a
650 scratch file handle.
651 Its use is usually unnecessary because file handle names that begin with
652 @samp{#} are assumed to refer to scratch files.  @pxref{File Handles},
653 for more information.
654 @end itemize
655
656 The NAME subcommand specifies the name of the file associated with the
657 handle.  It is required in all modes but SCRATCH mode, in which its
658 use is forbidden.
659
660 @node INPUT PROGRAM
661 @section INPUT PROGRAM
662 @vindex INPUT PROGRAM
663
664 @display
665 INPUT PROGRAM.
666 @dots{} input commands @dots{}
667 END INPUT PROGRAM.
668 @end display
669
670 @cmd{INPUT PROGRAM}@dots{}@cmd{END INPUT PROGRAM} specifies a
671 complex input program.  By placing data input commands within @cmd{INPUT
672 PROGRAM}, PSPP programs can take advantage of more complex file
673 structures than available with only @cmd{DATA LIST}.
674
675 The first sort of extended input program is to simply put multiple @cmd{DATA
676 LIST} commands within the @cmd{INPUT PROGRAM}.  This will cause all of
677 the data
678 files to be read in parallel.  Input will stop when end of file is
679 reached on any of the data files.
680
681 Transformations, such as conditional and looping constructs, can also be
682 included within @cmd{INPUT PROGRAM}.  These can be used to combine input
683 from several data files in more complex ways.  However, input will still
684 stop when end of file is reached on any of the data files.
685
686 To prevent @cmd{INPUT PROGRAM} from terminating at the first end of
687 file, use
688 the END subcommand on @cmd{DATA LIST}.  This subcommand takes a
689 variable name,
690 which should be a numeric scratch variable (@pxref{Scratch Variables}).
691 (It need not be a scratch variable but otherwise the results can be
692 surprising.)  The value of this variable is set to 0 when reading the
693 data file, or 1 when end of file is encountered.
694
695 Two additional commands are useful in conjunction with @cmd{INPUT PROGRAM}.
696 @cmd{END CASE} is the first.  Normally each loop through the
697 @cmd{INPUT PROGRAM}
698 structure produces one case.  @cmd{END CASE} controls exactly
699 when cases are output.  When @cmd{END CASE} is used, looping from the end of
700 @cmd{INPUT PROGRAM} to the beginning does not cause a case to be output.
701
702 @cmd{END FILE} is the second.  When the END subcommand is used on @cmd{DATA
703 LIST}, there is no way for the @cmd{INPUT PROGRAM} construct to stop
704 looping,
705 so an infinite loop results.  @cmd{END FILE}, when executed,
706 stops the flow of input data and passes out of the @cmd{INPUT PROGRAM}
707 structure.
708
709 All this is very confusing.  A few examples should help to clarify.
710
711 @c If you change this example, change the regression test1 in
712 @c tests/command/input-program.sh to match.
713 @example
714 INPUT PROGRAM.
715         DATA LIST NOTABLE FILE='a.data'/X 1-10.
716         DATA LIST NOTABLE FILE='b.data'/Y 1-10.
717 END INPUT PROGRAM.
718 LIST.
719 @end example
720
721 The example above reads variable X from file @file{a.data} and variable
722 Y from file @file{b.data}.  If one file is shorter than the other then
723 the extra data in the longer file is ignored.
724
725 @c If you change this example, change the regression test2 in
726 @c tests/command/input-program.sh to match.
727 @example
728 INPUT PROGRAM.
729         NUMERIC #A #B.
730         
731         DO IF NOT #A.
732                 DATA LIST NOTABLE END=#A FILE='a.data'/X 1-10.
733         END IF.
734         DO IF NOT #B.
735                 DATA LIST NOTABLE END=#B FILE='b.data'/Y 1-10.
736         END IF.
737         DO IF #A AND #B.
738                 END FILE.
739         END IF.
740         END CASE.
741 END INPUT PROGRAM.
742 LIST.
743 @end example
744
745 The above example reads variable X from @file{a.data} and variable Y from
746 @file{b.data}.  If one file is shorter than the other then the missing
747 field is set to the system-missing value alongside the present value for
748 the remaining length of the longer file.
749
750 @c If you change this example, change the regression test3 in
751 @c tests/command/input-program.sh to match.
752 @example
753 INPUT PROGRAM.
754         NUMERIC #A #B.
755
756         DO IF #A.
757                 DATA LIST NOTABLE END=#B FILE='b.data'/X 1-10.
758                 DO IF #B.
759                         END FILE.
760                 ELSE.
761                         END CASE.
762                 END IF.
763         ELSE.
764                 DATA LIST NOTABLE END=#A FILE='a.data'/X 1-10.
765                 DO IF NOT #A.
766                         END CASE.
767                 END IF.
768         END IF.
769 END INPUT PROGRAM.
770 LIST.
771 @end example
772
773 The above example reads data from file @file{a.data}, then from
774 @file{b.data}, and concatenates them into a single active file.
775
776 @c If you change this example, change the regression test4 in
777 @c tests/command/input-program.sh to match.
778 @example
779 INPUT PROGRAM.
780         NUMERIC #EOF.
781
782         LOOP IF NOT #EOF.
783                 DATA LIST NOTABLE END=#EOF FILE='a.data'/X 1-10.
784                 DO IF NOT #EOF.
785                         END CASE.
786                 END IF.
787         END LOOP.
788
789         COMPUTE #EOF = 0.
790         LOOP IF NOT #EOF.
791                 DATA LIST NOTABLE END=#EOF FILE='b.data'/X 1-10.
792                 DO IF NOT #EOF.
793                         END CASE.
794                 END IF.
795         END LOOP.
796
797         END FILE.
798 END INPUT PROGRAM.
799 LIST.
800 @end example
801
802 The above example does the same thing as the previous example, in a
803 different way.
804
805 @c If you change this example, make similar changes to the regression
806 @c test5 in tests/command/input-program.sh.
807 @example
808 INPUT PROGRAM.
809         LOOP #I=1 TO 50.
810                 COMPUTE X=UNIFORM(10).
811                 END CASE.
812         END LOOP.
813         END FILE.
814 END INPUT PROGRAM.
815 LIST/FORMAT=NUMBERED.
816 @end example
817
818 The above example causes an active file to be created consisting of 50
819 random variates between 0 and 10.
820
821 @node LIST
822 @section LIST
823 @vindex LIST
824
825 @display
826 LIST
827         /VARIABLES=var_list
828         /CASES=FROM start_index TO end_index BY incr_index
829         /FORMAT=@{UNNUMBERED,NUMBERED@} @{WRAP,SINGLE@}
830 @end display
831
832 The @cmd{LIST} procedure prints the values of specified variables to the
833 listing file.
834
835 The VARIABLES subcommand specifies the variables whose values are to be
836 printed.  Keyword VARIABLES is optional.  If VARIABLES subcommand is not
837 specified then all variables in the active file are printed.
838
839 The CASES subcommand can be used to specify a subset of cases to be
840 printed.  Specify FROM and the case number of the first case to print,
841 TO and the case number of the last case to print, and BY and the number
842 of cases to advance between printing cases, or any subset of those
843 settings.  If CASES is not specified then all cases are printed.
844
845 The FORMAT subcommand can be used to change the output format.  NUMBERED
846 will print case numbers along with each case; UNNUMBERED, the default,
847 causes the case numbers to be omitted.  The WRAP and SINGLE settings are
848 currently not used.
849
850 Case numbers start from 1.  They are counted after all transformations
851 have been considered.
852
853 @cmd{LIST} attempts to fit all the values on a single line.  If needed
854 to make them fit, variable names are displayed vertically.  If values
855 cannot fit on a single line, then a multi-line format will be used.
856
857 @cmd{LIST} is a procedure.  It causes the data to be read.
858
859 @node NEW FILE
860 @section NEW FILE
861 @vindex NEW FILE
862
863 @display
864 NEW FILE.
865 @end display
866
867 @cmd{NEW FILE} command clears the current active file.
868
869 @node PRINT
870 @section PRINT
871 @vindex PRINT
872
873 @display
874 PRINT 
875         OUTFILE='file-name'
876         RECORDS=n_lines
877         @{NOTABLE,TABLE@}
878         [/[line_no] arg@dots{}]
879
880 arg takes one of the following forms:
881         'string' [start-end]
882         var_list start-end [type_spec]
883         var_list (fortran_spec)
884         var_list *
885 @end display
886
887 The @cmd{PRINT} transformation writes variable data to the listing
888 file or an output file.  @cmd{PRINT} is executed when a procedure
889 causes the data to be read.  Follow @cmd{PRINT} by @cmd{EXECUTE} to
890 print variable data without invoking a procedure (@pxref{EXECUTE}).
891
892 All @cmd{PRINT} subcommands are optional.  If no strings or variables
893 are specified, PRINT outputs a single blank line.
894
895 The OUTFILE subcommand specifies the file to receive the output.  The
896 file may be a file name as a string or a file handle (@pxref{File
897 Handles}).  If OUTFILE is not present then output will be sent to
898 PSPP's output listing file.  When OUTFILE is present, a space is
899 inserted at beginning of each output line, even lines that otherwise
900 would be blank.
901
902 The RECORDS subcommand specifies the number of lines to be output.  The
903 number of lines may optionally be surrounded by parentheses.
904
905 TABLE will cause the PRINT command to output a table to the listing file
906 that describes what it will print to the output file.  NOTABLE, the
907 default, suppresses this output table.
908
909 Introduce the strings and variables to be printed with a slash
910 (@samp{/}).  Optionally, the slash may be followed by a number
911 indicating which output line will be specified.  In the absence of this
912 line number, the next line number will be specified.  Multiple lines may
913 be specified using multiple slashes with the intended output for a line
914 following its respective slash.
915
916 Literal strings may be printed.  Specify the string itself.  Optionally
917 the string may be followed by a column number or range of column
918 numbers, specifying the location on the line for the string to be
919 printed.  Otherwise, the string will be printed at the current position
920 on the line.
921
922 Variables to be printed can be specified in the same ways as available
923 for @cmd{DATA LIST FIXED} (@pxref{DATA LIST FIXED}).  In addition, a
924 variable
925 list may be followed by an asterisk (@samp{*}), which indicates that the
926 variables should be printed in their dictionary print formats, separated
927 by spaces.  A variable list followed by a slash or the end of command
928 will be interpreted the same way.
929
930 If a FORTRAN type specification is used to move backwards on the current
931 line, then text is written at that point on the line, the line will be
932 truncated to that length, although additional text being added will
933 again extend the line to that length.
934
935 @node PRINT EJECT
936 @section PRINT EJECT
937 @vindex PRINT EJECT
938
939 @display
940 PRINT EJECT 
941         OUTFILE='file-name'
942         RECORDS=n_lines
943         @{NOTABLE,TABLE@}
944         /[line_no] arg@dots{}
945
946 arg takes one of the following forms:
947         'string' [start-end]
948         var_list start-end [type_spec]
949         var_list (fortran_spec)
950         var_list *
951 @end display
952
953 @cmd{PRINT EJECT} advances to the beginning of a new output page in
954 the listing file or output file.  It can also output data in the same
955 way as @cmd{PRINT}.
956
957 All @cmd{PRINT EJECT} subcommands are optional.
958
959 Without OUTFILE, PRINT EJECT ejects the current page in
960 the listing file, then it produces other output, if any is specified.
961
962 With OUTFILE, PRINT EJECT writes its output to the specified file.
963 The first line of output is written with @samp{1} inserted in the
964 first column.  Commonly, this is the only line of output.  If
965 additional lines of output are specified, these additional lines are
966 written with a space inserted in the first column, as with PRINT.
967
968 @xref{PRINT}, for more information on syntax and usage.
969
970 @node PRINT SPACE
971 @section PRINT SPACE
972 @vindex PRINT SPACE
973
974 @display
975 PRINT SPACE OUTFILE='file-name' n_lines.
976 @end display
977
978 @cmd{PRINT SPACE} prints one or more blank lines to an output file.
979
980 The OUTFILE subcommand is optional.  It may be used to direct output to
981 a file specified by file name as a string or file handle (@pxref{File
982 Handles}).  If OUTFILE is not specified then output will be directed to
983 the listing file.
984
985 n_lines is also optional.  If present, it is an expression
986 (@pxref{Expressions}) specifying the number of blank lines to be
987 printed.  The expression must evaluate to a nonnegative value.
988
989 @node REREAD
990 @section REREAD
991 @vindex REREAD
992
993 @display
994 REREAD FILE=handle COLUMN=column.
995 @end display
996
997 The @cmd{REREAD} transformation allows the previous input line in a
998 data file
999 already processed by @cmd{DATA LIST} or another input command to be re-read
1000 for further processing.
1001
1002 The FILE subcommand, which is optional, is used to specify the file to
1003 have its line re-read.  The file must be specified as the name of a file
1004 handle (@pxref{File Handles}).  If FILE is not specified then the last
1005 file specified on @cmd{DATA LIST} will be assumed (last file specified
1006 lexically, not in terms of flow-of-control).
1007
1008 By default, the line re-read is re-read in its entirety.  With the
1009 COLUMN subcommand, a prefix of the line can be exempted from
1010 re-reading.  Specify an expression (@pxref{Expressions}) evaluating to
1011 the first column that should be included in the re-read line.  Columns
1012 are numbered from 1 at the left margin.
1013
1014 Issuing @code{REREAD} multiple times will not back up in the data
1015 file.  Instead, it will re-read the same line multiple times.
1016
1017 @node REPEATING DATA
1018 @section REPEATING DATA
1019 @vindex REPEATING DATA
1020
1021 @display
1022 REPEATING DATA
1023         /STARTS=start-end
1024         /OCCURS=n_occurs
1025         /FILE='file-name'
1026         /LENGTH=length
1027         /CONTINUED[=cont_start-cont_end]
1028         /ID=id_start-id_end=id_var
1029         /@{TABLE,NOTABLE@}
1030         /DATA=var_spec@dots{}
1031
1032 where each var_spec takes one of the forms
1033         var_list start-end [type_spec]
1034         var_list (fortran_spec)
1035 @end display
1036
1037 @cmd{REPEATING DATA} parses groups of data repeating in
1038 a uniform format, possibly with several groups on a single line.  Each
1039 group of data corresponds with one case.  @cmd{REPEATING DATA} may only be
1040 used within an @cmd{INPUT PROGRAM} structure (@pxref{INPUT PROGRAM}).
1041 When used with @cmd{DATA LIST}, it
1042 can be used to parse groups of cases that share a subset of variables
1043 but differ in their other data.
1044
1045 The STARTS subcommand is required.  Specify a range of columns, using
1046 literal numbers or numeric variable names.  This range specifies the
1047 columns on the first line that are used to contain groups of data.  The
1048 ending column is optional.  If it is not specified, then the record
1049 width of the input file is used.  For the inline file (@pxref{BEGIN
1050 DATA}) this is 80 columns; for a file with fixed record widths it is the
1051 record width; for other files it is 1024 characters by default.
1052
1053 The OCCURS subcommand is required.  It must be a number or the name of a
1054 numeric variable.  Its value is the number of groups present in the
1055 current record.
1056
1057 The DATA subcommand is required.  It must be the last subcommand
1058 specified.  It is used to specify the data present within each repeating
1059 group.  Column numbers are specified relative to the beginning of a
1060 group at column 1.  Data is specified in the same way as with @cmd{DATA LIST
1061 FIXED} (@pxref{DATA LIST FIXED}).
1062
1063 All other subcommands are optional.
1064
1065 FILE specifies the file to read, either a file name as a string or a
1066 file handle (@pxref{File Handles}).  If FILE is not present then the
1067 default is the last file handle used on @cmd{DATA LIST} (lexically, not in
1068 terms of flow of control).
1069
1070 By default @cmd{REPEATING DATA} will output a table describing how it will
1071 parse the input data.  Specifying NOTABLE will disable this behavior;
1072 specifying TABLE will explicitly enable it.
1073
1074 The LENGTH subcommand specifies the length in characters of each group.
1075 If it is not present then length is inferred from the DATA subcommand.
1076 LENGTH can be a number or a variable name.
1077
1078 Normally all the data groups are expected to be present on a single
1079 line.  Use the CONTINUED command to indicate that data can be continued
1080 onto additional lines.  If data on continuation lines starts at the left
1081 margin and continues through the entire field width, no column
1082 specifications are necessary on CONTINUED.  Otherwise, specify the
1083 possible range of columns in the same way as on STARTS.
1084
1085 When data groups are continued from line to line, it is easy
1086 for cases to get out of sync through careless hand editing.  The
1087 ID subcommand allows a case identifier to be present on each line of
1088 repeating data groups.  @cmd{REPEATING DATA} will check for the same
1089 identifier on each line and report mismatches.  Specify the range of
1090 columns that the identifier will occupy, followed by an equals sign
1091 (@samp{=}) and the identifier variable name.  The variable must already
1092 have been declared with @cmd{NUMERIC} or another command.
1093
1094 @cmd{REPEATING DATA} should be the last command given within an
1095 @cmd{INPUT PROGRAM}.  It should not be enclosed within a @cmd{LOOP}
1096 structure (@pxref{LOOP}).  Use @cmd{DATA LIST} before, not after,
1097 @cmd{REPEATING DATA}.
1098
1099 @node WRITE
1100 @section WRITE
1101 @vindex WRITE
1102
1103 @display
1104 WRITE 
1105         OUTFILE='file-name'
1106         RECORDS=n_lines
1107         @{NOTABLE,TABLE@}
1108         /[line_no] arg@dots{}
1109
1110 arg takes one of the following forms:
1111         'string' [start-end]
1112         var_list start-end [type_spec]
1113         var_list (fortran_spec)
1114         var_list *
1115 @end display
1116
1117 @code{WRITE} writes text or binary data to an output file.  
1118
1119 @xref{PRINT}, for more information on syntax and usage.  @cmd{PRINT}
1120 and @cmd{WRITE} differ in only a few ways:
1121
1122 @itemize @bullet
1123 @item
1124 @cmd{WRITE} uses write formats by default, whereas @cmd{PRINT} uses
1125 print formats.
1126
1127 @item
1128 @cmd{PRINT} inserts a space between variables unless a format is
1129 explicitly specified, but @cmd{WRITE} never inserts space between
1130 variables in output.
1131
1132 @item
1133 @cmd{PRINT} inserts a space at the beginning of each line that it
1134 writes to an output file (and @cmd{PRINT EJECT} inserts @samp{1} at
1135 the beginning of each line that should begin a new page), but
1136 @cmd{WRITE} does not.
1137
1138 @item
1139 @cmd{PRINT} outputs the system-missing value according to its
1140 specified output format, whereas @cmd{WRITE} outputs the
1141 system-missing value as a field filled with spaces.  Binary formats
1142 are an exception.
1143 @end itemize