-@node Utilities, Not Implemented, Statistics, Top
+@node Utilities
@chapter Utilities
Commands that don't fit any other category are placed here.
@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.
* 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.
* SET:: Adjust PSPP runtime parameters.
* SHOW:: Display runtime parameters.
* TITLE:: Provide a document title.
@end menu
-@node ADD DOCUMENT, COMMENT, Utilities, Utilities
+@node ADD DOCUMENT
@comment node-name, next, previous, up
@section ADD DOCUMENT
@vindex ADD DOCUMENT
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, DOCUMENT, ADD DOCUMENT, Utilities
+@node COMMENT
@section COMMENT
@vindex COMMENT
@vindex *
-@node DOCUMENT, DISPLAY DOCUMENTS, COMMENT, Utilities
+@node DOCUMENT
@section DOCUMENT
@vindex DOCUMENT
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
This command is a PSPP extension.
-@node DROP DOCUMENTS, ECHO, DISPLAY FILE LABEL, Utilities
+@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, ERASE, DROP DOCUMENTS, Utilities
+@node ECHO
@section ECHO
@vindex ECHO
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, ECHO, 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.
-@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 'file-name'.
- @@file-name.
+ 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, SET, 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
This command cannot be used if the SAFER setting is active.
-@node SET, SHOW, PERMISSIONS, Utilities
+@node SET
@section SET
@vindex SET
/MXERRS=max_errs
/MXWARNS=max_warnings
/PROMPT='prompt'
+ /WORKSPACE=workspace_size
(program execution)
/MEXPAND=@{ON,OFF@}
/COMPRESSION=@{ON,OFF@}
/SCOMPRESSION=@{ON,OFF@}
-(security)
+(miscellaneous)
/SAFER=ON
+ /LOCALE='string'
+
(obsolete settings accepted for compatibility, but ignored)
/BOXSTRING=@{'xxx','xxxxxxxxxxx'@}
/SCRIPTTAB='c'
/TB1=@{'xxx','xxxxxxxxxxx'@}
/TBFONTS='string'
- /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 white space. An argument of SYSMIS or '.' will cause the
system-missing value to be assigned to null items. This is the
@item DECIMAL
@anchor{SET DECIMAL}
-The default DOT setting causes the decimal point character to be
-@samp{.} and the grouping character to be @samp{,}. A setting of COMMA
+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
@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
@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
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
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