DEBUG EVALUATE: Eliminate lexical corner case, rewrite tests in Autotest.

[pspp] / doc / utilities.texi

@node Utilities
@chapter Utilities

Commands that don't fit any other category are placed here.

Most of these commands are not affected by commands like @cmd{IF} and
@cmd{LOOP}:
they take effect only once, unconditionally, at the time that they are
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.
* SET::                         Adjust PSPP runtime parameters.
* SHOW::                        Display runtime parameters.
* SUBTITLE::                    Provide a document subtitle.
* TITLE::                       Provide a document title.
@end menu

@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 *

@display 
Two possibles syntaxes:
        COMMENT comment text @dots{} .
        *comment text @dots{} .
@end display

@cmd{COMMENT} is ignored.  It is used to provide information to
the author and other readers of the PSPP syntax file.  

@cmd{COMMENT} can extend over any number of lines.  Don't forget to
terminate it with a dot or a blank line.



@node DOCUMENT
@section DOCUMENT
@vindex DOCUMENT

@display
DOCUMENT @var{documentary_text}.
@end display

@cmd{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}.

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
@section DISPLAY DOCUMENTS
@vindex DISPLAY DOCUMENTS

@display
DISPLAY DOCUMENTS.
@end display

@cmd{DISPLAY DOCUMENTS} displays the documents in the active file.  Each
document is preceded by a line giving the time and date that it was
added.  @xref{DOCUMENT}.

@node DISPLAY FILE LABEL
@section DISPLAY FILE LABEL
@vindex DISPLAY FILE LABEL

@display
DISPLAY FILE LABEL.
@end display

@cmd{DISPLAY FILE LABEL} displays the file label contained in the
active file,
if any.  @xref{FILE LABEL}.

This command is a PSPP extension.

@node DROP DOCUMENTS
@section DROP DOCUMENTS
@vindex DROP DOCUMENTS

@display
DROP DOCUMENTS.
@end display

@cmd{DROP DOCUMENTS} removes all documents from the active file.
New documents can be added with @cmd{DOCUMENT} (@pxref{DOCUMENT}).

@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
@comment  node-name,  next,  previous,  up
@section ERASE
@vindex ERASE

@display
ERASE FILE file_name.
@end display

@cmd{ERASE FILE} deletes a file from the local filesystem.
file_name must be quoted.
This command cannot be used if the SAFER setting is active.


@node EXECUTE
@section EXECUTE
@vindex EXECUTE

@display
EXECUTE.
@end display

@cmd{EXECUTE} causes the active file to be read and all pending
transformations to be executed.

@node FILE LABEL
@section FILE LABEL
@vindex FILE LABEL

@display
FILE LABEL file_label.
@end display

@cmd{FILE LABEL} provides a title for the active file.  This
title will be saved into system files and portable files that are
created during this PSPP run.

file_label need not be quoted.  If quotes are
included, they become part of the file label.

@node FINISH
@section FINISH
@vindex FINISH

@display
FINISH.
@end display

@cmd{FINISH} terminates the current PSPP session and returns
control to the operating system.

@node HOST
@comment  node-name,  next,  previous,  up
@section HOST
@vindex HOST

@display
HOST.
@end display

@cmd{HOST} suspends the current PSPP session and temporarily returns control 
to the operating system.
This command cannot be used if the SAFER setting is active.


@node INCLUDE
@section INCLUDE
@vindex INCLUDE

@display
        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.


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
@cindex file mode
@cindex changing file permissions

@display
PERMISSIONS
        FILE='file-name'
        /PERMISSIONS = @{READONLY,WRITEABLE@}.
@end display

@cmd{PERMISSIONS} changes the permissions of a file.  
There is one mandatory subcommand which specifies the permissions to
which the file should be changed.  
If you set a file's  permission  to READONLY, then the file will become
unwritable either by you or anyone else on the system.
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 SET
@section SET
@vindex SET

@display
SET

(data input)
        /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='.'
        /NULLINE=@{ON,OFF@}

(interaction)
        /CPROMPT='cprompt_string'
        /DPROMPT='dprompt_string'
        /MXERRS=max_errs
        /MXWARNS=max_warnings
        /PROMPT='prompt'
        /WORKSPACE=workspace_size

(program execution)
        /MEXPAND=@{ON,OFF@}
        /MITERATE=max_iterations
        /MNEST=max_nest
        /MPRINT=@{ON,OFF@}
        /MXLOOPS=max_loops
        /SEED=@{RANDOM,seed_value@}
        /UNDEFINED=@{WARN,NOWARN@}

(data output)
        /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)
        /ERRORS=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}
        /MESSAGES=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}
        /PRINTBACK=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}
        /RESULTS=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}

(output driver options)
        /HEADERS=@{NO,YES,BLANK@}
        /LENGTH=@{NONE,length_in_lines@}
        /MORE=@{ON,OFF@}
        /WIDTH=@{NARROW,WIDTH,n_characters@}

(logging)
        /JOURNAL=@{ON,OFF@} ['file-name']

(system files)
        /COMPRESSION=@{ON,OFF@}
        /SCOMPRESSION=@{ON,OFF@}

(miscellaneous)
        /SAFER=ON
        /LOCALE='string'


(obsolete settings accepted for compatibility, but ignored)
        /BOXSTRING=@{'xxx','xxxxxxxxxxx'@}
        /CASE=@{UPPER,UPLOW@}
        /CPI=cpi_value
        /HIGHRES=@{ON,OFF@}
        /HISTOGRAM='c'
        /LOWRES=@{AUTO,ON,OFF@}
        /LPI=lpi_value
        /MENUS=@{STANDARD,EXTENDED@}
        /MXMEMORY=max_memory
        /SCRIPTTAB='c'
        /TB1=@{'xxx','xxxxxxxxxxx'@}
        /TBFONTS='string'
        /XSORT=@{YES,NO@}
@end display

@cmd{SET} allows the user to adjust several parameters relating to
PSPP's execution.  Since there are many subcommands to this command, its
subcommands will be examined in groups.

On subcommands that take boolean values, ON and YES are synonym, and
as are OFF and NO, when used as subcommand values.

The data input subcommands affect the way that data is read from data
files.  The data input subcommands are

@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
default.  Any real value may be assigned.

@item DECIMAL
@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 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 command file.  They are

@table @asis
@item ENDCMD
This is a single character indicating the end of a command.  The default
is @samp{.}.  Don't change this.

@item NULLINE
Whether a blank line is interpreted as ending the current command.  The
default is ON.
@end table

Interaction subcommands affect the way that PSPP interacts with an
online user.  The interaction subcommands are

@table @asis
@item CPROMPT
The command continuation prompt.  The default is @samp{    > }.

@item DPROMPT
Prompt used when expecting data input within @cmd{BEGIN DATA} (@pxref{BEGIN
DATA}).  The default is @samp{data> }.

@item MXERRS
The maximum number of errors before PSPP halts processing of the current
command file.  The default is 50.

@item MXWARNS
The maximum number of warnings + errors before PSPP halts processing the
current command file.  The default is 100.

@item PROMPT
The command prompt.  The default is @samp{PSPP> }.
@end table

Program execution subcommands control the way that PSPP commands
execute.  The program execution subcommands are

@table @asis
@item MEXPAND
@itemx MITERATE
@itemx MNEST
@itemx MPRINT
Currently not used.

@item MXLOOPS
The maximum number of iterations for an uncontrolled loop (@pxref{LOOP}).

@item SEED
The initial pseudo-random number seed.  Set to a real number or to
RANDOM, which will obtain an initial seed from the current time of day.

@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
subcommands are

@table @asis
@item CCA
@itemx CCB
@itemx CCC
@itemx CCD
@itemx CCE
@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
@samp{.}.  A setting of COMMA causes the decimal point character to be
@samp{,}.

@item FORMAT
Allows the default numeric input/output format to be specified.  The
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

In the PSPP text-based interface, the output routing subcommands
affect where output is sent.  The following values are allowed for
each of these subcommands:

@table @asis
@item OFF
@item NONE
Discard this kind of output.

@item TERMINAL
Write this output to the terminal, but not to listing files and other
output devices.

@item LISTING
Write this output to listing files and other output devices, but not
to the terminal.

@item ON
@itemx BOTH
Write this type of output to all output devices.
@end table

These output routing subcommands are:

@table @asis
@item ERRORS
Applies to error and warning messages.  The default is BOTH.

@itemx MESSAGES
Applies to notes.  The default is BOTH.

@itemx PRINTBACK
Determines whether the syntax used for input is printed back as part
of the output.  The default is NONE.

@itemx RESULTS
Applies to everything not in one of the above categories, such as the
results of statistical procedures.  The default is BOTH.
@end table

These subcommands have no effect on output in the PSPP GUI
environment.

Output driver option subcommands affect output drivers' settings.  These
subcommands are

@table @asis
@item HEADERS
@itemx LENGTH
@itemx MORE
@itemx PAGER 
@itemx WIDTH
@end table

@cindex headers
@cindex length
@cindex more
@cindex pager 
@cindex width


Logging subcommands affect logging of commands executed to external
files.  These subcommands are

@table @asis
@item JOURNAL
@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
produced by PSPP.  These subcommands are

@table @asis
@item COMPRESSION
Not currently used.

@item SCOMPRESSION
Whether system files created by @cmd{SAVE} or @cmd{XSAVE} are
compressed by default.  The default is ON.
@end table

Security subcommands affect the operations that commands are allowed to
perform.  The security subcommands are

@table @asis
@item SAFER
Setting this option disables the following operations:

@itemize @bullet
@item
The ERASE command.
@item
The HOST command.
@item
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
@comment  node-name,  next,  previous,  up
@section SHOW
@vindex SHOW

@display
SHOW
        [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.  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 (@pxref{License}).
@end table

Specifying @cmd{SHOW} without any subcommands is equivalent to SHOW ALL.

@node SUBTITLE
@section SUBTITLE
@vindex SUBTITLE

@display
SUBTITLE 'subtitle_string'.
  or
SUBTITLE subtitle_string.
@end display

@cmd{SUBTITLE} provides a subtitle to a particular PSPP
run.  This subtitle appears at the top of each output page below the
title, if headers are enabled on the output device.

Specify a subtitle as a string in quotes.  The alternate syntax that did
not require quotes is now obsolete.  If it is used then the subtitle is
converted to all uppercase.

@node TITLE
@section TITLE
@vindex TITLE

@display
TITLE 'title_string'.
  or
TITLE title_string.
@end display

@cmd{TITLE} provides a title to a particular PSPP run.
This title appears at the top of each output page, if headers are enabled
on the output device.

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.