+@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
@node Language
@chapter The @pspp{} language
@cindex language, @pspp{}
@item Transformations
@cindex transformations
Perform operations on data and write data to output files. Transformations
-are not carried out until a procedure is executed.
+are not carried out until a procedure is executed.
@item Restricted transformations
@cindex restricted transformations
referenced. This section describes the details of command ordering,
but most users will have no need to refer to them.
-@pspp{} possesses five internal states, called initial, INPUT PROGRAM,
-FILE TYPE, transformation, and procedure states. (Please note the
+@pspp{} possesses five internal states, called @dfn{initial}, @dfn{input-program}
+@dfn{file-type}, @dfn{transformation}, and @dfn{procedure} states. (Please note the
distinction between the @cmd{INPUT PROGRAM} and @cmd{FILE TYPE}
-@emph{commands} and the INPUT PROGRAM and FILE TYPE @emph{states}.)
+@emph{commands} and the @dfn{input-program} and @dfn{file-type} @emph{states}.)
@pspp{} starts in the initial state. Each successful completion
of a command may cause a state transition. Each type of command has its
Valid in any state.
@item
When executed in the initial or procedure state, causes a transition to
-the transformation state.
+the transformation state.
@item
Clears the active dataset if executed in the procedure or transformation
state.
@item @cmd{INPUT PROGRAM}
@itemize @bullet
@item
-Invalid in INPUT PROGRAM and FILE TYPE states.
+Invalid in input-program and file-type states.
@item
-Causes a transition to the INPUT PROGRAM state.
+Causes a transition to the intput-program state.
@item
Clears the active dataset.
@end itemize
@item @cmd{FILE TYPE}
@itemize @bullet
@item
-Invalid in INPUT PROGRAM and FILE TYPE states.
+Invalid in intput-program and file-type states.
@item
-Causes a transition to the FILE TYPE state.
+Causes a transition to the file-type state.
@item
Clears the active dataset.
@end itemize
@item Other file definition commands
@itemize @bullet
@item
-Invalid in INPUT PROGRAM and FILE TYPE states.
+Invalid in input-program and file-type states.
@item
Cause a transition to the transformation state.
@item
@item Transformations
@itemize @bullet
@item
-Invalid in initial and FILE TYPE states.
+Invalid in initial and file-type states.
@item
Cause a transition to the transformation state.
@end itemize
@item Restricted transformations
@itemize @bullet
@item
-Invalid in initial, INPUT PROGRAM, and FILE TYPE states.
+Invalid in initial, input-program, and file-type states.
@item
Cause a transition to the transformation state.
@end itemize
@item Procedures
@itemize @bullet
@item
-Invalid in initial, INPUT PROGRAM, and FILE TYPE states.
+Invalid in initial, input-program, and file-type states.
@item
Cause a transition to the procedure state.
@end itemize
@item Custom attributes
User-defined associations between names and values. @xref{VARIABLE
ATTRIBUTE}.
+
+@cindex variable role
+@item Role
+The intended role of a variable for use in dialog boxes in graphical
+user interfaces. @xref{VARIABLE ROLE}.
@end table
@node System Variables
most of the time, the distinction between print and write formats is
unimportant.
-Input and output formats are specified to @pspp{} with a @dfn{format
-specification} of the form @code{TYPEw} or @code{TYPEw.d}, where
-@code{TYPE} is one of the format types described later, @code{w} is a
-field width measured in columns, and @code{d} is an optional number of
-decimal places. If @code{d} is omitted, a value of 0 is assumed. Some
-formats do not allow a nonzero @code{d} to be specified.
+Input and output formats are specified to @pspp{} with
+a @dfn{format specification} of the
+form @subcmd{@var{TYPE}@var{w}} or @code{TYPE@var{w}.@var{d}}, where
+@var{TYPE} is one of the format types described later, @var{w} is a
+field width measured in columns, and @var{d} is an optional number of
+decimal places. If @var{d} is omitted, a value of 0 is assumed. Some
+formats do not allow a nonzero @var{d} to be specified.
The following sections describe the input and output formats supported
by @pspp{}.
@menu
-* Basic Numeric Formats::
-* Custom Currency Formats::
-* Legacy Numeric Formats::
-* Binary and Hexadecimal Numeric Formats::
-* Time and Date Formats::
-* Date Component Formats::
-* String Formats::
+* Basic Numeric Formats::
+* Custom Currency Formats::
+* Legacy Numeric Formats::
+* Binary and Hexadecimal Numeric Formats::
+* Time and Date Formats::
+* Date Component Formats::
+* String Formats::
@end menu
@node Basic Numeric Formats
@display
SET CC@var{x}=@t{"}@var{string}@t{"}.
@end display
-@noindent
+@noindent
where @var{x} is A, B, C, D, or E, and @var{string} is no more than 16
characters long.
In @pspp{}, a @dfn{time} is an interval. The time formats translate
between human-friendly descriptions of time intervals and @pspp{}'s
internal representation of time intervals, which is simply the number of
-seconds in the interval. @pspp{} has two time formats:
+seconds in the interval. @pspp{} has three time formats:
@float
-@multitable {Time Format} {@code{dd-mmm-yyyy HH:MM:SS.ss}} {@code{01-OCT-1978 04:31:17.01}}
+@multitable {Time Format} {@code{dd-mmm-yyyy HH:MM:SS.ss}} {@code{01-OCT-1978 01:31:17.01}}
@headitem Time Format @tab Template @tab Example
-@item TIME @tab @code{hh:MM:SS.ss} @tab @code{04:31:17.01}
+@item MTIME @tab @code{MM:SS.ss} @tab @code{91:17.01}
+@item TIME @tab @code{hh:MM:SS.ss} @tab @code{01:31:17.01}
@item DTIME @tab @code{DD HH:MM:SS.ss} @tab @code{00 04:31:17.01}
@end multitable
@end float
@item MOYR @tab @code{mmm yyyy} @tab @code{OCT 1978}
@item WKYR @tab @code{ww WK yyyy} @tab @code{40 WK 1978}
@item DATETIME @tab @code{dd-mmm-yyyy HH:MM:SS.ss} @tab @code{01-OCT-1978 04:31:17.01}
+@item YMDHMS @tab @code{yyyy-mm-dd HH:MM:SS.ss} @tab @code{1978-01-OCT 04:31:17.01}
@end multitable
@end float
accepted.
@item yyyy
-Year. In output, DATETIME always produces a 4-digit year; other
-formats can produce a 2- or 4-digit year. The century assumed for
-2-digit years depends on the EPOCH setting (@pxref{SET EPOCH}). In
-output, a year outside the epoch causes the whole field to be filled
-with asterisks (@samp{*}).
+Year. In output, DATETIME and YMDHMS always produce 4-digit years;
+other formats can produce a 2- or 4-digit year. The century assumed
+for 2-digit years depends on the EPOCH setting (@pxref{SET EPOCH}).
+In output, a year outside the epoch causes the whole field to be
+filled with asterisks (@samp{*}).
@item jjj
Day of year (Julian day), from 1 to 366. This is exactly three digits
Hour of day, from 0 to 23. Output as exactly two digits.
@item MM
-Minute of hour, from 0 to 59. Output as exactly two digits.
+In MTIME, count of minutes, which may be positive or negative. Output
+as at least two digits.
+
+In other formats, minute of hour, from 0 to 59. Output as exactly two
+digits.
@item SS.ss
Seconds within minute, from 0 to 59. The integer part is output as
For output, the date and time formats use the delimiters indicated in
the table. For input, date components may be separated by spaces or by
one of the characters @samp{-}, @samp{/}, @samp{.}, or @samp{,}, and
-time components may be separated by spaces, @samp{:}, or @samp{.}. On
+time components may be separated by spaces or @samp{:}. On
input, the @samp{Q} separating quarter from year and the @samp{WK}
separating week from year may be uppercase or lowercase, and the spaces
around them are optional.
@float
@multitable {DATETIME} {Min. Input Width} {Min. Output Width} {4-digit year}
-@headitem Format @tab Min. Input Width @tab Min. Output Width @tab Option
+@headitem Format @tab Min. Input Width @tab Min. Output Width @tab Option
@item DATE @tab 8 @tab 9 @tab 4-digit year
@item ADATE @tab 8 @tab 8 @tab 4-digit year
@item EDATE @tab 8 @tab 8 @tab 4-digit year
@item MOYR @tab 6 @tab 6 @tab 4-digit year
@item WKYR @tab 6 @tab 8 @tab 4-digit year
@item DATETIME @tab 17 @tab 17 @tab seconds
+@item YMDHMS @tab 12 @tab 16 @tab seconds
+@item MTIME @tab 4 @tab 5
@item TIME @tab 5 @tab 5 @tab seconds
@item DTIME @tab 8 @tab 8 @tab seconds
@end multitable
@end float
-@noindent
+@noindent
In the table, ``Option'' describes what increased output width enables:
@table @asis
@item 4-digit year
A field 2 columns wider than minimum will include a 4-digit year.
-(DATETIME format always includes a 4-digit year.)
+(DATETIME and YMDHMS formats always include a 4-digit year.)
@item seconds
A field 3 columns wider than minimum will include seconds as well as
When a time or date exceeds the field width, characters are trimmed from
the end until it fits. This can occur in an unusual situation, e.g.@:
with a year greater than 9999 (which adds an extra digit), or for a
-negative value on TIME or DTIME (which adds a leading minus sign).
+negative value on MTIME, TIME, or DTIME (which adds a leading minus sign).
@c What about out-of-range values?
The system-missing value is output as a period at the right end of the
-field.
+field.
@node Date Component Formats
@subsubsection Date Component Formats
However, sometimes it's useful to have a variable that keeps its value
between cases. You can do this with @cmd{LEAVE} (@pxref{LEAVE}), or you can
use a @dfn{scratch variable}. Scratch variables are variables whose
-names begin with an octothorpe (@samp{#}).
+names begin with an octothorpe (@samp{#}).
Scratch variables have the same properties as variables left with
@cmd{LEAVE}: they retain their values between cases, and for the first
@section File Handles
@cindex file handles
-A @dfn{file handle} is a reference to a data file, system file, or
+A @dfn{file handle} is a reference to a data file, system file, or
portable file. Most often, a file handle is specified as the
name of a file as a string, that is, enclosed within @samp{'} or
@samp{"}.
@cindex @code{.}
@item @code{.}
The end of the command. This is not necessarily an actual dot in the
-syntax file: @xref{Commands}, for more details.
+syntax file (@pxref{Commands}).
@end table
@item
projects / pspp / blobdiff