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