-@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
@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
obvious security reasons.
@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
projects / pspp-builds.git / blobdiff