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 * SET:: Adjust PSPP runtime parameters.
29 * SHOW:: Display runtime parameters.
30 * SUBTITLE:: Provide a document subtitle.
31 * TITLE:: Provide a document title.
35 @comment node-name, next, previous, up
41 'line one' 'line two' @dots{} 'last line' .
45 @cmd{ADD DOCUMENT} adds one or more lines of descriptive commentary to
46 the active file. Documents added in this way are saved to system files.
47 They can be viewed using @cmd{SYSFILE INFO} or @cmd{DISPLAY
48 DOCUMENTS}. They can be removed from the active file with @cmd{DROP
51 Each line of documentary text must be enclosed in quotation marks, and
52 may not be more than 80 bytes long. @xref{DOCUMENT}.
58 @cindex changing directory
64 @cmd{CD} changes the current directory. The new directory will become that specified by the command.
72 Two possibles syntaxes:
73 COMMENT comment text @dots{} .
74 *comment text @dots{} .
77 @cmd{COMMENT} is ignored. It is used to provide information to
78 the author and other readers of the PSPP syntax file.
80 @cmd{COMMENT} can extend over any number of lines. Don't forget to
81 terminate it with a dot or a blank line.
90 DOCUMENT @var{documentary_text}.
93 @cmd{DOCUMENT} adds one or more lines of descriptive commentary to the
94 active file. Documents added in this way are saved to system files.
95 They can be viewed using @cmd{SYSFILE INFO} or @cmd{DISPLAY
96 DOCUMENTS}. They can be removed from the active file with @cmd{DROP
99 Specify the @var{documentary text} following the DOCUMENT keyword.
100 It is interpreted literally --- any quotes or other punctuation marks
101 will be included in the file.
102 You can extend the documentary text over as many lines as necessary.
103 Lines are truncated at 80 bytes. Don't forget to terminate
104 the command with a dot or a blank line. @xref{ADD DOCUMENT}.
106 @node DISPLAY DOCUMENTS
107 @section DISPLAY DOCUMENTS
108 @vindex DISPLAY DOCUMENTS
114 @cmd{DISPLAY DOCUMENTS} displays the documents in the active file. Each
115 document is preceded by a line giving the time and date that it was
116 added. @xref{DOCUMENT}.
118 @node DISPLAY FILE LABEL
119 @section DISPLAY FILE LABEL
120 @vindex DISPLAY FILE LABEL
126 @cmd{DISPLAY FILE LABEL} displays the file label contained in the
128 if any. @xref{FILE LABEL}.
130 This command is a PSPP extension.
133 @section DROP DOCUMENTS
134 @vindex DROP DOCUMENTS
140 @cmd{DROP DOCUMENTS} removes all documents from the active file.
141 New documents can be added with @cmd{DOCUMENT} (@pxref{DOCUMENT}).
143 @cmd{DROP DOCUMENTS} changes only the active file. It does not modify any
144 system files stored on disk.
151 ECHO 'arbitrary text' .
154 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}).
157 @comment node-name, next, previous, up
162 ERASE FILE file_name.
165 @cmd{ERASE FILE} deletes a file from the local filesystem.
166 file_name must be quoted.
167 This command cannot be used if the SAFER setting is active.
178 @cmd{EXECUTE} causes the active file to be read and all pending
179 transformations to be executed.
186 FILE LABEL file_label.
189 @cmd{FILE LABEL} provides a title for the active file. This
190 title will be saved into system files and portable files that are
191 created during this PSPP run.
193 file_label need not be quoted. If quotes are
194 included, they become part of the file label.
204 @cmd{FINISH} terminates the current PSPP session and returns
205 control to the operating system.
208 @comment node-name, next, previous, up
216 @cmd{HOST} suspends the current PSPP session and temporarily returns control
217 to the operating system.
218 This command cannot be used if the SAFER setting is active.
226 INCLUDE [FILE=]'file-name'.
229 @cmd{INCLUDE} causes the PSPP command processor to read an
230 additional command file as if it were included bodily in the current
232 If errors are encountered in the included file, then command processing will
233 stop and no more commands will be processed.
234 Include files may be nested to any depth, up to the limit of available
238 The @cmd{INSERT} command (@pxref{INSERT}) may be used instead of
239 @cmd{INCLUDE} if you require more flexible options.
242 INCLUDE FILE=@var{file-name}.
245 functions identically to
247 INSERT FILE=@var{file-name} ERROR=STOP CD=NO SYNTAX=BATCH.
256 INSERT [FILE=]'file-name'
258 [ERROR=@{CONTINUE,STOP@}]
259 [SYNTAX=@{BATCH,INTERACTIVE@}].
262 @cmd{INSERT} is similar to @cmd{INCLUDE} (@pxref{INCLUDE})
263 but somewhat more flexible.
264 It causes the command processor to read a file as if it were embedded in the
265 current command file.
267 If @samp{CD=YES} is specified, then before including the file, the
268 current directory will be changed to the directory of the included
270 The default setting is @samp{CD=NO}.
271 Note that this directory will remain current until it is
272 changed explicitly (with the @cmd{CD} command, or a subsequent
273 @cmd{INSERT} command with the @samp{CD=YES} option).
274 It will not revert to its original setting even after the included
275 file is finished processing.
277 If @samp{ERROR=STOP} is specified, errors encountered in the
278 inserted file will cause processing to immediately cease.
279 Otherwise processing will continue at the next command.
280 The default setting is @samp{ERROR=CONTINUE}.
282 If @samp{SYNTAX=INTERACTIVE} is specified then the syntax contained in
283 the included file must conform to interactive syntax
284 conventions. @xref{Syntax Variants}.
285 The default setting is @samp{SYNTAX=BATCH}.
292 @cindex changing file permissions
297 /PERMISSIONS = @{READONLY,WRITEABLE@}.
300 @cmd{PERMISSIONS} changes the permissions of a file.
301 There is one mandatory subcommand which specifies the permissions to
302 which the file should be changed.
303 If you set a file's permission to READONLY, then the file will become
304 unwritable either by you or anyone else on the system.
305 If you set the permission to WRITEABLE, then the file will become
306 writeable by you; the permissions afforded to others will be
308 This command cannot be used if the SAFER setting is active.
319 /BLANKS=@{SYSMIS,'.',number@}
320 /DECIMAL=@{DOT,COMMA@}
322 /EPOCH=@{AUTOMATIC,year@}
323 /RIB=@{NATIVE,MSBFIRST,LSBFIRST,VAX@}
324 /RRB=@{NATIVE,ISL,ISB,IDL,IDB,VF,VD,VG,ZS,ZL@}
331 /CPROMPT='cprompt_string'
332 /DPROMPT='dprompt_string'
334 /MXWARNS=max_warnings
336 /WORKSPACE=workspace_size
340 /MITERATE=max_iterations
344 /SEED=@{RANDOM,seed_value@}
345 /UNDEFINED=@{WARN,NOWARN@}
348 /CC@{A,B,C,D,E@}=@{'npre,pre,suf,nsuf','npre.pre.suf.nsuf'@}
349 /DECIMAL=@{DOT,COMMA@}
351 /WIB=@{NATIVE,MSBFIRST,LSBFIRST,VAX@}
352 /WRB=@{NATIVE,ISL,ISB,IDL,IDB,VF,VD,VG,ZS,ZL@}
355 /ERRORS=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}
356 /MESSAGES=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}
357 /PRINTBACK=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}
358 /RESULTS=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}
360 (output driver options)
361 /HEADERS=@{NO,YES,BLANK@}
362 /LENGTH=@{NONE,length_in_lines@}
364 /WIDTH=@{NARROW,WIDTH,n_characters@}
367 /JOURNAL=@{ON,OFF@} ['file-name']
370 /COMPRESSION=@{ON,OFF@}
371 /SCOMPRESSION=@{ON,OFF@}
378 (obsolete settings accepted for compatibility, but ignored)
379 /BOXSTRING=@{'xxx','xxxxxxxxxxx'@}
380 /CASE=@{UPPER,UPLOW@}
384 /LOWRES=@{AUTO,ON,OFF@}
386 /MENUS=@{STANDARD,EXTENDED@}
389 /TB1=@{'xxx','xxxxxxxxxxx'@}
394 @cmd{SET} allows the user to adjust several parameters relating to
395 PSPP's execution. Since there are many subcommands to this command, its
396 subcommands will be examined in groups.
398 On subcommands that take boolean values, ON and YES are synonym, and
399 as are OFF and NO, when used as subcommand values.
401 The data input subcommands affect the way that data is read from data
402 files. The data input subcommands are
407 This is the value assigned to an item data item that is empty or
408 contains only white space. An argument of SYSMIS or '.' will cause the
409 system-missing value to be assigned to null items. This is the
410 default. Any real value may be assigned.
414 This value may be set to DOT or COMMA.
415 Setting it to DOT causes the decimal point character to be
416 @samp{.} and the grouping character to be @samp{,}.
418 causes the decimal point character to be @samp{,} and the grouping
419 character to be @samp{.}.
420 The default value is determined from the system locale.
423 Allows the default numeric input/output format to be specified. The
424 default is F8.2. @xref{Input and Output Formats}.
428 Specifies the range of years used when a 2-digit year is read from a
429 data file or used in a date construction expression (@pxref{Date
430 Construction}). If a 4-digit year is specified for the epoch, then
431 2-digit years are interpreted starting from that year, known as the
432 epoch. If AUTOMATIC (the default) is specified, then the epoch begins
433 69 years before the current date.
438 PSPP extension to set the byte ordering (endianness) used for reading
439 data in IB or PIB format (@pxref{Binary and Hexadecimal Numeric
440 Formats}). In MSBFIRST ordering, the most-significant byte appears at
441 the left end of a IB or PIB field. In LSBFIRST ordering, the
442 least-significant byte appears at the left end. VAX ordering is like
443 MSBFIRST, except that each pair of bytes is in reverse order. NATIVE,
444 the default, is equivalent to MSBFIRST or LSBFIRST depending on the
445 native format of the machine running PSPP.
450 PSPP extension to set the floating-point format used for reading data in
451 RB format (@pxref{Binary and Hexadecimal Numeric Formats}). The
456 The native format of the machine running PSPP. Equivalent to either IDL
460 32-bit IEEE 754 single-precision floating point, in little-endian byte
464 32-bit IEEE 754 single-precision floating point, in big-endian byte
468 64-bit IEEE 754 double-precision floating point, in little-endian byte
472 64-bit IEEE 754 double-precision floating point, in big-endian byte
476 32-bit VAX F format, in VAX-endian byte order.
479 64-bit VAX D format, in VAX-endian byte order.
482 64-bit VAX G format, in VAX-endian byte order.
485 32-bit IBM Z architecture short format hexadecimal floating point, in
486 big-endian byte order.
489 64-bit IBM Z architecture long format hexadecimal floating point, in
490 big-endian byte order.
492 Z architecture also supports IEEE 754 floating point. The ZS and ZL
493 formats are only for use with very old input files.
495 The default is NATIVE.
498 Program input subcommands affect the way that programs are parsed when
499 they are typed interactively or run from a command file. They are
503 This is a single character indicating the end of a command. The default
504 is @samp{.}. Don't change this.
507 Whether a blank line is interpreted as ending the current command. The
511 Interaction subcommands affect the way that PSPP interacts with an
512 online user. The interaction subcommands are
516 The command continuation prompt. The default is @samp{ > }.
519 Prompt used when expecting data input within @cmd{BEGIN DATA} (@pxref{BEGIN
520 DATA}). The default is @samp{data> }.
523 The maximum number of errors before PSPP halts processing of the current
524 command file. The default is 50.
527 The maximum number of warnings + errors before PSPP halts processing the
528 current command file.
529 The special value of zero means that all warning situations should be ignored.
530 No warnings will be issued, except a single initial warning advising the user
531 that warnings will not be given.
532 The default value is 100.
535 The command prompt. The default is @samp{PSPP> }.
538 Program execution subcommands control the way that PSPP commands
539 execute. The program execution subcommands are
549 The maximum number of iterations for an uncontrolled loop (@pxref{LOOP}).
552 The initial pseudo-random number seed. Set to a real number or to
553 RANDOM, which will obtain an initial seed from the current time of day.
559 The maximum amount of memory that PSPP will use to store data being processed.
560 If memory in excess of the workspace size is required, then PSPP will start
561 to use temporary files to store the data.
562 Setting a higher value will, in general, mean procedures will run faster,
563 but may cause other applications to run slower.
564 On platforms without virtual memory management, setting a very large workspace
565 may cause PSPP to abort.
567 @cindex memory, amount used to store cases
570 Data output subcommands affect the format of output data. These
579 @anchor{CCx Settings}
581 Set up custom currency formats. @xref{Custom Currency Formats}, for
585 The default DOT setting causes the decimal point character to be
586 @samp{.}. A setting of COMMA causes the decimal point character to be
590 Allows the default numeric input/output format to be specified. The
591 default is F8.2. @xref{Input and Output Formats}.
596 PSPP extension to set the byte ordering (endianness) used for writing
597 data in IB or PIB format (@pxref{Binary and Hexadecimal Numeric
598 Formats}). In MSBFIRST ordering, the most-significant byte appears at
599 the left end of a IB or PIB field. In LSBFIRST ordering, the
600 least-significant byte appears at the left end. VAX ordering is like
601 MSBFIRST, except that each pair of bytes is in reverse order. NATIVE,
602 the default, is equivalent to MSBFIRST or LSBFIRST depending on the
603 native format of the machine running PSPP.
608 PSPP extension to set the floating-point format used for writing data in
609 RB format (@pxref{Binary and Hexadecimal Numeric Formats}). The choices
610 are the same as SET RIB. The default is NATIVE.
613 In the PSPP text-based interface, the output routing subcommands
614 affect where output is sent. The following values are allowed for
615 each of these subcommands:
620 Discard this kind of output.
623 Write this output to the terminal, but not to listing files and other
627 Write this output to listing files and other output devices, but not
632 Write this type of output to all output devices.
635 These output routing subcommands are:
639 Applies to error and warning messages. The default is BOTH.
642 Applies to notes. The default is BOTH.
645 Determines whether the syntax used for input is printed back as part
646 of the output. The default is NONE.
649 Applies to everything not in one of the above categories, such as the
650 results of statistical procedures. The default is BOTH.
653 These subcommands have no effect on output in the PSPP GUI
656 Output driver option subcommands affect output drivers' settings. These
674 Logging subcommands affect logging of commands executed to external
675 files. These subcommands are
680 These subcommands, which are synonyms, control the journal. The
681 default is ON, which causes commands entered interactively to be
682 written to the journal file. Commands included from syntax files that
683 are included interactively and error messages printed by PSPP are also
684 written to the journal file, prefixed by @samp{>}. OFF disables use
687 The journal is named @file{pspp.jnl} by default. A different name may
691 System file subcommands affect the default format of system files
692 produced by PSPP. These subcommands are
699 Whether system files created by @cmd{SAVE} or @cmd{XSAVE} are
700 compressed by default. The default is ON.
703 Security subcommands affect the operations that commands are allowed to
704 perform. The security subcommands are
708 Setting this option disables the following operations:
716 The PERMISSIONS command.
718 Pipes (file names beginning or ending with @samp{|}).
721 Be aware that this setting does not guarantee safety (commands can still
722 overwrite files, for instance) but it is an improvement.
723 When set, this setting cannot be reset during the same session, for
724 obvious security reasons.
728 @cindex encoding, characters
729 This item is used to set the default character encoding.
730 The encoding may be specified either as an encoding name or alias
731 (see @url{http://www.iana.org/assignments/character-sets}), or
733 If given as a locale name, only the character encoding of the
736 System files written by PSPP will use this encoding.
737 System files read by PSPP, for which the encoding is unknown, will be
738 interpreted using this encoding.
740 The full list of valid encodings and locale names/alias are operating system
742 The following are all examples of acceptable syntax on common GNU/Linux
746 SET LOCALE='iso-8859-1'.
748 SET LOCALE='ru_RU.cp1251'.
750 SET LOCALE='japanese'.
754 Contrary to the intuition, this command does not affect any aspect
755 of the system's locale.
759 @comment node-name, next, previous, up
788 @cmd{SHOW} can be used to display the current state of PSPP's execution
789 parameters. Parameters that can be changed using @cmd{SET}
790 (@pxref{SET}), can be examined using @cmd{SHOW} using the subcommand
791 with the same name. @code{SHOW} supports the following additional
798 Show all custom currency settings (CCA through CCE).
800 Show details of the lack of warranty for PSPP.
802 Display the terms of PSPP's copyright licence (@pxref{License}).
805 Specifying @cmd{SHOW} without any subcommands is equivalent to SHOW ALL.
812 SUBTITLE 'subtitle_string'.
814 SUBTITLE subtitle_string.
817 @cmd{SUBTITLE} provides a subtitle to a particular PSPP
818 run. This subtitle appears at the top of each output page below the
819 title, if headers are enabled on the output device.
821 Specify a subtitle as a string in quotes. The alternate syntax that did
822 not require quotes is now obsolete. If it is used then the subtitle is
823 converted to all uppercase.
830 TITLE 'title_string'.
835 @cmd{TITLE} provides a title to a particular PSPP run.
836 This title appears at the top of each output page, if headers are enabled
837 on the output device.
839 Specify a title as a string in quotes. The alternate syntax that did
840 not require quotes is now obsolete. If it is used then the title is
841 converted to all uppercase.