Utilities
*********

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

Most of these commands are not affected by commands like IF and LOOP: they take effect only once, unconditionally, at the time that they are encountered in the input.

ADD DOCUMENT
============

     ADD DOCUMENT
         'line one' 'line two' ... 'last line' .

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 SYSFILE INFO or DISPLAY DOCUMENTS.  They can be removed from the active file with DROP DOCUMENTS.

Each line of documentary text must be enclosed in quotation marks, and may not be more than 80 bytes long. See DOCUMENT.

CD
==

     CD 'new directory' .

CD changes the current directory.  The new directory will become that specified by the command.

COMMENT
=======

     Two possibles syntaxes:
             COMMENT comment text ... .
             *comment text ... .

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

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

DOCUMENT
========

     DOCUMENT DOCUMENTARY_TEXT.

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 SYSFILE INFO or DISPLAY DOCUMENTS.  They can be removed from the active file with DROP DOCUMENTS.

Specify the 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. See ADD DOCUMENT.

DISPLAY DOCUMENTS
=================

     DISPLAY DOCUMENTS.

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.  See DOCUMENT.

DISPLAY FILE LABEL
==================

     DISPLAY FILE LABEL.

DISPLAY FILE LABEL displays the file label contained in the active file, if any.  See FILE LABEL.

This command is a PSPP extension.

DROP DOCUMENTS
==============

     DROP DOCUMENTS.

DROP DOCUMENTS removes all documents from the active file. New documents can be added with DOCUMENT (see DOCUMENT).

DROP DOCUMENTS changes only the active file.  It does not modify any system files stored on disk.

ECHO
====

     ECHO 'arbitrary text' .

Use ECHO to write arbitrary text to the output stream. The text should be enclosed in quotation marks following the normal rules for string tokens (see Tokens).

ERASE
=====

     ERASE FILE file_name.

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.

EXECUTE
=======

     EXECUTE.

EXECUTE causes the active file to be read and all pending transformations to be executed.

FILE LABEL
==========

     FILE LABEL file_label.

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.

FINISH
======

     FINISH.

FINISH terminates the current PSPP session and returns control to the operating system.

HOST
====

     HOST.

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.

INCLUDE
=======

             INCLUDE [FILE=]'file-name'.

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 INSERT command (see INSERT) may be used instead of INCLUDE if you require more flexible options. The syntax

     INCLUDE FILE=FILE-NAME.

functions identically to

     INSERT FILE=FILE-NAME ERROR=STOP CD=NO SYNTAX=BATCH.

INSERT
======

          INSERT [FILE=]'file-name'
             [CD={NO,YES}]
             [ERROR={CONTINUE,STOP}]
             [SYNTAX={BATCH,INTERACTIVE}].

INSERT is similar to INCLUDE (see 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 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 CD=NO. Note that this directory will remain current until it is changed explicitly (with the CD command, or a subsequent INSERT command with the CD=YES option). It will not revert to its original setting even after the included file is finished processing.

If 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 ERROR=CONTINUE.

If SYNTAX=INTERACTIVE is specified then the syntax contained in the included file must conform to interactive syntax conventions. See Syntax Variants. The default setting is SYNTAX=BATCH.

PERMISSIONS
===========

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

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.

SET
===

     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'
             /ERRORBREAK={OFF,ON}
             /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)
             /ECHO={ON,OFF}
             /ERRORS={ON,OFF,TERMINAL,LISTING,BOTH,NONE}
             /INCLUDE={ON,OFF}
             /MESSAGES={ON,OFF,TERMINAL,LISTING,BOTH,NONE}
             /PRINTBACK={ON,OFF}
             /RESULTS={ON,OFF,TERMINAL,LISTING,BOTH,NONE}

     (output driver options)
             /HEADERS={NO,YES,BLANK}
             /LENGTH={NONE,length_in_lines}
             /LISTING={ON,OFF,'file-name'}
             /MORE={ON,OFF}
             /WIDTH={NARROW,WIDTH,n_characters}

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

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

     (security)
             /SAFER=ON

     (obsolete settings accepted for compatibility, but ignored)
             /BOXSTRING={'xxx','xxxxxxxxxxx'}
             /CASE={UPPER,UPLOW}
             /CPI=cpi_value
             /DISK={ON,OFF}
             /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}

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

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.

DECIMAL
     The default DOT setting causes the decimal point character to be . and the grouping character to be ,.  A setting of COMMA causes the decimal point character to be , and the grouping character to be ..

FORMAT
     Allows the default numeric input/output format to be specified.  The default is F8.2.  See Input and Output Formats.

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 (see 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.

RIB

     PSPP extension to set the byte ordering (endianness) used for reading data in IB or PIB format (see 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.

RRB

     PSPP extension to set the floating-point format used for reading data in RB format (see Binary and Hexadecimal Numeric Formats).  The possibilities are:

     NATIVE
          The native format of the machine running PSPP.  Equivalent to either IDL or IDB.

     ISL
          32-bit IEEE 754 single-precision floating point, in little-endian byte order.

     ISB
          32-bit IEEE 754 single-precision floating point, in big-endian byte order.

     IDL
          64-bit IEEE 754 double-precision floating point, in little-endian byte order.

     IDB
          64-bit IEEE 754 double-precision floating point, in big-endian byte order.

     VF
          32-bit VAX F format, in VAX-endian byte order.

     VD
          64-bit VAX D format, in VAX-endian byte order.

     VG
          64-bit VAX G format, in VAX-endian byte order.

     ZS
          32-bit IBM Z architecture short format hexadecimal floating point, in big-endian byte order.

     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.

     The default is NATIVE.

Program input subcommands affect the way that programs are parsed when they are typed interactively or run from a command file.  They are

ENDCMD
     This is a single character indicating the end of a command.  The default is ..  Don't change this.

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

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

CPROMPT
     The command continuation prompt.  The default is     > .

DPROMPT
     Prompt used when expecting data input within BEGIN DATA (see BEGIN DATA).  The default is data> .

ERRORBREAK
     Whether an error causes PSPP to stop processing the current command file after finishing the current command.  The default is OFF.

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

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

PROMPT
     The command prompt.  The default is PSPP> .

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

MEXPAND
MITERATE
MNEST
MPRINT
     Currently not used.

MXLOOPS
     The maximum number of iterations for an uncontrolled loop (see LOOP).

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.

UNDEFINED
     Currently not used.

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.

Data output subcommands affect the format of output data.  These subcommands are

CCA
CCB
CCC
CCD
CCE

     Set up custom currency formats.  See Custom Currency Formats, for details.

DECIMAL
     The default DOT setting causes the decimal point character to be ..  A setting of COMMA causes the decimal point character to be ,.

FORMAT
     Allows the default numeric input/output format to be specified.  The default is F8.2.  See Input and Output Formats.

WIB

     PSPP extension to set the byte ordering (endianness) used for writing data in IB or PIB format (see 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.

WRB

     PSPP extension to set the floating-point format used for writing data in RB format (see Binary and Hexadecimal Numeric Formats).  The choices are the same as SET RIB.  The default is NATIVE.

Output routing subcommands affect where the output of transformations and procedures is sent.  These subcommands are

ECHO

     If turned on, commands are written to the listing file as they are read from command files.  The default is OFF.

ERRORS
INCLUDE
MESSAGES

PRINTBACK

RESULTS
     Currently not used.

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

HEADERS
LENGTH
LISTING
MORE
PAGER
WIDTH

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

JOURNAL
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 >.  OFF disables use of the journal.

     The journal is named pspp.jnl by default.  A different name may be specified.

System file subcommands affect the default format of system files produced by PSPP.  These subcommands are

COMPRESSION
     Not currently used.

SCOMPRESSION
     Whether system files created by SAVE or XSAVE are compressed by default.  The default is ON.

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

SAFER
     Setting this option disables the following operations:

       * The ERASE command.

       * The HOST command.

       * The PERMISSIONS command.

       * Pipes (file names beginning or ending with |).

     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.

SHOW
====

     SHOW
             [ALL]
             [BLANKS]
             [CC]
             [CCA]
             [CCB]
             [CCC]
             [CCD]
             [CCE]
             [COPYING]
             [DECIMALS]
             [ENDCMD]
             [FORMAT]
             [LENGTH]
             [MXERRS]
             [MXLOOPS]
             [MXWARNS]
             [SCOMPRESSION]
             [UNDEFINED]
             [WARRANTY]
             [WEIGHT]
             [WIDTH]

SHOW can be used to display the current state of PSPP's execution parameters.  Parameters that can be changed using SET (see SET), can be examined using SHOW using the subcommand with the same name.  SHOW supports the following additional subcommands:

ALL
     Show all settings.

CC
     Show all custom currency settings (CCA through CCE).

WARRANTY
     Show details of the lack of warranty for PSPP.

COPYING
     Display the terms of PSPP's copyright licence (see License).

Specifying SHOW without any subcommands is equivalent to SHOW ALL.

SUBTITLE
========

     SUBTITLE 'subtitle_string'.
       or
     SUBTITLE subtitle_string.

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.

TITLE
=====

     TITLE 'title_string'.
       or
     TITLE title_string.

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.