DEBUG EVALUATE: Eliminate lexical corner case, rewrite tests in Autotest.
[pspp] / doc / language.texi
1 @node Language
2 @chapter The PSPP language
3 @cindex language, PSPP
4 @cindex PSPP, language
5
6 This chapter discusses elements common to many PSPP commands.
7 Later chapters will describe individual commands in detail.
8
9 @menu
10 * Tokens::                      Characters combine to form tokens.
11 * Commands::                    Tokens combine to form commands.
12 * Syntax Variants::             Batch vs. Interactive mode
13 * Types of Commands::           Commands come in several flavors.
14 * Order of Commands::           Commands combine to form syntax files.
15 * Missing Observations::        Handling missing observations.
16 * Variables::                   The unit of data storage.
17 * Files::                       Files used by PSPP.
18 * File Handles::                How files are named.
19 * BNF::                         How command syntax is described.
20 @end menu
21
22
23 @node Tokens
24 @section Tokens
25 @cindex language, lexical analysis
26 @cindex language, tokens
27 @cindex tokens
28 @cindex lexical analysis
29
30 PSPP divides most syntax file lines into series of short chunks
31 called @dfn{tokens}.
32 Tokens are then grouped to form commands, each of which tells
33 PSPP to take some action---read in data, write out data, perform
34 a statistical procedure, etc.  Each type of token is
35 described below.
36
37 @table @strong
38 @cindex identifiers
39 @item Identifiers
40 Identifiers are names that typically specify variables, commands, or
41 subcommands.  The first character in an identifier must be a letter,
42 @samp{#}, or @samp{@@}.  The remaining characters in the identifier
43 must be letters, digits, or one of the following special characters:
44
45 @example
46 @center @.  _  $  #  @@
47 @end example
48
49 @cindex case-sensitivity
50 Identifiers may be any length, but only the first 64 bytes are
51 significant.  Identifiers are not case-sensitive: @code{foobar},
52 @code{Foobar}, @code{FooBar}, @code{FOOBAR}, and @code{FoObaR} are
53 different representations of the same identifier.
54
55 @cindex identifiers, reserved
56 @cindex reserved identifiers
57 Some identifiers are reserved.  Reserved identifiers may not be used
58 in any context besides those explicitly described in this manual.  The
59 reserved identifiers are:
60
61 @example
62 @center ALL  AND  BY  EQ  GE  GT  LE  LT  NE  NOT  OR  TO  WITH
63 @end example
64
65 @item Keywords
66 Keywords are a subclass of identifiers that form a fixed part of
67 command syntax.  For example, command and subcommand names are
68 keywords.  Keywords may be abbreviated to their first 3 characters if
69 this abbreviation is unambiguous.  (Unique abbreviations of 3 or more
70 characters are also accepted: @samp{FRE}, @samp{FREQ}, and
71 @samp{FREQUENCIES} are equivalent when the last is a keyword.)
72
73 Reserved identifiers are always used as keywords.  Other identifiers
74 may be used both as keywords and as user-defined identifiers, such as
75 variable names.
76
77 @item Numbers
78 @cindex numbers
79 @cindex integers
80 @cindex reals
81 Numbers are expressed in decimal.  A decimal point is optional.
82 Numbers may be expressed in scientific notation by adding @samp{e} and
83 a base-10 exponent, so that @samp{1.234e3} has the value 1234.  Here
84 are some more examples of valid numbers:
85
86 @example
87 -5  3.14159265359  1e100  -.707  8945.
88 @end example
89
90 Negative numbers are expressed with a @samp{-} prefix.  However, in
91 situations where a literal @samp{-} token is expected, what appears to
92 be a negative number is treated as @samp{-} followed by a positive
93 number.
94
95 No white space is allowed within a number token, except for horizontal
96 white space between @samp{-} and the rest of the number.
97
98 The last example above, @samp{8945.} will be interpreted as two
99 tokens, @samp{8945} and @samp{.}, if it is the last token on a line.
100 @xref{Commands, , Forming commands of tokens}.
101
102 @item Strings
103 @cindex strings
104 @cindex @samp{'}
105 @cindex @samp{"}
106 @cindex case-sensitivity
107 Strings are literal sequences of characters enclosed in pairs of
108 single quotes (@samp{'}) or double quotes (@samp{"}).  To include the
109 character used for quoting in the string, double it, e.g.@:
110 @samp{'it''s an apostrophe'}.  White space and case of letters are
111 significant inside strings.
112
113 Strings can be concatenated using @samp{+}, so that @samp{"a" + 'b' +
114 'c'} is equivalent to @samp{'abc'}.  Concatenation is useful for
115 splitting a single string across multiple source lines.
116
117 Strings may also be expressed as hexadecimal, octal, or binary
118 character values by prefixing the initial quote character by @samp{X},
119 @samp{O}, or @samp{B} or their lowercase equivalents.  Each pair,
120 triplet, or octet of characters, according to the radix, is
121 transformed into a single character with the given value.  If there is
122 an incomplete group of characters, the missing final digits are
123 assumed to be @samp{0}.  These forms of strings are nonportable
124 because numeric values are associated with different characters by
125 different operating systems.  Therefore, their use should be confined
126 to syntax files that will not be widely distributed.
127
128 @cindex characters, reserved
129 @cindex 0
130 @cindex white space
131 The character with value 00 is reserved for
132 internal use by PSPP.  Its use in strings causes an error and
133 replacement by a space character.
134
135 @item Punctuators and Operators
136 @cindex punctuators
137 @cindex operators
138 These tokens are the punctuators and operators:
139
140 @example
141 @center ,  /  =  (  )  +  -  *  /  **  <  <=  <>  >  >=  ~=  &  |  .
142 @end example
143
144 Most of these appear within the syntax of commands, but the period
145 (@samp{.}) punctuator is used only at the end of a command.  It is a
146 punctuator only as the last character on a line (except white space).
147 When it is the last non-space character on a line, a period is not
148 treated as part of another token, even if it would otherwise be part
149 of, e.g.@:, an identifier or a floating-point number.
150
151 Actually, the character that ends a command can be changed with
152 @cmd{SET}'s ENDCMD subcommand (@pxref{SET}), but we do not recommend
153 doing so.  Throughout the remainder of this manual we will assume that
154 the default setting is in effect.
155 @end table
156
157 @node Commands
158 @section Forming commands of tokens
159
160 @cindex PSPP, command structure
161 @cindex language, command structure
162 @cindex commands, structure
163
164 Most PSPP commands share a common structure.  A command begins with a
165 command name, such as @cmd{FREQUENCIES}, @cmd{DATA LIST}, or @cmd{N OF
166 CASES}.  The command name may be abbreviated to its first word, and
167 each word in the command name may be abbreviated to its first three
168 or more characters, where these abbreviations are unambiguous.
169
170 The command name may be followed by one or more @dfn{subcommands}.
171 Each subcommand begins with a subcommand name, which may be
172 abbreviated to its first three letters.  Some subcommands accept a
173 series of one or more specifications, which follow the subcommand
174 name, optionally separated from it by an equals sign
175 (@samp{=}). Specifications may be separated from each other
176 by commas or spaces.  Each subcommand must be separated from the next (if any)
177 by a forward slash (@samp{/}).
178
179 There are multiple ways to mark the end of a command.  The most common
180 way is to end the last line of the command with a period (@samp{.}) as
181 described in the previous section (@pxref{Tokens}).  A blank line, or
182 one that consists only of white space or comments, also ends a command
183 by default, although you can use the NULLINE subcommand of @cmd{SET}
184 to disable this feature (@pxref{SET}).
185
186 @node Syntax Variants
187 @section Variants of syntax.
188
189 @cindex Batch syntax
190 @cindex Interactive syntax
191
192 There are two variants of command syntax, @i{viz}: @dfn{batch} mode and
193 @dfn{interactive} mode.
194 Batch mode is the default when reading commands from a file.
195 Interactive mode is the default when commands are typed at a prompt
196 by a user.
197 Certain commands, such as @cmd{INSERT} (@pxref{INSERT}), may explicitly
198 change the syntax mode. 
199
200 In batch mode, any line that contains a non-space character
201 in the leftmost column begins a new command. 
202 Thus, each command consists of a flush-left line followed by any
203 number of lines indented from the left margin. 
204 In this mode, a plus or minus sign (@samp{+}, @samp{@minus{}}) as the
205 first character in a line is ignored and causes that line to begin a
206 new command, which allows for visual indentation of a command without
207 that command being considered part of the previous command. 
208 The period terminating the end of a command is optional but recommended.
209
210 In interactive mode, each command must be terminated with a period
211 or by a blank line.
212 The use of @samp{+} and @samp{@minus{}} as continuation characters is not
213 permitted.
214
215 @node Types of Commands
216 @section Types of Commands
217
218 Commands in PSPP are divided roughly into six categories:
219
220 @table @strong
221 @item Utility commands
222 @cindex utility commands
223 Set or display various global options that affect PSPP operations.
224 May appear anywhere in a syntax file.  @xref{Utilities, , Utility
225 commands}.
226
227 @item File definition commands
228 @cindex file definition commands
229 Give instructions for reading data from text files or from special
230 binary ``system files''.  Most of these commands replace any previous
231 data or variables with new data or
232 variables.  At least one file definition command must appear before the first command in any of
233 the categories below.  @xref{Data Input and Output}.
234
235 @item Input program commands
236 @cindex input program commands
237 Though rarely used, these provide tools for reading data files
238 in arbitrary textual or binary formats.  @xref{INPUT PROGRAM}.
239
240 @item Transformations
241 @cindex transformations
242 Perform operations on data and write data to output files.  Transformations
243 are not carried out until a procedure is executed.  
244
245 @item Restricted transformations
246 @cindex restricted transformations
247 Transformations that cannot appear in certain contexts.  @xref{Order
248 of Commands}, for details.
249
250 @item Procedures
251 @cindex procedures
252 Analyze data, writing results of analyses to the listing file.  Cause
253 transformations specified earlier in the file to be performed.  In a
254 more general sense, a @dfn{procedure} is any command that causes the
255 active file (the data) to be read.
256 @end table
257
258 @node Order of Commands
259 @section Order of Commands
260 @cindex commands, ordering
261 @cindex order of commands
262
263 PSPP does not place many restrictions on ordering of commands.  The
264 main restriction is that variables must be defined before they are otherwise
265 referenced.  This section describes the details of command ordering,
266 but most users will have no need to refer to them.
267
268 PSPP possesses five internal states, called initial, INPUT PROGRAM,
269 FILE TYPE, transformation, and procedure states.  (Please note the
270 distinction between the @cmd{INPUT PROGRAM} and @cmd{FILE TYPE}
271 @emph{commands} and the INPUT PROGRAM and FILE TYPE @emph{states}.)
272
273 PSPP starts in the initial state.  Each successful completion
274 of a command may cause a state transition.  Each type of command has its
275 own rules for state transitions:
276
277 @table @strong
278 @item Utility commands
279 @itemize @bullet
280 @item
281 Valid in any state.
282 @item
283 Do not cause state transitions.  Exception: when @cmd{N OF CASES}
284 is executed in the procedure state, it causes a transition to the
285 transformation state.
286 @end itemize
287
288 @item @cmd{DATA LIST}
289 @itemize @bullet
290 @item
291 Valid in any state.
292 @item
293 When executed in the initial or procedure state, causes a transition to
294 the transformation state.  
295 @item
296 Clears the active file if executed in the procedure or transformation
297 state.
298 @end itemize
299
300 @item @cmd{INPUT PROGRAM}
301 @itemize @bullet
302 @item
303 Invalid in INPUT PROGRAM and FILE TYPE states.
304 @item
305 Causes a transition to the INPUT PROGRAM state.  
306 @item
307 Clears the active file.
308 @end itemize
309
310 @item @cmd{FILE TYPE}
311 @itemize @bullet
312 @item
313 Invalid in INPUT PROGRAM and FILE TYPE states.
314 @item
315 Causes a transition to the FILE TYPE state.
316 @item
317 Clears the active file.
318 @end itemize
319
320 @item Other file definition commands
321 @itemize @bullet
322 @item
323 Invalid in INPUT PROGRAM and FILE TYPE states.
324 @item
325 Cause a transition to the transformation state.
326 @item
327 Clear the active file, except for @cmd{ADD FILES}, @cmd{MATCH FILES},
328 and @cmd{UPDATE}.
329 @end itemize
330
331 @item Transformations
332 @itemize @bullet
333 @item
334 Invalid in initial and FILE TYPE states.
335 @item
336 Cause a transition to the transformation state.
337 @end itemize
338
339 @item Restricted transformations
340 @itemize @bullet
341 @item
342 Invalid in initial, INPUT PROGRAM, and FILE TYPE states.
343 @item
344 Cause a transition to the transformation state.
345 @end itemize
346
347 @item Procedures
348 @itemize @bullet
349 @item
350 Invalid in initial, INPUT PROGRAM, and FILE TYPE states.
351 @item
352 Cause a transition to the procedure state.
353 @end itemize
354 @end table
355
356 @node Missing Observations
357 @section Handling missing observations
358 @cindex missing values
359 @cindex values, missing
360
361 PSPP includes special support for unknown numeric data values.
362 Missing observations are assigned a special value, called the
363 @dfn{system-missing value}.  This ``value'' actually indicates the
364 absence of a value; it means that the actual value is unknown.  Procedures
365 automatically exclude from analyses those observations or cases that
366 have missing values.  Details of missing value exclusion depend on the
367 procedure and can often be controlled by the user; refer to
368 descriptions of individual procedures for details.
369
370 The system-missing value exists only for numeric variables.  String
371 variables always have a defined value, even if it is only a string of
372 spaces.
373
374 Variables, whether numeric or string, can have designated
375 @dfn{user-missing values}.  Every user-missing value is an actual value
376 for that variable.  However, most of the time user-missing values are
377 treated in the same way as the system-missing value.
378
379 For more information on missing values, see the following sections:
380 @ref{Variables}, @ref{MISSING VALUES}, @ref{Expressions}.  See also the
381 documentation on individual procedures for information on how they
382 handle missing values.
383
384 @node Variables
385 @section Variables
386 @cindex variables
387 @cindex dictionary
388
389 Variables are the basic unit of data storage in PSPP.  All the
390 variables in a file taken together, apart from any associated data, are
391 said to form a @dfn{dictionary}.  
392 Some details of variables are described in the sections below.
393
394 @menu
395 * Attributes::                  Attributes of variables.
396 * System Variables::            Variables automatically defined by PSPP.
397 * Sets of Variables::           Lists of variable names.
398 * Input and Output Formats::    Input and output formats.
399 * Scratch Variables::           Variables deleted by procedures.
400 @end menu
401
402 @node Attributes
403 @subsection Attributes of Variables
404 @cindex variables, attributes of
405 @cindex attributes of variables
406 Each variable has a number of attributes, including:
407
408 @table @strong
409 @item Name
410 An identifier, up to 64 bytes long.  Each variable must have a different name.
411 @xref{Tokens}.
412
413 Some system variable names begin with @samp{$}, but user-defined
414 variables' names may not begin with @samp{$}.
415
416 @cindex @samp{.}
417 @cindex period
418 @cindex variable names, ending with period
419 The final character in a variable name should not be @samp{.}, because
420 such an identifier will be misinterpreted when it is the final token
421 on a line: @code{FOO.} will be divided into two separate tokens,
422 @samp{FOO} and @samp{.}, indicating end-of-command.  @xref{Tokens}.
423
424 @cindex @samp{_}
425 The final character in a variable name should not be @samp{_}, because
426 some such identifiers are used for special purposes by PSPP
427 procedures.
428
429 As with all PSPP identifiers, variable names are not case-sensitive.
430 PSPP capitalizes variable names on output the same way they were
431 capitalized at their point of definition in the input.
432
433 @cindex variables, type
434 @cindex type of variables
435 @item Type
436 Numeric or string.
437
438 @cindex variables, width
439 @cindex width of variables
440 @item Width
441 (string variables only) String variables with a width of 8 characters or
442 fewer are called @dfn{short string variables}.  Short string variables
443 may be used in a few contexts where @dfn{long string variables} (those
444 with widths greater than 8) are not allowed.
445
446 @item Position
447 Variables in the dictionary are arranged in a specific order.
448 @cmd{DISPLAY} can be used to show this order: see @ref{DISPLAY}.
449
450 @item Initialization
451 Either reinitialized to 0 or spaces for each case, or left at its
452 existing value.  @xref{LEAVE}.
453
454 @cindex missing values
455 @cindex values, missing
456 @item Missing values
457 Optionally, up to three values, or a range of values, or a specific
458 value plus a range, can be specified as @dfn{user-missing values}.
459 There is also a @dfn{system-missing value} that is assigned to an
460 observation when there is no other obvious value for that observation.
461 Observations with missing values are automatically excluded from
462 analyses.  User-missing values are actual data values, while the
463 system-missing value is not a value at all.  @xref{Missing Observations}.
464
465 @cindex variable labels
466 @cindex labels, variable
467 @item Variable label
468 A string that describes the variable.  @xref{VARIABLE LABELS}.
469
470 @cindex value labels
471 @cindex labels, value
472 @item Value label
473 Optionally, these associate each possible value of the variable with a
474 string.  @xref{VALUE LABELS}.
475
476 @cindex print format
477 @item Print format
478 Display width, format, and (for numeric variables) number of decimal
479 places.  This attribute does not affect how data are stored, just how
480 they are displayed.  Example: a width of 8, with 2 decimal places.
481 @xref{Input and Output Formats}.
482
483 @cindex write format
484 @item Write format
485 Similar to print format, but used by the @cmd{WRITE} command
486 (@pxref{WRITE}).
487
488 @cindex custom attributes
489 @item Custom attributes
490 User-defined associations between names and values.  @xref{VARIABLE
491 ATTRIBUTE}.
492 @end table
493
494 @node System Variables
495 @subsection Variables Automatically Defined by PSPP
496 @cindex system variables
497 @cindex variables, system
498
499 There are seven system variables.  These are not like ordinary
500 variables because system variables are not always stored.  They can be used only
501 in expressions.  These system variables, whose values and output formats
502 cannot be modified, are described below.
503
504 @table @code
505 @cindex @code{$CASENUM}
506 @item $CASENUM
507 Case number of the case at the moment.  This changes as cases are
508 shuffled around.
509
510 @cindex @code{$DATE}
511 @item $DATE
512 Date the PSPP process was started, in format A9, following the
513 pattern @code{DD MMM YY}.
514
515 @cindex @code{$JDATE}
516 @item $JDATE
517 Number of days between 15 Oct 1582 and the time the PSPP process
518 was started.
519
520 @cindex @code{$LENGTH}
521 @item $LENGTH
522 Page length, in lines, in format F11.
523
524 @cindex @code{$SYSMIS}
525 @item $SYSMIS
526 System missing value, in format F1.
527
528 @cindex @code{$TIME}
529 @item $TIME
530 Number of seconds between midnight 14 Oct 1582 and the time the active file
531 was read, in format F20.
532
533 @cindex @code{$WIDTH}
534 @item $WIDTH
535 Page width, in characters, in format F3.
536 @end table
537
538 @node Sets of Variables
539 @subsection Lists of variable names
540 @cindex @code{TO} convention
541 @cindex convention, @code{TO}
542
543 To refer to a set of variables, list their names one after another.
544 Optionally, their names may be separated by commas.  To include a
545 range of variables from the dictionary in the list, write the name of
546 the first and last variable in the range, separated by @code{TO}.  For
547 instance, if the dictionary contains six variables with the names
548 @code{ID}, @code{X1}, @code{X2}, @code{GOAL}, @code{MET}, and
549 @code{NEXTGOAL}, in that order, then @code{X2 TO MET} would include
550 variables @code{X2}, @code{GOAL}, and @code{MET}.
551
552 Commands that define variables, such as @cmd{DATA LIST}, give
553 @code{TO} an alternate meaning.  With these commands, @code{TO} define
554 sequences of variables whose names end in consecutive integers.  The
555 syntax is two identifiers that begin with the same root and end with
556 numbers, separated by @code{TO}.  The syntax @code{X1 TO X5} defines 5
557 variables, named @code{X1}, @code{X2}, @code{X3}, @code{X4}, and
558 @code{X5}.  The syntax @code{ITEM0008 TO ITEM0013} defines 6
559 variables, named @code{ITEM0008}, @code{ITEM0009}, @code{ITEM0010},
560 @code{ITEM0011}, @code{ITEM0012}, and @code{ITEM00013}.  The syntaxes
561 @code{QUES001 TO QUES9} and @code{QUES6 TO QUES3} are invalid.
562
563 After a set of variables has been defined with @cmd{DATA LIST} or
564 another command with this method, the same set can be referenced on
565 later commands using the same syntax.
566
567 @node Input and Output Formats
568 @subsection Input and Output Formats
569
570 @cindex formats
571 An @dfn{input format} describes how to interpret the contents of an
572 input field as a number or a string.  It might specify that the field
573 contains an ordinary decimal number, a time or date, a number in binary
574 or hexadecimal notation, or one of several other notations.  Input
575 formats are used by commands such as @cmd{DATA LIST} that read data or
576 syntax files into the PSPP active file.
577
578 Every input format corresponds to a default @dfn{output format} that
579 specifies the formatting used when the value is output later.  It is
580 always possible to explicitly specify an output format that resembles
581 the input format.  Usually, this is the default, but in cases where the
582 input format is unfriendly to human readability, such as binary or
583 hexadecimal formats, the default output format is an easier-to-read
584 decimal format.
585
586 Every variable has two output formats, called its @dfn{print format} and
587 @dfn{write format}.  Print formats are used in most output contexts;
588 write formats are used only by @cmd{WRITE} (@pxref{WRITE}).  Newly
589 created variables have identical print and write formats, and
590 @cmd{FORMATS}, the most commonly used command for changing formats
591 (@pxref{FORMATS}), sets both of them to the same value as well.  Thus,
592 most of the time, the distinction between print and write formats is
593 unimportant.
594
595 Input and output formats are specified to PSPP with a @dfn{format
596 specification} of the form @code{TYPEw} or @code{TYPEw.d}, where
597 @code{TYPE} is one of the format types described later, @code{w} is a
598 field width measured in columns, and @code{d} is an optional number of
599 decimal places.  If @code{d} is omitted, a value of 0 is assumed.  Some
600 formats do not allow a nonzero @code{d} to be specified.
601
602 The following sections describe the input and output formats supported
603 by PSPP.
604
605 @menu
606 * Basic Numeric Formats::       
607 * Custom Currency Formats::     
608 * Legacy Numeric Formats::      
609 * Binary and Hexadecimal Numeric Formats::  
610 * Time and Date Formats::       
611 * Date Component Formats::      
612 * String Formats::              
613 @end menu
614
615 @node Basic Numeric Formats
616 @subsubsection Basic Numeric Formats
617
618 @cindex numeric formats
619 The basic numeric formats are used for input and output of real numbers
620 in standard or scientific notation.  The following table shows an
621 example of how each format displays positive and negative numbers with
622 the default decimal point setting:
623
624 @float
625 @multitable {DOLLAR10.2} {@code{@tie{}$3,141.59}} {@code{-$3,141.59}}
626 @headitem Format @tab @code{@tie{}3141.59}   @tab @code{-3141.59}
627 @item F8.2       @tab @code{@tie{}3141.59}   @tab @code{-3141.59}
628 @item COMMA9.2   @tab @code{@tie{}3,141.59}  @tab @code{-3,141.59}
629 @item DOT9.2     @tab @code{@tie{}3.141,59}  @tab @code{-3.141,59}
630 @item DOLLAR10.2 @tab @code{@tie{}$3,141.59} @tab @code{-$3,141.59}
631 @item PCT9.2     @tab @code{@tie{}3141.59%}  @tab @code{-3141.59%}
632 @item E8.1       @tab @code{@tie{}3.1E+003}  @tab @code{-3.1E+003}
633 @end multitable
634 @end float
635
636 On output, numbers in F format are expressed in standard decimal
637 notation with the requested number of decimal places.  The other formats
638 output some variation on this style:
639
640 @itemize @bullet
641 @item
642 Numbers in COMMA format are additionally grouped every three digits by
643 inserting a grouping character.  The grouping character is ordinarily a
644 comma, but it can be changed to a period (@pxref{SET DECIMAL}).
645
646 @item
647 DOT format is like COMMA format, but it interchanges the role of the
648 decimal point and grouping characters.  That is, the current grouping
649 character is used as a decimal point and vice versa.
650
651 @item
652 DOLLAR format is like COMMA format, but it prefixes the number with
653 @samp{$}.
654
655 @item
656 PCT format is like F format, but adds @samp{%} after the number.
657
658 @item
659 The E format always produces output in scientific notation.
660 @end itemize
661
662 On input, the basic numeric formats accept positive and numbers in
663 standard decimal notation or scientific notation.  Leading and trailing
664 spaces are allowed.  An empty or all-spaces field, or one that contains
665 only a single period, is treated as the system missing value.
666
667 In scientific notation, the exponent may be introduced by a sign
668 (@samp{+} or @samp{-}), or by one of the letters @samp{e} or @samp{d}
669 (in uppercase or lowercase), or by a letter followed by a sign.  A
670 single space may follow the letter or the sign or both.
671
672 On fixed-format @cmd{DATA LIST} (@pxref{DATA LIST FIXED}) and in a few
673 other contexts, decimals are implied when the field does not contain a
674 decimal point.  In F6.5 format, for example, the field @code{314159} is
675 taken as the value 3.14159 with implied decimals.  Decimals are never
676 implied if an explicit decimal point is present or if scientific
677 notation is used.
678
679 E and F formats accept the basic syntax already described.  The other
680 formats allow some additional variations:
681
682 @itemize @bullet
683 @item
684 COMMA, DOLLAR, and DOT formats ignore grouping characters within the
685 integer part of the input field.  The identity of the grouping
686 character depends on the format.
687
688 @item
689 DOLLAR format allows a dollar sign to precede the number.  In a negative
690 number, the dollar sign may precede or follow the minus sign.
691
692 @item
693 PCT format allows a percent sign to follow the number.
694 @end itemize
695
696 All of the basic number formats have a maximum field width of 40 and
697 accept no more than 16 decimal places, on both input and output.  Some
698 additional restrictions apply:
699
700 @itemize @bullet
701 @item
702 As input formats, the basic numeric formats allow no more decimal places
703 than the field width.  As output formats, the field width must be
704 greater than the number of decimal places; that is, large enough to
705 allow for a decimal point and the number of requested decimal places.
706 DOLLAR and PCT formats must allow an additional column for @samp{$} or
707 @samp{%}.
708
709 @item
710 The default output format for a given input format increases the field
711 width enough to make room for optional input characters.  If an input
712 format calls for decimal places, the width is increased by 1 to make
713 room for an implied decimal point.  COMMA, DOT, and DOLLAR formats also
714 increase the output width to make room for grouping characters.  DOLLAR
715 and PCT further increase the output field width by 1 to make room for
716 @samp{$} or @samp{%}.  The increased output width is capped at 40, the
717 maximum field width.
718
719 @item
720 The E format is exceptional.  For output, E format has a minimum width
721 of 7 plus the number of decimal places.  The default output format for
722 an E input format is an E format with at least 3 decimal places and
723 thus a minimum width of 10.
724 @end itemize
725
726 More details of basic numeric output formatting are given below:
727
728 @itemize @bullet
729 @item
730 Output rounds to nearest, with ties rounded away from zero.  Thus, 2.5
731 is output as @code{3} in F1.0 format, and -1.125 as @code{-1.13} in F5.1
732 format.
733
734 @item
735 The system-missing value is output as a period in a field of spaces,
736 placed in the decimal point's position, or in the rightmost column if no
737 decimal places are requested.  A period is used even if the decimal
738 point character is a comma.
739
740 @item
741 A number that does not fill its field is right-justified within the
742 field.
743
744 @item
745 A number is too large for its field causes decimal places to be dropped
746 to make room.  If dropping decimals does not make enough room,
747 scientific notation is used if the field is wide enough.  If a number
748 does not fit in the field, even in scientific notation, the overflow is
749 indicated by filling the field with asterisks (@samp{*}).
750
751 @item
752 COMMA, DOT, and DOLLAR formats insert grouping characters only if space
753 is available for all of them.  Grouping characters are never inserted
754 when all decimal places must be dropped.  Thus, 1234.56 in COMMA5.2
755 format is output as @samp{@tie{}1235} without a comma, even though there
756 is room for one, because all decimal places were dropped.
757
758 @item
759 DOLLAR or PCT format drop the @samp{$} or @samp{%} only if the number
760 would not fit at all without it.  Scientific notation with @samp{$} or
761 @samp{%} is preferred to ordinary decimal notation without it.
762
763 @item
764 Except in scientific notation, a decimal point is included only when
765 it is followed by a digit.  If the integer part of the number being
766 output is 0, and a decimal point is included, then the zero before the
767 decimal point is dropped.
768
769 In scientific notation, the number always includes a decimal point,
770 even if it is not followed by a digit.
771
772 @item
773 A negative number includes a minus sign only in the presence of a
774 nonzero digit: -0.01 is output as @samp{-.01} in F4.2 format but as
775 @samp{@tie{}@tie{}.0} in F4.1 format.  Thus, a ``negative zero'' never
776 includes a minus sign.
777
778 @item
779 In negative numbers output in DOLLAR format, the dollar sign follows the
780 negative sign.  Thus, -9.99 in DOLLAR6.2 format is output as
781 @code{-$9.99}.
782
783 @item
784 In scientific notation, the exponent is output as @samp{E} followed by
785 @samp{+} or @samp{-} and exactly three digits.  Numbers with magnitude
786 less than 10**-999 or larger than 10**999 are not supported by most
787 computers, but if they are supported then their output is considered
788 to overflow the field and will be output as asterisks.
789
790 @item
791 On most computers, no more than 15 decimal digits are significant in
792 output, even if more are printed.  In any case, output precision cannot
793 be any higher than input precision; few data sets are accurate to 15
794 digits of precision.  Unavoidable loss of precision in intermediate
795 calculations may also reduce precision of output.
796
797 @item
798 Special values such as infinities and ``not a number'' values are
799 usually converted to the system-missing value before printing.  In a few
800 circumstances, these values are output directly.  In fields of width 3
801 or greater, special values are output as however many characters will
802 fit from @code{+Infinity} or @code{-Infinity} for infinities, from
803 @code{NaN} for ``not a number,'' or from @code{Unknown} for other values
804 (if any are supported by the system).  In fields under 3 columns wide,
805 special values are output as asterisks.
806 @end itemize
807
808 @node Custom Currency Formats
809 @subsubsection Custom Currency Formats
810
811 @cindex currency formats
812 The custom currency formats are closely related to the basic numeric
813 formats, but they allow users to customize the output format.  The
814 SET command configures custom currency formats, using the syntax
815 @display
816 SET CC@var{x}=@t{"}@var{string}@t{"}.
817 @end display
818 @noindent 
819 where @var{x} is A, B, C, D, or E, and @var{string} is no more than 16
820 characters long.
821
822 @var{string} must contain exactly three commas or exactly three periods
823 (but not both), except that a single quote character may be used to
824 ``escape'' a following comma, period, or single quote.  If three commas
825 are used, commas will be used for grouping in output, and a period will
826 be used as the decimal point.  Uses of periods reverses these roles.
827
828 The commas or periods divide @var{string} into four fields, called the
829 @dfn{negative prefix}, @dfn{prefix}, @dfn{suffix}, and @dfn{negative
830 suffix}, respectively.  The prefix and suffix are added to output
831 whenever space is available.  The negative prefix and negative suffix
832 are always added to a negative number when the output includes a nonzero
833 digit.
834
835 The following syntax shows how custom currency formats could be used to
836 reproduce basic numeric formats:
837
838 @example
839 @group
840 SET CCA="-,,,".  /* Same as COMMA.
841 SET CCB="-...".  /* Same as DOT.
842 SET CCC="-,$,,". /* Same as DOLLAR.
843 SET CCD="-,,%,". /* Like PCT, but groups with commas.
844 @end group
845 @end example
846
847 Here are some more examples of custom currency formats.  The final
848 example shows how to use a single quote to escape a delimiter:
849
850 @example
851 @group
852 SET CCA=",EUR,,-".   /* Euro.
853 SET CCB="(,USD ,,)". /* US dollar.
854 SET CCC="-.R$..".    /* Brazilian real.
855 SET CCD="-,, NIS,".  /* Israel shekel.
856 SET CCE="-.Rp'. ..". /* Indonesia Rupiah.
857 @end group
858 @end example
859
860 @noindent These formats would yield the following output:
861
862 @float
863 @multitable {CCD13.2} {@code{@tie{}@tie{}USD 3,145.59}} {@code{(USD 3,145.59)}}
864 @headitem Format @tab @code{@tie{}3145.59}         @tab @code{-3145.59}
865 @item CCA12.2 @tab @code{@tie{}EUR3,145.59}        @tab @code{EUR3,145.59-}
866 @item CCB14.2 @tab @code{@tie{}@tie{}USD 3,145.59} @tab @code{(USD 3,145.59)}
867 @item CCC11.2 @tab @code{@tie{}R$3.145,59}         @tab @code{-R$3.145,59}
868 @item CCD13.2 @tab @code{@tie{}3,145.59 NIS}       @tab @code{-3,145.59 NIS}
869 @item CCE10.0 @tab @code{@tie{}Rp. 3.146}          @tab @code{-Rp. 3.146}
870 @end multitable
871 @end float
872
873 The default for all the custom currency formats is @samp{-,,,},
874 equivalent to COMMA format.
875
876 @node Legacy Numeric Formats
877 @subsubsection Legacy Numeric Formats
878
879 The N and Z numeric formats provide compatibility with legacy file
880 formats.  They have much in common:
881
882 @itemize @bullet
883 @item
884 Output is rounded to the nearest representable value, with ties rounded
885 away from zero.
886
887 @item
888 Numbers too large to display are output as a field filled with asterisks
889 (@samp{*}).
890
891 @item
892 The decimal point is always implicitly the specified number of digits
893 from the right edge of the field, except that Z format input allows an
894 explicit decimal point.
895
896 @item
897 Scientific notation may not be used.
898
899 @item
900 The system-missing value is output as a period in a field of spaces.
901 The period is placed just to the right of the implied decimal point in
902 Z format, or at the right end in N format or in Z format if no decimal
903 places are requested.  A period is used even if the decimal point
904 character is a comma.
905
906 @item
907 Field width may range from 1 to 40.  Decimal places may range from 0 up
908 to the field width, to a maximum of 16.
909
910 @item
911 When a legacy numeric format used for input is converted to an output
912 format, it is changed into the equivalent F format.  The field width is
913 increased by 1 if any decimal places are specified, to make room for a
914 decimal point.  For Z format, the field width is increased by 1 more
915 column, to make room for a negative sign.  The output field width is
916 capped at 40 columns.
917 @end itemize
918
919 @subsubheading N Format
920
921 The N format supports input and output of fields that contain only
922 digits.  On input, leading or trailing spaces, a decimal point, or any
923 other non-digit character causes the field to be read as the
924 system-missing value.  As a special exception, an N format used on
925 @cmd{DATA LIST FREE} or @cmd{DATA LIST LIST} is treated as the
926 equivalent F format.
927
928 On output, N pads the field on the left with zeros.  Negative numbers
929 are output like the system-missing value.
930
931 @subsubheading Z Format
932
933 The Z format is a ``zoned decimal'' format used on IBM mainframes.  Z
934 format encodes the sign as part of the final digit, which must be one of
935 the following:
936 @example
937 0123456789
938 @{ABCDEFGHI
939 @}JKLMNOPQR
940 @end example
941 @noindent
942 where the characters in each row represent digits 0 through 9 in order.
943 Characters in the first two rows indicate a positive sign; those in the
944 third indicate a negative sign.
945
946 On output, Z fields are padded on the left with spaces.  On input,
947 leading and trailing spaces are ignored.  Any character in an input
948 field other than spaces, the digit characters above, and @samp{.} causes
949 the field to be read as system-missing.
950
951 The decimal point character for input and output is always @samp{.},
952 even if the decimal point character is a comma (@pxref{SET DECIMAL}).
953
954 Nonzero, negative values output in Z format are marked as negative even
955 when no nonzero digits are output.  For example, -0.2 is output in Z1.0
956 format as @samp{J}.  The ``negative zero'' value supported by most
957 machines is output as positive.
958
959 @node Binary and Hexadecimal Numeric Formats
960 @subsubsection Binary and Hexadecimal Numeric Formats
961
962 @cindex binary formats
963 @cindex hexadecimal formats
964 The binary and hexadecimal formats are primarily designed for
965 compatibility with existing machine formats, not for human readability.
966 All of them therefore have a F format as default output format.  Some of
967 these formats are only portable between machines with compatible byte
968 ordering (endianness) or floating-point format.
969
970 Binary formats use byte values that in text files are interpreted as
971 special control functions, such as carriage return and line feed.  Thus,
972 data in binary formats should not be included in syntax files or read
973 from data files with variable-length records, such as ordinary text
974 files.  They may be read from or written to data files with fixed-length
975 records.  @xref{FILE HANDLE}, for information on working with
976 fixed-length records.
977
978 @subsubheading P and PK Formats
979
980 These are binary-coded decimal formats, in which every byte (except the
981 last, in P format) represents two decimal digits.  The most-significant
982 4 bits of the first byte is the most-significant decimal digit, the
983 least-significant 4 bits of the first byte is the next decimal digit,
984 and so on.
985
986 In P format, the most-significant 4 bits of the last byte are the
987 least-significant decimal digit.  The least-significant 4 bits represent
988 the sign: decimal 15 indicates a negative value, decimal 13 indicates a
989 positive value.
990
991 Numbers are rounded downward on output.  The system-missing value and
992 numbers outside representable range are output as zero.
993
994 The maximum field width is 16.  Decimal places may range from 0 up to
995 the number of decimal digits represented by the field.
996
997 The default output format is an F format with twice the input field
998 width, plus one column for a decimal point (if decimal places were
999 requested).
1000
1001 @subsubheading IB and PIB Formats
1002
1003 These are integer binary formats.  IB reads and writes 2's complement
1004 binary integers, and PIB reads and writes unsigned binary integers.  The
1005 byte ordering is by default the host machine's, but SET RIB may be used
1006 to select a specific byte ordering for reading (@pxref{SET RIB}) and
1007 SET WIB, similarly, for writing (@pxref{SET WIB}).
1008
1009 The maximum field width is 8.  Decimal places may range from 0 up to the
1010 number of decimal digits in the largest value representable in the field
1011 width.
1012
1013 The default output format is an F format whose width is the number of
1014 decimal digits in the largest value representable in the field width,
1015 plus 1 if the format has decimal places.
1016
1017 @subsubheading RB Format
1018
1019 This is a binary format for real numbers.  By default it reads and
1020 writes the host machine's floating-point format, but SET RRB may be
1021 used to select an alternate floating-point format for reading
1022 (@pxref{SET RRB}) and SET WRB, similarly, for writing (@pxref{SET
1023 WRB}).
1024
1025 The recommended field width depends on the floating-point format.
1026 NATIVE (the default format), IDL, IDB, VD, VG, and ZL formats should use
1027 a field width of 8.  ISL, ISB, VF, and ZS formats should use a field
1028 width of 4.  Other field widths will not produce useful results.  The
1029 maximum field width is 8.  No decimal places may be specified.
1030
1031 The default output format is F8.2.
1032
1033 @subsubheading PIBHEX and RBHEX Formats
1034
1035 These are hexadecimal formats, for reading and writing binary formats
1036 where each byte has been recoded as a pair of hexadecimal digits.
1037
1038 A hexadecimal field consists solely of hexadecimal digits
1039 @samp{0}@dots{}@samp{9} and @samp{A}@dots{}@samp{F}.  Uppercase and
1040 lowercase are accepted on input; output is in uppercase.
1041
1042 Other than the hexadecimal representation, these formats are equivalent
1043 to PIB and RB formats, respectively.  However, bytes in PIBHEX format
1044 are always ordered with the most-significant byte first (big-endian
1045 order), regardless of the host machine's native byte order or PSPP
1046 settings.
1047
1048 Field widths must be even and between 2 and 16.  RBHEX format allows no
1049 decimal places; PIBHEX allows as many decimal places as a PIB format
1050 with half the given width.
1051
1052 @node Time and Date Formats
1053 @subsubsection Time and Date Formats
1054
1055 @cindex time formats
1056 @cindex date formats
1057 In PSPP, a @dfn{time} is an interval.  The time formats translate
1058 between human-friendly descriptions of time intervals and PSPP's
1059 internal representation of time intervals, which is simply the number of
1060 seconds in the interval.  PSPP has two time formats:
1061
1062 @float
1063 @multitable {Time Format} {@code{dd-mmm-yyyy HH:MM:SS.ss}} {@code{01-OCT-1978 04:31:17.01}}
1064 @headitem Time Format @tab Template                  @tab Example
1065 @item TIME     @tab @code{hh:MM:SS.ss}          @tab @code{04:31:17.01}
1066 @item DTIME    @tab @code{DD HH:MM:SS.ss}       @tab @code{00 04:31:17.01}
1067 @end multitable
1068 @end float
1069
1070 A @dfn{date} is a moment in the past or the future.  Internally, PSPP
1071 represents a date as the number of seconds since the @dfn{epoch},
1072 midnight, Oct. 14, 1582.  The date formats translate between
1073 human-readable dates and PSPP's numeric representation of dates and
1074 times.  PSPP has several date formats:
1075
1076 @float
1077 @multitable {Date Format} {@code{dd-mmm-yyyy HH:MM:SS.ss}} {@code{01-OCT-1978 04:31:17.01}}
1078 @headitem Date Format @tab Template                  @tab Example
1079 @item DATE     @tab @code{dd-mmm-yyyy}          @tab @code{01-OCT-1978}
1080 @item ADATE    @tab @code{mm/dd/yyyy}           @tab @code{10/01/1978}
1081 @item EDATE    @tab @code{dd.mm.yyyy}           @tab @code{01.10.1978}
1082 @item JDATE    @tab @code{yyyyjjj}              @tab @code{1978274}
1083 @item SDATE    @tab @code{yyyy/mm/dd}           @tab @code{1978/10/01}
1084 @item QYR      @tab @code{q Q yyyy}             @tab @code{3 Q 1978}
1085 @item MOYR     @tab @code{mmm yyyy}             @tab @code{OCT 1978}
1086 @item WKYR     @tab @code{ww WK yyyy}           @tab @code{40 WK 1978}
1087 @item DATETIME @tab @code{dd-mmm-yyyy HH:MM:SS.ss} @tab @code{01-OCT-1978 04:31:17.01}
1088 @end multitable
1089 @end float
1090
1091 The templates in the preceding tables describe how the time and date
1092 formats are input and output:
1093
1094 @table @code
1095 @item dd
1096 Day of month, from 1 to 31.  Always output as two digits.
1097
1098 @item mm
1099 @itemx mmm
1100 Month.  In output, @code{mm} is output as two digits, @code{mmm} as the
1101 first three letters of an English month name (January, February,
1102 @dots{}).  In input, both of these formats, plus Roman numerals, are
1103 accepted.
1104
1105 @item yyyy
1106 Year.  In output, DATETIME always produces a 4-digit year; other
1107 formats can produce a 2- or 4-digit year.  The century assumed for
1108 2-digit years depends on the EPOCH setting (@pxref{SET EPOCH}).  In
1109 output, a year outside the epoch causes the whole field to be filled
1110 with asterisks (@samp{*}).
1111
1112 @item jjj
1113 Day of year (Julian day), from 1 to 366.  This is exactly three digits
1114 giving the count of days from the start of the year.  January 1 is
1115 considered day 1.
1116
1117 @item q
1118 Quarter of year, from 1 to 4.  Quarters start on January 1, April 1,
1119 July 1, and October 1.
1120
1121 @item ww
1122 Week of year, from 1 to 53.  Output as exactly two digits.  January 1 is
1123 the first day of week 1.
1124
1125 @item DD
1126 Count of days, which may be positive or negative.  Output as at least
1127 two digits.
1128
1129 @item hh
1130 Count of hours, which may be positive or negative.  Output as at least
1131 two digits.
1132
1133 @item HH
1134 Hour of day, from 0 to 23.  Output as exactly two digits.
1135
1136 @item MM
1137 Minute of hour, from 0 to 59.  Output as exactly two digits.
1138
1139 @item SS.ss
1140 Seconds within minute, from 0 to 59.  The integer part is output as
1141 exactly two digits.  On output, seconds and fractional seconds may or
1142 may not be included, depending on field width and decimal places.  On
1143 input, seconds and fractional seconds are optional.  The DECIMAL setting
1144 controls the character accepted and displayed as the decimal point
1145 (@pxref{SET DECIMAL}).
1146 @end table
1147
1148 For output, the date and time formats use the delimiters indicated in
1149 the table.  For input, date components may be separated by spaces or by
1150 one of the characters @samp{-}, @samp{/}, @samp{.}, or @samp{,}, and
1151 time components may be separated by spaces, @samp{:}, or @samp{.}.  On
1152 input, the @samp{Q} separating quarter from year and the @samp{WK}
1153 separating week from year may be uppercase or lowercase, and the spaces
1154 around them are optional.
1155
1156 On input, all time and date formats accept any amount of leading and
1157 trailing white space.
1158
1159 The maximum width for time and date formats is 40 columns.  Minimum
1160 input and output width for each of the time and date formats is shown
1161 below:
1162
1163 @float
1164 @multitable {DATETIME} {Min. Input Width} {Min. Output Width} {4-digit year}
1165 @headitem Format @tab Min. Input Width @tab Min. Output Width @tab Option 
1166 @item DATE @tab 8 @tab 9 @tab 4-digit year
1167 @item ADATE @tab 8 @tab 8 @tab 4-digit year
1168 @item EDATE @tab 8 @tab 8 @tab 4-digit year
1169 @item JDATE @tab 5 @tab 5 @tab 4-digit year
1170 @item SDATE @tab 8 @tab 8 @tab 4-digit year
1171 @item QYR @tab 4 @tab 6 @tab 4-digit year
1172 @item MOYR @tab 6 @tab 6 @tab 4-digit year
1173 @item WKYR @tab 6 @tab 8 @tab 4-digit year
1174 @item DATETIME @tab 17 @tab 17 @tab seconds
1175 @item TIME @tab 5 @tab 5 @tab seconds
1176 @item DTIME @tab 8 @tab 8 @tab seconds
1177 @end multitable
1178 @end float
1179 @noindent 
1180 In the table, ``Option'' describes what increased output width enables:
1181
1182 @table @asis
1183 @item 4-digit year
1184 A field 2 columns wider than minimum will include a 4-digit year.
1185 (DATETIME format always includes a 4-digit year.)
1186
1187 @item seconds
1188 A field 3 columns wider than minimum will include seconds as well as
1189 minutes.  A field 5 columns wider than minimum, or more, can also
1190 include a decimal point and fractional seconds (but no more than allowed
1191 by the format's decimal places).
1192 @end table
1193
1194 For the time and date formats, the default output format is the same as
1195 the input format, except that PSPP increases the field width, if
1196 necessary, to the minimum allowed for output.
1197
1198 Time or dates narrower than the field width are right-justified within
1199 the field.
1200
1201 When a time or date exceeds the field width, characters are trimmed from
1202 the end until it fits.  This can occur in an unusual situation, e.g.@:
1203 with a year greater than 9999 (which adds an extra digit), or for a
1204 negative value on TIME or DTIME (which adds a leading minus sign).
1205
1206 @c What about out-of-range values?
1207
1208 The system-missing value is output as a period at the right end of the
1209 field.  
1210
1211 @node Date Component Formats
1212 @subsubsection Date Component Formats
1213
1214 The WKDAY and MONTH formats provide input and output for the names of
1215 weekdays and months, respectively.
1216
1217 On output, these formats convert a number between 1 and 7, for WKDAY, or
1218 between 1 and 12, for MONTH, into the English name of a day or month,
1219 respectively.  If the name is longer than the field, it is trimmed to
1220 fit.  If the name is shorter than the field, it is padded on the right
1221 with spaces.  Values outside the valid range, and the system-missing
1222 value, are output as all spaces.
1223
1224 On input, English weekday or month names (in uppercase or lowercase) are
1225 converted back to their corresponding numbers.  Weekday and month names
1226 may be abbreviated to their first 2 or 3 letters, respectively.
1227
1228 The field width may range from 2 to 40, for WKDAY, or from 3 to 40, for
1229 MONTH.  No decimal places are allowed.
1230
1231 The default output format is the same as the input format.
1232
1233 @node String Formats
1234 @subsubsection String Formats
1235
1236 @cindex string formats
1237 The A and AHEX formats are the only ones that may be assigned to string
1238 variables.  Neither format allows any decimal places.
1239
1240 In A format, the entire field is treated as a string value.  The field
1241 width may range from 1 to 32,767, the maximum string width.  The default
1242 output format is the same as the input format.
1243
1244 In AHEX format, the field is composed of characters in a string encoded
1245 as hex digit pairs.  On output, hex digits are output in uppercase; on
1246 input, uppercase and lowercase are both accepted.  The default output
1247 format is A format with half the input width.
1248
1249 @node Scratch Variables
1250 @subsection Scratch Variables
1251
1252 @cindex scratch variables
1253 Most of the time, variables don't retain their values between cases.
1254 Instead, either they're being read from a data file or the active file,
1255 in which case they assume the value read, or, if created with
1256 @cmd{COMPUTE} or
1257 another transformation, they're initialized to the system-missing value
1258 or to blanks, depending on type.
1259
1260 However, sometimes it's useful to have a variable that keeps its value
1261 between cases.  You can do this with @cmd{LEAVE} (@pxref{LEAVE}), or you can
1262 use a @dfn{scratch variable}.  Scratch variables are variables whose
1263 names begin with an octothorpe (@samp{#}).  
1264
1265 Scratch variables have the same properties as variables left with
1266 @cmd{LEAVE}: they retain their values between cases, and for the first
1267 case they are initialized to 0 or blanks.  They have the additional
1268 property that they are deleted before the execution of any procedure.
1269 For this reason, scratch variables can't be used for analysis.  To use
1270 a scratch variable in an analysis, use @cmd{COMPUTE} (@pxref{COMPUTE})
1271 to copy its value into an ordinary variable, then use that ordinary
1272 variable in the analysis.
1273
1274 @node Files
1275 @section Files Used by PSPP
1276
1277 PSPP makes use of many files each time it runs.  Some of these it
1278 reads, some it writes, some it creates.  Here is a table listing the
1279 most important of these files:
1280
1281 @table @strong
1282 @cindex file, command
1283 @cindex file, syntax file
1284 @cindex command file
1285 @cindex syntax file
1286 @item command file
1287 @itemx syntax file
1288 These names (synonyms) refer to the file that contains instructions
1289 that tell PSPP what to do.  The syntax file's name is specified on
1290 the PSPP command line.  Syntax files can also be read with
1291 @cmd{INCLUDE} (@pxref{INCLUDE}).
1292
1293 @cindex file, data
1294 @cindex data file
1295 @item data file
1296 Data files contain raw data in text or binary format.  Data can also
1297 be embedded in a syntax file with @cmd{BEGIN DATA} and @cmd{END DATA}.
1298
1299 @cindex file, output
1300 @cindex output file
1301 @item listing file
1302 One or more output files are created by PSPP each time it is
1303 run.  The output files receive the tables and charts produced by
1304 statistical procedures.  The output files may be in any number of formats,
1305 depending on how PSPP is configured.
1306
1307 @cindex active file
1308 @cindex file, active
1309 @item active file
1310 The active file is the ``file'' on which all PSPP procedures are
1311 performed.  The active file consists of a dictionary and a set of cases.
1312 The active file is not necessarily a disk file: it is stored in memory
1313 if there is room.
1314
1315 @cindex system file
1316 @cindex file, system
1317 @item system file
1318 System files are binary files that store a dictionary and a set of
1319 cases.  @cmd{GET} and @cmd{SAVE} read and write system files.
1320
1321 @cindex portable file
1322 @cindex file, portable
1323 @item portable file
1324 Portable files are files in a text-based format that store a dictionary
1325 and a set of cases.  @cmd{IMPORT} and @cmd{EXPORT} read and write
1326 portable files.
1327
1328 @cindex scratch file
1329 @cindex file, scratch
1330 @item scratch file
1331 Scratch files consist of a dictionary and cases and may be stored in
1332 memory or on disk.  Most procedures that act on a system file or
1333 portable file can use a scratch file instead.  The contents of scratch
1334 files persist within a single PSPP session only.  @cmd{GET} and
1335 @cmd{SAVE} can be used to read and write scratch files.  Scratch files
1336 are a PSPP extension.
1337 @end table
1338
1339 @node File Handles
1340 @section File Handles
1341 @cindex file handles
1342
1343 A @dfn{file handle} is a reference to a data file, system file, portable
1344 file, or scratch file.  Most often, a file handle is specified as the
1345 name of a file as a string, that is, enclosed within @samp{'} or
1346 @samp{"}.
1347
1348 A file name string that begins or ends with @samp{|} is treated as the
1349 name of a command to pipe data to or from.  You can use this feature
1350 to read data over the network using a program such as @samp{curl}
1351 (e.g.@: @code{GET '|curl -s -S http://example.com/mydata.sav'}), to
1352 read compressed data from a file using a program such as @samp{zcat}
1353 (e.g.@: @code{GET '|zcat mydata.sav.gz'}), and for many other
1354 purposes.
1355
1356 PSPP also supports declaring named file handles with the @cmd{FILE
1357 HANDLE} command.  This command associates an identifier of your choice
1358 (the file handle's name) with a file.  Later, the file handle name can
1359 be substituted for the name of the file.  When PSPP syntax accesses a
1360 file multiple times, declaring a named file handle simplifies updating
1361 the syntax later to use a different file.  Use of @cmd{FILE HANDLE} is
1362 also required to read data files in binary formats.  @xref{FILE HANDLE},
1363 for more information.
1364
1365 PSPP assumes that a file handle name that begins with @samp{#} refers to
1366 a scratch file, unless the name has already been declared on @cmd{FILE
1367 HANDLE} to refer to another kind of file.  A scratch file is similar to
1368 a system file, except that it persists only for the duration of a given
1369 PSPP session.  Most commands that read or write a system or portable
1370 file, such as @cmd{GET} and @cmd{SAVE}, also accept scratch file
1371 handles.  Scratch file handles may also be declared explicitly with
1372 @cmd{FILE HANDLE}.  Scratch files are a PSPP extension.
1373
1374 In some circumstances, PSPP must distinguish whether a file handle
1375 refers to a system file or a portable file.  When this is necessary to
1376 read a file, e.g.@: as an input file for @cmd{GET} or @cmd{MATCH FILES},
1377 PSPP uses the file's contents to decide.  In the context of writing a
1378 file, e.g.@: as an output file for @cmd{SAVE} or @cmd{AGGREGATE}, PSPP
1379 decides based on the file's name: if it ends in @samp{.por} (with any
1380 capitalization), then PSPP writes a portable file; otherwise, PSPP
1381 writes a system file.
1382
1383 INLINE is reserved as a file handle name.  It refers to the ``data
1384 file'' embedded into the syntax file between @cmd{BEGIN DATA} and
1385 @cmd{END DATA}.  @xref{BEGIN DATA}, for more information.
1386
1387 The file to which a file handle refers may be reassigned on a later
1388 @cmd{FILE HANDLE} command if it is first closed using @cmd{CLOSE FILE
1389 HANDLE}.  The @cmd{CLOSE FILE HANDLE} command is also useful to free the
1390 storage associated with a scratch file.  @xref{CLOSE FILE HANDLE}, for
1391 more information.
1392
1393 @node BNF
1394 @section Backus-Naur Form
1395 @cindex BNF
1396 @cindex Backus-Naur Form
1397 @cindex command syntax, description of
1398 @cindex description of command syntax
1399
1400 The syntax of some parts of the PSPP language is presented in this
1401 manual using the formalism known as @dfn{Backus-Naur Form}, or BNF. The
1402 following table describes BNF:
1403
1404 @itemize @bullet
1405 @cindex keywords
1406 @cindex terminals
1407 @item
1408 Words in all-uppercase are PSPP keyword tokens.  In BNF, these are
1409 often called @dfn{terminals}.  There are some special terminals, which
1410 are written in lowercase for clarity:
1411
1412 @table @asis
1413 @cindex @code{number}
1414 @item @code{number}
1415 A real number.
1416
1417 @cindex @code{integer}
1418 @item @code{integer}
1419 An integer number.
1420
1421 @cindex @code{string}
1422 @item @code{string}
1423 A string.
1424
1425 @cindex @code{var-name}
1426 @item @code{var-name}
1427 A single variable name.
1428
1429 @cindex operators
1430 @cindex punctuators
1431 @item @code{=}, @code{/}, @code{+}, @code{-}, etc.
1432 Operators and punctuators.
1433
1434 @cindex @code{.}
1435 @item @code{.}
1436 The end of the command.  This is not necessarily an actual dot in the
1437 syntax file: @xref{Commands}, for more details.
1438 @end table
1439
1440 @item
1441 @cindex productions
1442 @cindex nonterminals
1443 Other words in all lowercase refer to BNF definitions, called
1444 @dfn{productions}.  These productions are also known as
1445 @dfn{nonterminals}.  Some nonterminals are very common, so they are
1446 defined here in English for clarity:
1447
1448 @table @code
1449 @cindex @code{var-list}
1450 @item var-list
1451 A list of one or more variable names or the keyword @code{ALL}.
1452
1453 @cindex @code{expression}
1454 @item expression
1455 An expression.  @xref{Expressions}, for details.
1456 @end table
1457
1458 @item
1459 @cindex ``is defined as''
1460 @cindex productions
1461 @samp{::=} means ``is defined as''.  The left side of @samp{::=} gives
1462 the name of the nonterminal being defined.  The right side of @samp{::=}
1463 gives the definition of that nonterminal.  If the right side is empty,
1464 then one possible expansion of that nonterminal is nothing.  A BNF
1465 definition is called a @dfn{production}.
1466
1467 @item
1468 @cindex terminals and nonterminals, differences
1469 So, the key difference between a terminal and a nonterminal is that a
1470 terminal cannot be broken into smaller parts---in fact, every terminal
1471 is a single token (@pxref{Tokens}).  On the other hand, nonterminals are
1472 composed of a (possibly empty) sequence of terminals and nonterminals.
1473 Thus, terminals indicate the deepest level of syntax description.  (In
1474 parsing theory, terminals are the leaves of the parse tree; nonterminals
1475 form the branches.)
1476
1477 @item
1478 @cindex start symbol
1479 @cindex symbol, start
1480 The first nonterminal defined in a set of productions is called the
1481 @dfn{start symbol}.  The start symbol defines the entire syntax for
1482 that command.
1483 @end itemize