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