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".
10 @c (modify-syntax-entry ?_ "w")
11 @c (modify-syntax-entry ?' "'")
12 @c (modify-syntax-entry ?@ "'")
15 @node Data Input and Output
16 @chapter Data Input and Output
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.
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}.)
35 These commands tell @pspp{} how to read data, but the data will not
36 actually be read until a procedure is executed.
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.
63 @cindex Embedding data in syntax files
64 @cindex Data, embedding in syntax files
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:
84 @node CLOSE FILE HANDLE
85 @section CLOSE FILE HANDLE
88 CLOSE FILE HANDLE @var{handle_name}.
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.
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.
100 @cmd{CLOSE FILE HANDLE} is a @pspp{} extension.
102 @node DATAFILE ATTRIBUTE
103 @section DATAFILE ATTRIBUTE
104 @vindex 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{}
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.
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.
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.
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.
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.
145 @cmd{DATAFILE ATTRIBUTE} takes effect immediately. It is not affected
146 by conditional and looping structures such as @cmd{DO IF} or
150 @section DATASET commands
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@}.
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
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.
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.
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.
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}).
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.
201 @vindex DATASET DISPLAY
202 The DATASET DISPLAY command lists all the currently defined datasets.
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:
211 Do not change how the window is displayed. This is the default for
212 DATASET NAME and DATASET ACTIVATE.
215 Raise the dataset's window to the top. Make it the default dataset
219 Display the window ``minimized'' to an icon. Prefer other datasets
220 for running syntax. This is the default for DATASET COPY and DATASET
224 Hide the dataset's window. Prefer other datasets for running syntax.
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
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.
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
246 Each form of @cmd{DATA LIST} is described in detail below.
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
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.
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
269 [FILE='@var{file_name}' [ENCODING='@var{encoding}']]
270 [RECORDS=@var{record_count}]
272 [SKIP=@var{record_count}]
273 /[line_no] @var{var_spec}@dots{}
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})
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.
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.
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.
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}.
299 The @subcmd{END} subcommand is only useful in conjunction with @cmd{INPUT
300 PROGRAM}. @xref{INPUT PROGRAM}, for details.
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.
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.
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.
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
319 Variables}). There are two ways to specify the location of the variable
320 on the line: columnar style and FORTRAN style.
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.)
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)}.
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.
341 Changing the variable format and adding implied decimal places can be
342 done together; for instance, @samp{(N,5)}.
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.
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.
354 Implied decimal places also exist in FORTRAN style. A format
355 specification with @var{d} decimal places also has @var{d} implied
358 In addition to the standard format specifiers (@pxref{Input and Output
359 Formats}), FORTRAN style defines some extensions:
363 Advance the current column on this line by one character position.
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.
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.
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
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.
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.
389 * DATA LIST FIXED Examples:: Examples of DATA LIST FIXED.
392 @node DATA LIST FIXED Examples
393 @unnumberedsubsubsec Examples
397 @c Update the corresponding test in tests/language/commands/data-list.at if you change this.
399 DATA LIST TABLE /NAME 1-10 (A) INFO1 TO INFO3 12-17 (1).
408 Defines the following variables:
412 @code{NAME}, a 10-character-wide string variable, in columns 1
416 @code{INFO1}, a numeric variable, in columns 12 through 13.
419 @code{INFO2}, a numeric variable, in columns 14 through 15.
422 @code{INFO3}, a numeric variable, in columns 16 through 17.
425 The @code{BEGIN DATA}/@code{END DATA} commands cause three cases to be
429 Case NAME INFO1 INFO2 INFO3
430 1 John Smith 10 23 11
431 2 Bob Arnold 12 20 15
435 The @code{TABLE} keyword causes @pspp{} to print out a table
436 describing the four variables defined.
439 @c Update the corresponding test in tests/language/commands/data-list.at if you change this.
441 DATA LIST FILE="survey.dat"
442 /ID 1-5 NAME 7-36 (A) SURNAME 38-67 (A) MINITIAL 69 (A)
447 Defines the following variables:
451 @code{ID}, a numeric variable, in columns 1-5 of the first record.
454 @code{NAME}, a 30-character string variable, in columns 7-36 of the
458 @code{SURNAME}, a 30-character string variable, in columns 38-67 of
462 @code{MINITIAL}, a 1-character string variable, in column 69 of
466 Fifty variables @code{Q01}, @code{Q02}, @code{Q03}, @dots{}, @code{Q49},
467 @code{Q50}, all numeric, @code{Q01} in column 7, @code{Q02} in column 8,
468 @dots{}, @code{Q49} in column 55, @code{Q50} in column 56, all in the second
472 Cases are separated by a blank record.
474 Data is read from file @file{survey.dat} in the current directory.
478 @subsection DATA LIST FREE
479 @vindex DATA LIST FREE
483 [(@{TAB,'@var{c}'@}, @dots{})]
485 [FILE='@var{file_name}' [ENCODING='@var{encoding}']]
486 [SKIP=@var{n_records}]
487 /@var{var_spec}@dots{}
489 where each @var{var_spec} takes one of the forms
490 @var{var_list} [(@var{type_spec})]
494 In free format, the input data is, by default, structured as a series
495 of fields separated by spaces, tabs, or line breaks.
496 If the current @subcmd{DECIMAL} separator is @subcmd{DOT} (@pxref{SET}),
497 then commas are also treated as field separators.
499 field's content may be unquoted, or it may be quoted with a pairs of
500 apostrophes (@samp{'}) or double quotes (@samp{"}). Unquoted white
501 space separates fields but is not part of any field. Any mix of
502 spaces, tabs, and line breaks is equivalent to a single space for the
503 purpose of separating fields, but consecutive commas will skip a
506 Alternatively, delimiters can be specified explicitly, as a
507 parenthesized, comma-separated list of single-character strings
508 immediately following FREE. The word TAB may also be used to specify
509 a tab character as a delimiter. When delimiters are specified
510 explicitly, only the given characters, plus line breaks, separate
511 fields. Furthermore, leading spaces at the beginnings of fields are
512 not trimmed, consecutive delimiters define empty fields, and no form
513 of quoting is allowed.
515 The @subcmd{NOTABLE} and @subcmd{TABLE} subcommands are as in @cmd{DATA LIST FIXED} above.
516 @subcmd{NOTABLE} is the default.
518 The @subcmd{FILE}, @subcmd{SKIP}, and @subcmd{ENCODING} subcommands
519 are as in @cmd{DATA LIST FIXED} above.
521 The variables to be parsed are given as a single list of variable names.
522 This list must be introduced by a single slash (@samp{/}). The set of
523 variable names may contain format specifications in parentheses
524 (@pxref{Input and Output Formats}). Format specifications apply to all
525 variables back to the previous parenthesized format specification.
527 In addition, an asterisk may be used to indicate that all variables
528 preceding it are to have input/output format @samp{F8.0}.
530 Specified field widths are ignored on input, although all normal limits
531 on field width apply, but they are honored on output.
534 @subsection DATA LIST LIST
535 @vindex DATA LIST LIST
539 [(@{TAB,'@var{c}'@}, @dots{})]
541 [FILE='@var{file_name}' [ENCODING='@var{encoding}']]
542 [SKIP=@var{record_count}]
543 /@var{var_spec}@dots{}
545 where each @var{var_spec} takes one of the forms
546 @var{var_list} [(@var{type_spec})]
550 With one exception, @cmd{DATA LIST LIST} is syntactically and
551 semantically equivalent to @cmd{DATA LIST FREE}. The exception is
552 that each input line is expected to correspond to exactly one input
553 record. If more or fewer fields are found on an input line than
554 expected, an appropriate diagnostic is issued.
564 @cmd{END CASE} is used only within @cmd{INPUT PROGRAM} to output the
565 current case. @xref{INPUT PROGRAM}, for details.
575 @cmd{END FILE} is used only within @cmd{INPUT PROGRAM} to terminate
576 the current input program. @xref{INPUT PROGRAM}.
584 FILE HANDLE @var{handle_name}
585 /NAME='@var{file_name}
588 /TABWIDTH=@var{tab_width}
589 [ENCODING='@var{encoding}']
591 For binary files in native encoding with fixed-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 in native encoding with variable-length records:
599 FILE HANDLE @var{handle_name}
600 /NAME='@var{file_name}'
602 [/LRECL=@var{rec_len}]
603 [ENCODING='@var{encoding}']
605 For binary files encoded in EBCDIC:
606 FILE HANDLE @var{handle_name}
607 /NAME='@var{file_name}'
609 /RECFORM=@{FIXED,VARIABLE,SPANNED@}
610 [/LRECL=@var{rec_len}]
611 [ENCODING='@var{encoding}']
614 Use @cmd{FILE HANDLE} to associate a file handle name with a file and
615 its attributes, so that later commands can refer to the file by its
616 handle name. Names of text files can be specified directly on
617 commands that access files, so that @cmd{FILE HANDLE} is only needed when a
618 file is not an ordinary file containing lines of text. However,
619 @cmd{FILE HANDLE} may be used even for text files, and it may be
620 easier to specify a file's name once and later refer to it by an
623 Specify the file handle name as the identifier immediately following the
624 @cmd{FILE HANDLE} command name. The identifier INLINE is reserved for
625 representing data embedded in the syntax file (@pxref{BEGIN DATA}) The
626 file handle name must not already have been used in a previous
627 invocation of @cmd{FILE HANDLE}, unless it has been closed by an
628 intervening command (@pxref{CLOSE FILE HANDLE}).
630 The effect and syntax of @cmd{FILE HANDLE} depends on the selected MODE:
634 In CHARACTER mode, the default, the data file is read as a text file.
635 Each text line is read as one record.
637 In CHARACTER mode only, tabs are expanded to spaces by input programs,
638 except by @cmd{DATA LIST FREE} with explicitly specified delimiters.
639 Each tab is 4 characters wide by default, but TABWIDTH (a @pspp{}
640 extension) may be used to specify an alternate width. Use a TABWIDTH
641 of 0 to suppress tab expansion.
643 A file written in CHARACTER mode by default uses the line ends of the
644 system on which PSPP is running, that is, on Windows, the default is
645 CR LF line ends, and on other systems the default is LF only. Specify
646 ENDS as CR or CRLF to override the default. PSPP reads files using
647 either convention on any kind of system, regardless of ENDS.
650 In IMAGE mode, the data file is treated as a series of fixed-length
651 binary records. LRECL should be used to specify the record length in
652 bytes, with a default of 1024. On input, it is an error if an IMAGE
653 file's length is not a integer multiple of the record length. On
654 output, each record is padded with spaces or truncated, if necessary,
655 to make it exactly the correct length.
658 In BINARY mode, the data file is treated as a series of
659 variable-length binary records. LRECL may be specified, but its value
660 is ignored. The data for each record is both preceded and followed by
661 a 32-bit signed integer in little-endian byte order that specifies the
662 length of the record. (This redundancy permits records in these
663 files to be efficiently read in reverse order, although @pspp{} always
664 reads them in forward order.) The length does not include either
668 Mode 360 reads and writes files in formats first used for tapes in the
669 1960s on IBM mainframe operating systems and still supported today by
670 the modern successors of those operating systems. For more
671 information, see @cite{OS/400 Tape and Diskette Device Programming},
672 available on IBM's website.
674 Alphanumeric data in mode 360 files are encoded in EBCDIC. @pspp{}
675 translates EBCDIC to or from the host's native format as necessary on
676 input or output, using an ASCII/EBCDIC translation that is one-to-one,
677 so that a ``round trip'' from ASCII to EBCDIC back to ASCII, or vice
678 versa, always yields exactly the original data.
680 The @subcmd{RECFORM} subcommand is required in mode 360. The precise file
681 format depends on its setting:
686 This record format is equivalent to IMAGE mode, except for EBCDIC
689 IBM documentation calls this @code{*F} (fixed-length, deblocked)
694 The file comprises a sequence of zero or more variable-length blocks.
695 Each block begins with a 4-byte @dfn{block descriptor word} (BDW).
696 The first two bytes of the BDW are an unsigned integer in big-endian
697 byte order that specifies the length of the block, including the BDW
698 itself. The other two bytes of the BDW are ignored on input and
699 written as zeros on output.
701 Following the BDW, the remainder of each block is a sequence of one or
702 more variable-length records, each of which in turn begins with a
703 4-byte @dfn{record descriptor word} (RDW) that has the same format as
704 the BDW. Following the RDW, the remainder of each record is the
707 The maximum length of a record in VARIABLE mode is 65,527 bytes:
708 65,535 bytes (the maximum value of a 16-bit unsigned integer), minus 4
709 bytes for the BDW, minus 4 bytes for the RDW.
711 In mode VARIABLE, LRECL specifies a maximum, not a fixed, record
712 length, in bytes. The default is 8,192.
714 IBM documentation calls this @code{*VB} (variable-length, blocked,
719 The file format is like that of VARIABLE mode, except that logical
720 records may be split among multiple physical records (called
721 @dfn{segments}) or blocks. In SPANNED mode, the third byte of each
722 RDW is called the segment control character (SCC). Odd SCC values
723 cause the segment to be appended to a record buffer maintained in
724 memory; even values also append the segment and then flush its
725 contents to the input procedure. Canonically, SCC value 0 designates
726 a record not spanned among multiple segments, and values 1 through 3
727 designate the first segment, the last segment, or an intermediate
728 segment, respectively, within a multi-segment record. The record
729 buffer is also flushed at end of file regardless of the final record's
732 The maximum length of a logical record in VARIABLE mode is limited
733 only by memory available to @pspp{}. Segments are limited to 65,527
734 bytes, as in VARIABLE mode.
736 This format is similar to what IBM documentation call @code{*VS}
737 (variable-length, deblocked, spanned) format.
740 In mode 360, fields of type A that extend beyond the end of a record
741 read from disk are padded with spaces in the host's native character
742 set, which are then translated from EBCDIC to the native character
743 set. Thus, when the host's native character set is based on ASCII,
744 these fields are effectively padded with character @code{X'80'}. This
745 wart is implemented for compatibility.
748 The @subcmd{NAME} subcommand specifies the name of the file associated with the
749 handle. It is required in all modes but SCRATCH mode, in which its
752 The ENCODING subcommand specifies the encoding of text in the file.
753 For reading text files in CHARACTER mode, all of the forms described
754 for ENCODING on the INSERT command are supported (@pxref{INSERT}).
755 For reading in other file-based modes, encoding autodetection is not
756 supported; if the specified encoding requests autodetection then the
757 default encoding is used. This is also true when a file handle
758 is used for writing a file in any mode.
761 @section INPUT PROGRAM
762 @vindex INPUT PROGRAM
766 @dots{} input commands @dots{}
770 @cmd{INPUT PROGRAM}@dots{}@cmd{END INPUT PROGRAM} specifies a
771 complex input program. By placing data input commands within @cmd{INPUT
772 PROGRAM}, @pspp{} programs can take advantage of more complex file
773 structures than available with only @cmd{DATA LIST}.
775 The first sort of extended input program is to simply put multiple @cmd{DATA
776 LIST} commands within the @cmd{INPUT PROGRAM}. This will cause all of
778 files to be read in parallel. Input will stop when end of file is
779 reached on any of the data files.
781 Transformations, such as conditional and looping constructs, can also be
782 included within @cmd{INPUT PROGRAM}. These can be used to combine input
783 from several data files in more complex ways. However, input will still
784 stop when end of file is reached on any of the data files.
786 To prevent @cmd{INPUT PROGRAM} from terminating at the first end of
788 the @subcmd{END} subcommand on @cmd{DATA LIST}. This subcommand takes a
790 which should be a numeric scratch variable (@pxref{Scratch Variables}).
791 (It need not be a scratch variable but otherwise the results can be
792 surprising.) The value of this variable is set to 0 when reading the
793 data file, or 1 when end of file is encountered.
795 Two additional commands are useful in conjunction with @cmd{INPUT PROGRAM}.
796 @cmd{END CASE} is the first. Normally each loop through the
798 structure produces one case. @cmd{END CASE} controls exactly
799 when cases are output. When @cmd{END CASE} is used, looping from the end of
800 @cmd{INPUT PROGRAM} to the beginning does not cause a case to be output.
802 @cmd{END FILE} is the second. When the @subcmd{END} subcommand is used on @cmd{DATA
803 LIST}, there is no way for the @cmd{INPUT PROGRAM} construct to stop
805 so an infinite loop results. @cmd{END FILE}, when executed,
806 stops the flow of input data and passes out of the @cmd{INPUT PROGRAM}
809 @cmd{INPUT PROGRAM} must contain at least one @cmd{DATA LIST} or
810 @cmd{END FILE} command.
812 @subheading Example 1: Read two files in parallel to the end of the shorter
814 The following example reads variable X from file @file{a.txt} and
815 variable Y from file @file{b.txt}. If one file is shorter than the
816 other then the extra data in the longer file is ignored.
820 DATA LIST NOTABLE FILE='a.txt'/X 1-10.
821 DATA LIST NOTABLE FILE='b.txt'/Y 1-10.
826 @subheading Example 2: Read two files in parallel, supplementing the shorter
828 The following example also reads variable X from @file{a.txt} and
829 variable Y from @file{b.txt}. If one file is shorter than the other
830 then it continues reading the longer to its end, setting the other
831 variable to system-missing.
838 DATA LIST NOTABLE END=#A FILE='a.txt'/X 1-10.
841 DATA LIST NOTABLE END=#B FILE='b.txt'/Y 1-10.
851 @subheading Example 3: Concatenate two files (version 1)
853 The following example reads data from file @file{a.txt}, then from
854 @file{b.txt}, and concatenates them into a single active dataset.
861 DATA LIST NOTABLE END=#B FILE='b.txt'/X 1-10.
868 DATA LIST NOTABLE END=#A FILE='a.txt'/X 1-10.
877 @subheading Example 4: Concatenate two files (version 2)
879 This is another way to do the same thing as Example 3.
886 DATA LIST NOTABLE END=#EOF FILE='a.txt'/X 1-10.
894 DATA LIST NOTABLE END=#EOF FILE='b.txt'/X 1-10.
905 @subheading Example 5: Generate random variates
907 The follows example creates a dataset that consists of 50 random
908 variates between 0 and 10.
913 COMPUTE X=UNIFORM(10).
918 LIST /FORMAT=NUMBERED.
927 /VARIABLES=@var{var_list}
928 /CASES=FROM @var{start_index} TO @var{end_index} BY @var{incr_index}
929 /FORMAT=@{UNNUMBERED,NUMBERED@} @{WRAP,SINGLE@}
932 The @cmd{LIST} procedure prints the values of specified variables to the
935 The @subcmd{VARIABLES} subcommand specifies the variables whose values are to be
936 printed. Keyword VARIABLES is optional. If @subcmd{VARIABLES} subcommand is not
937 specified then all variables in the active dataset are printed.
939 The @subcmd{CASES} subcommand can be used to specify a subset of cases to be
940 printed. Specify @subcmd{FROM} and the case number of the first case to print,
941 @subcmd{TO} and the case number of the last case to print, and @subcmd{BY} and the number
942 of cases to advance between printing cases, or any subset of those
943 settings. If @subcmd{CASES} is not specified then all cases are printed.
945 The @subcmd{FORMAT} subcommand can be used to change the output format. @subcmd{NUMBERED}
946 will print case numbers along with each case; @subcmd{UNNUMBERED}, the default,
947 causes the case numbers to be omitted. The @subcmd{WRAP} and @subcmd{SINGLE} settings are
950 Case numbers start from 1. They are counted after all transformations
951 have been considered.
953 @cmd{LIST} is a procedure. It causes the data to be read.
963 @cmd{NEW FILE} command clears the dictionary and data from the current
972 [OUTFILE='@var{file_name}']
973 [RECORDS=@var{n_lines}]
975 [ENCODING='@var{encoding}']
976 [/[@var{line_no}] @var{arg}@dots{}]
978 @var{arg} takes one of the following forms:
979 '@var{string}' [@var{start}]
980 @var{var_list} @var{start}-@var{end} [@var{type_spec}]
981 @var{var_list} (@var{fortran_spec})
985 The @cmd{PRINT} transformation writes variable data to the listing
986 file or an output file. @cmd{PRINT} is executed when a procedure
987 causes the data to be read. Follow @cmd{PRINT} by @cmd{EXECUTE} to
988 print variable data without invoking a procedure (@pxref{EXECUTE}).
990 All @cmd{PRINT} subcommands are optional. If no strings or variables
991 are specified, @cmd{PRINT} outputs a single blank line.
993 The @subcmd{OUTFILE} subcommand specifies the file to receive the output. The
994 file may be a file name as a string or a file handle (@pxref{File
995 Handles}). If @subcmd{OUTFILE} is not present then output is sent to
996 @pspp{}'s output listing file. When @subcmd{OUTFILE} is present, the
997 output is written to @var{file_name} in a plain text format, with a
998 space inserted at beginning of each output line, even lines that
999 otherwise would be blank.
1001 The @subcmd{ENCODING} subcommand may only be used if the
1002 @subcmd{OUTFILE} subcommand is also used. It specifies the character
1003 encoding of the file. @xref{INSERT}, for information on supported
1006 The @subcmd{RECORDS} subcommand specifies the number of lines to be output. The
1007 number of lines may optionally be surrounded by parentheses.
1009 @subcmd{TABLE} will cause the @cmd{PRINT} command to output a table to the listing file
1010 that describes what it will print to the output file. @subcmd{NOTABLE}, the
1011 default, suppresses this output table.
1013 Introduce the strings and variables to be printed with a slash
1014 (@samp{/}). Optionally, the slash may be followed by a number
1015 indicating which output line is specified. In the absence of this
1016 line number, the next line number is specified. Multiple lines may
1017 be specified using multiple slashes with the intended output for a line
1018 following its respective slash.
1020 Literal strings may be printed. Specify the string itself.
1021 Optionally the string may be followed by a column number, specifying
1022 the column on the line where the string should start. Otherwise, the
1023 string is printed at the current position on the line.
1025 Variables to be printed can be specified in the same ways as available
1026 for @cmd{DATA LIST FIXED} (@pxref{DATA LIST FIXED}). In addition, a
1028 list may be followed by an asterisk (@samp{*}), which indicates that the
1029 variables should be printed in their dictionary print formats, separated
1030 by spaces. A variable list followed by a slash or the end of command
1031 is interpreted in the same way.
1033 If a FORTRAN type specification is used to move backwards on the current
1034 line, then text is written at that point on the line, the line is
1035 truncated to that length, although additional text being added will
1036 again extend the line to that length.
1039 @section PRINT EJECT
1044 OUTFILE='@var{file_name}'
1045 RECORDS=@var{n_lines}
1047 /[@var{line_no}] @var{arg}@dots{}
1049 @var{arg} takes one of the following forms:
1050 '@var{string}' [@var{start}-@var{end}]
1051 @var{var_list} @var{start}-@var{end} [@var{type_spec}]
1052 @var{var_list} (@var{fortran_spec})
1056 @cmd{PRINT EJECT} advances to the beginning of a new output page in
1057 the listing file or output file. It can also output data in the same
1060 All @cmd{PRINT EJECT} subcommands are optional.
1062 Without @subcmd{OUTFILE}, @cmd{PRINT EJECT} ejects the current page in
1063 the listing file, then it produces other output, if any is specified.
1065 With @subcmd{OUTFILE}, @cmd{PRINT EJECT} writes its output to the specified file.
1066 The first line of output is written with @samp{1} inserted in the
1067 first column. Commonly, this is the only line of output. If
1068 additional lines of output are specified, these additional lines are
1069 written with a space inserted in the first column, as with @subcmd{PRINT}.
1071 @xref{PRINT}, for more information on syntax and usage.
1074 @section PRINT SPACE
1078 PRINT SPACE [OUTFILE='file_name'] [ENCODING='@var{encoding}'] [n_lines].
1081 @cmd{PRINT SPACE} prints one or more blank lines to an output file.
1083 The @subcmd{OUTFILE} subcommand is optional. It may be used to direct output to
1084 a file specified by file name as a string or file handle (@pxref{File
1085 Handles}). If OUTFILE is not specified then output is directed to
1088 The @subcmd{ENCODING} subcommand may only be used if @subcmd{OUTFILE}
1089 is also used. It specifies the character encoding of the file.
1090 @xref{INSERT}, for information on supported encodings.
1092 n_lines is also optional. If present, it is an expression
1093 (@pxref{Expressions}) specifying the number of blank lines to be
1094 printed. The expression must evaluate to a nonnegative value.
1101 REREAD [FILE=handle] [COLUMN=column] [ENCODING='@var{encoding}'].
1104 The @cmd{REREAD} transformation allows the previous input line in a
1106 already processed by @cmd{DATA LIST} or another input command to be re-read
1107 for further processing.
1109 The @subcmd{FILE} subcommand, which is optional, is used to specify the file to
1110 have its line re-read. The file must be specified as the name of a file
1111 handle (@pxref{File Handles}). If FILE is not specified then the last
1112 file specified on @cmd{DATA LIST} is assumed (last file specified
1113 lexically, not in terms of flow-of-control).
1115 By default, the line re-read is re-read in its entirety. With the
1116 @subcmd{COLUMN} subcommand, a prefix of the line can be exempted from
1117 re-reading. Specify an expression (@pxref{Expressions}) evaluating to
1118 the first column that should be included in the re-read line. Columns
1119 are numbered from 1 at the left margin.
1121 The @subcmd{ENCODING} subcommand may only be used if the @subcmd{FILE}
1122 subcommand is also used. It specifies the character encoding of the
1123 file. @xref{INSERT}, for information on supported encodings.
1125 Issuing @code{REREAD} multiple times will not back up in the data
1126 file. Instead, it will re-read the same line multiple times.
1128 @node REPEATING DATA
1129 @section REPEATING DATA
1130 @vindex REPEATING DATA
1134 /STARTS=@var{start}-@var{end}
1135 /OCCURS=@var{n_occurs}
1136 /FILE='@var{file_name}'
1137 /LENGTH=@var{length}
1138 /CONTINUED[=@var{cont_start}-@var{cont_end}]
1139 /ID=@var{id_start}-@var{id_end}=@var{id_var}
1141 /DATA=@var{var_spec}@dots{}
1143 where each @var{var_spec} takes one of the forms
1144 @var{var_list} @var{start}-@var{end} [@var{type_spec}]
1145 @var{var_list} (@var{fortran_spec})
1148 @cmd{REPEATING DATA} parses groups of data repeating in
1149 a uniform format, possibly with several groups on a single line. Each
1150 group of data corresponds with one case. @cmd{REPEATING DATA} may only be
1151 used within an @cmd{INPUT PROGRAM} structure (@pxref{INPUT PROGRAM}).
1152 When used with @cmd{DATA LIST}, it
1153 can be used to parse groups of cases that share a subset of variables
1154 but differ in their other data.
1156 The @subcmd{STARTS} subcommand is required. Specify a range of columns, using
1157 literal numbers or numeric variable names. This range specifies the
1158 columns on the first line that are used to contain groups of data. The
1159 ending column is optional. If it is not specified, then the record
1160 width of the input file is used. For the inline file (@pxref{BEGIN
1161 DATA}) this is 80 columns; for a file with fixed record widths it is the
1162 record width; for other files it is 1024 characters by default.
1164 The @subcmd{OCCURS} subcommand is required. It must be a number or the name of a
1165 numeric variable. Its value is the number of groups present in the
1168 The @subcmd{DATA} subcommand is required. It must be the last subcommand
1169 specified. It is used to specify the data present within each repeating
1170 group. Column numbers are specified relative to the beginning of a
1171 group at column 1. Data is specified in the same way as with @cmd{DATA LIST
1172 FIXED} (@pxref{DATA LIST FIXED}).
1174 All other subcommands are optional.
1176 FILE specifies the file to read, either a file name as a string or a
1177 file handle (@pxref{File Handles}). If FILE is not present then the
1178 default is the last file handle used on @cmd{DATA LIST} (lexically, not in
1179 terms of flow of control).
1181 By default @cmd{REPEATING DATA} will output a table describing how it will
1182 parse the input data. Specifying @subcmd{NOTABLE} will disable this behavior;
1183 specifying TABLE will explicitly enable it.
1185 The @subcmd{LENGTH} subcommand specifies the length in characters of each group.
1186 If it is not present then length is inferred from the @subcmd{DATA} subcommand.
1187 LENGTH can be a number or a variable name.
1189 Normally all the data groups are expected to be present on a single
1190 line. Use the @subcmd{CONTINUED} command to indicate that data can be continued
1191 onto additional lines. If data on continuation lines starts at the left
1192 margin and continues through the entire field width, no column
1193 specifications are necessary on @subcmd{CONTINUED}. Otherwise, specify the
1194 possible range of columns in the same way as on STARTS.
1196 When data groups are continued from line to line, it is easy
1197 for cases to get out of sync through careless hand editing. The
1198 @subcmd{ID} subcommand allows a case identifier to be present on each line of
1199 repeating data groups. @cmd{REPEATING DATA} will check for the same
1200 identifier on each line and report mismatches. Specify the range of
1201 columns that the identifier will occupy, followed by an equals sign
1202 (@samp{=}) and the identifier variable name. The variable must already
1203 have been declared with @cmd{NUMERIC} or another command.
1205 @cmd{REPEATING DATA} should be the last command given within an
1206 @cmd{INPUT PROGRAM}. It should not be enclosed within a @cmd{LOOP}
1207 structure (@pxref{LOOP}). Use @cmd{DATA LIST} before, not after,
1208 @cmd{REPEATING DATA}.
1216 OUTFILE='@var{file_name}'
1217 RECORDS=@var{n_lines}
1219 /[@var{line_no}] @var{arg}@dots{}
1221 @var{arg} takes one of the following forms:
1222 '@var{string}' [@var{start}-@var{end}]
1223 @var{var_list} @var{start}-@var{end} [@var{type_spec}]
1224 @var{var_list} (@var{fortran_spec})
1228 @code{WRITE} writes text or binary data to an output file.
1230 @xref{PRINT}, for more information on syntax and usage. @cmd{PRINT}
1231 and @cmd{WRITE} differ in only a few ways:
1235 @cmd{WRITE} uses write formats by default, whereas @cmd{PRINT} uses
1239 @cmd{PRINT} inserts a space between variables unless a format is
1240 explicitly specified, but @cmd{WRITE} never inserts space between
1241 variables in output.
1244 @cmd{PRINT} inserts a space at the beginning of each line that it
1245 writes to an output file (and @cmd{PRINT EJECT} inserts @samp{1} at
1246 the beginning of each line that should begin a new page), but
1247 @cmd{WRITE} does not.
1250 @cmd{PRINT} outputs the system-missing value according to its
1251 specified output format, whereas @cmd{WRITE} outputs the
1252 system-missing value as a field filled with spaces. Binary formats