+@c PSPP - a program for statistical analysis.
+@c Copyright (C) 2017 Free Software Foundation, Inc.
+@c Permission is granted to copy, distribute and/or modify this document
+@c under the terms of the GNU Free Documentation License, Version 1.3
+@c or any later version published by the Free Software Foundation;
+@c with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+@c A copy of the license is included in the section entitled "GNU
+@c Free Documentation License".
+@c
+@c (modify-syntax-entry ?_ "w")
+@c (modify-syntax-entry ?' "'")
+@c (modify-syntax-entry ?@ "'")
+
+
@node Data Input and Output
@chapter Data Input and Output
@cindex input
* INPUT PROGRAM:: Support for complex input programs.
* LIST:: List cases in the active dataset.
* NEW FILE:: Clear the active dataset.
+* MATRIX DATA:: Defining matrix material for procedures.
* PRINT:: Display values in print formats.
* PRINT EJECT:: Eject the current page then print.
* PRINT SPACE:: Print blank lines.
@section CLOSE FILE HANDLE
@display
-CLOSE FILE HANDLE handle_name.
+CLOSE FILE HANDLE @var{handle_name}.
@end display
@cmd{CLOSE FILE HANDLE} disassociates the name of a file handle with a
@display
DATAFILE ATTRIBUTE
- ATTRIBUTE=name('value') [name('value')]@dots{}
- ATTRIBUTE=name@b{[}index@b{]}('value') [name@b{[}index@b{]}('value')]@dots{}
- DELETE=name [name]@dots{}
- DELETE=name@b{[}index@b{]} [name@b{[}index@b{]}]@dots{}
+ ATTRIBUTE=@var{name}('@var{value}') [@var{name}('@var{value}')]@dots{}
+ ATTRIBUTE=@var{name}@b{[}@var{index}@b{]}('@var{value}') [@var{name}@b{[}@var{index}@b{]}('@var{value}')]@dots{}
+ DELETE=@var{name} [@var{name}]@dots{}
+ DELETE=@var{name}@b{[}@var{index}@b{]} [@var{name}@b{[}@var{index}@b{]}]@dots{}
@end display
@cmd{DATAFILE ATTRIBUTE} adds, modifies, or removes user-defined
attributes are not interpreted by @pspp{}, but they are saved as part of
system files and may be used by other software that reads them.
-Use the ATTRIBUTE subcommand to add or modify a custom data file
+Use the @subcmd{ATTRIBUTE} subcommand to add or modify a custom data file
attribute. Specify the name of the attribute as an identifier
(@pxref{Tokens}), followed by the desired value, in parentheses, as a
quoted string. Attribute names that begin with @code{$} are reserved
indexes start at 1, not 0. An attribute array that has a single
element (number 1) is not distinguished from a non-array attribute.
-Use the DELETE subcommand to delete an attribute. Specify an
+Use the @subcmd{DELETE} subcommand to delete an attribute. Specify an
attribute name by itself to delete an entire attribute, including all
array elements for attribute arrays. Specify an attribute name
followed by an array index in square brackets to delete a single
@vindex DATASET
@display
-DATASET NAME name [WINDOW=@{ASIS,FRONT@}].
-DATASET ACTIVATE name [WINDOW=@{ASIS,FRONT@}].
-DATASET COPY name [WINDOW=@{MINIMIZED,HIDDEN,FRONT@}].
-DATASET DECLARE name [WINDOW=@{MINIMIZED,HIDDEN,FRONT@}].
-DATASET CLOSE @{name,*,ALL@}.
+DATASET NAME @var{name} [WINDOW=@{ASIS,FRONT@}].
+DATASET ACTIVATE @var{name} [WINDOW=@{ASIS,FRONT@}].
+DATASET COPY @var{name} [WINDOW=@{MINIMIZED,HIDDEN,FRONT@}].
+DATASET DECLARE @var{name} [WINDOW=@{MINIMIZED,HIDDEN,FRONT@}].
+DATASET CLOSE @{@var{name},*,ALL@}.
DATASET DISPLAY.
@end display
@vindex DATASET DISPLAY
The DATASET DISPLAY command lists all the currently defined datasets.
-Many DATASET commands accept an optional WINDOW subcommand. In the
+Many DATASET commands accept an optional @subcmd{WINDOW} subcommand. In the
@pspp{}IRE GUI, the value given for this subcommand influences how the
-dataset's window is displayed. Outside the GUI, the WINDOW subcommand
+dataset's window is displayed. Outside the GUI, the @subcmd{WINDOW} subcommand
has no effect. The valid values are:
@table @asis
@display
DATA LIST [FIXED]
@{TABLE,NOTABLE@}
- [FILE='file-name' [ENCODING='encoding']]
- [RECORDS=record_count]
- [END=end_var]
- [SKIP=record_count]
- /[line_no] var_spec@dots{}
-
-where each var_spec takes one of the forms
- var_list start-end [type_spec]
- var_list (fortran_spec)
+ [FILE='@var{file_name}' [ENCODING='@var{encoding}']]
+ [RECORDS=@var{record_count}]
+ [END=@var{end_var}]
+ [SKIP=@var{record_count}]
+ /[line_no] @var{var_spec}@dots{}
+
+where each @var{var_spec} takes one of the forms
+ @var{var_list} @var{start}-@var{end} [@var{type_spec}]
+ @var{var_list} (@var{fortran_spec})
@end display
@cmd{DATA LIST FIXED} is used to read data files that have values at fixed
positions on each line of single-line or multiline records. The
keyword FIXED is optional.
-The FILE subcommand must be used if input is to be taken from an
+The @subcmd{FILE} subcommand must be used if input is to be taken from an
external file. It may be used to specify a file name as a string or a
-file handle (@pxref{File Handles}). If the FILE subcommand is not used,
+file handle (@pxref{File Handles}). If the @subcmd{FILE} subcommand is not used,
then input is assumed to be specified within the command file using
@cmd{BEGIN DATA}@dots{}@cmd{END DATA} (@pxref{BEGIN DATA}).
-The ENCODING subcommand may only be used if the FILE subcommand is also used.
-It specifies the character encoding of the file.
+The @subcmd{ENCODING} subcommand may only be used if the @subcmd{FILE}
+subcommand is also used. It specifies the character encoding of the
+file. @xref{INSERT}, for information on supported encodings.
-The optional RECORDS subcommand, which takes a single integer as an
-argument, is used to specify the number of lines per record. If RECORDS
+The optional @subcmd{RECORDS} subcommand, which takes a single integer as an
+argument, is used to specify the number of lines per record.
+If @subcmd{RECORDS}
is not specified, then the number of lines per record is calculated from
the list of variable specifications later in @cmd{DATA LIST}.
-The END subcommand is only useful in conjunction with @cmd{INPUT
+The @subcmd{END} subcommand is only useful in conjunction with @cmd{INPUT
PROGRAM}. @xref{INPUT PROGRAM}, for details.
-The optional SKIP subcommand specifies a number of records to skip at
+The optional @subcmd{SKIP} subcommand specifies a number of records to skip at
the beginning of an input file. It can be used to skip over a row
that contains variable names, for example.
@cmd{DATA LIST} can optionally output a table describing how the data file
-will be read. The TABLE subcommand enables this output, and NOTABLE
-disables it. The default is to output the table.
+will be read. The @subcmd{TABLE} subcommand enables this output, and
+@subcmd{NOTABLE} disables it. The default is to output the table.
The list of variables to be read from the data list must come last.
Each line in the data record is introduced by a slash (@samp{/}).
Each variable specification consists of a list of variable names
followed by a description of their location on the input line. Sets of
-variables may be specified using the @code{DATA LIST} TO convention
+variables may be specified using the @cmd{DATA LIST} @subcmd{TO} convention
(@pxref{Sets of
Variables}). There are two ways to specify the location of the variable
on the line: columnar style and FORTRAN style.
@display
DATA LIST FREE
- [(@{TAB,'c'@}, @dots{})]
+ [(@{TAB,'@var{c}'@}, @dots{})]
[@{NOTABLE,TABLE@}]
- [FILE='file-name' [ENCODING='encoding']]
- [SKIP=record_cnt]
- /var_spec@dots{}
+ [FILE='@var{file_name}' [ENCODING='@var{encoding}']]
+ [SKIP=@var{record_cnt}]
+ /@var{var_spec}@dots{}
-where each var_spec takes one of the forms
- var_list [(type_spec)]
- var_list *
+where each @var{var_spec} takes one of the forms
+ @var{var_list} [(@var{type_spec})]
+ @var{var_list} *
@end display
In free format, the input data is, by default, structured as a series
-of fields separated by spaces, tabs, commas, or line breaks. Each
+of fields separated by spaces, tabs, or line breaks.
+If the current @subcmd{DECIMAL} separator is @subcmd{DOT} (@pxref{SET}),
+then commas are also treated as field separators.
+Each
field's content may be unquoted, or it may be quoted with a pairs of
apostrophes (@samp{'}) or double quotes (@samp{"}). Unquoted white
space separates fields but is not part of any field. Any mix of
not trimmed, consecutive delimiters define empty fields, and no form
of quoting is allowed.
-The NOTABLE and TABLE subcommands are as in @cmd{DATA LIST FIXED} above.
-NOTABLE is the default.
+The @subcmd{NOTABLE} and @subcmd{TABLE} subcommands are as in @cmd{DATA LIST FIXED} above.
+@subcmd{NOTABLE} is the default.
-The FILE and SKIP subcommands are as in @cmd{DATA LIST FIXED} above.
+The @subcmd{FILE}, @subcmd{SKIP}, and @subcmd{ENCODING} subcommands
+are as in @cmd{DATA LIST FIXED} above.
The variables to be parsed are given as a single list of variable names.
This list must be introduced by a single slash (@samp{/}). The set of
@display
DATA LIST LIST
- [(@{TAB,'c'@}, @dots{})]
+ [(@{TAB,'@var{c}'@}, @dots{})]
[@{NOTABLE,TABLE@}]
- [FILE='file-name' [ENCODING='encoding']]
- [SKIP=record_count]
- /var_spec@dots{}
+ [FILE='@var{file_name}' [ENCODING='@var{encoding}']]
+ [SKIP=@var{record_count}]
+ /@var{var_spec}@dots{}
-where each var_spec takes one of the forms
- var_list [(type_spec)]
- var_list *
+where each @var{var_spec} takes one of the forms
+ @var{var_list} [(@var{type_spec})]
+ @var{var_list} *
@end display
With one exception, @cmd{DATA LIST LIST} is syntactically and
@display
For text files:
- FILE HANDLE handle_name
- /NAME='file-name'
+ FILE HANDLE @var{handle_name}
+ /NAME='@var{file_name}
[/MODE=CHARACTER]
- /TABWIDTH=tab_width
+ [/ENDS=@{CR,CRLF@}]
+ /TABWIDTH=@var{tab_width}
+ [ENCODING='@var{encoding}']
For binary files in native encoding with fixed-length records:
- FILE HANDLE handle_name
- /NAME='file-name'
+ FILE HANDLE @var{handle_name}
+ /NAME='@var{file_name}'
/MODE=IMAGE
- [/LRECL=rec_len]
+ [/LRECL=@var{rec_len}]
+ [ENCODING='@var{encoding}']
For binary files in native encoding with variable-length records:
- FILE HANDLE handle_name
- /NAME='file-name'
+ FILE HANDLE @var{handle_name}
+ /NAME='@var{file_name}'
/MODE=BINARY
- [/LRECL=rec_len]
+ [/LRECL=@var{rec_len}]
+ [ENCODING='@var{encoding}']
For binary files encoded in EBCDIC:
- FILE HANDLE handle_name
- /NAME='file-name'
+ FILE HANDLE @var{handle_name}
+ /NAME='@var{file_name}'
/MODE=360
/RECFORM=@{FIXED,VARIABLE,SPANNED@}
- [/LRECL=rec_len]
+ [/LRECL=@var{rec_len}]
+ [ENCODING='@var{encoding}']
@end display
Use @cmd{FILE HANDLE} to associate a file handle name with a file and
invocation of @cmd{FILE HANDLE}, unless it has been closed by an
intervening command (@pxref{CLOSE FILE HANDLE}).
-The effect and syntax of FILE HANDLE depends on the selected MODE:
+The effect and syntax of @cmd{FILE HANDLE} depends on the selected MODE:
@itemize
@item
-In CHARACTER mode, the default, the data file is read as a text file,
-according to the local system's conventions, and each text line is
-read as one record.
+In CHARACTER mode, the default, the data file is read as a text file.
+Each text line is read as one record.
In CHARACTER mode only, tabs are expanded to spaces by input programs,
except by @cmd{DATA LIST FREE} with explicitly specified delimiters.
extension) may be used to specify an alternate width. Use a TABWIDTH
of 0 to suppress tab expansion.
+A file written in CHARACTER mode by default uses the line ends of the
+system on which PSPP is running, that is, on Windows, the default is
+CR LF line ends, and on other systems the default is LF only. Specify
+ENDS as CR or CRLF to override the default. PSPP reads files using
+either convention on any kind of system, regardless of ENDS.
+
@item
In IMAGE mode, the data file is treated as a series of fixed-length
binary records. LRECL should be used to specify the record length in
so that a ``round trip'' from ASCII to EBCDIC back to ASCII, or vice
versa, always yields exactly the original data.
-The RECFORM subcommand is required in mode 360. The precise file
+The @subcmd{RECFORM} subcommand is required in mode 360. The precise file
format depends on its setting:
@table @asis
wart is implemented for compatibility.
@end itemize
-The NAME subcommand specifies the name of the file associated with the
+The @subcmd{NAME} subcommand specifies the name of the file associated with the
handle. It is required in all modes but SCRATCH mode, in which its
use is forbidden.
+The ENCODING subcommand specifies the encoding of text in the file.
+For reading text files in CHARACTER mode, all of the forms described
+for ENCODING on the INSERT command are supported (@pxref{INSERT}).
+For reading in other file-based modes, encoding autodetection is not
+supported; if the specified encoding requests autodetection then the
+default encoding will be used. This is also true when a file handle
+is used for writing a file in any mode.
+
@node INPUT PROGRAM
@section INPUT PROGRAM
@vindex INPUT PROGRAM
To prevent @cmd{INPUT PROGRAM} from terminating at the first end of
file, use
-the END subcommand on @cmd{DATA LIST}. This subcommand takes a
+the @subcmd{END} subcommand on @cmd{DATA LIST}. This subcommand takes a
variable name,
which should be a numeric scratch variable (@pxref{Scratch Variables}).
(It need not be a scratch variable but otherwise the results can be
when cases are output. When @cmd{END CASE} is used, looping from the end of
@cmd{INPUT PROGRAM} to the beginning does not cause a case to be output.
-@cmd{END FILE} is the second. When the END subcommand is used on @cmd{DATA
+@cmd{END FILE} is the second. When the @subcmd{END} subcommand is used on @cmd{DATA
LIST}, there is no way for the @cmd{INPUT PROGRAM} construct to stop
looping,
so an infinite loop results. @cmd{END FILE}, when executed,
stops the flow of input data and passes out of the @cmd{INPUT PROGRAM}
structure.
+@cmd{INPUT PROGRAM} must contain at least one @cmd{DATA LIST} or
+@cmd{END FILE} command.
+
All this is very confusing. A few examples should help to clarify.
@c If you change this example, change the regression test1 in
@display
LIST
- /VARIABLES=var_list
- /CASES=FROM start_index TO end_index BY incr_index
+ /VARIABLES=@var{var_list}
+ /CASES=FROM @var{start_index} TO @var{end_index} BY @var{incr_index}
/FORMAT=@{UNNUMBERED,NUMBERED@} @{WRAP,SINGLE@}
@end display
The @cmd{LIST} procedure prints the values of specified variables to the
listing file.
-The VARIABLES subcommand specifies the variables whose values are to be
-printed. Keyword VARIABLES is optional. If VARIABLES subcommand is not
+The @subcmd{VARIABLES} subcommand specifies the variables whose values are to be
+printed. Keyword VARIABLES is optional. If @subcmd{VARIABLES} subcommand is not
specified then all variables in the active dataset are printed.
-The CASES subcommand can be used to specify a subset of cases to be
-printed. Specify FROM and the case number of the first case to print,
-TO and the case number of the last case to print, and BY and the number
+The @subcmd{CASES} subcommand can be used to specify a subset of cases to be
+printed. Specify @subcmd{FROM} and the case number of the first case to print,
+@subcmd{TO} and the case number of the last case to print, and @subcmd{BY} and the number
of cases to advance between printing cases, or any subset of those
-settings. If CASES is not specified then all cases are printed.
+settings. If @subcmd{CASES} is not specified then all cases are printed.
-The FORMAT subcommand can be used to change the output format. NUMBERED
-will print case numbers along with each case; UNNUMBERED, the default,
-causes the case numbers to be omitted. The WRAP and SINGLE settings are
+The @subcmd{FORMAT} subcommand can be used to change the output format. @subcmd{NUMBERED}
+will print case numbers along with each case; @subcmd{UNNUMBERED}, the default,
+causes the case numbers to be omitted. The @subcmd{WRAP} and @subcmd{SINGLE} settings are
currently not used.
Case numbers start from 1. They are counted after all transformations
have been considered.
-@cmd{LIST} attempts to fit all the values on a single line. If needed
-to make them fit, variable names are displayed vertically. If values
-cannot fit on a single line, then a multi-line format will be used.
-
@cmd{LIST} is a procedure. It causes the data to be read.
@node NEW FILE
@cmd{NEW FILE} command clears the dictionary and data from the current
active dataset.
+@node MATRIX DATA
+@section MATRIX DATA
+@vindex MATRIX DATA
+
+@display
+MATRIX DATA
+ VARIABLES = @var{columns}
+ [FILE='@var{file_name}'| INLINE @}
+ [/FORMAT= [@{LIST | FREE@}]
+ [@{UPPER | LOWER | FULL@}]
+ [@{DIAGONAL | NODIAGONAL@}]]
+ [/N= @var{n}]
+ [/SPLIT= @var{split_variables}].
+@end display
+
+The @cmd{MATRIX DATA} command is used to input data in the form of matrices
+which can subsequently be used by other commands. If the
+@subcmd{FILE} is omitted or takes the value @samp{INLINE} then the command
+should immediately followed by @cmd{BEGIN DATA}, @xref{BEGIN DATA}.
+
+There is one mandatory subcommand, @i{viz:} @subcmd{VARIABLES}, which defines
+the @var{columns} of the matrix.
+Normally, the @var{columns} should include an item called @samp{ROWTYPE_}.
+The @samp{ROWTYPE_} column is used to specify the purpose of a row in the
+matrix.
+
+@example
+matrix data
+ variables = rowtype_ var01 TO var08.
+
+begin data.
+mean 24.3 5.4 69.7 20.1 13.4 2.7 27.9 3.7
+sd 5.7 1.5 23.5 5.8 2.8 4.5 5.4 1.5
+n 92 92 92 92 92 92 92 92
+corr 1.00
+corr .18 1.00
+corr -.22 -.17 1.00
+corr .36 .31 -.14 1.00
+corr .27 .16 -.12 .22 1.00
+corr .33 .15 -.17 .24 .21 1.00
+corr .50 .29 -.20 .32 .12 .38 1.00
+corr .17 .29 -.05 .20 .27 .20 .04 1.00
+end data.
+@end example
+
+In the above example, the first three rows have ROWTYPE_ values of
+@samp{mean}, @samp{sd}, and @samp{n}. These indicate that the rows
+contain mean values, standard deviations and counts, respectively.
+All subsequent rows have a ROWTYPE_ of @samp{corr} which indicates
+that the values are correlation coefficients.
+
+Note that in this example, the upper right values of the @samp{corr}
+values are blank, and in each case, the rightmost value is unity.
+This is because, the
+@subcmd{FORMAT} subcommand defaults to @samp{LOWER DIAGONAL},
+which indicates that only the lower triangle is provided in the data.
+The opposite triangle is automatically inferred. One could instead
+specify the upper triangle as follows:
+
+
+@example
+matrix data
+ variables = rowtype_ var01 TO var08
+ /format = upper nodiagonal.
+
+begin data.
+mean 24.3 5.4 69.7 20.1 13.4 2.7 27.9 3.7
+sd 5.7 1.5 23.5 5.8 2.8 4.5 5.4 1.5
+n 92 92 92 92 92 92 92 92
+corr .17 .50 -.33 .27 .36 -.22 .18
+corr .29 .29 -.20 .32 .12 .38
+corr .05 .20 -.15 .16 .21
+corr .20 .32 -.17 .12
+corr .27 .12 -.24
+corr -.20 -.38
+corr .04
+end data.
+@end example
+
+In this example the @samp{NODIAGONAL} keyword is used. Accordingly
+the diagonal values of the matrix are omitted. This implies that
+there is one less @samp{corr} line than there are variables.
+If the @samp{FULL} option is passed to the @subcmd{FORMAT} subcommand,
+then all the matrix elements must be provided, including the diagonal
+elements.
+
+In the preceding examples, each matrix row has been specified on a
+single line. If you pass the keyword @var{FREE} to @subcmd{FORMAT}
+then the data may be data for several matrix rows may be specified on
+the same line, or a single row may be split across lines.
+
+The @subcmd{N} subcommand may be used to specify the number
+of valid cases for each variable. It should not be used if the
+data contains a record whose ROWTYPE_ column is @samp{N} or @samp{N_VECTOR}.
+It implies a @samp{N} record whose values are all @var{n}.
+That is to say,
+@example
+matrix data
+ variables = rowtype_ var01 TO var04
+ /format = upper nodiagonal
+ /n = 99.
+begin data
+mean 34 35 36 37
+sd 22 11 55 66
+corr 9 8 7
+corr 6 5
+corr 4
+end data.
+@end example
+produces an effect identical to
+@example
+matrix data
+ variables = rowtype_ var01 TO var04
+ /format = upper nodiagonal
+begin data
+n 99 99 99 99
+mean 34 35 36 37
+sd 22 11 55 66
+corr 9 8 7
+corr 6 5
+corr 4
+end data.
+@end example
+
+
+The @subcmd{SPLIT} is used to indicate that variables are to be
+considered as split variables. For example, the following
+defines two matrices using the variable @samp{S1} to distinguish
+between them.
+
+@example
+matrix data
+ variables = s1 rowtype_ var01 TO var04
+ /split = s1
+ /format = full diagonal.
+
+begin data
+0 mean 34 35 36 37
+0 sd 22 11 55 66
+0 n 99 98 99 92
+0 corr 1 9 8 7
+0 corr 9 1 6 5
+0 corr 8 6 1 4
+0 corr 7 5 4 1
+1 mean 44 45 34 39
+1 sd 23 15 51 46
+1 n 98 34 87 23
+1 corr 1 2 3 4
+1 corr 2 1 5 6
+1 corr 3 5 1 7
+1 corr 4 6 7 1
+end data.
+@end example
+
@node PRINT
@section PRINT
@vindex PRINT
@display
PRINT
- OUTFILE='file-name'
- RECORDS=n_lines
- @{NOTABLE,TABLE@}
- [/[line_no] arg@dots{}]
-
-arg takes one of the following forms:
- 'string' [start-end]
- var_list start-end [type_spec]
- var_list (fortran_spec)
- var_list *
+ [OUTFILE='@var{file_name}']
+ [RECORDS=@var{n_lines}]
+ [@{NOTABLE,TABLE@}]
+ [ENCODING='@var{encoding}']
+ [/[@var{line_no}] @var{arg}@dots{}]
+
+@var{arg} takes one of the following forms:
+ '@var{string}' [@var{start}]
+ @var{var_list} @var{start}-@var{end} [@var{type_spec}]
+ @var{var_list} (@var{fortran_spec})
+ @var{var_list} *
@end display
The @cmd{PRINT} transformation writes variable data to the listing
print variable data without invoking a procedure (@pxref{EXECUTE}).
All @cmd{PRINT} subcommands are optional. If no strings or variables
-are specified, PRINT outputs a single blank line.
+are specified, @cmd{PRINT} outputs a single blank line.
-The OUTFILE subcommand specifies the file to receive the output. The
+The @subcmd{OUTFILE} subcommand specifies the file to receive the output. The
file may be a file name as a string or a file handle (@pxref{File
-Handles}). If OUTFILE is not present then output will be sent to
-@pspp{}'s output listing file. When OUTFILE is present, a space is
+Handles}). If @subcmd{OUTFILE} is not present then output will be sent to
+@pspp{}'s output listing file. When @subcmd{OUTFILE} is present, a space is
inserted at beginning of each output line, even lines that otherwise
would be blank.
-The RECORDS subcommand specifies the number of lines to be output. The
+The @subcmd{ENCODING} subcommand may only be used if the
+@subcmd{OUTFILE} subcommand is also used. It specifies the character
+encoding of the file. @xref{INSERT}, for information on supported
+encodings.
+
+The @subcmd{RECORDS} subcommand specifies the number of lines to be output. The
number of lines may optionally be surrounded by parentheses.
-TABLE will cause the PRINT command to output a table to the listing file
-that describes what it will print to the output file. NOTABLE, the
+@subcmd{TABLE} will cause the @cmd{PRINT} command to output a table to the listing file
+that describes what it will print to the output file. @subcmd{NOTABLE}, the
default, suppresses this output table.
Introduce the strings and variables to be printed with a slash
be specified using multiple slashes with the intended output for a line
following its respective slash.
-Literal strings may be printed. Specify the string itself. Optionally
-the string may be followed by a column number or range of column
-numbers, specifying the location on the line for the string to be
-printed. Otherwise, the string will be printed at the current position
-on the line.
+Literal strings may be printed. Specify the string itself.
+Optionally the string may be followed by a column number, specifying
+the column on the line where the string should start. Otherwise, the
+string will be printed at the current position on the line.
Variables to be printed can be specified in the same ways as available
for @cmd{DATA LIST FIXED} (@pxref{DATA LIST FIXED}). In addition, a
@display
PRINT EJECT
- OUTFILE='file-name'
- RECORDS=n_lines
+ OUTFILE='@var{file_name}'
+ RECORDS=@var{n_lines}
@{NOTABLE,TABLE@}
- /[line_no] arg@dots{}
+ /[@var{line_no}] @var{arg}@dots{}
-arg takes one of the following forms:
- 'string' [start-end]
- var_list start-end [type_spec]
- var_list (fortran_spec)
- var_list *
+@var{arg} takes one of the following forms:
+ '@var{string}' [@var{start}-@var{end}]
+ @var{var_list} @var{start}-@var{end} [@var{type_spec}]
+ @var{var_list} (@var{fortran_spec})
+ @var{var_list} *
@end display
@cmd{PRINT EJECT} advances to the beginning of a new output page in
All @cmd{PRINT EJECT} subcommands are optional.
-Without OUTFILE, PRINT EJECT ejects the current page in
+Without @subcmd{OUTFILE}, @cmd{PRINT EJECT} ejects the current page in
the listing file, then it produces other output, if any is specified.
-With OUTFILE, PRINT EJECT writes its output to the specified file.
+With @subcmd{OUTFILE}, @cmd{PRINT EJECT} writes its output to the specified file.
The first line of output is written with @samp{1} inserted in the
first column. Commonly, this is the only line of output. If
additional lines of output are specified, these additional lines are
-written with a space inserted in the first column, as with PRINT.
+written with a space inserted in the first column, as with @subcmd{PRINT}.
@xref{PRINT}, for more information on syntax and usage.
@vindex PRINT SPACE
@display
-PRINT SPACE OUTFILE='file-name' n_lines.
+PRINT SPACE [OUTFILE='file_name'] [ENCODING='@var{encoding}'] [n_lines].
@end display
@cmd{PRINT SPACE} prints one or more blank lines to an output file.
-The OUTFILE subcommand is optional. It may be used to direct output to
+The @subcmd{OUTFILE} subcommand is optional. It may be used to direct output to
a file specified by file name as a string or file handle (@pxref{File
Handles}). If OUTFILE is not specified then output will be directed to
the listing file.
+The @subcmd{ENCODING} subcommand may only be used if @subcmd{OUTFILE}
+is also used. It specifies the character encoding of the file.
+@xref{INSERT}, for information on supported encodings.
+
n_lines is also optional. If present, it is an expression
(@pxref{Expressions}) specifying the number of blank lines to be
printed. The expression must evaluate to a nonnegative value.
@vindex REREAD
@display
-REREAD FILE=handle COLUMN=column.
+REREAD [FILE=handle] [COLUMN=column] [ENCODING='@var{encoding}'].
@end display
The @cmd{REREAD} transformation allows the previous input line in a
already processed by @cmd{DATA LIST} or another input command to be re-read
for further processing.
-The FILE subcommand, which is optional, is used to specify the file to
+The @subcmd{FILE} subcommand, which is optional, is used to specify the file to
have its line re-read. The file must be specified as the name of a file
handle (@pxref{File Handles}). If FILE is not specified then the last
file specified on @cmd{DATA LIST} will be assumed (last file specified
lexically, not in terms of flow-of-control).
By default, the line re-read is re-read in its entirety. With the
-COLUMN subcommand, a prefix of the line can be exempted from
+@subcmd{COLUMN} subcommand, a prefix of the line can be exempted from
re-reading. Specify an expression (@pxref{Expressions}) evaluating to
the first column that should be included in the re-read line. Columns
are numbered from 1 at the left margin.
+The @subcmd{ENCODING} subcommand may only be used if the @subcmd{FILE}
+subcommand is also used. It specifies the character encoding of the
+file. @xref{INSERT}, for information on supported encodings.
+
Issuing @code{REREAD} multiple times will not back up in the data
file. Instead, it will re-read the same line multiple times.
@display
REPEATING DATA
- /STARTS=start-end
- /OCCURS=n_occurs
- /FILE='file-name'
- /LENGTH=length
- /CONTINUED[=cont_start-cont_end]
- /ID=id_start-id_end=id_var
+ /STARTS=@var{start}-@var{end}
+ /OCCURS=@var{n_occurs}
+ /FILE='@var{file_name}'
+ /LENGTH=@var{length}
+ /CONTINUED[=@var{cont_start}-@var{cont_end}]
+ /ID=@var{id_start}-@var{id_end}=@var{id_var}
/@{TABLE,NOTABLE@}
- /DATA=var_spec@dots{}
+ /DATA=@var{var_spec}@dots{}
-where each var_spec takes one of the forms
- var_list start-end [type_spec]
- var_list (fortran_spec)
+where each @var{var_spec} takes one of the forms
+ @var{var_list} @var{start}-@var{end} [@var{type_spec}]
+ @var{var_list} (@var{fortran_spec})
@end display
@cmd{REPEATING DATA} parses groups of data repeating in
can be used to parse groups of cases that share a subset of variables
but differ in their other data.
-The STARTS subcommand is required. Specify a range of columns, using
+The @subcmd{STARTS} subcommand is required. Specify a range of columns, using
literal numbers or numeric variable names. This range specifies the
columns on the first line that are used to contain groups of data. The
ending column is optional. If it is not specified, then the record
DATA}) this is 80 columns; for a file with fixed record widths it is the
record width; for other files it is 1024 characters by default.
-The OCCURS subcommand is required. It must be a number or the name of a
+The @subcmd{OCCURS} subcommand is required. It must be a number or the name of a
numeric variable. Its value is the number of groups present in the
current record.
-The DATA subcommand is required. It must be the last subcommand
+The @subcmd{DATA} subcommand is required. It must be the last subcommand
specified. It is used to specify the data present within each repeating
group. Column numbers are specified relative to the beginning of a
group at column 1. Data is specified in the same way as with @cmd{DATA LIST
terms of flow of control).
By default @cmd{REPEATING DATA} will output a table describing how it will
-parse the input data. Specifying NOTABLE will disable this behavior;
+parse the input data. Specifying @subcmd{NOTABLE} will disable this behavior;
specifying TABLE will explicitly enable it.
-The LENGTH subcommand specifies the length in characters of each group.
-If it is not present then length is inferred from the DATA subcommand.
+The @subcmd{LENGTH} subcommand specifies the length in characters of each group.
+If it is not present then length is inferred from the @subcmd{DATA} subcommand.
LENGTH can be a number or a variable name.
Normally all the data groups are expected to be present on a single
-line. Use the CONTINUED command to indicate that data can be continued
+line. Use the @subcmd{CONTINUED} command to indicate that data can be continued
onto additional lines. If data on continuation lines starts at the left
margin and continues through the entire field width, no column
-specifications are necessary on CONTINUED. Otherwise, specify the
+specifications are necessary on @subcmd{CONTINUED}. Otherwise, specify the
possible range of columns in the same way as on STARTS.
When data groups are continued from line to line, it is easy
for cases to get out of sync through careless hand editing. The
-ID subcommand allows a case identifier to be present on each line of
+@subcmd{ID} subcommand allows a case identifier to be present on each line of
repeating data groups. @cmd{REPEATING DATA} will check for the same
identifier on each line and report mismatches. Specify the range of
columns that the identifier will occupy, followed by an equals sign
@display
WRITE
- OUTFILE='file-name'
- RECORDS=n_lines
+ OUTFILE='@var{file_name}'
+ RECORDS=@var{n_lines}
@{NOTABLE,TABLE@}
- /[line_no] arg@dots{}
+ /[@var{line_no}] @var{arg}@dots{}
-arg takes one of the following forms:
- 'string' [start-end]
- var_list start-end [type_spec]
- var_list (fortran_spec)
- var_list *
+@var{arg} takes one of the following forms:
+ '@var{string}' [@var{start}-@var{end}]
+ @var{var_list} @var{start}-@var{end} [@var{type_spec}]
+ @var{var_list} (@var{fortran_spec})
+ @var{var_list} *
@end display
@code{WRITE} writes text or binary data to an output file.