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