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.
42 'line one' 'line two' @dots{} 'last line' .
46 @cmd{ADD DOCUMENT} adds one or more lines of descriptive commentary to
47 the active dataset. Documents added in this way are saved to system files.
48 They can be viewed using @cmd{SYSFILE INFO} or @cmd{DISPLAY
49 DOCUMENTS}. They can be removed from the active dataset with @cmd{DROP
52 Each line of documentary text must be enclosed in quotation marks, and
53 may not be more than 80 bytes long. @xref{DOCUMENT}.
63 This command is accepted, for compatibility, but it has no effect.
69 @cindex changing directory
75 @cmd{CD} changes the current directory. The new directory will become that specified by the command.
83 Two possibles syntaxes:
84 COMMENT comment text @dots{} .
85 *comment text @dots{} .
88 @cmd{COMMENT} is ignored. It is used to provide information to
89 the author and other readers of the @pspp{} syntax file.
91 @cmd{COMMENT} can extend over any number of lines. Don't forget to
92 terminate it with a dot or a blank line.
101 DOCUMENT @var{documentary_text}.
104 @cmd{DOCUMENT} adds one or more lines of descriptive commentary to the
105 active dataset. Documents added in this way are saved to system files.
106 They can be viewed using @cmd{SYSFILE INFO} or @cmd{DISPLAY
107 DOCUMENTS}. They can be removed from the active dataset with @cmd{DROP
110 Specify the @var{documentary text} following the DOCUMENT keyword.
111 It is interpreted literally --- any quotes or other punctuation marks
112 will be included in the file.
113 You can extend the documentary text over as many lines as necessary.
114 Lines are truncated at 80 bytes. Don't forget to terminate
115 the command with a dot or a blank line. @xref{ADD DOCUMENT}.
117 @node DISPLAY DOCUMENTS
118 @section DISPLAY DOCUMENTS
119 @vindex DISPLAY DOCUMENTS
125 @cmd{DISPLAY DOCUMENTS} displays the documents in the active dataset. Each
126 document is preceded by a line giving the time and date that it was
127 added. @xref{DOCUMENT}.
129 @node DISPLAY FILE LABEL
130 @section DISPLAY FILE LABEL
131 @vindex DISPLAY FILE LABEL
137 @cmd{DISPLAY FILE LABEL} displays the file label contained in the
139 if any. @xref{FILE LABEL}.
141 This command is a @pspp{} extension.
144 @section DROP DOCUMENTS
145 @vindex DROP DOCUMENTS
151 @cmd{DROP DOCUMENTS} removes all documents from the active dataset.
152 New documents can be added with @cmd{DOCUMENT} (@pxref{DOCUMENT}).
154 @cmd{DROP DOCUMENTS} changes only the active dataset. It does not modify any
155 system files stored on disk.
162 ECHO 'arbitrary text' .
165 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}).
172 ERASE FILE file_name.
175 @cmd{ERASE FILE} deletes a file from the local filesystem.
176 file_name must be quoted.
177 This command cannot be used if the SAFER (@pxref{SET}) setting is active.
188 @cmd{EXECUTE} causes the active dataset to be read and all pending
189 transformations to be executed.
196 FILE LABEL @var{file_label}.
199 @cmd{FILE LABEL} provides a title for the active dataset. This
200 title will be saved into system files and portable files that are
201 created during this @pspp{} run.
203 @var{file_label} should not be quoted.
204 If quotes are included, they are literally interpreted and become part of the file label.
214 @cmd{FINISH} terminates the current @pspp{} session and returns
215 control to the operating system.
223 HOST COMMAND=['@var{command}'...].
226 @cmd{HOST} suspends the current @pspp{} session and temporarily returns control
227 to the operating system.
228 This command cannot be used if the SAFER (@pxref{SET}) setting is active.
230 If the @subcmd{COMMAND} subcommand is specified, as a sequence of shell
231 commands as quoted strings within square brackets, then @pspp{} executes
232 them together in a single subshell.
234 If no subcommands are specified, then @pspp{} invokes an interactive
242 INCLUDE [FILE=]'@var{file_name}' [ENCODING='@var{encoding}'].
245 @cmd{INCLUDE} causes the @pspp{} command processor to read an
246 additional command file as if it were included bodily in the current
248 If errors are encountered in the included file, then command processing will
249 stop and no more commands will be processed.
250 Include files may be nested to any depth, up to the limit of available
253 The @cmd{INSERT} command (@pxref{INSERT}) is a more flexible
254 alternative to @cmd{INCLUDE}. An @cmd{INCLUDE} command acts the same as
255 @cmd{INSERT} with @subcmd{ERROR=STOP CD=NO SYNTAX=BATCH} specified.
257 The optional @subcmd{ENCODING} subcommand has the same meaning as with @cmd{INSERT}.
264 INSERT [FILE=]'@var{file_name}'
266 [ERROR=@{CONTINUE,STOP@}]
267 [SYNTAX=@{BATCH,INTERACTIVE@}]
268 [ENCODING=@{LOCALE, '@var{charset_name}'@}].
271 @cmd{INSERT} is similar to @cmd{INCLUDE} (@pxref{INCLUDE})
272 but somewhat more flexible.
273 It causes the command processor to read a file as if it were embedded in the
274 current command file.
276 If @subcmd{CD=YES} is specified, then before including the file, the
277 current directory will be changed to the directory of the included
279 The default setting is @samp{CD=NO}.
280 Note that this directory will remain current until it is
281 changed explicitly (with the @cmd{CD} command, or a subsequent
282 @cmd{INSERT} command with the @samp{CD=YES} option).
283 It will not revert to its original setting even after the included
284 file is finished processing.
286 If @subcmd{ERROR=STOP} is specified, errors encountered in the
287 inserted file will cause processing to immediately cease.
288 Otherwise processing will continue at the next command.
289 The default setting is @subcmd{ERROR=CONTINUE}.
291 If @subcmd{SYNTAX=INTERACTIVE} is specified then the syntax contained in
292 the included file must conform to interactive syntax
293 conventions. @xref{Syntax Variants}.
294 The default setting is @subcmd{SYNTAX=BATCH}.
296 @subcmd{ENCODING} optionally specifies the character set used by the included
297 file. Its argument, which is not case-sensitive, must be in one of
301 @item @subcmd{LOCALE}
302 The encoding used by the system locale, or as overridden by the
303 @cmd{SET} command (@pxref{SET}). On GNU/Linux and other Unix-like systems,
304 environment variables, e.g.@: @env{LANG} or @env{LC_ALL}, determine the
307 @item @var{charset_name}
308 One of the character set names listed by IANA at
309 @uref{http://www.iana.org/assignments/character-sets}. Some examples
310 are @code{ASCII} (United States), @code{ISO-8859-1} (western Europe),
311 @code{EUC-JP} (Japan), and @code{windows-1252} (Windows). Not all
312 systems support all character sets.
314 @item @code{Auto,@var{encoding}}
315 Automatically detects whether a syntax file is encoded in an Unicode
316 encoding such as UTF-8, UTF-16, or UTF-32. If it is not, then @pspp{}
317 generally assumes that the file is encoded in @var{encoding} (an IANA
318 character set name). However, if @var{encoding} is UTF-8, and the
319 syntax file is not valid UTF-8, @pspp{} instead assumes that the file
320 is encoded in @code{windows-1252}.
322 For best results, @var{encoding} should be an ASCII-compatible
323 encoding (the most common locale encodings are all ASCII-compatible),
324 because encodings that are not ASCII compatible cannot be
325 automatically distinguished from UTF-8.
328 @item @code{Auto,Locale}
329 Automatic detection, as above, with the default encoding taken from
330 the system locale or the setting on SET LOCALE.
333 When ENCODING is not specified, the default is taken from the
334 @option{--syntax-encoding} command option, if it was specified, and
335 otherwise it is @code{Auto}.
342 @cindex changing file permissions
346 FILE='@var{file_name}'
347 /PERMISSIONS = @{READONLY,WRITEABLE@}.
350 @cmd{PERMISSIONS} changes the permissions of a file.
351 There is one mandatory subcommand which specifies the permissions to
352 which the file should be changed.
353 If you set a file's permission to @subcmd{READONLY}, then the file will become
354 unwritable either by you or anyone else on the system.
355 If you set the permission to @subcmd{WRITEABLE}, then the file will become
356 writeable by you; the permissions afforded to others will be
358 This command cannot be used if the @subcmd{SAFER} (@pxref{SET}) setting is active.
361 @node PRESERVE and RESTORE
362 @section PRESERVE and RESTORE
372 @cmd{PRESERVE} saves all of the settings that @cmd{SET} (@pxref{SET})
373 can adjust. A later @cmd{RESTORE} command restores those settings.
375 @cmd{PRESERVE} can be nested up to five levels deep.
385 /BLANKS=@{SYSMIS,'.',number@}
386 /DECIMAL=@{DOT,COMMA@}
387 /FORMAT=@var{fmt_spec}
388 /EPOCH=@{AUTOMATIC,@var{year}@}
389 /RIB=@{NATIVE,MSBFIRST,LSBFIRST,VAX@}
390 /RRB=@{NATIVE,ISL,ISB,IDL,IDB,VF,VD,VG,ZS,ZL@}
393 /MXERRS=@var{max_errs}
394 /MXWARNS=@var{max_warnings}
395 /WORKSPACE=@var{workspace_size}
398 /LOCALE='@var{locale}'
400 /MITERATE=@var{max_iterations}
401 /MNEST=@var{max_nest}
403 /MXLOOPS=@var{max_loops}
404 /SEED=@{RANDOM,@var{seed_value}@}
405 /UNDEFINED=@{WARN,NOWARN@}
408 /CC@{A,B,C,D,E@}=@{'@var{npre},@var{pre},@var{suf},@var{nsuf}','@var{npre}.@var{pre}.@var{suf}.@var{nsuf}'@}
409 /DECIMAL=@{DOT,COMMA@}
410 /FORMAT=@var{fmt_spec}
411 /WIB=@{NATIVE,MSBFIRST,LSBFIRST,VAX@}
412 /WRB=@{NATIVE,ISL,ISB,IDL,IDB,VF,VD,VG,ZS,ZL@}
415 /ERRORS=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}
416 /MESSAGES=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}
417 /PRINTBACK=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}
418 /RESULTS=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}
420 (output driver options)
421 /HEADERS=@{NO,YES,BLANK@}
422 /LENGTH=@{NONE,@var{n_lines}@}
424 /WIDTH=@{NARROW,WIDTH,@var{n_characters}@}
425 /TNUMBERS=@{VALUES,LABELS,BOTH@}
428 /JOURNAL=@{ON,OFF@} ['@var{file_name}']
431 /COMPRESSION=@{ON,OFF@}
432 /SCOMPRESSION=@{ON,OFF@}
436 /LOCALE='@var{string}'
439 (obsolete settings accepted for compatibility, but ignored)
440 /BOXSTRING=@{'@var{xxx}','@var{xxxxxxxxxxx}'@}
441 /CASE=@{UPPER,UPLOW@}
445 /LOWRES=@{AUTO,ON,OFF@}
447 /MENUS=@{STANDARD,EXTENDED@}
448 /MXMEMORY=@var{max_memory}
450 /TB1=@{'@var{xxx}','@var{xxxxxxxxxxx}'@}
451 /TBFONTS='@var{string}'
455 @cmd{SET} allows the user to adjust several parameters relating to
456 @pspp{}'s execution. Since there are many subcommands to this command, its
457 subcommands will be examined in groups.
459 For subcommands that take boolean values, @subcmd{ON} and @subcmd{YES} are synonymous,
460 as are @subcmd{OFF} and @subcmd{NO}, when used as subcommand values.
462 The data input subcommands affect the way that data is read from data
463 files. The data input subcommands are
468 This is the value assigned to an item data item that is empty or
469 contains only white space. An argument of SYSMIS or '.' will cause the
470 system-missing value to be assigned to null items. This is the
471 default. Any real value may be assigned.
475 This value may be set to @subcmd{DOT} or @subcmd{COMMA}.
476 Setting it to DOT causes the decimal point character to be
477 @samp{.} and the grouping character to be @samp{,}.
478 Setting it to @subcmd{COMMA}
479 causes the decimal point character to be @samp{,} and the grouping
480 character to be @samp{.}.
481 The default value is determined from the system locale.
484 Allows the default numeric input/output format to be specified. The
485 default is F8.2. @xref{Input and Output Formats}.
489 Specifies the range of years used when a 2-digit year is read from a
490 data file or used in a date construction expression (@pxref{Date
491 Construction}). If a 4-digit year is specified for the epoch, then
492 2-digit years are interpreted starting from that year, known as the
493 epoch. If @subcmd{AUTOMATIC} (the default) is specified, then the epoch begins
494 69 years before the current date.
499 @pspp{} extension to set the byte ordering (endianness) used for reading
500 data in IB or PIB format (@pxref{Binary and Hexadecimal Numeric
501 Formats}). In MSBFIRST ordering, the most-significant byte appears at
502 the left end of a IB or PIB field. In LSBFIRST ordering, the
503 least-significant byte appears at the left end. VAX ordering is like
504 MSBFIRST, except that each pair of bytes is in reverse order. NATIVE,
505 the default, is equivalent to MSBFIRST or LSBFIRST depending on the
506 native format of the machine running @pspp{}.
511 @pspp{} extension to set the floating-point format used for reading data in
512 RB format (@pxref{Binary and Hexadecimal Numeric Formats}). The
517 The native format of the machine running @pspp{}. Equivalent to either IDL
521 32-bit IEEE 754 single-precision floating point, in little-endian byte
525 32-bit IEEE 754 single-precision floating point, in big-endian byte
529 64-bit IEEE 754 double-precision floating point, in little-endian byte
533 64-bit IEEE 754 double-precision floating point, in big-endian byte
537 32-bit VAX F format, in VAX-endian byte order.
540 64-bit VAX D format, in VAX-endian byte order.
543 64-bit VAX G format, in VAX-endian byte order.
546 32-bit IBM Z architecture short format hexadecimal floating point, in
547 big-endian byte order.
550 64-bit IBM Z architecture long format hexadecimal floating point, in
551 big-endian byte order.
553 Z architecture also supports IEEE 754 floating point. The ZS and ZL
554 formats are only for use with very old input files.
556 The default is NATIVE.
559 Interaction subcommands affect the way that @pspp{} interacts with an
560 online user. The interaction subcommands are
564 The maximum number of errors before @pspp{} halts processing of the current
565 command file. The default is 50.
568 The maximum number of warnings + errors before @pspp{} halts processing the
569 current command file.
570 The special value of zero means that all warning situations should be ignored.
571 No warnings will be issued, except a single initial warning advising the user
572 that warnings will not be given.
573 The default value is 100.
576 Syntax execution subcommands control the way that @pspp{} commands
577 execute. The syntax execution subcommands are
581 Overrides the system locale for the purpose of reading and writing
582 syntax and data files. The argument should be a locale name in the
583 general form @code{language_country.encoding}, where @code{language}
584 and @code{country} are 2-character language and country abbreviations,
585 respectively, and @code{encoding} is an IANA character set name.
586 Example locales are @code{en_US.UTF-8} (UTF-8 encoded English as
587 spoken in the United States) and @code{ja_JP.EUC-JP} (EUC-JP encoded
588 Japanese as spoken in Japan).
597 The maximum number of iterations for an uncontrolled loop (@pxref{LOOP}).
598 The default @var{max_loops} is 40.
601 The initial pseudo-random number seed. Set to a real number or to
602 RANDOM, which will obtain an initial seed from the current time of day.
608 The maximum amount of memory that @pspp{} will use to store data being processed.
609 If memory in excess of the workspace size is required, then @pspp{} will start
610 to use temporary files to store the data.
611 Setting a higher value will, in general, mean procedures will run faster,
612 but may cause other applications to run slower.
613 On platforms without virtual memory management, setting a very large workspace
614 may cause @pspp{} to abort.
616 @cindex memory, amount used to store cases
619 Data output subcommands affect the format of output data. These
628 @anchor{CCx Settings}
630 Set up custom currency formats. @xref{Custom Currency Formats}, for
634 The default DOT setting causes the decimal point character to be
635 @samp{.}. A setting of COMMA causes the decimal point character to be
639 Allows the default numeric input/output format to be specified. The
640 default is F8.2. @xref{Input and Output Formats}.
645 @pspp{} extension to set the byte ordering (endianness) used for writing
646 data in IB or PIB format (@pxref{Binary and Hexadecimal Numeric
647 Formats}). In MSBFIRST ordering, the most-significant byte appears at
648 the left end of a IB or PIB field. In LSBFIRST ordering, the
649 least-significant byte appears at the left end. VAX ordering is like
650 MSBFIRST, except that each pair of bytes is in reverse order. NATIVE,
651 the default, is equivalent to MSBFIRST or LSBFIRST depending on the
652 native format of the machine running @pspp{}.
657 @pspp{} extension to set the floating-point format used for writing data in
658 RB format (@pxref{Binary and Hexadecimal Numeric Formats}). The choices
659 are the same as SET RIB. The default is NATIVE.
662 In the @pspp{} text-based interface, the output routing subcommands
663 affect where output is sent. The following values are allowed for
664 each of these subcommands:
669 Discard this kind of output.
672 Write this output to the terminal, but not to listing files and other
676 Write this output to listing files and other output devices, but not
681 Write this type of output to all output devices.
684 These output routing subcommands are:
688 Applies to error and warning messages. The default is BOTH.
691 Applies to notes. The default is BOTH.
694 Determines whether the syntax used for input is printed back as part
695 of the output. The default is NONE.
698 Applies to everything not in one of the above categories, such as the
699 results of statistical procedures. The default is BOTH.
702 These subcommands have no effect on output in the @pspp{} GUI
705 Output driver option subcommands affect output drivers' settings. These
714 The TNUMBERS option sets the way in which values are displayed in output tables.
715 The valid settings are VALUES, LABELS and BOTH.
716 If TNUMBERS is set to VALUES, then all values are displayed with their literal value
717 (which for a numeric value is a number and for a string value an alphanumeric string).
718 If TNUMBERS is set to LABELS, then values are displayed using their assigned labels if any.
719 (@xref{VALUE LABELS}.)
720 If the a value has no label, then it will be displayed using its literal value.
721 If TNUMBERS is set to BOTH, then values will be displayed with both their label
722 (if any) and their literal value in parenthesis.
733 Logging subcommands affect logging of commands executed to external
734 files. These subcommands are
739 These subcommands, which are synonyms, control the journal. The
740 default is ON, which causes commands entered interactively to be
741 written to the journal file. Commands included from syntax files that
742 are included interactively and error messages printed by @pspp{} are also
743 written to the journal file, prefixed by @samp{>}. OFF disables use
746 The journal is named @file{pspp.jnl} by default. A different name may
750 System file subcommands affect the default format of system files
751 produced by @pspp{}. These subcommands are
758 Whether system files created by @cmd{SAVE} or @cmd{XSAVE} are
759 compressed by default. The default is ON.
762 Security subcommands affect the operations that commands are allowed to
763 perform. The security subcommands are
767 Setting this option disables the following operations:
771 The @cmd{ERASE} command.
773 The @cmd{HOST} command.
775 The @cmd{PERMISSIONS} command.
777 Pipes (file names beginning or ending with @samp{|}).
780 Be aware that this setting does not guarantee safety (commands can still
781 overwrite files, for instance) but it is an improvement.
782 When set, this setting cannot be reset during the same session, for
783 obvious security reasons.
787 @cindex encoding, characters
788 This item is used to set the default character encoding.
789 The encoding may be specified either as an encoding name or alias
790 (see @url{http://www.iana.org/assignments/character-sets}), or
792 If given as a locale name, only the character encoding of the
795 System files written by @pspp{} will use this encoding.
796 System files read by @pspp{}, for which the encoding is unknown, will be
797 interpreted using this encoding.
799 The full list of valid encodings and locale names/alias are operating system
801 The following are all examples of acceptable syntax on common GNU/Linux
804 SET LOCALE='iso-8859-1'.
806 SET LOCALE='ru_RU.cp1251'.
808 SET LOCALE='japanese'.
811 Contrary to the intuition, this command does not affect any aspect
812 of the system's locale.
847 @cmd{SHOW} can be used to display the current state of @pspp{}'s execution
848 parameters. Parameters that can be changed using @cmd{SET}
849 (@pxref{SET}), can be examined using @cmd{SHOW} using the subcommand
850 with the same name. @cmd{SHOW} supports the following additional
857 Show all custom currency settings (CCA through CCE).
858 @item @subcmd{DIRECTORY}
859 Shows the current working directory.
860 @item @subcmd{ENVIRONMENT}
861 Shows the operating system details.
862 @item @subcmd{TEMPDIR}
863 Shows the path of the directory where temporary files will be stored.
864 @item @subcmd{VERSION}
865 Shows the version of this installation of @pspp{}.
866 @item @subcmd{WARRANTY}
867 Show details of the lack of warranty for @pspp{}.
868 @item @subcmd{COPYING} / @subcmd{LICENSE}
869 Display the terms of @pspp{}'s copyright licence (@pxref{License}).
872 Specifying @cmd{SHOW} without any subcommands is equivalent to @subcmd{SHOW ALL}.
879 SUBTITLE '@var{subtitle_string}'.
881 SUBTITLE @var{subtitle_string}.
884 @cmd{SUBTITLE} provides a subtitle to a particular @pspp{}
885 run. This subtitle appears at the top of each output page below the
886 title, if headers are enabled on the output device.
888 Specify a subtitle as a string in quotes. The alternate syntax that did
889 not require quotes is now obsolete. If it is used then the subtitle is
890 converted to all uppercase.
897 TITLE '@var{title_string}'.
899 TITLE @var{title_string}.
902 @cmd{TITLE} provides a title to a particular @pspp{} run.
903 This title appears at the top of each output page, if headers are enabled
904 on the output device.
906 Specify a title as a string in quotes. The alternate syntax that did
907 not require quotes is now obsolete. If it is used then the title is
908 converted to all uppercase.