1 @node Data Input and Output, System and Portable Files, Expressions, Top
2 @chapter Data Input and Output
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.
16 the PSPP commands for defining variables and reading and writing data.
19 These commands tell PSPP how to read data, but the data will not
20 actually be read until a procedure is executed.
24 * BEGIN DATA:: Embed data within a syntax file.
25 * CLEAR TRANSFORMATIONS:: Clear pending transformations.
26 * CLOSE FILE HANDLE:: Close a file handle.
27 * DATA LIST:: Fundamental data reading command.
28 * END CASE:: Output the current case.
29 * END FILE:: Terminate the current input program.
30 * FILE HANDLE:: Support for special file formats.
31 * INPUT PROGRAM:: Support for complex input programs.
32 * LIST:: List cases in the active file.
33 * MATRIX DATA:: Read matrices in text format.
34 * NEW FILE:: Clear the active file and dictionary.
35 * PRINT:: Display values in print formats.
36 * PRINT EJECT:: Eject the current page then print.
37 * PRINT SPACE:: Print blank lines.
38 * REREAD:: Take another look at the previous input line.
39 * REPEATING DATA:: Multiple cases on a single line.
40 * WRITE:: Display values in write formats.
47 @cindex Embedding data in syntax files
48 @cindex Data, embedding in syntax files
56 @cmd{BEGIN DATA} and @cmd{END DATA} can be used to embed raw ASCII
57 data in a PSPP syntax file. @cmd{DATA LIST} or another input
58 procedure must be used before @cmd{BEGIN DATA} (@pxref{DATA LIST}).
59 @cmd{BEGIN DATA} and @cmd{END DATA} must be used together. @cmd{END
60 DATA} must appear by itself on a single line, with no leading
61 white space and exactly one space between the words @code{END} and
62 @code{DATA}, like this:
68 @node CLEAR TRANSFORMATIONS
69 @section CLEAR TRANSFORMATIONS
70 @vindex CLEAR TRANSFORMATIONS
73 CLEAR TRANSFORMATIONS.
76 @cmd{CLEAR TRANSFORMATIONS} clears out all pending
77 transformations. It does not cancel the current input program.
79 @node CLOSE FILE HANDLE
80 @section CLOSE FILE HANDLE
83 CLOSE FILE HANDLE handle_name.
86 @cmd{CLOSE FILE HANDLE} disassociates the name of a file handle with a
87 given file. The only specification is the name of the handle to close.
91 If the file handle name refers to a scratch file, then the storage
92 associated with the scratch file in memory or on disk will be freed.
93 If the scratch file is in use, e.g.@: it has been specified on a
94 @cmd{GET} command whose execution has not completed, then freeing is
95 delayed until it is no longer in use.
97 The file named INLINE, which represents data entered between @cmd{BEGIN
98 DATA} and @cmd{END DATA}, cannot be closed. Attempts to close it with
99 @cmd{CLOSE FILE HANDLE} have no effect.
101 @cmd{CLOSE FILE HANDLE} is a PSPP extension.
106 @cindex reading data from a file
107 @cindex data, reading from a file
108 @cindex data, embedding in syntax files
109 @cindex embedding data in syntax files
111 Used to read text or binary data, @cmd{DATA LIST} is the most
112 fundamental data-reading command. Even the more sophisticated input
113 methods use @cmd{DATA LIST} commands as a building block.
114 Understanding @cmd{DATA LIST} is important to understanding how to use
115 PSPP to read your data files.
117 There are two major variants of @cmd{DATA LIST}, which are fixed
118 format and free format. In addition, free format has a minor variant,
119 list format, which is discussed in terms of its differences from vanilla
122 Each form of @cmd{DATA LIST} is described in detail below.
125 * DATA LIST FIXED:: Fixed columnar locations for data.
126 * DATA LIST FREE:: Any spacing you like.
127 * DATA LIST LIST:: Each case must be on a single line.
130 @node DATA LIST FIXED
131 @subsection DATA LIST FIXED
132 @vindex DATA LIST FIXED
133 @cindex reading fixed-format data
134 @cindex fixed-format data, reading
135 @cindex data, fixed-format, reading
136 @cindex embedding fixed-format data
142 [RECORDS=record_count]
145 /[line_no] var_spec@dots{}
147 where each var_spec takes one of the forms
148 var_list start-end [type_spec]
149 var_list (fortran_spec)
152 @cmd{DATA LIST FIXED} is used to read data files that have values at fixed
153 positions on each line of single-line or multiline records. The
154 keyword FIXED is optional.
156 The FILE subcommand must be used if input is to be taken from an
157 external file. It may be used to specify a file name as a string or a
158 file handle (@pxref{File Handles}). If the FILE subcommand is not used,
159 then input is assumed to be specified within the command file using
160 @cmd{BEGIN DATA}@dots{}@cmd{END DATA} (@pxref{BEGIN DATA}).
162 The optional RECORDS subcommand, which takes a single integer as an
163 argument, is used to specify the number of lines per record. If RECORDS
164 is not specified, then the number of lines per record is calculated from
165 the list of variable specifications later in @cmd{DATA LIST}.
167 The END subcommand is only useful in conjunction with @cmd{INPUT
168 PROGRAM}. @xref{INPUT PROGRAM}, for details.
170 The optional SKIP subcommand specifies a number of records to skip at
171 the beginning of an input file. It can be used to skip over a row
172 that contains variable names, for example.
174 @cmd{DATA LIST} can optionally output a table describing how the data file
175 will be read. The TABLE subcommand enables this output, and NOTABLE
176 disables it. The default is to output the table.
178 The list of variables to be read from the data list must come last.
179 Each line in the data record is introduced by a slash (@samp{/}).
180 Optionally, a line number may follow the slash. Following, any number
181 of variable specifications may be present.
183 Each variable specification consists of a list of variable names
184 followed by a description of their location on the input line. Sets of
185 variables may be specified using the @code{DATA LIST} TO convention
187 Variables}). There are two ways to specify the location of the variable
188 on the line: columnar style and FORTRAN style.
190 In columnar style, the starting column and ending column for the field
191 are specified after the variable name, separated by a dash (@samp{-}).
192 For instance, the third through fifth columns on a line would be
193 specified @samp{3-5}. By default, variables are considered to be in
194 @samp{F} format (@pxref{Input and Output Formats}). (This default can be
195 changed; see @ref{SET} for more information.)
197 In columnar style, to use a variable format other than the default,
198 specify the format type in parentheses after the column numbers. For
199 instance, for alphanumeric @samp{A} format, use @samp{(A)}.
201 In addition, implied decimal places can be specified in parentheses
202 after the column numbers. As an example, suppose that a data file has a
203 field in which the characters @samp{1234} should be interpreted as
204 having the value 12.34. Then this field has two implied decimal places,
205 and the corresponding specification would be @samp{(2)}. If a field
206 that has implied decimal places contains a decimal point, then the
207 implied decimal places are not applied.
209 Changing the variable format and adding implied decimal places can be
210 done together; for instance, @samp{(N,5)}.
212 When using columnar style, the input and output width of each variable is
213 computed from the field width. The field width must be evenly divisible
214 into the number of variables specified.
216 FORTRAN style is an altogether different approach to specifying field
217 locations. With this approach, a list of variable input format
218 specifications, separated by commas, are placed after the variable names
219 inside parentheses. Each format specifier advances as many characters
220 into the input line as it uses.
222 Implied decimal places also exist in FORTRAN style. A format
223 specification with @var{d} decimal places also has @var{d} implied
226 In addition to the standard format specifiers (@pxref{Input and Output
227 Formats}), FORTRAN style defines some extensions:
231 Advance the current column on this line by one character position.
233 @item @code{T}@var{x}
234 Set the current column on this line to column @var{x}, with column
235 numbers considered to begin with 1 at the left margin.
237 @item @code{NEWREC}@var{x}
238 Skip forward @var{x} lines in the current record, resetting the active
239 column to the left margin.
242 Any format specifier may be preceded by a number. This causes the
243 action of that format specifier to be repeated the specified number of
246 @item (@var{spec1}, @dots{}, @var{specN})
247 Group the given specifiers together. This is most useful when preceded
248 by a repeat count. Groups may be nested arbitrarily.
251 FORTRAN and columnar styles may be freely intermixed. Columnar style
252 leaves the active column immediately after the ending column
253 specified. Record motion using @code{NEWREC} in FORTRAN style also
254 applies to later FORTRAN and columnar specifiers.
257 * DATA LIST FIXED Examples:: Examples of DATA LIST FIXED.
260 @node DATA LIST FIXED Examples
261 @unnumberedsubsubsec Examples
266 DATA LIST TABLE /NAME 1-10 (A) INFO1 TO INFO3 12-17 (1).
275 Defines the following variables:
279 @code{NAME}, a 10-character-wide long string variable, in columns 1
283 @code{INFO1}, a numeric variable, in columns 12 through 13.
286 @code{INFO2}, a numeric variable, in columns 14 through 15.
289 @code{INFO3}, a numeric variable, in columns 16 through 17.
292 The @code{BEGIN DATA}/@code{END DATA} commands cause three cases to be
296 Case NAME INFO1 INFO2 INFO3
297 1 John Smith 10 23 11
298 2 Bob Arnold 12 20 15
302 The @code{TABLE} keyword causes PSPP to print out a table
303 describing the four variables defined.
307 DAT LIS FIL="survey.dat"
308 /ID 1-5 NAME 7-36 (A) SURNAME 38-67 (A) MINITIAL 69 (A)
313 Defines the following variables:
317 @code{ID}, a numeric variable, in columns 1-5 of the first record.
320 @code{NAME}, a 30-character long string variable, in columns 7-36 of the
324 @code{SURNAME}, a 30-character long string variable, in columns 38-67 of
328 @code{MINITIAL}, a 1-character short string variable, in column 69 of
332 Fifty variables @code{Q01}, @code{Q02}, @code{Q03}, @dots{}, @code{Q49},
333 @code{Q50}, all numeric, @code{Q01} in column 7, @code{Q02} in column 8,
334 @dots{}, @code{Q49} in column 55, @code{Q50} in column 56, all in the second
338 Cases are separated by a blank record.
340 Data is read from file @file{survey.dat} in the current directory.
342 This example shows keywords abbreviated to their first 3 letters.
347 @subsection DATA LIST FREE
348 @vindex DATA LIST FREE
352 [(@{TAB,'c'@}, @dots{})]
359 where each var_spec takes one of the forms
360 var_list [(type_spec)]
364 In free format, the input data is, by default, structured as a series
365 of fields separated by spaces, tabs, commas, or line breaks. Each
366 field's content may be unquoted, or it may be quoted with a pairs of
367 apostrophes (@samp{'}) or double quotes (@samp{"}). Unquoted white
368 space separates fields but is not part of any field. Any mix of
369 spaces, tabs, and line breaks is equivalent to a single space for the
370 purpose of separating fields, but consecutive commas will skip a
373 Alternatively, delimiters can be specified explicitly, as a
374 parenthesized, comma-separated list of single-character strings
375 immediately following FREE. The word TAB may also be used to specify
376 a tab character as a delimiter. When delimiters are specified
377 explicitly, only the given characters, plus line breaks, separate
378 fields. Furthermore, leading spaces at the beginnings of fields are
379 not trimmed, consecutive delimiters define empty fields, and no form
380 of quoting is allowed.
382 The NOTABLE and TABLE subcommands are as in @cmd{DATA LIST FIXED} above.
383 NOTABLE is the default.
385 The FILE, END, and SKIP subcommands are as in @cmd{DATA LIST FIXED} above.
387 The variables to be parsed are given as a single list of variable names.
388 This list must be introduced by a single slash (@samp{/}). The set of
389 variable names may contain format specifications in parentheses
390 (@pxref{Input and Output Formats}). Format specifications apply to all
391 variables back to the previous parenthesized format specification.
393 In addition, an asterisk may be used to indicate that all variables
394 preceding it are to have input/output format @samp{F8.0}.
396 Specified field widths are ignored on input, although all normal limits
397 on field width apply, but they are honored on output.
400 @subsection DATA LIST LIST
401 @vindex DATA LIST LIST
405 [(@{TAB,'c'@}, @dots{})]
412 where each var_spec takes one of the forms
413 var_list [(type_spec)]
417 With one exception, @cmd{DATA LIST LIST} is syntactically and
418 semantically equivalent to @cmd{DATA LIST FREE}. The exception is
419 that each input line is expected to correspond to exactly one input
420 record. If more or fewer fields are found on an input line than
421 expected, an appropriate diagnostic is issued.
431 @cmd{END CASE} is used only within @cmd{INPUT PROGRAM} to output the
432 current case. @xref{INPUT PROGRAM}, for details.
442 @cmd{END FILE} is used only within @cmd{INPUT PROGRAM} to terminate
443 the current input program. @xref{INPUT PROGRAM}.
451 FILE HANDLE handle_name
456 For binary files with fixed-length records:
457 FILE HANDLE handle_name
462 To explicitly declare a scratch handle:
463 FILE HANDLE handle_name
467 Use @cmd{FILE HANDLE} to associate a file handle name with a file and
468 its attributes, so that later commands can refer to the file by its
469 handle name. Names of text files can be specified directly on
470 commands that access files, so that @cmd{FILE HANDLE} is only needed when a
471 file is not an ordinary file containing lines of text. However,
472 @cmd{FILE HANDLE} may be used even for text files, and it may be
473 easier to specify a file's name once and later refer to it by an
476 Specify the file handle name as the identifier immediately following the
477 @cmd{FILE HANDLE} command name. The identifier INLINE is reserved for
478 representing data embedded in the syntax file (@pxref{BEGIN DATA}) The
479 file handle name must not already have been used in a previous
480 invocation of @cmd{FILE HANDLE}, unless it has been closed by an
481 intervening command (@pxref{CLOSE FILE HANDLE}).
483 MODE specifies a file mode. In CHARACTER mode, the default, the data
484 file is read as a text file, according to the local system's
485 conventions, and each text line is read as one record.
486 In CHARACTER mode, most input programs will expand tabs to spaces
487 (@cmd{DATA LIST FREE} with explicitly specified delimiters is an
488 exception). By default, each tab is 4 characters wide, but an
489 alternate width may be specified on TABWIDTH. A tab width of 0
490 suppresses tab expansion entirely.
492 In IMAGE mode, the data file is opened in ANSI C binary mode. Record
493 length is fixed, with output data truncated or padded with spaces to
494 the record length. LRECL specifies the record length in bytes, with a
495 default of 1024. Tab characters are never expanded to spaces in
498 The NAME subcommand specifies the name of the file associated with the
499 handle. It is required in CHARACTER and IMAGE modes.
501 The SCRATCH mode designates the file handle as a scratch file handle.
502 Its use is usually unnecessary because file handle names that begin with
503 @samp{#} are assumed to refer to scratch files. @pxref{File Handles},
504 for more information.
507 @section INPUT PROGRAM
508 @vindex INPUT PROGRAM
512 @dots{} input commands @dots{}
516 @cmd{INPUT PROGRAM}@dots{}@cmd{END INPUT PROGRAM} specifies a
517 complex input program. By placing data input commands within @cmd{INPUT
518 PROGRAM}, PSPP programs can take advantage of more complex file
519 structures than available with only @cmd{DATA LIST}.
521 The first sort of extended input program is to simply put multiple @cmd{DATA
522 LIST} commands within the @cmd{INPUT PROGRAM}. This will cause all of
524 files to be read in parallel. Input will stop when end of file is
525 reached on any of the data files.
527 Transformations, such as conditional and looping constructs, can also be
528 included within @cmd{INPUT PROGRAM}. These can be used to combine input
529 from several data files in more complex ways. However, input will still
530 stop when end of file is reached on any of the data files.
532 To prevent @cmd{INPUT PROGRAM} from terminating at the first end of
534 the END subcommand on @cmd{DATA LIST}. This subcommand takes a
536 which should be a numeric scratch variable (@pxref{Scratch Variables}).
537 (It need not be a scratch variable but otherwise the results can be
538 surprising.) The value of this variable is set to 0 when reading the
539 data file, or 1 when end of file is encountered.
541 Two additional commands are useful in conjunction with @cmd{INPUT PROGRAM}.
542 @cmd{END CASE} is the first. Normally each loop through the
544 structure produces one case. @cmd{END CASE} controls exactly
545 when cases are output. When @cmd{END CASE} is used, looping from the end of
546 @cmd{INPUT PROGRAM} to the beginning does not cause a case to be output.
548 @cmd{END FILE} is the second. When the END subcommand is used on @cmd{DATA
549 LIST}, there is no way for the @cmd{INPUT PROGRAM} construct to stop
551 so an infinite loop results. @cmd{END FILE}, when executed,
552 stops the flow of input data and passes out of the @cmd{INPUT PROGRAM}
555 All this is very confusing. A few examples should help to clarify.
559 DATA LIST NOTABLE FILE='a.data'/X 1-10.
560 DATA LIST NOTABLE FILE='b.data'/Y 1-10.
565 The example above reads variable X from file @file{a.data} and variable
566 Y from file @file{b.data}. If one file is shorter than the other then
567 the extra data in the longer file is ignored.
574 DATA LIST NOTABLE END=#A FILE='a.data'/X 1-10.
577 DATA LIST NOTABLE END=#B FILE='b.data'/Y 1-10.
587 The above example reads variable X from @file{a.data} and variable Y from
588 @file{b.data}. If one file is shorter than the other then the missing
589 field is set to the system-missing value alongside the present value for
590 the remaining length of the longer file.
597 DATA LIST NOTABLE END=#B FILE='b.data'/X 1-10.
604 DATA LIST NOTABLE END=#A FILE='a.data'/X 1-10.
613 The above example reads data from file @file{a.data}, then from
614 @file{b.data}, and concatenates them into a single active file.
621 DATA LIST NOTABLE END=#EOF FILE='a.data'/X 1-10.
629 DATA LIST NOTABLE END=#EOF FILE='b.data'/X 1-10.
640 The above example does the same thing as the previous example, in a
646 COMPUTE X=UNIFORM(10).
651 LIST/FORMAT=NUMBERED.
654 The above example causes an active file to be created consisting of 50
655 random variates between 0 and 10.
664 /CASES=FROM start_index TO end_index BY incr_index
665 /FORMAT=@{UNNUMBERED,NUMBERED@} @{WRAP,SINGLE@}
669 The @cmd{LIST} procedure prints the values of specified variables to the
672 The VARIABLES subcommand specifies the variables whose values are to be
673 printed. Keyword VARIABLES is optional. If VARIABLES subcommand is not
674 specified then all variables in the active file are printed.
676 The CASES subcommand can be used to specify a subset of cases to be
677 printed. Specify FROM and the case number of the first case to print,
678 TO and the case number of the last case to print, and BY and the number
679 of cases to advance between printing cases, or any subset of those
680 settings. If CASES is not specified then all cases are printed.
682 The FORMAT subcommand can be used to change the output format. NUMBERED
683 will print case numbers along with each case; UNNUMBERED, the default,
684 causes the case numbers to be omitted. The WRAP and SINGLE settings are
685 currently not used. WEIGHT will cause case weights to be printed along
686 with variable values; NOWEIGHT, the default, causes case weights to be
687 omitted from the output.
689 Case numbers start from 1. They are counted after all transformations
690 have been considered.
692 @cmd{LIST} attempts to fit all the values on a single line. If needed
693 to make them fit, variable names are displayed vertically. If values
694 cannot fit on a single line, then a multi-line format will be used.
696 @cmd{LIST} is a procedure. It causes the data to be read.
706 /FORMAT=@{LIST,FREE@} @{LOWER,UPPER,FULL@} @{DIAGONAL,NODIAGONAL@}
707 /SPLIT=@{new_var,var_list@}
711 /CONTENTS=@{N_VECTOR,N_SCALAR,N_MATRIX,MEAN,STDDEV,COUNT,MSE,
712 DFE,MAT,COV,CORR,PROX@}
715 @cmd{MATRIX DATA} command reads square matrices in one of several textual
716 formats. @cmd{MATRIX DATA} clears the dictionary and replaces it and
720 Use VARIABLES to specify the variables that form the rows and columns of
721 the matrices. You may not specify a variable named @code{VARNAME_}. You
722 should specify VARIABLES first.
724 Specify the file to read on FILE, either as a file name string or a file
725 handle (@pxref{File Handles}). If FILE is not specified then matrix data
726 must immediately follow @cmd{MATRIX DATA} with a @cmd{BEGIN
727 DATA}@dots{}@cmd{END DATA}
728 construct (@pxref{BEGIN DATA}).
730 The FORMAT subcommand specifies how the matrices are formatted. LIST,
731 the default, indicates that there is one line per row of matrix data;
732 FREE allows single matrix rows to be broken across multiple lines. This
733 is analogous to the difference between @cmd{DATA LIST FREE} and
735 (@pxref{DATA LIST}). LOWER, the default, indicates that the lower
736 triangle of the matrix is given; UPPER indicates the upper triangle; and
737 FULL indicates that the entire matrix is given. DIAGONAL, the default,
738 indicates that the diagonal is part of the data; NODIAGONAL indicates
739 that it is omitted. DIAGONAL/NODIAGONAL have no effect when FULL is
742 The SPLIT subcommand is used to specify @cmd{SPLIT FILE} variables for the
743 input matrices (@pxref{SPLIT FILE}). Specify either a single variable
744 not specified on VARIABLES, or one or more variables that are specified
745 on VARIABLES. In the former case, the SPLIT values are not present in
746 the data and ROWTYPE_ may not be specified on VARIABLES. In the latter
747 case, the SPLIT values are present in the data.
749 Specify a list of factor variables on FACTORS. Factor variables must
750 also be listed on VARIABLES. Factor variables are used when there are
751 some variables where, for each possible combination of their values,
752 statistics on the matrix variables are included in the data.
754 If FACTORS is specified and ROWTYPE_ is not specified on VARIABLES, the
755 CELLS subcommand is required. Specify the number of factor variable
756 combinations that are given. For instance, if factor variable A has 2
757 values and factor variable B has 3 values, specify 6.
759 The N subcommand specifies a population number of observations. When N
760 is specified, one N record is output for each @cmd{SPLIT FILE}.
762 Use CONTENTS to specify what sort of information the matrices include.
763 Each possible option is described in more detail below. When ROWTYPE_
764 is specified on VARIABLES, CONTENTS is optional; otherwise, if CONTENTS
765 is not specified then /CONTENTS=CORR is assumed.
770 Number of observations as a vector, one value for each variable.
772 Number of observations as a single value.
778 Vector of standard deviations.
782 Vector of mean squared errors.
784 Vector of degrees of freedom.
795 The exact semantics of the matrices read by @cmd{MATRIX DATA} are complex.
796 Right now @cmd{MATRIX DATA} isn't too useful due to a lack of procedures
797 accepting or producing related data, so these semantics aren't
798 documented. Later, they'll be described here in detail.
808 @cmd{NEW FILE} command clears the current active file.
819 [/[line_no] arg@dots{}]
821 arg takes one of the following forms:
823 var_list start-end [type_spec]
824 var_list (fortran_spec)
828 The @cmd{PRINT} transformation writes variable data to the listing
829 file or an output file. @cmd{PRINT} is executed when a procedure
830 causes the data to be read. Follow @cmd{PRINT} by @cmd{EXECUTE} to
831 print variable data without invoking a procedure (@pxref{EXECUTE}).
833 All @cmd{PRINT} subcommands are optional. If no strings or variables
834 are specified, PRINT outputs a single blank line.
836 The OUTFILE subcommand specifies the file to receive the output. The
837 file may be a file name as a string or a file handle (@pxref{File
838 Handles}). If OUTFILE is not present then output will be sent to
839 PSPP's output listing file. When OUTFILE is present, a space is
840 inserted at beginning of each output line, even lines that otherwise
843 The RECORDS subcommand specifies the number of lines to be output. The
844 number of lines may optionally be surrounded by parentheses.
846 TABLE will cause the PRINT command to output a table to the listing file
847 that describes what it will print to the output file. NOTABLE, the
848 default, suppresses this output table.
850 Introduce the strings and variables to be printed with a slash
851 (@samp{/}). Optionally, the slash may be followed by a number
852 indicating which output line will be specified. In the absence of this
853 line number, the next line number will be specified. Multiple lines may
854 be specified using multiple slashes with the intended output for a line
855 following its respective slash.
857 Literal strings may be printed. Specify the string itself. Optionally
858 the string may be followed by a column number or range of column
859 numbers, specifying the location on the line for the string to be
860 printed. Otherwise, the string will be printed at the current position
863 Variables to be printed can be specified in the same ways as available
864 for @cmd{DATA LIST FIXED} (@pxref{DATA LIST FIXED}). In addition, a
866 list may be followed by an asterisk (@samp{*}), which indicates that the
867 variables should be printed in their dictionary print formats, separated
868 by spaces. A variable list followed by a slash or the end of command
869 will be interpreted the same way.
871 If a FORTRAN type specification is used to move backwards on the current
872 line, then text is written at that point on the line, the line will be
873 truncated to that length, although additional text being added will
874 again extend the line to that length.
885 /[line_no] arg@dots{}
887 arg takes one of the following forms:
889 var_list start-end [type_spec]
890 var_list (fortran_spec)
894 @cmd{PRINT EJECT} advances to the beginning of a new output page in
895 the listing file or output file. It can also output data in the same
898 All @cmd{PRINT EJECT} subcommands are optional.
900 Without OUTFILE, PRINT EJECT ejects the current page in
901 the listing file, then it produces other output, if any is specified.
903 With OUTFILE, PRINT EJECT writes its output to the specified file.
904 The first line of output is written with @samp{1} inserted in the
905 first column. Commonly, this is the only line of output. If
906 additional lines of output are specified, these additional lines are
907 written with a space inserted in the first column, as with PRINT.
909 @xref{PRINT}, for more information on syntax and usage.
916 PRINT SPACE OUTFILE='file-name' n_lines.
919 @cmd{PRINT SPACE} prints one or more blank lines to an output file.
921 The OUTFILE subcommand is optional. It may be used to direct output to
922 a file specified by file name as a string or file handle (@pxref{File
923 Handles}). If OUTFILE is not specified then output will be directed to
926 n_lines is also optional. If present, it is an expression
927 (@pxref{Expressions}) specifying the number of blank lines to be
928 printed. The expression must evaluate to a nonnegative value.
935 REREAD FILE=handle COLUMN=column.
938 The @cmd{REREAD} transformation allows the previous input line in a
940 already processed by @cmd{DATA LIST} or another input command to be re-read
941 for further processing.
943 The FILE subcommand, which is optional, is used to specify the file to
944 have its line re-read. The file must be specified as the name of a file
945 handle (@pxref{File Handles}). If FILE is not specified then the last
946 file specified on @cmd{DATA LIST} will be assumed (last file specified
947 lexically, not in terms of flow-of-control).
949 By default, the line re-read is re-read in its entirety. With the
950 COLUMN subcommand, a prefix of the line can be exempted from
951 re-reading. Specify an expression (@pxref{Expressions}) evaluating to
952 the first column that should be included in the re-read line. Columns
953 are numbered from 1 at the left margin.
955 Issuing @code{REREAD} multiple times will not back up in the data
956 file. Instead, it will re-read the same line multiple times.
959 @section REPEATING DATA
960 @vindex REPEATING DATA
968 /CONTINUED[=cont_start-cont_end]
969 /ID=id_start-id_end=id_var
971 /DATA=var_spec@dots{}
973 where each var_spec takes one of the forms
974 var_list start-end [type_spec]
975 var_list (fortran_spec)
978 @cmd{REPEATING DATA} parses groups of data repeating in
979 a uniform format, possibly with several groups on a single line. Each
980 group of data corresponds with one case. @cmd{REPEATING DATA} may only be
981 used within an @cmd{INPUT PROGRAM} structure (@pxref{INPUT PROGRAM}).
982 When used with @cmd{DATA LIST}, it
983 can be used to parse groups of cases that share a subset of variables
984 but differ in their other data.
986 The STARTS subcommand is required. Specify a range of columns, using
987 literal numbers or numeric variable names. This range specifies the
988 columns on the first line that are used to contain groups of data. The
989 ending column is optional. If it is not specified, then the record
990 width of the input file is used. For the inline file (@pxref{BEGIN
991 DATA}) this is 80 columns; for a file with fixed record widths it is the
992 record width; for other files it is 1024 characters by default.
994 The OCCURS subcommand is required. It must be a number or the name of a
995 numeric variable. Its value is the number of groups present in the
998 The DATA subcommand is required. It must be the last subcommand
999 specified. It is used to specify the data present within each repeating
1000 group. Column numbers are specified relative to the beginning of a
1001 group at column 1. Data is specified in the same way as with @cmd{DATA LIST
1002 FIXED} (@pxref{DATA LIST FIXED}).
1004 All other subcommands are optional.
1006 FILE specifies the file to read, either a file name as a string or a
1007 file handle (@pxref{File Handles}). If FILE is not present then the
1008 default is the last file handle used on @cmd{DATA LIST} (lexically, not in
1009 terms of flow of control).
1011 By default @cmd{REPEATING DATA} will output a table describing how it will
1012 parse the input data. Specifying NOTABLE will disable this behavior;
1013 specifying TABLE will explicitly enable it.
1015 The LENGTH subcommand specifies the length in characters of each group.
1016 If it is not present then length is inferred from the DATA subcommand.
1017 LENGTH can be a number or a variable name.
1019 Normally all the data groups are expected to be present on a single
1020 line. Use the CONTINUED command to indicate that data can be continued
1021 onto additional lines. If data on continuation lines starts at the left
1022 margin and continues through the entire field width, no column
1023 specifications are necessary on CONTINUED. Otherwise, specify the
1024 possible range of columns in the same way as on STARTS.
1026 When data groups are continued from line to line, it is easy
1027 for cases to get out of sync through careless hand editing. The
1028 ID subcommand allows a case identifier to be present on each line of
1029 repeating data groups. @cmd{REPEATING DATA} will check for the same
1030 identifier on each line and report mismatches. Specify the range of
1031 columns that the identifier will occupy, followed by an equals sign
1032 (@samp{=}) and the identifier variable name. The variable must already
1033 have been declared with @cmd{NUMERIC} or another command.
1035 @cmd{REPEATING DATA} should be the last command given within an
1036 @cmd{INPUT PROGRAM}. It should not be enclosed within a @cmd{LOOP}
1037 structure (@pxref{LOOP}). Use @cmd{DATA LIST} before, not after,
1038 @cmd{REPEATING DATA}.
1049 /[line_no] arg@dots{}
1051 arg takes one of the following forms:
1052 'string' [start-end]
1053 var_list start-end [type_spec]
1054 var_list (fortran_spec)
1058 @code{WRITE} writes text or binary data to an output file.
1060 @xref{PRINT}, for more information on syntax and usage. @cmd{PRINT}
1061 and @cmd{WRITE} differ in only a few ways:
1065 @cmd{WRITE} uses write formats by default, whereas @cmd{PRINT} uses
1069 @cmd{PRINT} inserts a space between variables unless a format is
1070 explicitly specified, but @cmd{WRITE} never inserts space between
1071 variables in output.
1074 @cmd{PRINT} inserts a space at the beginning of each line that it
1075 writes to an output file (and @cmd{PRINT EJECT} inserts @samp{1} at
1076 the beginning of each line that should begin a new page), but
1077 @cmd{WRITE} does not.
1080 @cmd{PRINT} outputs the system-missing value according to its
1081 specified output format, whereas @cmd{WRITE} outputs the
1082 system-missing value as a field filled with spaces. Binary formats
1085 @setfilename ignored