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 * ADD DOCUMENT:: Add documentary text to the active file.
13 * COMMENT:: Document your syntax file.
14 * DOCUMENT:: Document the active file.
15 * DISPLAY DOCUMENTS:: Display active file documents.
16 * DISPLAY FILE LABEL:: Display the active file label.
17 * DROP DOCUMENTS:: Remove documents from the active file.
18 * ECHO:: Write a string to the output stream.
19 * ERASE:: Erase a file.
20 * EXECUTE:: Execute pending transformations.
21 * FILE LABEL:: Set the active file's label.
22 * FINISH:: Terminate the PSPP session.
23 * HOST:: Temporarily return to the operating system.
24 * INCLUDE:: Include a file within the current one.
25 * PERMISSIONS:: Change permissions on a file.
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 ADD DOCUMENT, COMMENT, Utilities, Utilities
33 @comment node-name, next, previous, up
39 'line one' 'line two' @dots{} 'last line' .
43 @cmd{ADD DOCUMENT} adds one or more lines of descriptive commentary to
44 the active file. Documents added in this way are saved to system files.
45 They can be viewed using @cmd{SYSFILE INFO} or @cmd{DISPLAY
46 DOCUMENTS}. They can be removed from the active file with @cmd{DROP
49 Each line of documentary text must be enclosed in quotation marks, and
50 may not be more than 80 bytes long. @xref{DOCUMENT}.
54 @node COMMENT, DOCUMENT, ADD DOCUMENT, Utilities
60 Two possibles syntaxes:
61 COMMENT comment text @dots{} .
62 *comment text @dots{} .
65 @cmd{COMMENT} is ignored. It is used to provide information to
66 the author and other readers of the PSPP syntax file.
68 @cmd{COMMENT} can extend over any number of lines. Don't forget to
69 terminate it with a dot or a blank line.
73 @node DOCUMENT, DISPLAY DOCUMENTS, COMMENT, Utilities
78 DOCUMENT @var{documentary_text}.
81 @cmd{DOCUMENT} adds one or more lines of descriptive commentary to the
82 active file. Documents added in this way are saved to system files.
83 They can be viewed using @cmd{SYSFILE INFO} or @cmd{DISPLAY
84 DOCUMENTS}. They can be removed from the active file with @cmd{DROP
87 Specify the @var{documentary text} following the DOCUMENT keyword.
88 It is interpreted literally --- any quotes or other punctuation marks
89 will be included in the file.
90 You can extend the documentary text over as many lines as necessary.
91 Lines are truncated at 80 bytes. Don't forget to terminate
92 the command with a dot or a blank line. @xref{ADD DOCUMENT}.
94 @node DISPLAY DOCUMENTS, DISPLAY FILE LABEL, DOCUMENT, Utilities
95 @section DISPLAY DOCUMENTS
96 @vindex DISPLAY DOCUMENTS
102 @cmd{DISPLAY DOCUMENTS} displays the documents in the active file. Each
103 document is preceded by a line giving the time and date that it was
104 added. @xref{DOCUMENT}.
106 @node DISPLAY FILE LABEL, DROP DOCUMENTS, DISPLAY DOCUMENTS, Utilities
107 @section DISPLAY FILE LABEL
108 @vindex DISPLAY FILE LABEL
114 @cmd{DISPLAY FILE LABEL} displays the file label contained in the
116 if any. @xref{FILE LABEL}.
118 This command is a PSPP extension.
120 @node DROP DOCUMENTS, ECHO, DISPLAY FILE LABEL, Utilities
121 @section DROP DOCUMENTS
122 @vindex DROP DOCUMENTS
128 @cmd{DROP DOCUMENTS} removes all documents from the active file.
129 New documents can be added with @cmd{DOCUMENT} (@pxref{DOCUMENT}).
131 @cmd{DROP DOCUMENTS} changes only the active file. It does not modify any
132 system files stored on disk.
134 @node ECHO, ERASE, DROP DOCUMENTS, Utilities
139 ECHO 'arbitrary text' .
142 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}).
144 @node ERASE, EXECUTE, ECHO, Utilities
145 @comment node-name, next, previous, up
150 ERASE FILE file_name.
153 @cmd{ERASE FILE} deletes a file from the local filesystem.
154 file_name must be quoted.
155 This command cannot be used if the SAFER setting is active.
158 @node EXECUTE, FILE LABEL, ERASE, Utilities
166 @cmd{EXECUTE} causes the active file to be read and all pending
167 transformations to be executed.
169 @node FILE LABEL, FINISH, EXECUTE, Utilities
174 FILE LABEL file_label.
177 @cmd{FILE LABEL} provides a title for the active file. This
178 title will be saved into system files and portable files that are
179 created during this PSPP run.
181 file_label need not be quoted. If quotes are
182 included, they become part of the file label.
184 @node FINISH, HOST, FILE LABEL, Utilities
192 @cmd{FINISH} terminates the current PSPP session and returns
193 control to the operating system.
195 @node HOST, INCLUDE, FINISH, Utilities
196 @comment node-name, next, previous, up
204 @cmd{HOST} suspends the current PSPP session and temporarily returns control
205 to the operating system.
206 This command cannot be used if the SAFER setting is active.
209 @node INCLUDE, PERMISSIONS, HOST, Utilities
215 Two possible syntaxes:
220 @cmd{INCLUDE} causes the PSPP command processor to read an
221 additional command file as if it were included bodily in the current
224 Include files may be nested to any depth, up to the limit of available
227 @node PERMISSIONS, SET, INCLUDE, Utilities
228 @comment node-name, next, previous, up
233 @cindex changing file permissions
238 /PERMISSIONS = @{READONLY,WRITEABLE@}.
241 @cmd{PERMISSIONS} changes the permissions of a file.
242 There is one mandatory subcommand which specifies the permissions to
243 which the file should be changed.
244 If you set a file's permission to READONLY, then the file will become
245 unwritable either by you or anyone else on the system.
246 If you set the permission to WRITEABLE, then the file will become
247 writeable by you; the permissions afforded to others will be
249 This command cannot be used if the SAFER setting is active.
252 @node SET, SHOW, PERMISSIONS, Utilities
260 /BLANKS=@{SYSMIS,'.',number@}
261 /DECIMAL=@{DOT,COMMA@}
263 /EPOCH=@{AUTOMATIC,year@}
264 /RIB=@{NATIVE,MSBFIRST,LSBFIRST,VAX@}
265 /RRB=@{NATIVE,ISL,ISB,IDL,IDB,VF,VD,VG,ZS,ZL@}
272 /CPROMPT='cprompt_string'
273 /DPROMPT='dprompt_string'
274 /ERRORBREAK=@{OFF,ON@}
276 /MXWARNS=max_warnings
281 /MITERATE=max_iterations
285 /SEED=@{RANDOM,seed_value@}
286 /UNDEFINED=@{WARN,NOWARN@}
289 /CC@{A,B,C,D,E@}=@{'npre,pre,suf,nsuf','npre.pre.suf.nsuf'@}
290 /DECIMAL=@{DOT,COMMA@}
292 /WIB=@{NATIVE,MSBFIRST,LSBFIRST,VAX@}
293 /WRB=@{NATIVE,ISL,ISB,IDL,IDB,VF,VD,VG,ZS,ZL@}
297 /ERRORS=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}
299 /MESSAGES=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}
300 /PRINTBACK=@{ON,OFF@}
301 /RESULTS=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}
303 (output driver options)
304 /HEADERS=@{NO,YES,BLANK@}
305 /LENGTH=@{NONE,length_in_lines@}
306 /LISTING=@{ON,OFF,'file-name'@}
308 /WIDTH=@{NARROW,WIDTH,n_characters@}
311 /JOURNAL=@{ON,OFF@} ['file-name']
314 /COMPRESSION=@{ON,OFF@}
315 /SCOMPRESSION=@{ON,OFF@}
320 (obsolete settings accepted for compatibility, but ignored)
321 /BOXSTRING=@{'xxx','xxxxxxxxxxx'@}
322 /CASE=@{UPPER,UPLOW@}
327 /LOWRES=@{AUTO,ON,OFF@}
329 /MENUS=@{STANDARD,EXTENDED@}
332 /TB1=@{'xxx','xxxxxxxxxxx'@}
334 /WORKSPACE=workspace_size
338 @cmd{SET} allows the user to adjust several parameters relating to
339 PSPP's execution. Since there are many subcommands to this command, its
340 subcommands will be examined in groups.
342 On subcommands that take boolean values, ON and YES are synonym, and
343 as are OFF and NO, when used as subcommand values.
345 The data input subcommands affect the way that data is read from data
346 files. The data input subcommands are
350 This is the value assigned to an item data item that is empty or
351 contains only white space. An argument of SYSMIS or '.' will cause the
352 system-missing value to be assigned to null items. This is the
353 default. Any real value may be assigned.
357 The default DOT setting causes the decimal point character to be
358 @samp{.} and the grouping character to be @samp{,}. A setting of COMMA
359 causes the decimal point character to be @samp{,} and the grouping
360 character to be @samp{.}.
363 Allows the default numeric input/output format to be specified. The
364 default is F8.2. @xref{Input and Output Formats}.
368 Specifies the range of years used when a 2-digit year is read from a
369 data file or used in a date construction expression (@pxref{Date
370 Construction}). If a 4-digit year is specified for the epoch, then
371 2-digit years are interpreted starting from that year, known as the
372 epoch. If AUTOMATIC (the default) is specified, then the epoch begins
373 69 years before the current date.
378 PSPP extension to set the byte ordering (endianness) used for reading
379 data in IB or PIB format (@pxref{Binary and Hexadecimal Numeric
380 Formats}). In MSBFIRST ordering, the most-significant byte appears at
381 the left end of a IB or PIB field. In LSBFIRST ordering, the
382 least-significant byte appears at the left end. VAX ordering is like
383 MSBFIRST, except that each pair of bytes is in reverse order. NATIVE,
384 the default, is equivalent to MSBFIRST or LSBFIRST depending on the
385 native format of the machine running PSPP.
390 PSPP extension to set the floating-point format used for reading data in
391 RB format (@pxref{Binary and Hexadecimal Numeric Formats}). The
396 The native format of the machine running PSPP. Equivalent to either IDL
400 32-bit IEEE 754 single-precision floating point, in little-endian byte
404 32-bit IEEE 754 single-precision floating point, in big-endian byte
408 64-bit IEEE 754 double-precision floating point, in little-endian byte
412 64-bit IEEE 754 double-precision floating point, in big-endian byte
416 32-bit VAX F format, in VAX-endian byte order.
419 64-bit VAX D format, in VAX-endian byte order.
422 64-bit VAX G format, in VAX-endian byte order.
425 32-bit IBM Z architecture short format hexadecimal floating point, in
426 big-endian byte order.
429 64-bit IBM Z architecture long format hexadecimal floating point, in
430 big-endian byte order.
432 Z architecture also supports IEEE 754 floating point. The ZS and ZL
433 formats are only for use with very old input files.
435 The default is NATIVE.
438 Program input subcommands affect the way that programs are parsed when
439 they are typed interactively or run from a command file. They are
443 This is a single character indicating the end of a command. The default
444 is @samp{.}. Don't change this.
447 Whether a blank line is interpreted as ending the current command. The
451 Interaction subcommands affect the way that PSPP interacts with an
452 online user. The interaction subcommands are
456 The command continuation prompt. The default is @samp{ > }.
459 Prompt used when expecting data input within @cmd{BEGIN DATA} (@pxref{BEGIN
460 DATA}). The default is @samp{data> }.
463 Whether an error causes PSPP to stop processing the current command
464 file after finishing the current command. The default is OFF.
467 The maximum number of errors before PSPP halts processing of the current
468 command file. The default is 50.
471 The maximum number of warnings + errors before PSPP halts processing the
472 current command file. The default is 100.
475 The command prompt. The default is @samp{PSPP> }.
478 Program execution subcommands control the way that PSPP commands
479 execute. The program execution subcommands are
489 The maximum number of iterations for an uncontrolled loop (@pxref{LOOP}).
492 The initial pseudo-random number seed. Set to a real number or to
493 RANDOM, which will obtain an initial seed from the current time of day.
499 Data output subcommands affect the format of output data. These
508 @anchor{CCx Settings}
510 Set up custom currency formats. @xref{Custom Currency Formats}, for
514 The default DOT setting causes the decimal point character to be
515 @samp{.}. A setting of COMMA causes the decimal point character to be
519 Allows the default numeric input/output format to be specified. The
520 default is F8.2. @xref{Input and Output Formats}.
525 PSPP extension to set the byte ordering (endianness) used for writing
526 data in IB or PIB format (@pxref{Binary and Hexadecimal Numeric
527 Formats}). In MSBFIRST ordering, the most-significant byte appears at
528 the left end of a IB or PIB field. In LSBFIRST ordering, the
529 least-significant byte appears at the left end. VAX ordering is like
530 MSBFIRST, except that each pair of bytes is in reverse order. NATIVE,
531 the default, is equivalent to MSBFIRST or LSBFIRST depending on the
532 native format of the machine running PSPP.
537 PSPP extension to set the floating-point format used for writing data in
538 RB format (@pxref{Binary and Hexadecimal Numeric Formats}). The choices
539 are the same as SET RIB. The default is NATIVE.
542 Output routing subcommands affect where the output of transformations
543 and procedures is sent. These subcommands are
548 If turned on, commands are written to the listing file as they are read
549 from command files. The default is OFF.
559 Output driver option subcommands affect output drivers' settings. These
579 Logging subcommands affect logging of commands executed to external
580 files. These subcommands are
588 System file subcommands affect the default format of system files
589 produced by PSPP. These subcommands are
596 Whether system files created by @cmd{SAVE} or @cmd{XSAVE} are
597 compressed by default. The default is ON.
600 Security subcommands affect the operations that commands are allowed to
601 perform. The security subcommands are
605 Setting this option disables the following operations:
613 The PERMISSIONS command.
615 Pipes (file names beginning or ending with @samp{|}).
618 Be aware that this setting does not guarantee safety (commands can still
619 overwrite files, for instance) but it is an improvement.
620 When set, this setting cannot be reset during the same session, for
621 obvious security reasons.
624 @node SHOW, SUBTITLE, SET, Utilities
625 @comment node-name, next, previous, up
654 @cmd{SHOW} can be used to display the current state of PSPP's execution
655 parameters. Parameters that can be changed using @cmd{SET}
656 (@pxref{SET}), can be examined using @cmd{SHOW} using the subcommand
657 with the same name. @code{SHOW} supports the following additional
664 Show all custom currency settings (CCA through CCE).
666 Show details of the lack of warranty for PSPP.
668 Display the terms of PSPP's copyright licence (@pxref{License}).
671 Specifying @cmd{SHOW} without any subcommands is equivalent to SHOW ALL.
673 @node SUBTITLE, TITLE, SHOW, Utilities
678 SUBTITLE 'subtitle_string'.
680 SUBTITLE subtitle_string.
683 @cmd{SUBTITLE} provides a subtitle to a particular PSPP
684 run. This subtitle appears at the top of each output page below the
685 title, if headers are enabled on the output device.
687 Specify a subtitle as a string in quotes. The alternate syntax that did
688 not require quotes is now obsolete. If it is used then the subtitle is
689 converted to all uppercase.
691 @node TITLE, , SUBTITLE, Utilities
696 TITLE 'title_string'.
701 @cmd{TITLE} provides a title to a particular PSPP run.
702 This title appears at the top of each output page, if headers are enabled
703 on the output device.
705 Specify a title as a string in quotes. The alternate syntax that did
706 not require quotes is now obsolete. If it is used then the title is
707 converted to all uppercase.