1 @node Utilities, Not Implemented, Statistics, Top
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 * COMMENT:: Document your syntax file.
13 * DOCUMENT:: Document the active file.
14 * DISPLAY DOCUMENTS:: Display active file documents.
15 * DISPLAY FILE LABEL:: Display the active file label.
16 * DROP DOCUMENTS:: Remove documents from the active file.
17 * ECHO:: Write a string to the output stream.
18 * ERASE:: Erase a file.
19 * EXECUTE:: Execute pending transformations.
20 * FILE LABEL:: Set the active file's label.
21 * FINISH:: Terminate the PSPP session.
22 * HOST:: Temporarily return to the operating system.
23 * INCLUDE:: Include a file within the current one.
24 * PERMISSIONS:: Change permissions on a file.
25 * QUIT:: Terminate the PSPP session.
26 * SET:: Adjust PSPP runtime parameters.
27 * SHOW:: Display runtime parameters.
28 * SUBTITLE:: Provide a document subtitle.
29 * TITLE:: Provide a document title.
32 @node COMMENT, DOCUMENT, Utilities, Utilities
38 Two possibles syntaxes:
39 COMMENT comment text @dots{} .
40 *comment text @dots{} .
43 @cmd{COMMENT} is ignored. It is used to provide information to
44 the author and other readers of the PSPP syntax file.
46 @cmd{COMMENT} can extend over any number of lines. Don't forget to
47 terminate it with a dot or a blank line.
49 @node DOCUMENT, DISPLAY DOCUMENTS, COMMENT, Utilities
54 DOCUMENT documentary_text.
57 @cmd{DOCUMENT} adds one or more lines of descriptive commentary to the
58 active file. Documents added in this way are saved to system files.
59 They can be viewed using @cmd{SYSFILE INFO} or @cmd{DISPLAY
60 DOCUMENTS}. They can be removed from the active file with @cmd{DROP
63 Specify the documentary text following the DOCUMENT keyword. You can
64 extend the documentary text over as many lines as necessary. Lines are
65 truncated at 80 characters width. Don't forget to terminate
66 the command with a dot or a blank line.
68 @node DISPLAY DOCUMENTS, DISPLAY FILE LABEL, DOCUMENT, Utilities
69 @section DISPLAY DOCUMENTS
70 @vindex DISPLAY DOCUMENTS
76 @cmd{DISPLAY DOCUMENTS} displays the documents in the active file. Each
77 document is preceded by a line giving the time and date that it was
78 added. @xref{DOCUMENT}.
80 @node DISPLAY FILE LABEL, DROP DOCUMENTS, DISPLAY DOCUMENTS, Utilities
81 @section DISPLAY FILE LABEL
82 @vindex DISPLAY FILE LABEL
88 @cmd{DISPLAY FILE LABEL} displays the file label contained in the
90 if any. @xref{FILE LABEL}.
92 @node DROP DOCUMENTS, ECHO, DISPLAY FILE LABEL, Utilities
93 @section DROP DOCUMENTS
94 @vindex DROP DOCUMENTS
100 @cmd{DROP DOCUMENTS} removes all documents from the active file.
101 New documents can be added with @cmd{DOCUMENT} (@pxref{DOCUMENT}).
103 @cmd{DROP DOCUMENTS} changes only the active file. It does not modify any
104 system files stored on disk.
106 @node ECHO, ERASE, DROP DOCUMENTS, Utilities
111 ECHO 'arbitrary text' .
114 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}).
116 @node ERASE, EXECUTE, ECHO, Utilities
117 @comment node-name, next, previous, up
122 ERASE FILE file_name.
125 @cmd{ERASE FILE} deletes a file from the local filesystem.
126 file_name must be quoted.
127 This command cannot be used if the SAFER setting is active.
130 @node EXECUTE, FILE LABEL, ERASE, Utilities
138 @cmd{EXECUTE} causes the active file to be read and all pending
139 transformations to be executed.
141 @node FILE LABEL, FINISH, EXECUTE, Utilities
146 FILE LABEL file_label.
149 @cmd{FILE LABEL} provides a title for the active file. This
150 title will be saved into system files and portable files that are
151 created during this PSPP run.
153 file_label need not be quoted. If quotes are
154 included, they become part of the file label.
156 @node FINISH, HOST, FILE LABEL, Utilities
164 @cmd{FINISH} terminates the current PSPP session and returns
165 control to the operating system.
167 This command is not valid in interactive mode.
169 @node HOST, INCLUDE, FINISH, Utilities
170 @comment node-name, next, previous, up
178 @cmd{HOST} suspends the current PSPP session and temporarily returns control
179 to the operating system.
180 This command cannot be used if the SAFER setting is active.
183 @node INCLUDE, PERMISSIONS, HOST, Utilities
189 Two possible syntaxes:
194 @cmd{INCLUDE} causes the PSPP command processor to read an
195 additional command file as if it were included bodily in the current
198 Include files may be nested to any depth, up to the limit of available
201 @node PERMISSIONS, QUIT, INCLUDE, Utilities
202 @comment node-name, next, previous, up
207 @cindex changing file permissions
212 /PERMISSIONS = @{READONLY,WRITEABLE@}.
215 @cmd{PERMISSIONS} changes the permissions of a file.
216 There is one mandatory subcommand which specifies the permissions to
217 which the file should be changed.
218 If you set a file's permission to READONLY, then the file will become
219 unwritable either by you or anyone else on the system.
220 If you set the permission to WRITEABLE, then the file will become
221 writeable by you; the permissions afforded to others will be
223 This command cannot be used if the SAFER setting is active.
226 @node QUIT, SET, PERMISSIONS, Utilities
231 Two possible syntaxes:
236 @cmd{QUIT} terminates the current PSPP session and returns control
237 to the operating system.
239 This command is not valid within a command file.
241 @node SET, SHOW, QUIT, Utilities
249 /BLANKS=@{SYSMIS,'.',number@}
250 /DECIMAL=@{DOT,COMMA@}
252 /EPOCH=@{AUTOMATIC,year@}
259 /CPROMPT='cprompt_string'
260 /DPROMPT='dprompt_string'
261 /ERRORBREAK=@{OFF,ON@}
263 /MXWARNS=max_warnings
265 /VIEWLENGTH=@{MINIMUM,MEDIAN,MAXIMUM,n_lines@}
266 /VIEWWIDTH=n_characters
270 /MITERATE=max_iterations
274 /SEED=@{RANDOM,seed_value@}
275 /UNDEFINED=@{WARN,NOWARN@}
278 /CC@{A,B,C,D,E@}=@{'npre,pre,suf,nsuf','npre.pre.suf.nsuf'@}
279 /DECIMAL=@{DOT,COMMA@}
284 /ERRORS=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}
286 /MESSAGES=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}
287 /PRINTBACK=@{ON,OFF@}
288 /RESULTS=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}
295 (output driver options)
296 /HEADERS=@{NO,YES,BLANK@}
297 /LENGTH=@{NONE,length_in_lines@}
300 /PAGER=@{OFF,"pager_name"@}
301 /WIDTH=@{NARROW,WIDTH,n_characters@}
304 /JOURNAL=@{ON,OFF@} [filename]
305 /LOG=@{ON,OFF@} [filename]
308 /COMPRESSION=@{ON,OFF@}
309 /SCOMPRESSION=@{ON,OFF@}
314 (obsolete settings accepted for compatibility, but ignored)
318 /BOXSTRING=@{'xxx','xxxxxxxxxxx'@}
319 /CASE=@{UPPER,UPLOW@}
324 /HELPWINDOWS=@{ON,OFF@}
327 /LOWRES=@{AUTO,ON,OFF@}
329 /MENUS=@{STANDARD,EXTENDED@}
331 /PTRANSLATE=@{ON,OFF@}
333 /RUNREVIEW=@{AUTO,MANUAL@}
335 /TB1=@{'xxx','xxxxxxxxxxx'@}
337 /WORKDEV=drive_letter
338 /WORKSPACE=workspace_size
342 @cmd{SET} allows the user to adjust several parameters relating to
343 PSPP's execution. Since there are many subcommands to this command, its
344 subcommands will be examined in groups.
346 On subcommands that take boolean values, ON and YES are synonym, and
347 as are OFF and NO, when used as subcommand values.
349 The data input subcommands affect the way that data is read from data
350 files. The data input subcommands are
354 This is the value assigned to an item data item that is empty or
355 contains only white space. An argument of SYSMIS or '.' will cause the
356 system-missing value to be assigned to null items. This is the
357 default. Any real value may be assigned.
360 The default DOT setting causes the decimal point character to be
361 @samp{.}. A setting of COMMA causes the decimal point character to be
365 Allows the default numeric input/output format to be specified. The
366 default is F8.2. @xref{Input/Output Formats}.
370 Specifies the range of years used when a 2-digit year is read from a
371 data file or used in a date construction expression (@pxref{Date
372 Construction}). If a 4-digit year is specified, then 2-digit years
373 are interpreted starting from that year, known as the epoch. If
374 AUTOMATIC (the default) is specified, then the epoch begins 69 years
375 before the current date.
378 Program input subcommands affect the way that programs are parsed when
379 they are typed interactively or run from a script. They are
383 This is a single character indicating the end of a command. The default
384 is @samp{.}. Don't change this.
387 Whether a blank line is interpreted as ending the current command. The
391 Interaction subcommands affect the way that PSPP interacts with an
392 online user. The interaction subcommands are
396 The command continuation prompt. The default is @samp{ > }.
399 Prompt used when expecting data input within @cmd{BEGIN DATA} (@pxref{BEGIN
400 DATA}). The default is @samp{data> }.
403 Whether an error causes PSPP to stop processing the current command
404 file after finishing the current command. The default is OFF.
407 The maximum number of errors before PSPP halts processing of the current
408 command file. The default is 50.
411 The maximum number of warnings + errors before PSPP halts processing the
412 current command file. The default is 100.
415 The command prompt. The default is @samp{PSPP> }.
418 The length of the screen in lines. MINIMUM means 25 lines, MEDIAN and
419 MAXIMUM mean 43 lines. Otherwise specify the number of lines. Normally
420 PSPP should auto-detect your screen size so this shouldn't have to be
424 The width of the screen in characters. Normally 80 or 132.
427 Program execution subcommands control the way that PSPP commands
428 execute. The program execution subcommands are
438 The maximum number of iterations for an uncontrolled loop (@pxref{LOOP}).
441 The initial pseudo-random number seed. Set to a real number or to
442 RANDOM, which will obtain an initial seed from the current time of day.
448 Data output subcommands affect the format of output data. These
457 Set up custom currency formats. The argument is a string which must
458 contain exactly three commas or exactly three periods. If commas, then
459 the grouping character for the currency format is @samp{,}, and the
460 decimal point character is @samp{.}; if periods, then the situation is
463 The commas or periods divide the string into four fields, which are, in
464 order, the negative prefix, prefix, suffix, and negative suffix. When a
465 value is formatted using the custom currency format, the prefix precedes
466 the value formatted and the suffix follows it. In addition, if the
467 value is negative, the negative prefix precedes the prefix and the
468 negative suffix follows the suffix.
471 The default DOT setting causes the decimal point character to be
472 @samp{.}. A setting of COMMA causes the decimal point character to be
476 Allows the default numeric input/output format to be specified. The
477 default is F8.2. @xref{Input/Output Formats}.
480 Output routing subcommands affect where the output of transformations
481 and procedures is sent. These subcommands are
486 If turned on, commands are written to the listing file as they are read
487 from command files. The default is OFF.
497 Output activation subcommands affect whether output devices of
498 particular types are enabled. These subcommands are
502 Enable or disable listing devices.
505 Enable or disable printer devices.
508 Enable or disable screen devices.
511 Output driver option subcommands affect output drivers' settings. These
531 Logging subcommands affect logging of commands executed to external
532 files. These subcommands are
540 System file subcommands affect the default format of system files
541 produced by PSPP. These subcommands are
548 Whether system files created by @cmd{SAVE} or @cmd{XSAVE} are
549 compressed by default. The default is ON.
552 Security subcommands affect the operations that commands are allowed to
553 perform. The security subcommands are
557 Setting this option disables the following operations:
565 The PERMISSIONS command.
567 Pipe filenames (filenames beginning or ending with @samp{|}).
570 Be aware that this setting does not guarantee safety (commands can still
571 overwrite files, for instance) but it is an improvement.
572 When set, this setting cannot be reset during the same session, for
573 obvious security reasons.
576 @node SHOW, SUBTITLE, SET, Utilities
577 @comment node-name, next, previous, up
587 @cmd{SHOW} can be used to display the current state of PSPP's
588 execution parameters. All of the parameters which can be changed
589 using @code{SET} @xref{SET}, can be examined using @cmd{SHOW}, by
590 using a subcommand with the same name.
591 In addition, @code{SHOW} supports the following subcommands:
595 Show details of the lack of warranty for PSPP.
597 Display the terms of PSPP's copyright licence @ref{License}.
602 @node SUBTITLE, TITLE, SHOW, Utilities
607 SUBTITLE 'subtitle_string'.
609 SUBTITLE subtitle_string.
612 @cmd{SUBTITLE} provides a subtitle to a particular PSPP
613 run. This subtitle appears at the top of each output page below the
614 title, if headers are enabled on the output device.
616 Specify a subtitle as a string in quotes. The alternate syntax that did
617 not require quotes is now obsolete. If it is used then the subtitle is
618 converted to all uppercase.
620 @node TITLE, , SUBTITLE, Utilities
625 TITLE 'title_string'.
630 @cmd{TITLE} provides a title to a particular PSPP run.
631 This title appears at the top of each output page, if headers are enabled
632 on the output device.
634 Specify a title as a string in quotes. The alternate syntax that did
635 not require quotes is now obsolete. If it is used then the title is
636 converted to all uppercase.