-@node Utilities, Not Implemented, Statistics, Top
+@node Utilities
@chapter Utilities
Commands that don't fit any other category are placed here.
encountered in the input.
@menu
+* ADD DOCUMENT:: Add documentary text to the active file.
+* CD:: Change the current directory.
* COMMENT:: Document your syntax file.
* DOCUMENT:: Document the active file.
* DISPLAY DOCUMENTS:: Display active file documents.
* DISPLAY FILE LABEL:: Display the active file label.
* DROP DOCUMENTS:: Remove documents from the active file.
+* ECHO:: Write a string to the output stream.
* ERASE:: Erase a file.
* EXECUTE:: Execute pending transformations.
* FILE LABEL:: Set the active file's label.
* FINISH:: Terminate the PSPP session.
* HOST:: Temporarily return to the operating system.
* INCLUDE:: Include a file within the current one.
+* INSERT:: Insert a file within the current one.
* PERMISSIONS:: Change permissions on a file.
-* QUIT:: Terminate the PSPP session.
* SET:: Adjust PSPP runtime parameters.
* SHOW:: Display runtime parameters.
* SUBTITLE:: Provide a document subtitle.
* TITLE:: Provide a document title.
@end menu
-@node COMMENT, DOCUMENT, Utilities, Utilities
+@node ADD DOCUMENT
+@comment node-name, next, previous, up
+@section ADD DOCUMENT
+@vindex ADD DOCUMENT
+
+@display
+ADD DOCUMENT
+ 'line one' 'line two' @dots{} 'last line' .
+@end display
+
+
+@cmd{ADD DOCUMENT} adds one or more lines of descriptive commentary to
+the active file. Documents added in this way are saved to system files.
+They can be viewed using @cmd{SYSFILE INFO} or @cmd{DISPLAY
+DOCUMENTS}. They can be removed from the active file with @cmd{DROP
+DOCUMENTS}.
+
+Each line of documentary text must be enclosed in quotation marks, and
+may not be more than 80 bytes long. @xref{DOCUMENT}.
+
+@node CD
+@section CD
+@vindex CD
+@cindex directory
+@cindex changing directory
+
+@display
+CD 'new directory' .
+@end display
+
+@cmd{CD} changes the current directory. The new directory will become that specified by the command.
+
+@node COMMENT
@section COMMENT
@vindex COMMENT
@vindex *
@cmd{COMMENT} can extend over any number of lines. Don't forget to
terminate it with a dot or a blank line.
-@node DOCUMENT, DISPLAY DOCUMENTS, COMMENT, Utilities
+
+
+@node DOCUMENT
@section DOCUMENT
@vindex DOCUMENT
@display
-DOCUMENT documentary_text.
+DOCUMENT @var{documentary_text}.
@end display
@cmd{DOCUMENT} adds one or more lines of descriptive commentary to the
DOCUMENTS}. They can be removed from the active file with @cmd{DROP
DOCUMENTS}.
-Specify the documentary text following the DOCUMENT keyword. You can
-extend the documentary text over as many lines as necessary. Lines are
-truncated at 80 characters width. Don't forget to terminate
-the command with a dot or a blank line.
+Specify the @var{documentary text} following the DOCUMENT keyword.
+It is interpreted literally --- any quotes or other punctuation marks
+will be included in the file.
+You can extend the documentary text over as many lines as necessary.
+Lines are truncated at 80 bytes. Don't forget to terminate
+the command with a dot or a blank line. @xref{ADD DOCUMENT}.
-@node DISPLAY DOCUMENTS, DISPLAY FILE LABEL, DOCUMENT, Utilities
+@node DISPLAY DOCUMENTS
@section DISPLAY DOCUMENTS
@vindex DISPLAY DOCUMENTS
document is preceded by a line giving the time and date that it was
added. @xref{DOCUMENT}.
-@node DISPLAY FILE LABEL, DROP DOCUMENTS, DISPLAY DOCUMENTS, Utilities
+@node DISPLAY FILE LABEL
@section DISPLAY FILE LABEL
@vindex DISPLAY FILE LABEL
active file,
if any. @xref{FILE LABEL}.
-@node DROP DOCUMENTS, ERASE, DISPLAY FILE LABEL, Utilities
+This command is a PSPP extension.
+
+@node DROP DOCUMENTS
@section DROP DOCUMENTS
@vindex DROP DOCUMENTS
@cmd{DROP DOCUMENTS} changes only the active file. It does not modify any
system files stored on disk.
+@node ECHO
+@section ECHO
+@vindex ECHO
+
+@display
+ECHO 'arbitrary text' .
+@end display
+
+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}).
-@node ERASE, EXECUTE, DROP DOCUMENTS, Utilities
+@node ERASE
@comment node-name, next, previous, up
@section ERASE
@vindex ERASE
This command cannot be used if the SAFER setting is active.
-@node EXECUTE, FILE LABEL, ERASE, Utilities
+@node EXECUTE
@section EXECUTE
@vindex EXECUTE
@cmd{EXECUTE} causes the active file to be read and all pending
transformations to be executed.
-@node FILE LABEL, FINISH, EXECUTE, Utilities
+@node FILE LABEL
@section FILE LABEL
@vindex FILE LABEL
file_label need not be quoted. If quotes are
included, they become part of the file label.
-@node FINISH, HOST, FILE LABEL, Utilities
+@node FINISH
@section FINISH
@vindex FINISH
@cmd{FINISH} terminates the current PSPP session and returns
control to the operating system.
-This command is not valid in interactive mode.
-
-@node HOST, INCLUDE, FINISH, Utilities
+@node HOST
@comment node-name, next, previous, up
@section HOST
@vindex HOST
This command cannot be used if the SAFER setting is active.
-@node INCLUDE, PERMISSIONS, HOST, Utilities
+@node INCLUDE
@section INCLUDE
@vindex INCLUDE
-@vindex @@
@display
-Two possible syntaxes:
- INCLUDE 'filename'.
- @@filename.
+ INCLUDE [FILE=]'file-name'.
@end display
@cmd{INCLUDE} causes the PSPP command processor to read an
additional command file as if it were included bodily in the current
command file.
-
+If errors are encountered in the included file, then command processing will
+stop and no more commands will be processed.
Include files may be nested to any depth, up to the limit of available
memory.
-@node PERMISSIONS, QUIT, INCLUDE, Utilities
-@comment node-name, next, previous, up
+
+The @cmd{INSERT} command (@pxref{INSERT}) may be used instead of
+@cmd{INCLUDE} if you require more flexible options.
+The syntax
+@example
+INCLUDE FILE=@var{file-name}.
+@end example
+@noindent
+functions identically to
+@example
+INSERT FILE=@var{file-name} ERROR=STOP CD=NO SYNTAX=BATCH.
+@end example
+
+
+@node INSERT
+@section INSERT
+@vindex INSERT
+
+@display
+ INSERT [FILE=]'file-name'
+ [CD=@{NO,YES@}]
+ [ERROR=@{CONTINUE,STOP@}]
+ [SYNTAX=@{BATCH,INTERACTIVE@}].
+@end display
+
+@cmd{INSERT} is similar to @cmd{INCLUDE} (@pxref{INCLUDE})
+but somewhat more flexible.
+It causes the command processor to read a file as if it were embedded in the
+current command file.
+
+If @samp{CD=YES} is specified, then before including the file, the
+current directory will be changed to the directory of the included
+file.
+The default setting is @samp{CD=NO}.
+Note that this directory will remain current until it is
+changed explicitly (with the @cmd{CD} command, or a subsequent
+@cmd{INSERT} command with the @samp{CD=YES} option).
+It will not revert to its original setting even after the included
+file is finished processing.
+
+If @samp{ERROR=STOP} is specified, errors encountered in the
+inserted file will cause processing to immediately cease.
+Otherwise processing will continue at the next command.
+The default setting is @samp{ERROR=CONTINUE}.
+
+If @samp{SYNTAX=INTERACTIVE} is specified then the syntax contained in
+the included file must conform to interactive syntax
+conventions. @xref{Syntax Variants}.
+The default setting is @samp{SYNTAX=BATCH}.
+
+@node PERMISSIONS
@section PERMISSIONS
@vindex PERMISSIONS
@cindex mode
@display
PERMISSIONS
- FILE='filename'
+ FILE='file-name'
/PERMISSIONS = @{READONLY,WRITEABLE@}.
@end display
If you set the permission to WRITEABLE, then the file will become
writeable by you; the permissions afforded to others will be
unchanged.
+This command cannot be used if the SAFER setting is active.
-@node QUIT, SET, PERMISSIONS, Utilities
-@section QUIT
-@vindex QUIT
-
-@display
-Two possible syntaxes:
- QUIT.
- EXIT.
-@end display
-
-@cmd{QUIT} terminates the current PSPP session and returns control
-to the operating system.
-
-This command is not valid within a command file.
-
-@node SET, SHOW, QUIT, Utilities
+@node SET
@section SET
@vindex SET
/BLANKS=@{SYSMIS,'.',number@}
/DECIMAL=@{DOT,COMMA@}
/FORMAT=fmt_spec
+ /EPOCH=@{AUTOMATIC,year@}
+ /RIB=@{NATIVE,MSBFIRST,LSBFIRST,VAX@}
+ /RRB=@{NATIVE,ISL,ISB,IDL,IDB,VF,VD,VG,ZS,ZL@}
(program input)
/ENDCMD='.'
/MXERRS=max_errs
/MXWARNS=max_warnings
/PROMPT='prompt'
- /VIEWLENGTH=@{MINIMUM,MEDIAN,MAXIMUM,n_lines@}
- /VIEWWIDTH=n_characters
+ /WORKSPACE=workspace_size
(program execution)
/MEXPAND=@{ON,OFF@}
/CC@{A,B,C,D,E@}=@{'npre,pre,suf,nsuf','npre.pre.suf.nsuf'@}
/DECIMAL=@{DOT,COMMA@}
/FORMAT=fmt_spec
+ /WIB=@{NATIVE,MSBFIRST,LSBFIRST,VAX@}
+ /WRB=@{NATIVE,ISL,ISB,IDL,IDB,VF,VD,VG,ZS,ZL@}
(output routing)
/ECHO=@{ON,OFF@}
/PRINTBACK=@{ON,OFF@}
/RESULTS=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}
-(output activation)
- /LISTING=@{ON,OFF@}
- /PRINTER=@{ON,OFF@}
- /SCREEN=@{ON,OFF@}
-
(output driver options)
/HEADERS=@{NO,YES,BLANK@}
/LENGTH=@{NONE,length_in_lines@}
- /LISTING=filename
+ /LISTING=@{ON,OFF,'file-name'@}
/MORE=@{ON,OFF@}
- /PAGER=@{OFF,"pager_name"@}
/WIDTH=@{NARROW,WIDTH,n_characters@}
(logging)
- /JOURNAL=@{ON,OFF@} [filename]
- /LOG=@{ON,OFF@} [filename]
+ /JOURNAL=@{ON,OFF@} ['file-name']
(system files)
/COMPRESSION=@{ON,OFF@}
/SCOMPRESSION=@{ON,OFF@}
-(security)
+(miscellaneous)
/SAFER=ON
+ /LOCALE='string'
+
(obsolete settings accepted for compatibility, but ignored)
- /AUTOMENU=@{ON,OFF@}
- /BEEP=@{ON,OFF@}
- /BLOCK='c'
/BOXSTRING=@{'xxx','xxxxxxxxxxx'@}
/CASE=@{UPPER,UPLOW@}
- /COLOR=@dots{}
/CPI=cpi_value
/DISK=@{ON,OFF@}
- /EJECT=@{ON,OFF@}
- /HELPWINDOWS=@{ON,OFF@}
/HIGHRES=@{ON,OFF@}
/HISTOGRAM='c'
/LOWRES=@{AUTO,ON,OFF@}
/LPI=lpi_value
/MENUS=@{STANDARD,EXTENDED@}
/MXMEMORY=max_memory
- /PTRANSLATE=@{ON,OFF@}
- /RCOLORS=@dots{}
- /RUNREVIEW=@{AUTO,MANUAL@}
/SCRIPTTAB='c'
/TB1=@{'xxx','xxxxxxxxxxx'@}
/TBFONTS='string'
- /WORKDEV=drive_letter
- /WORKSPACE=workspace_size
/XSORT=@{YES,NO@}
@end display
@table @asis
@item BLANKS
+@anchor{SET BLANKS}
This is the value assigned to an item data item that is empty or
-contains only whitespace. An argument of SYSMIS or '.' will cause the
+contains only white space. An argument of SYSMIS or '.' will cause the
system-missing value to be assigned to null items. This is the
default. Any real value may be assigned.
@item DECIMAL
-The default DOT setting causes the decimal point character to be
-@samp{.}. A setting of COMMA causes the decimal point character to be
-@samp{,}.
+@anchor{SET DECIMAL}
+This value may be set to DOT or COMMA.
+Setting it to DOT causes the decimal point character to be
+@samp{.} and the grouping character to be @samp{,}.
+Setting it to COMMA
+causes the decimal point character to be @samp{,} and the grouping
+character to be @samp{.}.
+The default value is determined from the system locale.
@item FORMAT
Allows the default numeric input/output format to be specified. The
-default is F8.2. @xref{Input/Output Formats}.
+default is F8.2. @xref{Input and Output Formats}.
+
+@item EPOCH
+@anchor{SET EPOCH}
+Specifies the range of years used when a 2-digit year is read from a
+data file or used in a date construction expression (@pxref{Date
+Construction}). If a 4-digit year is specified for the epoch, then
+2-digit years are interpreted starting from that year, known as the
+epoch. If AUTOMATIC (the default) is specified, then the epoch begins
+69 years before the current date.
+
+@item RIB
+@anchor{SET RIB}
+
+PSPP extension to set the byte ordering (endianness) used for reading
+data in IB or PIB format (@pxref{Binary and Hexadecimal Numeric
+Formats}). In MSBFIRST ordering, the most-significant byte appears at
+the left end of a IB or PIB field. In LSBFIRST ordering, the
+least-significant byte appears at the left end. VAX ordering is like
+MSBFIRST, except that each pair of bytes is in reverse order. NATIVE,
+the default, is equivalent to MSBFIRST or LSBFIRST depending on the
+native format of the machine running PSPP.
+
+@item RRB
+@anchor{SET RRB}
+
+PSPP extension to set the floating-point format used for reading data in
+RB format (@pxref{Binary and Hexadecimal Numeric Formats}). The
+possibilities are:
+
+@table @asis
+@item NATIVE
+The native format of the machine running PSPP. Equivalent to either IDL
+or IDB.
+
+@item ISL
+32-bit IEEE 754 single-precision floating point, in little-endian byte
+order.
+
+@item ISB
+32-bit IEEE 754 single-precision floating point, in big-endian byte
+order.
+
+@item IDL
+64-bit IEEE 754 double-precision floating point, in little-endian byte
+order.
+
+@item IDB
+64-bit IEEE 754 double-precision floating point, in big-endian byte
+order.
+
+@item VF
+32-bit VAX F format, in VAX-endian byte order.
+
+@item VD
+64-bit VAX D format, in VAX-endian byte order.
+
+@item VG
+64-bit VAX G format, in VAX-endian byte order.
+
+@item ZS
+32-bit IBM Z architecture short format hexadecimal floating point, in
+big-endian byte order.
+
+@item ZL
+64-bit IBM Z architecture long format hexadecimal floating point, in
+big-endian byte order.
+
+Z architecture also supports IEEE 754 floating point. The ZS and ZL
+formats are only for use with very old input files.
+@end table
+The default is NATIVE.
@end table
Program input subcommands affect the way that programs are parsed when
-they are typed interactively or run from a script. They are
+they are typed interactively or run from a command file. They are
@table @asis
@item ENDCMD
@item PROMPT
The command prompt. The default is @samp{PSPP> }.
-
-@item VIEWLENGTH
-The length of the screen in lines. MINIMUM means 25 lines, MEDIAN and
-MAXIMUM mean 43 lines. Otherwise specify the number of lines. Normally
-PSPP should auto-detect your screen size so this shouldn't have to be
-used.
-
-@item VIEWWIDTH
-The width of the screen in characters. Normally 80 or 132.
@end table
Program execution subcommands control the way that PSPP commands
@item UNDEFINED
Currently not used.
+
+@item WORKSPACE
+The maximum amount of memory that PSPP will use to store data being processed.
+If memory in excess of the workspace size is required, then PSPP will start
+to use temporary files to store the data.
+Setting a higher value will, in general, mean procedures will run faster,
+but may cause other applications to run slower.
+On platforms without virtual memory management, setting a very large workspace
+may cause PSPP to abort.
+@cindex workspace
+@cindex memory, amount used to store cases
@end table
Data output subcommands affect the format of output data. These
@itemx CCC
@itemx CCD
@itemx CCE
-Set up custom currency formats. The argument is a string which must
-contain exactly three commas or exactly three periods. If commas, then
-the grouping character for the currency format is @samp{,}, and the
-decimal point character is @samp{.}; if periods, then the situation is
-reversed.
-
-The commas or periods divide the string into four fields, which are, in
-order, the negative prefix, prefix, suffix, and negative suffix. When a
-value is formatted using the custom currency format, the prefix precedes
-the value formatted and the suffix follows it. In addition, if the
-value is negative, the negative prefix precedes the prefix and the
-negative suffix follows the suffix.
+@anchor{CCx Settings}
+
+Set up custom currency formats. @xref{Custom Currency Formats}, for
+details.
@item DECIMAL
The default DOT setting causes the decimal point character to be
@item FORMAT
Allows the default numeric input/output format to be specified. The
-default is F8.2. @xref{Input/Output Formats}.
+default is F8.2. @xref{Input and Output Formats}.
+
+@item WIB
+@anchor{SET WIB}
+
+PSPP extension to set the byte ordering (endianness) used for writing
+data in IB or PIB format (@pxref{Binary and Hexadecimal Numeric
+Formats}). In MSBFIRST ordering, the most-significant byte appears at
+the left end of a IB or PIB field. In LSBFIRST ordering, the
+least-significant byte appears at the left end. VAX ordering is like
+MSBFIRST, except that each pair of bytes is in reverse order. NATIVE,
+the default, is equivalent to MSBFIRST or LSBFIRST depending on the
+native format of the machine running PSPP.
+
+@item WRB
+@anchor{SET WRB}
+
+PSPP extension to set the floating-point format used for writing data in
+RB format (@pxref{Binary and Hexadecimal Numeric Formats}). The choices
+are the same as SET RIB. The default is NATIVE.
@end table
Output routing subcommands affect where the output of transformations
Currently not used.
@end table
-Output activation subcommands affect whether output devices of
-particular types are enabled. These subcommands are
-
-@table @asis
-@item LISTING
-Enable or disable listing devices.
-
-@item PRINTER
-Enable or disable printer devices.
-
-@item SCREEN
-Enable or disable screen devices.
-@end table
-
Output driver option subcommands affect output drivers' settings. These
subcommands are
@itemx MORE
@itemx PAGER
@itemx WIDTH
-Currently not used.
@end table
+@cindex headers
+@cindex length
+@cindex listing
+@cindex more
+@cindex pager
+@cindex width
+
+
Logging subcommands affect logging of commands executed to external
files. These subcommands are
@table @asis
@item JOURNAL
-@item LOG
-Not currently used.
+@itemx LOG
+These subcommands, which are synonyms, control the journal. The
+default is ON, which causes commands entered interactively to be
+written to the journal file. Commands included from syntax files that
+are included interactively and error messages printed by PSPP are also
+written to the journal file, prefixed by @samp{>}. OFF disables use
+of the journal.
+
+The journal is named @file{pspp.jnl} by default. A different name may
+be specified.
@end table
System file subcommands affect the default format of system files
@table @asis
@item SAFER
-When set, this setting cannot ever be reset, for obvious security
-reasons. Setting this option disables the following operations:
+Setting this option disables the following operations:
@itemize @bullet
@item
@item
The HOST command.
@item
-Pipe filenames (filenames beginning or ending with @samp{|}).
+The PERMISSIONS command.
+@item
+Pipes (file names beginning or ending with @samp{|}).
@end itemize
Be aware that this setting does not guarantee safety (commands can still
overwrite files, for instance) but it is an improvement.
+When set, this setting cannot be reset during the same session, for
+obvious security reasons.
+
+@item LOCALE
+@cindex locale
+@cindex encoding, characters
+This item is used to set the default character encoding.
+The encoding may be specified either as an encoding name or alias
+(see @url{http://www.iana.org/assignments/character-sets}), or
+as a locale name.
+If given as a locale name, only the character encoding of the
+locale is relevant.
+
+System files written by PSPP will use this encoding.
+System files read by PSPP, for which the encoding is unknown, will be
+interpreted using this encoding.
+
+The full list of valid encodings and locale names/alias are operating system
+dependent.
+The following are all examples of acceptable syntax on common GNU/Linux
+systems.
+@example
+
+SET LOCALE='iso-8859-1'.
+
+SET LOCALE='ru_RU.cp1251'.
+
+SET LOCALE='japanese'.
+
+@end example
+
+Contrary to the intuition, this command does not affect any aspect
+of the system's locale.
@end table
-@node SHOW, SUBTITLE, SET, Utilities
+@node SHOW
@comment node-name, next, previous, up
@section SHOW
@vindex SHOW
@display
SHOW
- /@var{subcommand}
-
+ [ALL]
+ [BLANKS]
+ [CC]
+ [CCA]
+ [CCB]
+ [CCC]
+ [CCD]
+ [CCE]
+ [COPYING]
+ [DECIMALS]
+ [ENDCMD]
+ [FORMAT]
+ [LENGTH]
+ [MXERRS]
+ [MXLOOPS]
+ [MXWARNS]
+ [SCOMPRESSION]
+ [UNDEFINED]
+ [WARRANTY]
+ [WEIGHT]
+ [WIDTH]
@end display
-@cmd{SHOW} can be used to display the current state of PSPP's
-execution parameters. All of the parameters which can be changed
-using @code{SET} @xref{SET}, can be examined using @cmd{SHOW}, by
-using a subcommand with the same name.
-In addition, @code{SHOW} supports the following subcommands:
+@cmd{SHOW} can be used to display the current state of PSPP's execution
+parameters. Parameters that can be changed using @cmd{SET}
+(@pxref{SET}), can be examined using @cmd{SHOW} using the subcommand
+with the same name. @code{SHOW} supports the following additional
+subcommands:
@table @code
+@item ALL
+Show all settings.
+@item CC
+Show all custom currency settings (CCA through CCE).
@item WARRANTY
Show details of the lack of warranty for PSPP.
@item COPYING
-Display the terms of PSPP's copyright licence @ref{License}.
+Display the terms of PSPP's copyright licence (@pxref{License}).
@end table
+Specifying @cmd{SHOW} without any subcommands is equivalent to SHOW ALL.
-
-@node SUBTITLE, TITLE, SHOW, Utilities
+@node SUBTITLE
@section SUBTITLE
@vindex SUBTITLE
not require quotes is now obsolete. If it is used then the subtitle is
converted to all uppercase.
-@node TITLE, , SUBTITLE, Utilities
+@node TITLE
@section TITLE
@vindex TITLE
Specify a title as a string in quotes. The alternate syntax that did
not require quotes is now obsolete. If it is used then the title is
converted to all uppercase.
-@setfilename ignored
projects / pspp-builds.git / blobdiff