4 Commands that don't fit any other category are placed here.
6 Most of these commands are not affected by commands like @cmd{IF} and
8 they take effect only once, unconditionally, at the time that they are
9 encountered in the input.
12 * ADD DOCUMENT:: Add documentary text to the active dataset.
13 * CACHE:: Ignored for compatibility.
14 * CD:: Change the current directory.
15 * COMMENT:: Document your syntax file.
16 * DOCUMENT:: Document the active dataset.
17 * DISPLAY DOCUMENTS:: Display active dataset documents.
18 * DISPLAY FILE LABEL:: Display the active dataset label.
19 * DROP DOCUMENTS:: Remove documents from the active dataset.
20 * ECHO:: Write a string to the output stream.
21 * ERASE:: Erase a file.
22 * EXECUTE:: Execute pending transformations.
23 * FILE LABEL:: Set the active dataset's label.
24 * FINISH:: Terminate the PSPP session.
25 * HOST:: Temporarily return to the operating system.
26 * INCLUDE:: Include a file within the current one.
27 * INSERT:: Insert a file within the current one.
28 * PERMISSIONS:: Change permissions on a file.
29 * PRESERVE and RESTORE:: Saving settings and restoring them later.
30 * SET:: Adjust PSPP runtime parameters.
31 * SHOW:: Display runtime parameters.
32 * SUBTITLE:: Provide a document subtitle.
33 * TITLE:: Provide a document title.
37 @comment node-name, next, previous, up
43 'line one' 'line two' @dots{} 'last line' .
47 @cmd{ADD DOCUMENT} adds one or more lines of descriptive commentary to
48 the active dataset. Documents added in this way are saved to system files.
49 They can be viewed using @cmd{SYSFILE INFO} or @cmd{DISPLAY
50 DOCUMENTS}. They can be removed from the active dataset with @cmd{DROP
53 Each line of documentary text must be enclosed in quotation marks, and
54 may not be more than 80 bytes long. @xref{DOCUMENT}.
64 This command is accepted, for compatibility, but it has no effect.
70 @cindex changing directory
76 @cmd{CD} changes the current directory. The new directory will become that specified by the command.
84 Two possibles syntaxes:
85 COMMENT comment text @dots{} .
86 *comment text @dots{} .
89 @cmd{COMMENT} is ignored. It is used to provide information to
90 the author and other readers of the PSPP syntax file.
92 @cmd{COMMENT} can extend over any number of lines. Don't forget to
93 terminate it with a dot or a blank line.
102 DOCUMENT @var{documentary_text}.
105 @cmd{DOCUMENT} adds one or more lines of descriptive commentary to the
106 active dataset. Documents added in this way are saved to system files.
107 They can be viewed using @cmd{SYSFILE INFO} or @cmd{DISPLAY
108 DOCUMENTS}. They can be removed from the active dataset with @cmd{DROP
111 Specify the @var{documentary text} following the DOCUMENT keyword.
112 It is interpreted literally --- any quotes or other punctuation marks
113 will be included in the file.
114 You can extend the documentary text over as many lines as necessary.
115 Lines are truncated at 80 bytes. Don't forget to terminate
116 the command with a dot or a blank line. @xref{ADD DOCUMENT}.
118 @node DISPLAY DOCUMENTS
119 @section DISPLAY DOCUMENTS
120 @vindex DISPLAY DOCUMENTS
126 @cmd{DISPLAY DOCUMENTS} displays the documents in the active dataset. Each
127 document is preceded by a line giving the time and date that it was
128 added. @xref{DOCUMENT}.
130 @node DISPLAY FILE LABEL
131 @section DISPLAY FILE LABEL
132 @vindex DISPLAY FILE LABEL
138 @cmd{DISPLAY FILE LABEL} displays the file label contained in the
140 if any. @xref{FILE LABEL}.
142 This command is a PSPP extension.
145 @section DROP DOCUMENTS
146 @vindex DROP DOCUMENTS
152 @cmd{DROP DOCUMENTS} removes all documents from the active dataset.
153 New documents can be added with @cmd{DOCUMENT} (@pxref{DOCUMENT}).
155 @cmd{DROP DOCUMENTS} changes only the active dataset. It does not modify any
156 system files stored on disk.
163 ECHO 'arbitrary text' .
166 Use @cmd{ECHO} to write arbitrary text to the output stream. The text should be enclosed in quotation marks following the normal rules for string tokens (@pxref{Tokens}).
169 @comment node-name, next, previous, up
174 ERASE FILE file_name.
177 @cmd{ERASE FILE} deletes a file from the local filesystem.
178 file_name must be quoted.
179 This command cannot be used if the SAFER setting is active.
190 @cmd{EXECUTE} causes the active dataset to be read and all pending
191 transformations to be executed.
198 FILE LABEL file_label.
201 @cmd{FILE LABEL} provides a title for the active dataset. This
202 title will be saved into system files and portable files that are
203 created during this PSPP run.
205 file_label need not be quoted. If quotes are
206 included, they become part of the file label.
216 @cmd{FINISH} terminates the current PSPP session and returns
217 control to the operating system.
220 @comment node-name, next, previous, up
226 HOST COMMAND=['command'...].
229 @cmd{HOST} suspends the current PSPP session and temporarily returns control
230 to the operating system.
231 This command cannot be used if the SAFER setting is active.
233 If the COMMAND subcommand is specified, as a sequence of shell
234 commands as quoted strings within square brackets, then PSPP executes
235 them together in a single subshell.
237 If no subcommands are specified, then PSPP invokes an interactive
245 INCLUDE [FILE=]'file-name' [ENCODING='encoding'].
248 @cmd{INCLUDE} causes the PSPP command processor to read an
249 additional command file as if it were included bodily in the current
251 If errors are encountered in the included file, then command processing will
252 stop and no more commands will be processed.
253 Include files may be nested to any depth, up to the limit of available
256 The @cmd{INSERT} command (@pxref{INSERT}) is a more flexible
257 alternative to @cmd{INCLUDE}. An INCLUDE command acts the same as
258 INSERT with ERROR=STOP CD=NO SYNTAX=BATCH specified.
260 The optional ENCODING subcommand has the same meaning as on INSERT.
267 INSERT [FILE=]'file-name'
269 [ERROR=@{CONTINUE,STOP@}]
270 [SYNTAX=@{BATCH,INTERACTIVE@}]
271 [ENCODING='encoding'].
274 @cmd{INSERT} is similar to @cmd{INCLUDE} (@pxref{INCLUDE})
275 but somewhat more flexible.
276 It causes the command processor to read a file as if it were embedded in the
277 current command file.
279 If @samp{CD=YES} is specified, then before including the file, the
280 current directory will be changed to the directory of the included
282 The default setting is @samp{CD=NO}.
283 Note that this directory will remain current until it is
284 changed explicitly (with the @cmd{CD} command, or a subsequent
285 @cmd{INSERT} command with the @samp{CD=YES} option).
286 It will not revert to its original setting even after the included
287 file is finished processing.
289 If @samp{ERROR=STOP} is specified, errors encountered in the
290 inserted file will cause processing to immediately cease.
291 Otherwise processing will continue at the next command.
292 The default setting is @samp{ERROR=CONTINUE}.
294 If @samp{SYNTAX=INTERACTIVE} is specified then the syntax contained in
295 the included file must conform to interactive syntax
296 conventions. @xref{Syntax Variants}.
297 The default setting is @samp{SYNTAX=BATCH}.
299 ENCODING optionally specifies the character set used by the included
300 file. Its argument, which is not case-sensitive, must be in one of
305 The encoding used by the system locale, or as overridden by the SET
306 LOCALE command (@pxref{SET}). On Unix systems, environment variables,
307 e.g.@: @env{LANG} or @env{LC_ALL}, determine the system locale.
309 @item IANA character set name
310 One of the character set names listed by IANA at
311 @uref{http://www.iana.org/assignments/character-sets}. Some examples
312 are @code{ASCII} (United States), @code{ISO-8859-1} (western Europe),
313 @code{EUC-JP} (Japan), and @code{windows-1252} (Windows). Not all
314 systems support all character sets.
317 @item @code{Auto,@var{encoding}}
318 Automatically detects whether a syntax file is encoded in
319 @var{encoding} or in a Unicode encoding such as UTF-8, UTF-16, or
320 UTF-32. The @var{encoding} may be an IANA character set name or
321 @code{Locale} (the default). Only ASCII compatible encodings can
322 automatically be distinguished from UTF-8 (the most common locale
323 encodings are all ASCII-compatible).
326 When ENCODING is not specified, the default is taken from the
327 @option{--syntax-encoding} command option, if it was specified, and
328 otherwise it is @code{Auto}.
335 @cindex changing file permissions
340 /PERMISSIONS = @{READONLY,WRITEABLE@}.
343 @cmd{PERMISSIONS} changes the permissions of a file.
344 There is one mandatory subcommand which specifies the permissions to
345 which the file should be changed.
346 If you set a file's permission to READONLY, then the file will become
347 unwritable either by you or anyone else on the system.
348 If you set the permission to WRITEABLE, then the file will become
349 writeable by you; the permissions afforded to others will be
351 This command cannot be used if the SAFER setting is active.
354 @node PRESERVE and RESTORE
355 @section PRESERVE and RESTORE
365 @cmd{PRESERVE} saves all of the settings that @cmd{SET} (@pxref{SET})
366 can adjust. A later @cmd{RESTORE} command restores those settings.
368 @cmd{PRESERVE} can be nested up to five levels deep.
378 /BLANKS=@{SYSMIS,'.',number@}
379 /DECIMAL=@{DOT,COMMA@}
381 /EPOCH=@{AUTOMATIC,year@}
382 /RIB=@{NATIVE,MSBFIRST,LSBFIRST,VAX@}
383 /RRB=@{NATIVE,ISL,ISB,IDL,IDB,VF,VD,VG,ZS,ZL@}
387 /MXWARNS=max_warnings
388 /WORKSPACE=workspace_size
393 /MITERATE=max_iterations
397 /SEED=@{RANDOM,seed_value@}
398 /UNDEFINED=@{WARN,NOWARN@}
401 /CC@{A,B,C,D,E@}=@{'npre,pre,suf,nsuf','npre.pre.suf.nsuf'@}
402 /DECIMAL=@{DOT,COMMA@}
404 /WIB=@{NATIVE,MSBFIRST,LSBFIRST,VAX@}
405 /WRB=@{NATIVE,ISL,ISB,IDL,IDB,VF,VD,VG,ZS,ZL@}
408 /ERRORS=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}
409 /MESSAGES=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}
410 /PRINTBACK=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}
411 /RESULTS=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}
413 (output driver options)
414 /HEADERS=@{NO,YES,BLANK@}
415 /LENGTH=@{NONE,length_in_lines@}
417 /WIDTH=@{NARROW,WIDTH,n_characters@}
420 /JOURNAL=@{ON,OFF@} ['file-name']
423 /COMPRESSION=@{ON,OFF@}
424 /SCOMPRESSION=@{ON,OFF@}
431 (obsolete settings accepted for compatibility, but ignored)
432 /BOXSTRING=@{'xxx','xxxxxxxxxxx'@}
433 /CASE=@{UPPER,UPLOW@}
437 /LOWRES=@{AUTO,ON,OFF@}
439 /MENUS=@{STANDARD,EXTENDED@}
442 /TB1=@{'xxx','xxxxxxxxxxx'@}
447 @cmd{SET} allows the user to adjust several parameters relating to
448 PSPP's execution. Since there are many subcommands to this command, its
449 subcommands will be examined in groups.
451 On subcommands that take boolean values, ON and YES are synonym, and
452 as are OFF and NO, when used as subcommand values.
454 The data input subcommands affect the way that data is read from data
455 files. The data input subcommands are
460 This is the value assigned to an item data item that is empty or
461 contains only white space. An argument of SYSMIS or '.' will cause the
462 system-missing value to be assigned to null items. This is the
463 default. Any real value may be assigned.
467 This value may be set to DOT or COMMA.
468 Setting it to DOT causes the decimal point character to be
469 @samp{.} and the grouping character to be @samp{,}.
471 causes the decimal point character to be @samp{,} and the grouping
472 character to be @samp{.}.
473 The default value is determined from the system locale.
476 Allows the default numeric input/output format to be specified. The
477 default is F8.2. @xref{Input and Output Formats}.
481 Specifies the range of years used when a 2-digit year is read from a
482 data file or used in a date construction expression (@pxref{Date
483 Construction}). If a 4-digit year is specified for the epoch, then
484 2-digit years are interpreted starting from that year, known as the
485 epoch. If AUTOMATIC (the default) is specified, then the epoch begins
486 69 years before the current date.
491 PSPP extension to set the byte ordering (endianness) used for reading
492 data in IB or PIB format (@pxref{Binary and Hexadecimal Numeric
493 Formats}). In MSBFIRST ordering, the most-significant byte appears at
494 the left end of a IB or PIB field. In LSBFIRST ordering, the
495 least-significant byte appears at the left end. VAX ordering is like
496 MSBFIRST, except that each pair of bytes is in reverse order. NATIVE,
497 the default, is equivalent to MSBFIRST or LSBFIRST depending on the
498 native format of the machine running PSPP.
503 PSPP extension to set the floating-point format used for reading data in
504 RB format (@pxref{Binary and Hexadecimal Numeric Formats}). The
509 The native format of the machine running PSPP. Equivalent to either IDL
513 32-bit IEEE 754 single-precision floating point, in little-endian byte
517 32-bit IEEE 754 single-precision floating point, in big-endian byte
521 64-bit IEEE 754 double-precision floating point, in little-endian byte
525 64-bit IEEE 754 double-precision floating point, in big-endian byte
529 32-bit VAX F format, in VAX-endian byte order.
532 64-bit VAX D format, in VAX-endian byte order.
535 64-bit VAX G format, in VAX-endian byte order.
538 32-bit IBM Z architecture short format hexadecimal floating point, in
539 big-endian byte order.
542 64-bit IBM Z architecture long format hexadecimal floating point, in
543 big-endian byte order.
545 Z architecture also supports IEEE 754 floating point. The ZS and ZL
546 formats are only for use with very old input files.
548 The default is NATIVE.
551 Interaction subcommands affect the way that PSPP interacts with an
552 online user. The interaction subcommands are
556 The maximum number of errors before PSPP halts processing of the current
557 command file. The default is 50.
560 The maximum number of warnings + errors before PSPP halts processing the
561 current command file.
562 The special value of zero means that all warning situations should be ignored.
563 No warnings will be issued, except a single initial warning advising the user
564 that warnings will not be given.
565 The default value is 100.
568 Syntax execution subcommands control the way that PSPP commands
569 execute. The syntax execution subcommands are
573 Overrides the system locale for the purpose of reading and writing
574 syntax and data files. The argument should be a locale name in the
575 general form @code{language_country.encoding}, where @code{language}
576 and @code{country} are 2-character language and country abbreviations,
577 respectively, and @code{encoding} is an IANA character set name.
578 Example locales are @code{en_US.UTF-8} (UTF-8 encoded English as
579 spoken in the United States) and @code{ja_JP.EUC-JP} (EUC-JP encoded
580 Japanese as spoken in Japan).
589 The maximum number of iterations for an uncontrolled loop (@pxref{LOOP}).
592 The initial pseudo-random number seed. Set to a real number or to
593 RANDOM, which will obtain an initial seed from the current time of day.
599 The maximum amount of memory that PSPP will use to store data being processed.
600 If memory in excess of the workspace size is required, then PSPP will start
601 to use temporary files to store the data.
602 Setting a higher value will, in general, mean procedures will run faster,
603 but may cause other applications to run slower.
604 On platforms without virtual memory management, setting a very large workspace
605 may cause PSPP to abort.
607 @cindex memory, amount used to store cases
610 Data output subcommands affect the format of output data. These
619 @anchor{CCx Settings}
621 Set up custom currency formats. @xref{Custom Currency Formats}, for
625 The default DOT setting causes the decimal point character to be
626 @samp{.}. A setting of COMMA causes the decimal point character to be
630 Allows the default numeric input/output format to be specified. The
631 default is F8.2. @xref{Input and Output Formats}.
636 PSPP extension to set the byte ordering (endianness) used for writing
637 data in IB or PIB format (@pxref{Binary and Hexadecimal Numeric
638 Formats}). In MSBFIRST ordering, the most-significant byte appears at
639 the left end of a IB or PIB field. In LSBFIRST ordering, the
640 least-significant byte appears at the left end. VAX ordering is like
641 MSBFIRST, except that each pair of bytes is in reverse order. NATIVE,
642 the default, is equivalent to MSBFIRST or LSBFIRST depending on the
643 native format of the machine running PSPP.
648 PSPP extension to set the floating-point format used for writing data in
649 RB format (@pxref{Binary and Hexadecimal Numeric Formats}). The choices
650 are the same as SET RIB. The default is NATIVE.
653 In the PSPP text-based interface, the output routing subcommands
654 affect where output is sent. The following values are allowed for
655 each of these subcommands:
660 Discard this kind of output.
663 Write this output to the terminal, but not to listing files and other
667 Write this output to listing files and other output devices, but not
672 Write this type of output to all output devices.
675 These output routing subcommands are:
679 Applies to error and warning messages. The default is BOTH.
682 Applies to notes. The default is BOTH.
685 Determines whether the syntax used for input is printed back as part
686 of the output. The default is NONE.
689 Applies to everything not in one of the above categories, such as the
690 results of statistical procedures. The default is BOTH.
693 These subcommands have no effect on output in the PSPP GUI
696 Output driver option subcommands affect output drivers' settings. These
714 Logging subcommands affect logging of commands executed to external
715 files. These subcommands are
720 These subcommands, which are synonyms, control the journal. The
721 default is ON, which causes commands entered interactively to be
722 written to the journal file. Commands included from syntax files that
723 are included interactively and error messages printed by PSPP are also
724 written to the journal file, prefixed by @samp{>}. OFF disables use
727 The journal is named @file{pspp.jnl} by default. A different name may
731 System file subcommands affect the default format of system files
732 produced by PSPP. These subcommands are
739 Whether system files created by @cmd{SAVE} or @cmd{XSAVE} are
740 compressed by default. The default is ON.
743 Security subcommands affect the operations that commands are allowed to
744 perform. The security subcommands are
748 Setting this option disables the following operations:
756 The PERMISSIONS command.
758 Pipes (file names beginning or ending with @samp{|}).
761 Be aware that this setting does not guarantee safety (commands can still
762 overwrite files, for instance) but it is an improvement.
763 When set, this setting cannot be reset during the same session, for
764 obvious security reasons.
768 @cindex encoding, characters
769 This item is used to set the default character encoding.
770 The encoding may be specified either as an encoding name or alias
771 (see @url{http://www.iana.org/assignments/character-sets}), or
773 If given as a locale name, only the character encoding of the
776 System files written by PSPP will use this encoding.
777 System files read by PSPP, for which the encoding is unknown, will be
778 interpreted using this encoding.
780 The full list of valid encodings and locale names/alias are operating system
782 The following are all examples of acceptable syntax on common GNU/Linux
786 SET LOCALE='iso-8859-1'.
788 SET LOCALE='ru_RU.cp1251'.
790 SET LOCALE='japanese'.
794 Contrary to the intuition, this command does not affect any aspect
795 of the system's locale.
799 @comment node-name, next, previous, up
827 @cmd{SHOW} can be used to display the current state of PSPP's execution
828 parameters. Parameters that can be changed using @cmd{SET}
829 (@pxref{SET}), can be examined using @cmd{SHOW} using the subcommand
830 with the same name. @code{SHOW} supports the following additional
837 Show all custom currency settings (CCA through CCE).
839 Show details of the lack of warranty for PSPP.
841 Display the terms of PSPP's copyright licence (@pxref{License}).
844 Specifying @cmd{SHOW} without any subcommands is equivalent to SHOW ALL.
851 SUBTITLE 'subtitle_string'.
853 SUBTITLE subtitle_string.
856 @cmd{SUBTITLE} provides a subtitle to a particular PSPP
857 run. This subtitle appears at the top of each output page below the
858 title, if headers are enabled on the output device.
860 Specify a subtitle as a string in quotes. The alternate syntax that did
861 not require quotes is now obsolete. If it is used then the subtitle is
862 converted to all uppercase.
869 TITLE 'title_string'.
874 @cmd{TITLE} provides a title to a particular PSPP run.
875 This title appears at the top of each output page, if headers are enabled
876 on the output device.
878 Specify a title as a string in quotes. The alternate syntax that did
879 not require quotes is now obsolete. If it is used then the title is
880 converted to all uppercase.