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