1 @c (modify-syntax-entry ?_ "w")
2 @c (modify-syntax-entry ?' "'")
3 @c (modify-syntax-entry ?@ "'")
6 @node Data Input and Output
7 @chapter Data Input and Output
14 Data are the focus of the @pspp{} language.
15 Each datum belongs to a @dfn{case} (also called an @dfn{observation}).
16 Each case represents an individual or ``experimental unit''.
17 For example, in the results of a survey, the names of the respondents,
18 their sex, age, etc.@: and their responses are all data and the data
19 pertaining to single respondent is a case.
21 the @pspp{} commands for defining variables and reading and writing data.
22 There are alternative commands to read data from predefined sources
23 such as system files or databases (@xref{GET, GET DATA}.)
26 These commands tell @pspp{} how to read data, but the data will not
27 actually be read until a procedure is executed.
31 * BEGIN DATA:: Embed data within a syntax file.
32 * CLOSE FILE HANDLE:: Close a file handle.
33 * DATAFILE ATTRIBUTE:: Set custom attributes on data files.
34 * DATASET:: Manage multiple datasets.
35 * DATA LIST:: Fundamental data reading command.
36 * END CASE:: Output the current case.
37 * END FILE:: Terminate the current input program.
38 * FILE HANDLE:: Support for special file formats.
39 * INPUT PROGRAM:: Support for complex input programs.
40 * LIST:: List cases in the active dataset.
41 * NEW FILE:: Clear the active dataset.
42 * MATRIX DATA:: Defining matrix material for procedures.
43 * PRINT:: Display values in print formats.
44 * PRINT EJECT:: Eject the current page then print.
45 * PRINT SPACE:: Print blank lines.
46 * REREAD:: Take another look at the previous input line.
47 * REPEATING DATA:: Multiple cases on a single line.
48 * WRITE:: Display values in write formats.
55 @cindex Embedding data in syntax files
56 @cindex Data, embedding in syntax files
64 @cmd{BEGIN DATA} and @cmd{END DATA} can be used to embed raw ASCII
65 data in a @pspp{} syntax file. @cmd{DATA LIST} or another input
66 procedure must be used before @cmd{BEGIN DATA} (@pxref{DATA LIST}).
67 @cmd{BEGIN DATA} and @cmd{END DATA} must be used together. @cmd{END
68 DATA} must appear by itself on a single line, with no leading
69 white space and exactly one space between the words @code{END} and
70 @code{DATA}, like this:
76 @node CLOSE FILE HANDLE
77 @section CLOSE FILE HANDLE
80 CLOSE FILE HANDLE @var{handle_name}.
83 @cmd{CLOSE FILE HANDLE} disassociates the name of a file handle with a
84 given file. The only specification is the name of the handle to close.
88 The file named INLINE, which represents data entered between @cmd{BEGIN
89 DATA} and @cmd{END DATA}, cannot be closed. Attempts to close it with
90 @cmd{CLOSE FILE HANDLE} have no effect.
92 @cmd{CLOSE FILE HANDLE} is a @pspp{} extension.
94 @node DATAFILE ATTRIBUTE
95 @section DATAFILE ATTRIBUTE
96 @vindex DATAFILE ATTRIBUTE
100 ATTRIBUTE=@var{name}('@var{value}') [@var{name}('@var{value}')]@dots{}
101 ATTRIBUTE=@var{name}@b{[}@var{index}@b{]}('@var{value}') [@var{name}@b{[}@var{index}@b{]}('@var{value}')]@dots{}
102 DELETE=@var{name} [@var{name}]@dots{}
103 DELETE=@var{name}@b{[}@var{index}@b{]} [@var{name}@b{[}@var{index}@b{]}]@dots{}
106 @cmd{DATAFILE ATTRIBUTE} adds, modifies, or removes user-defined
107 attributes associated with the active dataset. Custom data file
108 attributes are not interpreted by @pspp{}, but they are saved as part of
109 system files and may be used by other software that reads them.
111 Use the @subcmd{ATTRIBUTE} subcommand to add or modify a custom data file
112 attribute. Specify the name of the attribute as an identifier
113 (@pxref{Tokens}), followed by the desired value, in parentheses, as a
114 quoted string. Attribute names that begin with @code{$} are reserved
115 for @pspp{}'s internal use, and attribute names that begin with @code{@@}
116 or @code{$@@} are not displayed by most @pspp{} commands that display
117 other attributes. Other attribute names are not treated specially.
119 Attributes may also be organized into arrays. To assign to an array
120 element, add an integer array index enclosed in square brackets
121 (@code{[} and @code{]}) between the attribute name and value. Array
122 indexes start at 1, not 0. An attribute array that has a single
123 element (number 1) is not distinguished from a non-array attribute.
125 Use the @subcmd{DELETE} subcommand to delete an attribute. Specify an
126 attribute name by itself to delete an entire attribute, including all
127 array elements for attribute arrays. Specify an attribute name
128 followed by an array index in square brackets to delete a single
129 element of an attribute array. In the latter case, all the array
130 elements numbered higher than the deleted element are shifted down,
131 filling the vacated position.
133 To associate custom attributes with particular variables, instead of
134 with the entire active dataset, use @cmd{VARIABLE ATTRIBUTE}
135 (@pxref{VARIABLE ATTRIBUTE}) instead.
137 @cmd{DATAFILE ATTRIBUTE} takes effect immediately. It is not affected
138 by conditional and looping structures such as @cmd{DO IF} or
142 @section DATASET commands
146 DATASET NAME @var{name} [WINDOW=@{ASIS,FRONT@}].
147 DATASET ACTIVATE @var{name} [WINDOW=@{ASIS,FRONT@}].
148 DATASET COPY @var{name} [WINDOW=@{MINIMIZED,HIDDEN,FRONT@}].
149 DATASET DECLARE @var{name} [WINDOW=@{MINIMIZED,HIDDEN,FRONT@}].
150 DATASET CLOSE @{@var{name},*,ALL@}.
154 The @cmd{DATASET} commands simplify use of multiple datasets within a
155 @pspp{} session. They allow datasets to be created and destroyed. At
156 any given time, most @pspp{} commands work with a single dataset, called
160 The DATASET NAME command gives the active dataset the specified name, or
161 if it already had a name, it renames it. If another dataset already
162 had the given name, that dataset is deleted.
164 @vindex DATASET ACTIVATE
165 The DATASET ACTIVATE command selects the named dataset, which must
166 already exist, as the active dataset. Before switching the active
167 dataset, any pending transformations are executed, as if @cmd{EXECUTE}
168 had been specified. If the active dataset is unnamed before
169 switching, then it is deleted and becomes unavailable after switching.
172 The DATASET COPY command creates a new dataset with the specified
173 name, whose contents are a copy of the active dataset. Any pending
174 transformations are executed, as if @cmd{EXECUTE} had been specified,
175 before making the copy. If a dataset with the given name already
176 exists, it is replaced. If the name is the name of the active
177 dataset, then the active dataset becomes unnamed.
179 @vindex DATASET DECLARE
180 The DATASET DECLARE command creates a new dataset that is initially
181 ``empty,'' that is, it has no dictionary or data. If a dataset with
182 the given name already exists, this has no effect. The new dataset
183 can be used with commands that support output to a dataset,
184 e.g. AGGREGATE (@pxref{AGGREGATE}).
186 @vindex DATASET CLOSE
187 The DATASET CLOSE command deletes a dataset. If the active dataset is
188 specified by name, or if @samp{*} is specified, then the active
189 dataset becomes unnamed. If a different dataset is specified by name,
190 then it is deleted and becomes unavailable. Specifying ALL deletes
191 all datasets except for the active dataset, which becomes unnamed.
193 @vindex DATASET DISPLAY
194 The DATASET DISPLAY command lists all the currently defined datasets.
196 Many DATASET commands accept an optional @subcmd{WINDOW} subcommand. In the
197 @pspp{}IRE GUI, the value given for this subcommand influences how the
198 dataset's window is displayed. Outside the GUI, the @subcmd{WINDOW} subcommand
199 has no effect. The valid values are:
203 Do not change how the window is displayed. This is the default for
204 DATASET NAME and DATASET ACTIVATE.
207 Raise the dataset's window to the top. Make it the default dataset
211 Display the window ``minimized'' to an icon. Prefer other datasets
212 for running syntax. This is the default for DATASET COPY and DATASET
216 Hide the dataset's window. Prefer other datasets for running syntax.
222 @cindex reading data from a file
223 @cindex data, reading from a file
224 @cindex data, embedding in syntax files
225 @cindex embedding data in syntax files
227 Used to read text or binary data, @cmd{DATA LIST} is the most
228 fundamental data-reading command. Even the more sophisticated input
229 methods use @cmd{DATA LIST} commands as a building block.
230 Understanding @cmd{DATA LIST} is important to understanding how to use
231 @pspp{} to read your data files.
233 There are two major variants of @cmd{DATA LIST}, which are fixed
234 format and free format. In addition, free format has a minor variant,
235 list format, which is discussed in terms of its differences from vanilla
238 Each form of @cmd{DATA LIST} is described in detail below.
240 @xref{GET DATA}, for a command that offers a few enhancements over
241 DATA LIST and that may be substituted for DATA LIST in many
245 * DATA LIST FIXED:: Fixed columnar locations for data.
246 * DATA LIST FREE:: Any spacing you like.
247 * DATA LIST LIST:: Each case must be on a single line.
250 @node DATA LIST FIXED
251 @subsection DATA LIST FIXED
252 @vindex DATA LIST FIXED
253 @cindex reading fixed-format data
254 @cindex fixed-format data, reading
255 @cindex data, fixed-format, reading
256 @cindex embedding fixed-format data
261 [FILE='@var{file_name}' [ENCODING='@var{encoding}']]
262 [RECORDS=@var{record_count}]
264 [SKIP=@var{record_count}]
265 /[line_no] @var{var_spec}@dots{}
267 where each @var{var_spec} takes one of the forms
268 @var{var_list} @var{start}-@var{end} [@var{type_spec}]
269 @var{var_list} (@var{fortran_spec})
272 @cmd{DATA LIST FIXED} is used to read data files that have values at fixed
273 positions on each line of single-line or multiline records. The
274 keyword FIXED is optional.
276 The @subcmd{FILE} subcommand must be used if input is to be taken from an
277 external file. It may be used to specify a file name as a string or a
278 file handle (@pxref{File Handles}). If the @subcmd{FILE} subcommand is not used,
279 then input is assumed to be specified within the command file using
280 @cmd{BEGIN DATA}@dots{}@cmd{END DATA} (@pxref{BEGIN DATA}).
281 The @subcmd{ENCODING} subcommand may only be used if the @subcmd{FILE}
282 subcommand is also used. It specifies the character encoding of the
283 file. @xref{INSERT}, for information on supported encodings.
285 The optional @subcmd{RECORDS} subcommand, which takes a single integer as an
286 argument, is used to specify the number of lines per record.
288 is not specified, then the number of lines per record is calculated from
289 the list of variable specifications later in @cmd{DATA LIST}.
291 The @subcmd{END} subcommand is only useful in conjunction with @cmd{INPUT
292 PROGRAM}. @xref{INPUT PROGRAM}, for details.
294 The optional @subcmd{SKIP} subcommand specifies a number of records to skip at
295 the beginning of an input file. It can be used to skip over a row
296 that contains variable names, for example.
298 @cmd{DATA LIST} can optionally output a table describing how the data file
299 will be read. The @subcmd{TABLE} subcommand enables this output, and
300 @subcmd{NOTABLE} disables it. The default is to output the table.
302 The list of variables to be read from the data list must come last.
303 Each line in the data record is introduced by a slash (@samp{/}).
304 Optionally, a line number may follow the slash. Following, any number
305 of variable specifications may be present.
307 Each variable specification consists of a list of variable names
308 followed by a description of their location on the input line. Sets of
309 variables may be specified using the @cmd{DATA LIST} @subcmd{TO} convention
311 Variables}). There are two ways to specify the location of the variable
312 on the line: columnar style and FORTRAN style.
314 In columnar style, the starting column and ending column for the field
315 are specified after the variable name, separated by a dash (@samp{-}).
316 For instance, the third through fifth columns on a line would be
317 specified @samp{3-5}. By default, variables are considered to be in
318 @samp{F} format (@pxref{Input and Output Formats}). (This default can be
319 changed; see @ref{SET} for more information.)
321 In columnar style, to use a variable format other than the default,
322 specify the format type in parentheses after the column numbers. For
323 instance, for alphanumeric @samp{A} format, use @samp{(A)}.
325 In addition, implied decimal places can be specified in parentheses
326 after the column numbers. As an example, suppose that a data file has a
327 field in which the characters @samp{1234} should be interpreted as
328 having the value 12.34. Then this field has two implied decimal places,
329 and the corresponding specification would be @samp{(2)}. If a field
330 that has implied decimal places contains a decimal point, then the
331 implied decimal places are not applied.
333 Changing the variable format and adding implied decimal places can be
334 done together; for instance, @samp{(N,5)}.
336 When using columnar style, the input and output width of each variable is
337 computed from the field width. The field width must be evenly divisible
338 into the number of variables specified.
340 FORTRAN style is an altogether different approach to specifying field
341 locations. With this approach, a list of variable input format
342 specifications, separated by commas, are placed after the variable names
343 inside parentheses. Each format specifier advances as many characters
344 into the input line as it uses.
346 Implied decimal places also exist in FORTRAN style. A format
347 specification with @var{d} decimal places also has @var{d} implied
350 In addition to the standard format specifiers (@pxref{Input and Output
351 Formats}), FORTRAN style defines some extensions:
355 Advance the current column on this line by one character position.
357 @item @code{T}@var{x}
358 Set the current column on this line to column @var{x}, with column
359 numbers considered to begin with 1 at the left margin.
361 @item @code{NEWREC}@var{x}
362 Skip forward @var{x} lines in the current record, resetting the active
363 column to the left margin.
366 Any format specifier may be preceded by a number. This causes the
367 action of that format specifier to be repeated the specified number of
370 @item (@var{spec1}, @dots{}, @var{specN})
371 Group the given specifiers together. This is most useful when preceded
372 by a repeat count. Groups may be nested arbitrarily.
375 FORTRAN and columnar styles may be freely intermixed. Columnar style
376 leaves the active column immediately after the ending column
377 specified. Record motion using @code{NEWREC} in FORTRAN style also
378 applies to later FORTRAN and columnar specifiers.
381 * DATA LIST FIXED Examples:: Examples of DATA LIST FIXED.
384 @node DATA LIST FIXED Examples
385 @unnumberedsubsubsec Examples
390 DATA LIST TABLE /NAME 1-10 (A) INFO1 TO INFO3 12-17 (1).
399 Defines the following variables:
403 @code{NAME}, a 10-character-wide string variable, in columns 1
407 @code{INFO1}, a numeric variable, in columns 12 through 13.
410 @code{INFO2}, a numeric variable, in columns 14 through 15.
413 @code{INFO3}, a numeric variable, in columns 16 through 17.
416 The @code{BEGIN DATA}/@code{END DATA} commands cause three cases to be
420 Case NAME INFO1 INFO2 INFO3
421 1 John Smith 10 23 11
422 2 Bob Arnold 12 20 15
426 The @code{TABLE} keyword causes @pspp{} to print out a table
427 describing the four variables defined.
431 DAT LIS FIL="survey.dat"
432 /ID 1-5 NAME 7-36 (A) SURNAME 38-67 (A) MINITIAL 69 (A)
437 Defines the following variables:
441 @code{ID}, a numeric variable, in columns 1-5 of the first record.
444 @code{NAME}, a 30-character string variable, in columns 7-36 of the
448 @code{SURNAME}, a 30-character string variable, in columns 38-67 of
452 @code{MINITIAL}, a 1-character string variable, in column 69 of
456 Fifty variables @code{Q01}, @code{Q02}, @code{Q03}, @dots{}, @code{Q49},
457 @code{Q50}, all numeric, @code{Q01} in column 7, @code{Q02} in column 8,
458 @dots{}, @code{Q49} in column 55, @code{Q50} in column 56, all in the second
462 Cases are separated by a blank record.
464 Data is read from file @file{survey.dat} in the current directory.
466 This example shows keywords abbreviated to their first 3 letters.
471 @subsection DATA LIST FREE
472 @vindex DATA LIST FREE
476 [(@{TAB,'@var{c}'@}, @dots{})]
478 [FILE='@var{file_name}' [ENCODING='@var{encoding}']]
479 [SKIP=@var{record_cnt}]
480 /@var{var_spec}@dots{}
482 where each @var{var_spec} takes one of the forms
483 @var{var_list} [(@var{type_spec})]
487 In free format, the input data is, by default, structured as a series
488 of fields separated by spaces, tabs, or line breaks.
489 If the current @subcmd{DECIMAL} separator is @subcmd{DOT} (@pxref{SET}),
490 then commas are also treated as field separators.
492 field's content may be unquoted, or it may be quoted with a pairs of
493 apostrophes (@samp{'}) or double quotes (@samp{"}). Unquoted white
494 space separates fields but is not part of any field. Any mix of
495 spaces, tabs, and line breaks is equivalent to a single space for the
496 purpose of separating fields, but consecutive commas will skip a
499 Alternatively, delimiters can be specified explicitly, as a
500 parenthesized, comma-separated list of single-character strings
501 immediately following FREE. The word TAB may also be used to specify
502 a tab character as a delimiter. When delimiters are specified
503 explicitly, only the given characters, plus line breaks, separate
504 fields. Furthermore, leading spaces at the beginnings of fields are
505 not trimmed, consecutive delimiters define empty fields, and no form
506 of quoting is allowed.
508 The @subcmd{NOTABLE} and @subcmd{TABLE} subcommands are as in @cmd{DATA LIST FIXED} above.
509 @subcmd{NOTABLE} is the default.
511 The @subcmd{FILE}, @subcmd{SKIP}, and @subcmd{ENCODING} subcommands
512 are as in @cmd{DATA LIST FIXED} above.
514 The variables to be parsed are given as a single list of variable names.
515 This list must be introduced by a single slash (@samp{/}). The set of
516 variable names may contain format specifications in parentheses
517 (@pxref{Input and Output Formats}). Format specifications apply to all
518 variables back to the previous parenthesized format specification.
520 In addition, an asterisk may be used to indicate that all variables
521 preceding it are to have input/output format @samp{F8.0}.
523 Specified field widths are ignored on input, although all normal limits
524 on field width apply, but they are honored on output.
527 @subsection DATA LIST LIST
528 @vindex DATA LIST LIST
532 [(@{TAB,'@var{c}'@}, @dots{})]
534 [FILE='@var{file_name}' [ENCODING='@var{encoding}']]
535 [SKIP=@var{record_count}]
536 /@var{var_spec}@dots{}
538 where each @var{var_spec} takes one of the forms
539 @var{var_list} [(@var{type_spec})]
543 With one exception, @cmd{DATA LIST LIST} is syntactically and
544 semantically equivalent to @cmd{DATA LIST FREE}. The exception is
545 that each input line is expected to correspond to exactly one input
546 record. If more or fewer fields are found on an input line than
547 expected, an appropriate diagnostic is issued.
557 @cmd{END CASE} is used only within @cmd{INPUT PROGRAM} to output the
558 current case. @xref{INPUT PROGRAM}, for details.
568 @cmd{END FILE} is used only within @cmd{INPUT PROGRAM} to terminate
569 the current input program. @xref{INPUT PROGRAM}.
577 FILE HANDLE @var{handle_name}
578 /NAME='@var{file_name}
581 /TABWIDTH=@var{tab_width}
582 [ENCODING='@var{encoding}']
584 For binary files in native encoding with fixed-length records:
585 FILE HANDLE @var{handle_name}
586 /NAME='@var{file_name}'
588 [/LRECL=@var{rec_len}]
589 [ENCODING='@var{encoding}']
591 For binary files in native encoding with variable-length records:
592 FILE HANDLE @var{handle_name}
593 /NAME='@var{file_name}'
595 [/LRECL=@var{rec_len}]
596 [ENCODING='@var{encoding}']
598 For binary files encoded in EBCDIC:
599 FILE HANDLE @var{handle_name}
600 /NAME='@var{file_name}'
602 /RECFORM=@{FIXED,VARIABLE,SPANNED@}
603 [/LRECL=@var{rec_len}]
604 [ENCODING='@var{encoding}']
607 Use @cmd{FILE HANDLE} to associate a file handle name with a file and
608 its attributes, so that later commands can refer to the file by its
609 handle name. Names of text files can be specified directly on
610 commands that access files, so that @cmd{FILE HANDLE} is only needed when a
611 file is not an ordinary file containing lines of text. However,
612 @cmd{FILE HANDLE} may be used even for text files, and it may be
613 easier to specify a file's name once and later refer to it by an
616 Specify the file handle name as the identifier immediately following the
617 @cmd{FILE HANDLE} command name. The identifier INLINE is reserved for
618 representing data embedded in the syntax file (@pxref{BEGIN DATA}) The
619 file handle name must not already have been used in a previous
620 invocation of @cmd{FILE HANDLE}, unless it has been closed by an
621 intervening command (@pxref{CLOSE FILE HANDLE}).
623 The effect and syntax of @cmd{FILE HANDLE} depends on the selected MODE:
627 In CHARACTER mode, the default, the data file is read as a text file.
628 Each text line is read as one record.
630 In CHARACTER mode only, tabs are expanded to spaces by input programs,
631 except by @cmd{DATA LIST FREE} with explicitly specified delimiters.
632 Each tab is 4 characters wide by default, but TABWIDTH (a @pspp{}
633 extension) may be used to specify an alternate width. Use a TABWIDTH
634 of 0 to suppress tab expansion.
636 A file written in CHARACTER mode by default uses the line ends of the
637 system on which PSPP is running, that is, on Windows, the default is
638 CR LF line ends, and on other systems the default is LF only. Specify
639 ENDS as CR or CRLF to override the default. PSPP reads files using
640 either convention on any kind of system, regardless of ENDS.
643 In IMAGE mode, the data file is treated as a series of fixed-length
644 binary records. LRECL should be used to specify the record length in
645 bytes, with a default of 1024. On input, it is an error if an IMAGE
646 file's length is not a integer multiple of the record length. On
647 output, each record is padded with spaces or truncated, if necessary,
648 to make it exactly the correct length.
651 In BINARY mode, the data file is treated as a series of
652 variable-length binary records. LRECL may be specified, but its value
653 is ignored. The data for each record is both preceded and followed by
654 a 32-bit signed integer in little-endian byte order that specifies the
655 length of the record. (This redundancy permits records in these
656 files to be efficiently read in reverse order, although @pspp{} always
657 reads them in forward order.) The length does not include either
661 Mode 360 reads and writes files in formats first used for tapes in the
662 1960s on IBM mainframe operating systems and still supported today by
663 the modern successors of those operating systems. For more
664 information, see @cite{OS/400 Tape and Diskette Device Programming},
665 available on IBM's website.
667 Alphanumeric data in mode 360 files are encoded in EBCDIC. @pspp{}
668 translates EBCDIC to or from the host's native format as necessary on
669 input or output, using an ASCII/EBCDIC translation that is one-to-one,
670 so that a ``round trip'' from ASCII to EBCDIC back to ASCII, or vice
671 versa, always yields exactly the original data.
673 The @subcmd{RECFORM} subcommand is required in mode 360. The precise file
674 format depends on its setting:
679 This record format is equivalent to IMAGE mode, except for EBCDIC
682 IBM documentation calls this @code{*F} (fixed-length, deblocked)
687 The file comprises a sequence of zero or more variable-length blocks.
688 Each block begins with a 4-byte @dfn{block descriptor word} (BDW).
689 The first two bytes of the BDW are an unsigned integer in big-endian
690 byte order that specifies the length of the block, including the BDW
691 itself. The other two bytes of the BDW are ignored on input and
692 written as zeros on output.
694 Following the BDW, the remainder of each block is a sequence of one or
695 more variable-length records, each of which in turn begins with a
696 4-byte @dfn{record descriptor word} (RDW) that has the same format as
697 the BDW. Following the RDW, the remainder of each record is the
700 The maximum length of a record in VARIABLE mode is 65,527 bytes:
701 65,535 bytes (the maximum value of a 16-bit unsigned integer), minus 4
702 bytes for the BDW, minus 4 bytes for the RDW.
704 In mode VARIABLE, LRECL specifies a maximum, not a fixed, record
705 length, in bytes. The default is 8,192.
707 IBM documentation calls this @code{*VB} (variable-length, blocked,
712 The file format is like that of VARIABLE mode, except that logical
713 records may be split among multiple physical records (called
714 @dfn{segments}) or blocks. In SPANNED mode, the third byte of each
715 RDW is called the segment control character (SCC). Odd SCC values
716 cause the segment to be appended to a record buffer maintained in
717 memory; even values also append the segment and then flush its
718 contents to the input procedure. Canonically, SCC value 0 designates
719 a record not spanned among multiple segments, and values 1 through 3
720 designate the first segment, the last segment, or an intermediate
721 segment, respectively, within a multi-segment record. The record
722 buffer is also flushed at end of file regardless of the final record's
725 The maximum length of a logical record in VARIABLE mode is limited
726 only by memory available to @pspp{}. Segments are limited to 65,527
727 bytes, as in VARIABLE mode.
729 This format is similar to what IBM documentation call @code{*VS}
730 (variable-length, deblocked, spanned) format.
733 In mode 360, fields of type A that extend beyond the end of a record
734 read from disk are padded with spaces in the host's native character
735 set, which are then translated from EBCDIC to the native character
736 set. Thus, when the host's native character set is based on ASCII,
737 these fields are effectively padded with character @code{X'80'}. This
738 wart is implemented for compatibility.
741 The @subcmd{NAME} subcommand specifies the name of the file associated with the
742 handle. It is required in all modes but SCRATCH mode, in which its
745 The ENCODING subcommand specifies the encoding of text in the file.
746 For reading text files in CHARACTER mode, all of the forms described
747 for ENCODING on the INSERT command are supported (@pxref{INSERT}).
748 For reading in other file-based modes, encoding autodetection is not
749 supported; if the specified encoding requests autodetection then the
750 default encoding will be used. This is also true when a file handle
751 is used for writing a file in any mode.
754 @section INPUT PROGRAM
755 @vindex INPUT PROGRAM
759 @dots{} input commands @dots{}
763 @cmd{INPUT PROGRAM}@dots{}@cmd{END INPUT PROGRAM} specifies a
764 complex input program. By placing data input commands within @cmd{INPUT
765 PROGRAM}, @pspp{} programs can take advantage of more complex file
766 structures than available with only @cmd{DATA LIST}.
768 The first sort of extended input program is to simply put multiple @cmd{DATA
769 LIST} commands within the @cmd{INPUT PROGRAM}. This will cause all of
771 files to be read in parallel. Input will stop when end of file is
772 reached on any of the data files.
774 Transformations, such as conditional and looping constructs, can also be
775 included within @cmd{INPUT PROGRAM}. These can be used to combine input
776 from several data files in more complex ways. However, input will still
777 stop when end of file is reached on any of the data files.
779 To prevent @cmd{INPUT PROGRAM} from terminating at the first end of
781 the @subcmd{END} subcommand on @cmd{DATA LIST}. This subcommand takes a
783 which should be a numeric scratch variable (@pxref{Scratch Variables}).
784 (It need not be a scratch variable but otherwise the results can be
785 surprising.) The value of this variable is set to 0 when reading the
786 data file, or 1 when end of file is encountered.
788 Two additional commands are useful in conjunction with @cmd{INPUT PROGRAM}.
789 @cmd{END CASE} is the first. Normally each loop through the
791 structure produces one case. @cmd{END CASE} controls exactly
792 when cases are output. When @cmd{END CASE} is used, looping from the end of
793 @cmd{INPUT PROGRAM} to the beginning does not cause a case to be output.
795 @cmd{END FILE} is the second. When the @subcmd{END} subcommand is used on @cmd{DATA
796 LIST}, there is no way for the @cmd{INPUT PROGRAM} construct to stop
798 so an infinite loop results. @cmd{END FILE}, when executed,
799 stops the flow of input data and passes out of the @cmd{INPUT PROGRAM}
802 @cmd{INPUT PROGRAM} must contain at least one @cmd{DATA LIST} or
803 @cmd{END FILE} command.
805 All this is very confusing. A few examples should help to clarify.
807 @c If you change this example, change the regression test1 in
808 @c tests/command/input-program.sh to match.
811 DATA LIST NOTABLE FILE='a.data'/X 1-10.
812 DATA LIST NOTABLE FILE='b.data'/Y 1-10.
817 The example above reads variable X from file @file{a.data} and variable
818 Y from file @file{b.data}. If one file is shorter than the other then
819 the extra data in the longer file is ignored.
821 @c If you change this example, change the regression test2 in
822 @c tests/command/input-program.sh to match.
828 DATA LIST NOTABLE END=#A FILE='a.data'/X 1-10.
831 DATA LIST NOTABLE END=#B FILE='b.data'/Y 1-10.
841 The above example reads variable X from @file{a.data} and variable Y from
842 @file{b.data}. If one file is shorter than the other then the missing
843 field is set to the system-missing value alongside the present value for
844 the remaining length of the longer file.
846 @c If you change this example, change the regression test3 in
847 @c tests/command/input-program.sh to match.
853 DATA LIST NOTABLE END=#B FILE='b.data'/X 1-10.
860 DATA LIST NOTABLE END=#A FILE='a.data'/X 1-10.
869 The above example reads data from file @file{a.data}, then from
870 @file{b.data}, and concatenates them into a single active dataset.
872 @c If you change this example, change the regression test4 in
873 @c tests/command/input-program.sh to match.
879 DATA LIST NOTABLE END=#EOF FILE='a.data'/X 1-10.
887 DATA LIST NOTABLE END=#EOF FILE='b.data'/X 1-10.
898 The above example does the same thing as the previous example, in a
901 @c If you change this example, make similar changes to the regression
902 @c test5 in tests/command/input-program.sh.
906 COMPUTE X=UNIFORM(10).
911 LIST/FORMAT=NUMBERED.
914 The above example causes an active dataset to be created consisting of 50
915 random variates between 0 and 10.
923 /VARIABLES=@var{var_list}
924 /CASES=FROM @var{start_index} TO @var{end_index} BY @var{incr_index}
925 /FORMAT=@{UNNUMBERED,NUMBERED@} @{WRAP,SINGLE@}
928 The @cmd{LIST} procedure prints the values of specified variables to the
931 The @subcmd{VARIABLES} subcommand specifies the variables whose values are to be
932 printed. Keyword VARIABLES is optional. If @subcmd{VARIABLES} subcommand is not
933 specified then all variables in the active dataset are printed.
935 The @subcmd{CASES} subcommand can be used to specify a subset of cases to be
936 printed. Specify @subcmd{FROM} and the case number of the first case to print,
937 @subcmd{TO} and the case number of the last case to print, and @subcmd{BY} and the number
938 of cases to advance between printing cases, or any subset of those
939 settings. If @subcmd{CASES} is not specified then all cases are printed.
941 The @subcmd{FORMAT} subcommand can be used to change the output format. @subcmd{NUMBERED}
942 will print case numbers along with each case; @subcmd{UNNUMBERED}, the default,
943 causes the case numbers to be omitted. The @subcmd{WRAP} and @subcmd{SINGLE} settings are
946 Case numbers start from 1. They are counted after all transformations
947 have been considered.
949 @cmd{LIST} is a procedure. It causes the data to be read.
959 @cmd{NEW FILE} command clears the dictionary and data from the current
968 VARIABLES = @var{columns}
969 [FILE='@var{file_name}'| INLINE @}
970 [/FORMAT= [@{LIST | FREE@}]
971 [@{UPPER | LOWER | FULL@}]
972 [@{DIAGONAL | NODIAGONAL@}]]
974 [/SPLIT= @var{split_variables}].
977 The @cmd{MATRIX DATA} command is used to input data in the form of matrices
978 which can subsequently be used by other commands. If the
979 @subcmd{FILE} is omitted or takes the value @samp{INLINE} then the command
980 should immediately followed by @cmd{BEGIN DATA}, @xref{BEGIN DATA}.
982 There is one mandatory subcommand, @i{viz:} @subcmd{VARIABLES}, which defines
983 the @var{columns} of the matrix.
984 Normally, the @var{columns} should include an item called @samp{ROWTYPE_}.
985 The @samp{ROWTYPE_} column is used to specify the purpose of a row in the
990 variables = rowtype_ var01 TO var08.
993 mean 24.3 5.4 69.7 20.1 13.4 2.7 27.9 3.7
994 sd 5.7 1.5 23.5 5.8 2.8 4.5 5.4 1.5
995 n 92 92 92 92 92 92 92 92
999 corr .36 .31 -.14 1.00
1000 corr .27 .16 -.12 .22 1.00
1001 corr .33 .15 -.17 .24 .21 1.00
1002 corr .50 .29 -.20 .32 .12 .38 1.00
1003 corr .17 .29 -.05 .20 .27 .20 .04 1.00
1007 In the above example, the first three rows have ROWTYPE_ values of
1008 @samp{mean}, @samp{sd}, and @samp{n}. These indicate that the rows
1009 contain mean values, standard deviations and counts, respectively.
1010 All subsequent rows have a ROWTYPE_ of @samp{corr} which indicates
1011 that the values are correlation coefficients.
1013 Note that in this example, the upper right values of the @samp{corr}
1014 values are blank, and in each case, the rightmost value is unity.
1015 This is because, the
1016 @subcmd{FORMAT} subcommand defaults to @samp{LOWER DIAGONAL},
1017 which indicates that only the lower triangle is provided in the data.
1018 The opposite triangle is automatically inferred. One could instead
1019 specify the upper triangle as follows:
1024 variables = rowtype_ var01 TO var08
1025 /format = upper nodiagonal.
1028 mean 24.3 5.4 69.7 20.1 13.4 2.7 27.9 3.7
1029 sd 5.7 1.5 23.5 5.8 2.8 4.5 5.4 1.5
1030 n 92 92 92 92 92 92 92 92
1031 corr .17 .50 -.33 .27 .36 -.22 .18
1032 corr .29 .29 -.20 .32 .12 .38
1033 corr .05 .20 -.15 .16 .21
1034 corr .20 .32 -.17 .12
1041 In this example the @samp{NODIAGONAL} keyword is used. Accordingly
1042 the diagonal values of the matrix are omitted. This implies that
1043 there is one less @samp{corr} line than there are variables.
1044 If the @samp{FULL} option is passed to the @subcmd{FORMAT} subcommand,
1045 then all the matrix elements must be provided, including the diagonal
1048 In the preceding examples, each matrix row has been specified on a
1049 single line. If you pass the keyword @var{FREE} to @subcmd{FORMAT}
1050 then the data may be data for several matrix rows may be specified on
1051 the same line, or a single row may be split across lines.
1053 The @subcmd{N} subcommand may be used to specify the number
1054 of valid cases for each variable. It should not be used if the
1055 data contains a record whose ROWTYPE_ column is @samp{N} or @samp{N_VECTOR}.
1056 It implies a @samp{N} record whose values are all @var{n}.
1060 variables = rowtype_ var01 TO var04
1061 /format = upper nodiagonal
1071 produces an effect identical to
1074 variables = rowtype_ var01 TO var04
1075 /format = upper nodiagonal
1087 The @subcmd{SPLIT} is used to indicate that variables are to be
1088 considered as split variables. For example, the following
1089 defines two matrices using the variable @samp{S1} to distinguish
1094 variables = s1 rowtype_ var01 TO var04
1096 /format = full diagonal.
1122 [OUTFILE='@var{file_name}']
1123 [RECORDS=@var{n_lines}]
1125 [ENCODING='@var{encoding}']
1126 [/[@var{line_no}] @var{arg}@dots{}]
1128 @var{arg} takes one of the following forms:
1129 '@var{string}' [@var{start}]
1130 @var{var_list} @var{start}-@var{end} [@var{type_spec}]
1131 @var{var_list} (@var{fortran_spec})
1135 The @cmd{PRINT} transformation writes variable data to the listing
1136 file or an output file. @cmd{PRINT} is executed when a procedure
1137 causes the data to be read. Follow @cmd{PRINT} by @cmd{EXECUTE} to
1138 print variable data without invoking a procedure (@pxref{EXECUTE}).
1140 All @cmd{PRINT} subcommands are optional. If no strings or variables
1141 are specified, @cmd{PRINT} outputs a single blank line.
1143 The @subcmd{OUTFILE} subcommand specifies the file to receive the output. The
1144 file may be a file name as a string or a file handle (@pxref{File
1145 Handles}). If @subcmd{OUTFILE} is not present then output will be sent to
1146 @pspp{}'s output listing file. When @subcmd{OUTFILE} is present, a space is
1147 inserted at beginning of each output line, even lines that otherwise
1150 The @subcmd{ENCODING} subcommand may only be used if the
1151 @subcmd{OUTFILE} subcommand is also used. It specifies the character
1152 encoding of the file. @xref{INSERT}, for information on supported
1155 The @subcmd{RECORDS} subcommand specifies the number of lines to be output. The
1156 number of lines may optionally be surrounded by parentheses.
1158 @subcmd{TABLE} will cause the @cmd{PRINT} command to output a table to the listing file
1159 that describes what it will print to the output file. @subcmd{NOTABLE}, the
1160 default, suppresses this output table.
1162 Introduce the strings and variables to be printed with a slash
1163 (@samp{/}). Optionally, the slash may be followed by a number
1164 indicating which output line will be specified. In the absence of this
1165 line number, the next line number will be specified. Multiple lines may
1166 be specified using multiple slashes with the intended output for a line
1167 following its respective slash.
1169 Literal strings may be printed. Specify the string itself.
1170 Optionally the string may be followed by a column number, specifying
1171 the column on the line where the string should start. Otherwise, the
1172 string will be printed at the current position on the line.
1174 Variables to be printed can be specified in the same ways as available
1175 for @cmd{DATA LIST FIXED} (@pxref{DATA LIST FIXED}). In addition, a
1177 list may be followed by an asterisk (@samp{*}), which indicates that the
1178 variables should be printed in their dictionary print formats, separated
1179 by spaces. A variable list followed by a slash or the end of command
1180 will be interpreted the same way.
1182 If a FORTRAN type specification is used to move backwards on the current
1183 line, then text is written at that point on the line, the line will be
1184 truncated to that length, although additional text being added will
1185 again extend the line to that length.
1188 @section PRINT EJECT
1193 OUTFILE='@var{file_name}'
1194 RECORDS=@var{n_lines}
1196 /[@var{line_no}] @var{arg}@dots{}
1198 @var{arg} takes one of the following forms:
1199 '@var{string}' [@var{start}-@var{end}]
1200 @var{var_list} @var{start}-@var{end} [@var{type_spec}]
1201 @var{var_list} (@var{fortran_spec})
1205 @cmd{PRINT EJECT} advances to the beginning of a new output page in
1206 the listing file or output file. It can also output data in the same
1209 All @cmd{PRINT EJECT} subcommands are optional.
1211 Without @subcmd{OUTFILE}, @cmd{PRINT EJECT} ejects the current page in
1212 the listing file, then it produces other output, if any is specified.
1214 With @subcmd{OUTFILE}, @cmd{PRINT EJECT} writes its output to the specified file.
1215 The first line of output is written with @samp{1} inserted in the
1216 first column. Commonly, this is the only line of output. If
1217 additional lines of output are specified, these additional lines are
1218 written with a space inserted in the first column, as with @subcmd{PRINT}.
1220 @xref{PRINT}, for more information on syntax and usage.
1223 @section PRINT SPACE
1227 PRINT SPACE [OUTFILE='file_name'] [ENCODING='@var{encoding}'] [n_lines].
1230 @cmd{PRINT SPACE} prints one or more blank lines to an output file.
1232 The @subcmd{OUTFILE} subcommand is optional. It may be used to direct output to
1233 a file specified by file name as a string or file handle (@pxref{File
1234 Handles}). If OUTFILE is not specified then output will be directed to
1237 The @subcmd{ENCODING} subcommand may only be used if @subcmd{OUTFILE}
1238 is also used. It specifies the character encoding of the file.
1239 @xref{INSERT}, for information on supported encodings.
1241 n_lines is also optional. If present, it is an expression
1242 (@pxref{Expressions}) specifying the number of blank lines to be
1243 printed. The expression must evaluate to a nonnegative value.
1250 REREAD [FILE=handle] [COLUMN=column] [ENCODING='@var{encoding}'].
1253 The @cmd{REREAD} transformation allows the previous input line in a
1255 already processed by @cmd{DATA LIST} or another input command to be re-read
1256 for further processing.
1258 The @subcmd{FILE} subcommand, which is optional, is used to specify the file to
1259 have its line re-read. The file must be specified as the name of a file
1260 handle (@pxref{File Handles}). If FILE is not specified then the last
1261 file specified on @cmd{DATA LIST} will be assumed (last file specified
1262 lexically, not in terms of flow-of-control).
1264 By default, the line re-read is re-read in its entirety. With the
1265 @subcmd{COLUMN} subcommand, a prefix of the line can be exempted from
1266 re-reading. Specify an expression (@pxref{Expressions}) evaluating to
1267 the first column that should be included in the re-read line. Columns
1268 are numbered from 1 at the left margin.
1270 The @subcmd{ENCODING} subcommand may only be used if the @subcmd{FILE}
1271 subcommand is also used. It specifies the character encoding of the
1272 file. @xref{INSERT}, for information on supported encodings.
1274 Issuing @code{REREAD} multiple times will not back up in the data
1275 file. Instead, it will re-read the same line multiple times.
1277 @node REPEATING DATA
1278 @section REPEATING DATA
1279 @vindex REPEATING DATA
1283 /STARTS=@var{start}-@var{end}
1284 /OCCURS=@var{n_occurs}
1285 /FILE='@var{file_name}'
1286 /LENGTH=@var{length}
1287 /CONTINUED[=@var{cont_start}-@var{cont_end}]
1288 /ID=@var{id_start}-@var{id_end}=@var{id_var}
1290 /DATA=@var{var_spec}@dots{}
1292 where each @var{var_spec} takes one of the forms
1293 @var{var_list} @var{start}-@var{end} [@var{type_spec}]
1294 @var{var_list} (@var{fortran_spec})
1297 @cmd{REPEATING DATA} parses groups of data repeating in
1298 a uniform format, possibly with several groups on a single line. Each
1299 group of data corresponds with one case. @cmd{REPEATING DATA} may only be
1300 used within an @cmd{INPUT PROGRAM} structure (@pxref{INPUT PROGRAM}).
1301 When used with @cmd{DATA LIST}, it
1302 can be used to parse groups of cases that share a subset of variables
1303 but differ in their other data.
1305 The @subcmd{STARTS} subcommand is required. Specify a range of columns, using
1306 literal numbers or numeric variable names. This range specifies the
1307 columns on the first line that are used to contain groups of data. The
1308 ending column is optional. If it is not specified, then the record
1309 width of the input file is used. For the inline file (@pxref{BEGIN
1310 DATA}) this is 80 columns; for a file with fixed record widths it is the
1311 record width; for other files it is 1024 characters by default.
1313 The @subcmd{OCCURS} subcommand is required. It must be a number or the name of a
1314 numeric variable. Its value is the number of groups present in the
1317 The @subcmd{DATA} subcommand is required. It must be the last subcommand
1318 specified. It is used to specify the data present within each repeating
1319 group. Column numbers are specified relative to the beginning of a
1320 group at column 1. Data is specified in the same way as with @cmd{DATA LIST
1321 FIXED} (@pxref{DATA LIST FIXED}).
1323 All other subcommands are optional.
1325 FILE specifies the file to read, either a file name as a string or a
1326 file handle (@pxref{File Handles}). If FILE is not present then the
1327 default is the last file handle used on @cmd{DATA LIST} (lexically, not in
1328 terms of flow of control).
1330 By default @cmd{REPEATING DATA} will output a table describing how it will
1331 parse the input data. Specifying @subcmd{NOTABLE} will disable this behavior;
1332 specifying TABLE will explicitly enable it.
1334 The @subcmd{LENGTH} subcommand specifies the length in characters of each group.
1335 If it is not present then length is inferred from the @subcmd{DATA} subcommand.
1336 LENGTH can be a number or a variable name.
1338 Normally all the data groups are expected to be present on a single
1339 line. Use the @subcmd{CONTINUED} command to indicate that data can be continued
1340 onto additional lines. If data on continuation lines starts at the left
1341 margin and continues through the entire field width, no column
1342 specifications are necessary on @subcmd{CONTINUED}. Otherwise, specify the
1343 possible range of columns in the same way as on STARTS.
1345 When data groups are continued from line to line, it is easy
1346 for cases to get out of sync through careless hand editing. The
1347 @subcmd{ID} subcommand allows a case identifier to be present on each line of
1348 repeating data groups. @cmd{REPEATING DATA} will check for the same
1349 identifier on each line and report mismatches. Specify the range of
1350 columns that the identifier will occupy, followed by an equals sign
1351 (@samp{=}) and the identifier variable name. The variable must already
1352 have been declared with @cmd{NUMERIC} or another command.
1354 @cmd{REPEATING DATA} should be the last command given within an
1355 @cmd{INPUT PROGRAM}. It should not be enclosed within a @cmd{LOOP}
1356 structure (@pxref{LOOP}). Use @cmd{DATA LIST} before, not after,
1357 @cmd{REPEATING DATA}.
1365 OUTFILE='@var{file_name}'
1366 RECORDS=@var{n_lines}
1368 /[@var{line_no}] @var{arg}@dots{}
1370 @var{arg} takes one of the following forms:
1371 '@var{string}' [@var{start}-@var{end}]
1372 @var{var_list} @var{start}-@var{end} [@var{type_spec}]
1373 @var{var_list} (@var{fortran_spec})
1377 @code{WRITE} writes text or binary data to an output file.
1379 @xref{PRINT}, for more information on syntax and usage. @cmd{PRINT}
1380 and @cmd{WRITE} differ in only a few ways:
1384 @cmd{WRITE} uses write formats by default, whereas @cmd{PRINT} uses
1388 @cmd{PRINT} inserts a space between variables unless a format is
1389 explicitly specified, but @cmd{WRITE} never inserts space between
1390 variables in output.
1393 @cmd{PRINT} inserts a space at the beginning of each line that it
1394 writes to an output file (and @cmd{PRINT EJECT} inserts @samp{1} at
1395 the beginning of each line that should begin a new page), but
1396 @cmd{WRITE} does not.
1399 @cmd{PRINT} outputs the system-missing value according to its
1400 specified output format, whereas @cmd{WRITE} outputs the
1401 system-missing value as a field filled with spaces. Binary formats