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 file.
13 * CD:: Change the current directory.
14 * COMMENT:: Document your syntax file.
15 * DOCUMENT:: Document the active file.
16 * DISPLAY DOCUMENTS:: Display active file documents.
17 * DISPLAY FILE LABEL:: Display the active file label.
18 * DROP DOCUMENTS:: Remove documents from the active file.
19 * ECHO:: Write a string to the output stream.
20 * ERASE:: Erase a file.
21 * EXECUTE:: Execute pending transformations.
22 * FILE LABEL:: Set the active file's label.
23 * FINISH:: Terminate the PSPP session.
24 * HOST:: Temporarily return to the operating system.
25 * INCLUDE:: Include a file within the current one.
26 * INSERT:: Insert a file within the current one.
27 * PERMISSIONS:: Change permissions on a file.
28 * PRESERVE and RESTORE:: Saving settings and restoring them later.
29 * SET:: Adjust PSPP runtime parameters.
30 * SHOW:: Display runtime parameters.
31 * SUBTITLE:: Provide a document subtitle.
32 * TITLE:: Provide a document title.
36 @comment node-name, next, previous, up
42 'line one' 'line two' @dots{} 'last line' .
46 @cmd{ADD DOCUMENT} adds one or more lines of descriptive commentary to
47 the active file. 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 file 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}.
59 @cindex changing directory
65 @cmd{CD} changes the current directory. The new directory will become that specified by the command.
73 Two possibles syntaxes:
74 COMMENT comment text @dots{} .
75 *comment text @dots{} .
78 @cmd{COMMENT} is ignored. It is used to provide information to
79 the author and other readers of the PSPP syntax file.
81 @cmd{COMMENT} can extend over any number of lines. Don't forget to
82 terminate it with a dot or a blank line.
91 DOCUMENT @var{documentary_text}.
94 @cmd{DOCUMENT} adds one or more lines of descriptive commentary to the
95 active file. Documents added in this way are saved to system files.
96 They can be viewed using @cmd{SYSFILE INFO} or @cmd{DISPLAY
97 DOCUMENTS}. They can be removed from the active file with @cmd{DROP
100 Specify the @var{documentary text} following the DOCUMENT keyword.
101 It is interpreted literally --- any quotes or other punctuation marks
102 will be included in the file.
103 You can extend the documentary text over as many lines as necessary.
104 Lines are truncated at 80 bytes. Don't forget to terminate
105 the command with a dot or a blank line. @xref{ADD DOCUMENT}.
107 @node DISPLAY DOCUMENTS
108 @section DISPLAY DOCUMENTS
109 @vindex DISPLAY DOCUMENTS
115 @cmd{DISPLAY DOCUMENTS} displays the documents in the active file. Each
116 document is preceded by a line giving the time and date that it was
117 added. @xref{DOCUMENT}.
119 @node DISPLAY FILE LABEL
120 @section DISPLAY FILE LABEL
121 @vindex DISPLAY FILE LABEL
127 @cmd{DISPLAY FILE LABEL} displays the file label contained in the
129 if any. @xref{FILE LABEL}.
131 This command is a PSPP extension.
134 @section DROP DOCUMENTS
135 @vindex DROP DOCUMENTS
141 @cmd{DROP DOCUMENTS} removes all documents from the active file.
142 New documents can be added with @cmd{DOCUMENT} (@pxref{DOCUMENT}).
144 @cmd{DROP DOCUMENTS} changes only the active file. It does not modify any
145 system files stored on disk.
152 ECHO 'arbitrary text' .
155 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}).
158 @comment node-name, next, previous, up
163 ERASE FILE file_name.
166 @cmd{ERASE FILE} deletes a file from the local filesystem.
167 file_name must be quoted.
168 This command cannot be used if the SAFER setting is active.
179 @cmd{EXECUTE} causes the active file to be read and all pending
180 transformations to be executed.
187 FILE LABEL file_label.
190 @cmd{FILE LABEL} provides a title for the active file. This
191 title will be saved into system files and portable files that are
192 created during this PSPP run.
194 file_label need not be quoted. If quotes are
195 included, they become part of the file label.
205 @cmd{FINISH} terminates the current PSPP session and returns
206 control to the operating system.
209 @comment node-name, next, previous, up
215 HOST COMMAND=['command'...].
218 @cmd{HOST} suspends the current PSPP session and temporarily returns control
219 to the operating system.
220 This command cannot be used if the SAFER setting is active.
222 If the COMMAND subcommand is specified, as a sequence of shell
223 commands as quoted strings within square brackets, then PSPP executes
224 them together in a single subshell.
226 If no subcommands are specified, then PSPP invokes an interactive
234 INCLUDE [FILE=]'file-name'.
237 @cmd{INCLUDE} causes the PSPP command processor to read an
238 additional command file as if it were included bodily in the current
240 If errors are encountered in the included file, then command processing will
241 stop and no more commands will be processed.
242 Include files may be nested to any depth, up to the limit of available
246 The @cmd{INSERT} command (@pxref{INSERT}) may be used instead of
247 @cmd{INCLUDE} if you require more flexible options.
250 INCLUDE FILE=@var{file-name}.
253 functions identically to
255 INSERT FILE=@var{file-name} ERROR=STOP CD=NO SYNTAX=BATCH.
264 INSERT [FILE=]'file-name'
266 [ERROR=@{CONTINUE,STOP@}]
267 [SYNTAX=@{BATCH,INTERACTIVE@}].
270 @cmd{INSERT} is similar to @cmd{INCLUDE} (@pxref{INCLUDE})
271 but somewhat more flexible.
272 It causes the command processor to read a file as if it were embedded in the
273 current command file.
275 If @samp{CD=YES} is specified, then before including the file, the
276 current directory will be changed to the directory of the included
278 The default setting is @samp{CD=NO}.
279 Note that this directory will remain current until it is
280 changed explicitly (with the @cmd{CD} command, or a subsequent
281 @cmd{INSERT} command with the @samp{CD=YES} option).
282 It will not revert to its original setting even after the included
283 file is finished processing.
285 If @samp{ERROR=STOP} is specified, errors encountered in the
286 inserted file will cause processing to immediately cease.
287 Otherwise processing will continue at the next command.
288 The default setting is @samp{ERROR=CONTINUE}.
290 If @samp{SYNTAX=INTERACTIVE} is specified then the syntax contained in
291 the included file must conform to interactive syntax
292 conventions. @xref{Syntax Variants}.
293 The default setting is @samp{SYNTAX=BATCH}.
300 @cindex changing file permissions
305 /PERMISSIONS = @{READONLY,WRITEABLE@}.
308 @cmd{PERMISSIONS} changes the permissions of a file.
309 There is one mandatory subcommand which specifies the permissions to
310 which the file should be changed.
311 If you set a file's permission to READONLY, then the file will become
312 unwritable either by you or anyone else on the system.
313 If you set the permission to WRITEABLE, then the file will become
314 writeable by you; the permissions afforded to others will be
316 This command cannot be used if the SAFER setting is active.
319 @node PRESERVE and RESTORE
320 @section PRESERVE and RESTORE
330 @cmd{PRESERVE} saves all of the settings that @cmd{SET} (@pxref{SET})
331 can adjust. A later @cmd{RESTORE} command restores those settings.
333 @cmd{PRESERVE} can be nested up to five levels deep.
343 /BLANKS=@{SYSMIS,'.',number@}
344 /DECIMAL=@{DOT,COMMA@}
346 /EPOCH=@{AUTOMATIC,year@}
347 /RIB=@{NATIVE,MSBFIRST,LSBFIRST,VAX@}
348 /RRB=@{NATIVE,ISL,ISB,IDL,IDB,VF,VD,VG,ZS,ZL@}
355 /CPROMPT='cprompt_string'
356 /DPROMPT='dprompt_string'
358 /MXWARNS=max_warnings
360 /WORKSPACE=workspace_size
364 /MITERATE=max_iterations
368 /SEED=@{RANDOM,seed_value@}
369 /UNDEFINED=@{WARN,NOWARN@}
372 /CC@{A,B,C,D,E@}=@{'npre,pre,suf,nsuf','npre.pre.suf.nsuf'@}
373 /DECIMAL=@{DOT,COMMA@}
375 /WIB=@{NATIVE,MSBFIRST,LSBFIRST,VAX@}
376 /WRB=@{NATIVE,ISL,ISB,IDL,IDB,VF,VD,VG,ZS,ZL@}
379 /ERRORS=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}
380 /MESSAGES=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}
381 /PRINTBACK=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}
382 /RESULTS=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}
384 (output driver options)
385 /HEADERS=@{NO,YES,BLANK@}
386 /LENGTH=@{NONE,length_in_lines@}
388 /WIDTH=@{NARROW,WIDTH,n_characters@}
391 /JOURNAL=@{ON,OFF@} ['file-name']
394 /COMPRESSION=@{ON,OFF@}
395 /SCOMPRESSION=@{ON,OFF@}
402 (obsolete settings accepted for compatibility, but ignored)
403 /BOXSTRING=@{'xxx','xxxxxxxxxxx'@}
404 /CASE=@{UPPER,UPLOW@}
408 /LOWRES=@{AUTO,ON,OFF@}
410 /MENUS=@{STANDARD,EXTENDED@}
413 /TB1=@{'xxx','xxxxxxxxxxx'@}
418 @cmd{SET} allows the user to adjust several parameters relating to
419 PSPP's execution. Since there are many subcommands to this command, its
420 subcommands will be examined in groups.
422 On subcommands that take boolean values, ON and YES are synonym, and
423 as are OFF and NO, when used as subcommand values.
425 The data input subcommands affect the way that data is read from data
426 files. The data input subcommands are
431 This is the value assigned to an item data item that is empty or
432 contains only white space. An argument of SYSMIS or '.' will cause the
433 system-missing value to be assigned to null items. This is the
434 default. Any real value may be assigned.
438 This value may be set to DOT or COMMA.
439 Setting it to DOT causes the decimal point character to be
440 @samp{.} and the grouping character to be @samp{,}.
442 causes the decimal point character to be @samp{,} and the grouping
443 character to be @samp{.}.
444 The default value is determined from the system locale.
447 Allows the default numeric input/output format to be specified. The
448 default is F8.2. @xref{Input and Output Formats}.
452 Specifies the range of years used when a 2-digit year is read from a
453 data file or used in a date construction expression (@pxref{Date
454 Construction}). If a 4-digit year is specified for the epoch, then
455 2-digit years are interpreted starting from that year, known as the
456 epoch. If AUTOMATIC (the default) is specified, then the epoch begins
457 69 years before the current date.
462 PSPP extension to set the byte ordering (endianness) used for reading
463 data in IB or PIB format (@pxref{Binary and Hexadecimal Numeric
464 Formats}). In MSBFIRST ordering, the most-significant byte appears at
465 the left end of a IB or PIB field. In LSBFIRST ordering, the
466 least-significant byte appears at the left end. VAX ordering is like
467 MSBFIRST, except that each pair of bytes is in reverse order. NATIVE,
468 the default, is equivalent to MSBFIRST or LSBFIRST depending on the
469 native format of the machine running PSPP.
474 PSPP extension to set the floating-point format used for reading data in
475 RB format (@pxref{Binary and Hexadecimal Numeric Formats}). The
480 The native format of the machine running PSPP. Equivalent to either IDL
484 32-bit IEEE 754 single-precision floating point, in little-endian byte
488 32-bit IEEE 754 single-precision floating point, in big-endian byte
492 64-bit IEEE 754 double-precision floating point, in little-endian byte
496 64-bit IEEE 754 double-precision floating point, in big-endian byte
500 32-bit VAX F format, in VAX-endian byte order.
503 64-bit VAX D format, in VAX-endian byte order.
506 64-bit VAX G format, in VAX-endian byte order.
509 32-bit IBM Z architecture short format hexadecimal floating point, in
510 big-endian byte order.
513 64-bit IBM Z architecture long format hexadecimal floating point, in
514 big-endian byte order.
516 Z architecture also supports IEEE 754 floating point. The ZS and ZL
517 formats are only for use with very old input files.
519 The default is NATIVE.
522 Program input subcommands affect the way that programs are parsed when
523 they are typed interactively or run from a command file. They are
527 This is a single character indicating the end of a command. The default
528 is @samp{.}. Don't change this.
531 Whether a blank line is interpreted as ending the current command. The
535 Interaction subcommands affect the way that PSPP interacts with an
536 online user. The interaction subcommands are
540 The command continuation prompt. The default is @samp{ > }.
543 Prompt used when expecting data input within @cmd{BEGIN DATA} (@pxref{BEGIN
544 DATA}). The default is @samp{data> }.
547 The maximum number of errors before PSPP halts processing of the current
548 command file. The default is 50.
551 The maximum number of warnings + errors before PSPP halts processing the
552 current command file.
553 The special value of zero means that all warning situations should be ignored.
554 No warnings will be issued, except a single initial warning advising the user
555 that warnings will not be given.
556 The default value is 100.
559 The command prompt. The default is @samp{PSPP> }.
562 Program execution subcommands control the way that PSPP commands
563 execute. The program execution subcommands are
573 The maximum number of iterations for an uncontrolled loop (@pxref{LOOP}).
576 The initial pseudo-random number seed. Set to a real number or to
577 RANDOM, which will obtain an initial seed from the current time of day.
583 The maximum amount of memory that PSPP will use to store data being processed.
584 If memory in excess of the workspace size is required, then PSPP will start
585 to use temporary files to store the data.
586 Setting a higher value will, in general, mean procedures will run faster,
587 but may cause other applications to run slower.
588 On platforms without virtual memory management, setting a very large workspace
589 may cause PSPP to abort.
591 @cindex memory, amount used to store cases
594 Data output subcommands affect the format of output data. These
603 @anchor{CCx Settings}
605 Set up custom currency formats. @xref{Custom Currency Formats}, for
609 The default DOT setting causes the decimal point character to be
610 @samp{.}. A setting of COMMA causes the decimal point character to be
614 Allows the default numeric input/output format to be specified. The
615 default is F8.2. @xref{Input and Output Formats}.
620 PSPP extension to set the byte ordering (endianness) used for writing
621 data in IB or PIB format (@pxref{Binary and Hexadecimal Numeric
622 Formats}). In MSBFIRST ordering, the most-significant byte appears at
623 the left end of a IB or PIB field. In LSBFIRST ordering, the
624 least-significant byte appears at the left end. VAX ordering is like
625 MSBFIRST, except that each pair of bytes is in reverse order. NATIVE,
626 the default, is equivalent to MSBFIRST or LSBFIRST depending on the
627 native format of the machine running PSPP.
632 PSPP extension to set the floating-point format used for writing data in
633 RB format (@pxref{Binary and Hexadecimal Numeric Formats}). The choices
634 are the same as SET RIB. The default is NATIVE.
637 In the PSPP text-based interface, the output routing subcommands
638 affect where output is sent. The following values are allowed for
639 each of these subcommands:
644 Discard this kind of output.
647 Write this output to the terminal, but not to listing files and other
651 Write this output to listing files and other output devices, but not
656 Write this type of output to all output devices.
659 These output routing subcommands are:
663 Applies to error and warning messages. The default is BOTH.
666 Applies to notes. The default is BOTH.
669 Determines whether the syntax used for input is printed back as part
670 of the output. The default is NONE.
673 Applies to everything not in one of the above categories, such as the
674 results of statistical procedures. The default is BOTH.
677 These subcommands have no effect on output in the PSPP GUI
680 Output driver option subcommands affect output drivers' settings. These
698 Logging subcommands affect logging of commands executed to external
699 files. These subcommands are
704 These subcommands, which are synonyms, control the journal. The
705 default is ON, which causes commands entered interactively to be
706 written to the journal file. Commands included from syntax files that
707 are included interactively and error messages printed by PSPP are also
708 written to the journal file, prefixed by @samp{>}. OFF disables use
711 The journal is named @file{pspp.jnl} by default. A different name may
715 System file subcommands affect the default format of system files
716 produced by PSPP. These subcommands are
723 Whether system files created by @cmd{SAVE} or @cmd{XSAVE} are
724 compressed by default. The default is ON.
727 Security subcommands affect the operations that commands are allowed to
728 perform. The security subcommands are
732 Setting this option disables the following operations:
740 The PERMISSIONS command.
742 Pipes (file names beginning or ending with @samp{|}).
745 Be aware that this setting does not guarantee safety (commands can still
746 overwrite files, for instance) but it is an improvement.
747 When set, this setting cannot be reset during the same session, for
748 obvious security reasons.
752 @cindex encoding, characters
753 This item is used to set the default character encoding.
754 The encoding may be specified either as an encoding name or alias
755 (see @url{http://www.iana.org/assignments/character-sets}), or
757 If given as a locale name, only the character encoding of the
760 System files written by PSPP will use this encoding.
761 System files read by PSPP, for which the encoding is unknown, will be
762 interpreted using this encoding.
764 The full list of valid encodings and locale names/alias are operating system
766 The following are all examples of acceptable syntax on common GNU/Linux
770 SET LOCALE='iso-8859-1'.
772 SET LOCALE='ru_RU.cp1251'.
774 SET LOCALE='japanese'.
778 Contrary to the intuition, this command does not affect any aspect
779 of the system's locale.
783 @comment node-name, next, previous, up
812 @cmd{SHOW} can be used to display the current state of PSPP's execution
813 parameters. Parameters that can be changed using @cmd{SET}
814 (@pxref{SET}), can be examined using @cmd{SHOW} using the subcommand
815 with the same name. @code{SHOW} supports the following additional
822 Show all custom currency settings (CCA through CCE).
824 Show details of the lack of warranty for PSPP.
826 Display the terms of PSPP's copyright licence (@pxref{License}).
829 Specifying @cmd{SHOW} without any subcommands is equivalent to SHOW ALL.
836 SUBTITLE 'subtitle_string'.
838 SUBTITLE subtitle_string.
841 @cmd{SUBTITLE} provides a subtitle to a particular PSPP
842 run. This subtitle appears at the top of each output page below the
843 title, if headers are enabled on the output device.
845 Specify a subtitle as a string in quotes. The alternate syntax that did
846 not require quotes is now obsolete. If it is used then the subtitle is
847 converted to all uppercase.
854 TITLE 'title_string'.
859 @cmd{TITLE} provides a title to a particular PSPP run.
860 This title appears at the top of each output page, if headers are enabled
861 on the output device.
863 Specify a title as a string in quotes. The alternate syntax that did
864 not require quotes is now obsolete. If it is used then the title is
865 converted to all uppercase.