X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=doc%2Futilities.texi;h=6882aa2165f525aa2b12ae466da5d762eabe95af;hb=163b1639eab9b48eab64752205d75f951547b5c7;hp=1d279f57ed37a2fc9d2037365fda994dec5dc4c0;hpb=b016884ff112ca57e89f9d0298eb70079fece20d;p=pspp-builds.git diff --git a/doc/utilities.texi b/doc/utilities.texi index 1d279f57..6882aa21 100644 --- a/doc/utilities.texi +++ b/doc/utilities.texi @@ -1,4 +1,4 @@ -@node Utilities, Not Implemented, Statistics, Top +@node Utilities @chapter Utilities Commands that don't fit any other category are placed here. @@ -9,26 +9,61 @@ 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. -* 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 * @@ -45,12 +80,14 @@ 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, 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 @@ -59,12 +96,14 @@ 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 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 @@ -76,7 +115,7 @@ 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 @@ -88,7 +127,9 @@ 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 @@ -102,8 +143,17 @@ 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, EXECUTE, DROP DOCUMENTS, Utilities +@node ERASE @comment node-name, next, previous, up @section ERASE @vindex ERASE @@ -117,7 +167,7 @@ file_name must be quoted. This command cannot be used if the SAFER setting is active. -@node EXECUTE, FILE LABEL, ERASE, Utilities +@node EXECUTE @section EXECUTE @vindex EXECUTE @@ -128,7 +178,7 @@ 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 @@ -143,7 +193,7 @@ created during this PSPP run. 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 @@ -154,9 +204,7 @@ 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 @@ -170,26 +218,73 @@ to the operating system. 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 @@ -198,7 +293,7 @@ memory. @display PERMISSIONS - FILE='filename' + FILE='file-name' /PERMISSIONS = @{READONLY,WRITEABLE@}. @end display @@ -210,24 +305,10 @@ 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 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 @@ -238,6 +319,9 @@ 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='.' @@ -250,8 +334,7 @@ SET /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@} @@ -266,6 +349,8 @@ SET /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@} @@ -275,55 +360,39 @@ SET /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 @@ -339,23 +408,100 @@ 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 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 @@ -392,15 +538,6 @@ current command file. The default is 100. @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 @@ -422,6 +559,17 @@ 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 @@ -433,18 +581,10 @@ subcommands are @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 @@ -453,7 +593,26 @@ 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 @@ -473,20 +632,6 @@ from command files. The default is OFF. 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 @@ -497,16 +642,31 @@ 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 @@ -526,8 +686,7 @@ perform. The security subcommands are @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 @@ -535,40 +694,98 @@ The ERASE command. @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 @@ -586,7 +803,7 @@ 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, , SUBTITLE, Utilities +@node TITLE @section TITLE @vindex TITLE @@ -603,4 +820,3 @@ 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. -@setfilename ignored