X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=doc%2Fvariables.texi;h=c9e270bfc242b6d8fb5e5fa6df3c12d6d097e7a9;hb=HEAD;hp=8fda7c1ca191d3f24cf1c7620a7466f889e160f5;hpb=f6488be7a09e64b6def6e0af4536fbaca09e6860;p=pspp-builds.git diff --git a/doc/variables.texi b/doc/variables.texi index 8fda7c1c..c9e270bf 100644 --- a/doc/variables.texi +++ b/doc/variables.texi @@ -1,4 +1,4 @@ -@node Variable Attributes, Data Manipulation, System and Portable Files, Top +@node Variable Attributes @chapter Manipulating variables The variables in the active file dictionary are important. There are @@ -6,8 +6,8 @@ several utility functions for examining and adjusting them. @menu * ADD VALUE LABELS:: Add value labels to variables. -* DISPLAY:: Display variable names & descriptions. -* DISPLAY VECTORS:: Display a list of vectors. +* DELETE VARIABLES:: Delete variables. +* DISPLAY:: Display information about the active file. * FORMATS:: Set print and write formats. * LEAVE:: Don't clear variables between cases. * MISSING VALUES:: Set missing values for variables. @@ -17,12 +17,16 @@ several utility functions for examining and adjusting them. * RENAME VARIABLES:: Rename variables. * VALUE LABELS:: Set value labels for variables. * STRING:: Create new string variables. +* VARIABLE ATTRIBUTE:: Set custom attributes on variables. * VARIABLE LABELS:: Set variable labels for variables. +* VARIABLE ALIGNMENT:: Set the alignment for display. +* VARIABLE WIDTH:: Set the display width. +* VARIABLE LEVEL:: Set the measurement level. * VECTOR:: Declare an array of variables. * WRITE FORMATS:: Set variable write formats. @end menu -@node ADD VALUE LABELS, DISPLAY, Variable Attributes, Variable Attributes +@node ADD VALUE LABELS @section ADD VALUE LABELS @vindex ADD VALUE LABELS @@ -35,20 +39,48 @@ ADD VALUE LABELS LABELS} (@pxref{VALUE LABELS}), but it does not clear value labels from the variables before adding the ones specified. -@node DISPLAY, DISPLAY VECTORS, ADD VALUE LABELS, Variable Attributes +@node DELETE VARIABLES +@section DELETE VARIABLES +@vindex DELETE VARIABLES + +@display +DELETE VARIABLES var_list. +@end display + +@cmd{DELETE VARIABLES} deletes the specified variables from the +dictionary. It may not be used to delete all variables from the +dictionary; use @cmd{NEW FILE} to do that (@pxref{NEW FILE}). + +@cmd{DELETE VARIABLES} should not used after defining transformations +and before executing a procedure. If it is used in such a context, it +causes the data to be read. If it is used while @cmd{TEMPORARY} is in +effect, it causes the temporary transformations to become permanent. + +@node DISPLAY @section DISPLAY @vindex DISPLAY @display -DISPLAY @{NAMES,INDEX,LABELS,VARIABLES,DICTIONARY,SCRATCH@} - [SORTED] [var_list] +DISPLAY [SORTED] NAMES [[/VARIABLES=]var_list]. +DISPLAY [SORTED] INDEX [[/VARIABLES=]var_list]. +DISPLAY [SORTED] LABELS [[/VARIABLES=]var_list]. +DISPLAY [SORTED] VARIABLES [[/VARIABLES=]var_list]. +DISPLAY [SORTED] DICTIONARY [[/VARIABLES=]var_list]. +DISPLAY [SORTED] SCRATCH [[/VARIABLES=]var_list]. +DISPLAY [SORTED] ATTRIBUTES [[/VARIABLES=]var_list]. +DISPLAY [SORTED] @@ATTRIBUTES [[/VARIABLES=]var_list]. +DISPLAY [SORTED] VECTORS. @end display -@cmd{DISPLAY} displays requested information on variables. Variables can -optionally be sorted alphabetically. The entire dictionary or just -specified variables can be described. +@cmd{DISPLAY} displays information about the active file. A variety +of different forms of information can be requested. -One of the following keywords can be present: +The following keywords primarily cause information about variables to +be displayed. With these keywords, by default information is +displayed about all variable in the active file, in the order that +variables occur in the active file dictionary. The SORTED keyword +causes output to be sorted alphabetically by variable name. The +VARIABLES subcommand limits output to the specified variables. @table @asis @item NAMES @@ -70,25 +102,26 @@ Variable names, positions, print and write formats, missing values, variable labels, and value labels are displayed. @item SCRATCH -Varible names are displayed, for scratch variables only (@pxref{Scratch +Variable names are displayed, for scratch variables only (@pxref{Scratch Variables}). -@end table -If SORTED is specified, then the variables are displayed in ascending -order based on their names; otherwise, they are displayed in the order -that they occur in the active file dictionary. +@item ATTRIBUTES +Datafile and variable attributes are displayed, except that attributes +whose names begin with @code{@@} or @code{$@@} are omitted. -@node DISPLAY VECTORS, FORMATS, DISPLAY, Variable Attributes -@section DISPLAY VECTORS -@vindex DISPLAY VECTORS +@itemx @@ATTRIBUTES +All datafile and variable attributes are displayed. +@end table -@display -DISPLAY VECTORS. -@end display +With the @code{VECTOR} keyword, @cmd{DISPLAY} lists all the currently +declared vectors. If the SORTED keyword is given, the vectors are +listed in alphabetical order; otherwise, they are listed in textual +order of definition within the PSPP syntax file. -@cmd{DISPLAY VECTORS} lists all the currently declared vectors. +For related commands, see @ref{DISPLAY DOCUMENTS} and @ref{DISPLAY +FILE LABEL}. -@node FORMATS, LEAVE, DISPLAY VECTORS, Variable Attributes +@node FORMATS @section FORMATS @vindex FORMATS @@ -97,8 +130,8 @@ FORMATS var_list (fmt_spec). @end display @cmd{FORMATS} set both print and write formats for the specified -variables to the specified format specification. @xref{Input/Output -Formats}. +numeric variables to the specified format specification. +@xref{Input and Output Formats}. Specify a list of variables followed by a format specification in parentheses. The print and write formats of the specified variables @@ -110,7 +143,7 @@ delimited by a slash (@samp{/}). @cmd{FORMATS} takes effect immediately. It is not affected by conditional and looping structures such as @cmd{DO IF} or @cmd{LOOP}. -@node LEAVE, MISSING VALUES, FORMATS, Variable Attributes +@node LEAVE @section LEAVE @vindex LEAVE @@ -159,7 +192,7 @@ procedure command, because the left status of variables is reset by certain transformations---for instance, @cmd{COMPUTE} and @cmd{IF}. Left status is also reset by all procedure invocations. -@node MISSING VALUES, MODIFY VARS, LEAVE, Variable Attributes +@node MISSING VALUES @section MISSING VALUES @vindex MISSING VALUES @@ -179,9 +212,10 @@ As part of a range, LO or LOWEST may take the place of num1; HI or HIGHEST may take the place of num2. @end display -@cmd{MISSING VALUES} sets user-missing values for numeric and -short string variables. Long string variables may not have missing -values. +@cmd{MISSING VALUES} sets user-missing values for numeric and string +variables. Long string variables may have missing values, but +characters after the first 8 bytes of the missing value must be +spaces. Specify a list of variables, followed by a list of their user-missing values in parentheses. Up to three discrete values may be given, or, @@ -193,7 +227,7 @@ The @cmd{MISSING VALUES} command takes effect immediately. It is not affected by conditional and looping constructs such as @cmd{DO IF} or @cmd{LOOP}. -@node MODIFY VARS, NUMERIC, MISSING VALUES, Variable Attributes +@node MODIFY VARS @section MODIFY VARS @vindex MODIFY VARS @@ -240,7 +274,7 @@ not. @cmd{MODIFY VARS} may not be specified following @cmd{TEMPORARY} (@pxref{TEMPORARY}). -@node NUMERIC, PRINT FORMATS, MODIFY VARS, Variable Attributes +@node NUMERIC @section NUMERIC @vindex NUMERIC @@ -253,13 +287,13 @@ setting their output formats. Specify a slash (@samp{/}), followed by the names of the new numeric variables. If you wish to set their output formats, follow their names -by an output format specification in parentheses (@pxref{Input/Output +by an output format specification in parentheses (@pxref{Input and Output Formats}); otherwise, the default is F8.2. Variables created with @cmd{NUMERIC} are initialized to the system-missing value. -@node PRINT FORMATS, RENAME VARIABLES, NUMERIC, Variable Attributes +@node PRINT FORMATS @section PRINT FORMATS @vindex PRINT FORMATS @@ -268,12 +302,12 @@ PRINT FORMATS var_list (fmt_spec). @end display @cmd{PRINT FORMATS} sets the print formats for the specified -variables to the specified format specification. +numeric variables to the specified format specification. Its syntax is identical to that of @cmd{FORMATS} (@pxref{FORMATS}), but @cmd{PRINT FORMATS} sets only print formats, not write formats. -@node RENAME VARIABLES, VALUE LABELS, PRINT FORMATS, Variable Attributes +@node RENAME VARIABLES @section RENAME VARIABLES @vindex RENAME VARIABLES @@ -294,7 +328,7 @@ to be read. @cmd{RENAME VARIABLES} may not be specified following @cmd{TEMPORARY} (@pxref{TEMPORARY}). -@node VALUE LABELS, STRING, RENAME VARIABLES, Variable Attributes +@node VALUE LABELS @section VALUE LABELS @vindex VALUE LABELS @@ -309,15 +343,14 @@ stand for a long value. To set up value labels for a set of variables, specify the variable names after a slash (@samp{/}), followed by a list of values -and their associated labels, separated by spaces. Long string -variables may not be specified. +and their associated labels, separated by spaces. Before @cmd{VALUE LABELS} is executed, any existing value labels are cleared from the variables specified. Use @cmd{ADD VALUE LABELS} (@pxref{ADD VALUE LABELS}) to add value labels without clearing those already present. -@node STRING, VARIABLE LABELS, VALUE LABELS, Variable Attributes +@node STRING @section STRING @vindex STRING @@ -330,53 +363,176 @@ transformations. Specify a slash (@samp{/}), followed by the names of the string variables to create and the desired output format specification in -parentheses (@pxref{Input/Output Formats}). Variable widths are +parentheses (@pxref{Input and Output Formats}). Variable widths are implicitly derived from the specified output formats. Created variables are initialized to spaces. -@node VARIABLE LABELS, VECTOR, STRING, Variable Attributes + +@node VARIABLE ATTRIBUTE +@section VARIABLE ATTRIBUTE +@vindex VARIABLE ATTRIBUTE + +@display +VARIABLE ATTRIBUTE + VARIABLES=var_list + ATTRIBUTE=name('value') [name('value')]@dots{} + ATTRIBUTE=name@b{[}index@b{]}('value') [name@b{[}index@b{]}('value')]@dots{} + DELETE=name [name]@dots{} + DELETE=name@b{[}index@b{]} [name@b{[}index@b{]}]@dots{} +@end display + +@cmd{VARIABLE ATTRIBUTE} adds, modifies, or removes user-defined +attributes associated with variables in the active file. Custom +variable attributes are not interpreted by PSPP, but they are saved as +part of system files and may be used by other software that reads +them. + +The required VARIABLES subcommand must come first. Specify the +variables to which the following ATTRIBUTE or DELETE subcommand +should apply. + +Use the ATTRIBUTE subcommand to add or modify custom variable +attributes. Specify the name of the attribute as an identifier +(@pxref{Tokens}), followed by the desired value, in parentheses, as a +quoted string. The specified attributes are then added or modified in +the variables specified on VARIABLES. Attribute names that begin with +@code{$} are reserved for PSPP's internal use, and attribute names +that begin with @code{@@} or @code{$@@} are not displayed by most PSPP +commands that display other attributes. Other attribute names are not +treated specially. + +Attributes may also be organized into arrays. To assign to an array +element, add an integer array index enclosed in square brackets +(@code{[} and @code{]}) between the attribute name and value. Array +indexes start at 1, not 0. An attribute array that has a single +element (number 1) is not distinguished from a non-array attribute. + +Use the DELETE subcommand to delete an attribute from the variable +specified on VARIABLES. Specify an attribute name by itself to delete +an entire attribute, including all array elements for attribute +arrays. Specify an attribute name followed by an array index in +square brackets to delete a single element of an attribute array. In +the latter case, all the array elements numbered higher than the +deleted element are shifted down, filling the vacated position. + +To associate custom attributes with the entire active file, instead of +with particular variables, use @cmd{DATAFILE ATTRIBUTE} (@pxref{DATAFILE ATTRIBUTE}) instead. + +@cmd{VARIABLE ATTRIBUTE} takes effect immediately. It is not affected +by conditional and looping structures such as @cmd{DO IF} or +@cmd{LOOP}. + +@node VARIABLE LABELS @section VARIABLE LABELS @vindex VARIABLE LABELS @display VARIABLE LABELS - /var_list 'var_label'. + var_list 'var_label' + [ /var_list 'var_label'] + . + . + . + [ /var_list 'var_label'] @end display @cmd{VARIABLE LABELS} associates explanatory names with variables. This name, called a @dfn{variable label}, is displayed by statistical procedures. -To assign a variable label to a group of variables, specify a slash -(@samp{/}), followed by the list of variable names and the variable -label as a string. +To assign a variable label to a group of variables, specify a +list of variable names and the variable label as a string. +To assign different labels to different variables in the same command, +precede the subsequent variable list with a slash (@samp{/}). + + +@node VARIABLE ALIGNMENT +@comment node-name, next, previous, u +@section VARIABLE ALIGNMENT +@vindex VARIABLE ALIGNMENT -@node VECTOR, WRITE FORMATS, VARIABLE LABELS, Variable Attributes +@display +VARIABLE ALIGNMENT + var_list ( LEFT | RIGHT | CENTER ) + [ /var_list ( LEFT | RIGHT | CENTER ) ] + . + . + . + [ /var_list ( LEFT | RIGHT | CENTER ) ] +@end display + +@cmd{VARIABLE ALIGNMENT} sets the alignment of variables for display editing +purposes. This only has effect for third party software. It does not affect +the display of variables in the PSPP output. + + + + +@node VARIABLE WIDTH +@comment node-name, next, previous, up +@section VARIABLE WIDTH +@vindex VARIABLE WIDTH +@display +VARIABLE WIDTH + var_list (width) + [ /var_list (width) ] + . + . + . + [ /var_list (width) ] +@end display + +@cmd{VARIABLE WIDTH} sets the column width of variables for display editing +purposes. This only affects third party software. It does not affect +the display of variables in the PSPP output. + + +@node VARIABLE LEVEL +@comment node-name, next, previous, up +@section VARIABLE LEVEL +@vindex VARIABLE LEVEL +@display +VARIABLE LEVEL + var_list ( SCALE | NOMINAL | ORDINAL ) + [ /var_list ( SCALE | NOMINAL | ORDINAL ) ] + . + . + . + [ /var_list ( SCALE | NOMINAL | ORDINAL ) ] +@end display + +@cmd{VARIABLE LEVEL} sets the measurement level of variables. +Currently, this has no effect except for certain third party software. + + +@node VECTOR @section VECTOR @vindex VECTOR @display Two possible syntaxes: VECTOR vec_name=var_list. - VECTOR vec_name_list(count). + VECTOR vec_name_list(count [format]). @end display @cmd{VECTOR} allows a group of variables to be accessed as if they were consecutive members of an array with a vector(index) notation. -To make a vector out of a set of existing variables, specify a name for -the vector followed by an equals sign (@samp{=}) and the variables that -belong in the vector. +To make a vector out of a set of existing variables, specify a name +for the vector followed by an equals sign (@samp{=}) and the variables +to put in the vector. All the variables in the vector must be the same +type. String variables in a vector must all have the same width. To make a vector and create variables at the same time, specify one or more vector names followed by a count in parentheses. This will cause variables named @code{@var{vec}1} through @code{@var{vec}@var{count}} -to be created as numeric variables with print and write format F8.2. -Variable names including numeric suffixes may not exceed 8 characters -in length, and none of the variables may exist prior to @cmd{VECTOR}. - -All the variables in a vector must be the same type. +to be created as numeric variables. By default, the new variables +have print and write format F8.2, but an alternate format may be +specified inside the parentheses before or after the count and +separated from it by white space or a comma. Variable names including +numeric suffixes may not exceed 64 characters in length, and none of +the variables may exist prior to @cmd{VECTOR}. Vectors created with @cmd{VECTOR} disappear after any procedure or procedure-like command is executed. The variables contained in the @@ -386,7 +542,7 @@ Variables}). Variables within a vector may be referenced in expressions using @code{vector(index)} syntax. -@node WRITE FORMATS, , VECTOR, Variable Attributes +@node WRITE FORMATS @section WRITE FORMATS @vindex WRITE FORMATS @@ -394,8 +550,8 @@ Variables within a vector may be referenced in expressions using WRITE FORMATS var_list (fmt_spec). @end display -@cmd{WRITE FORMATS} sets the write formats for the specified variables +@cmd{WRITE FORMATS} sets the write formats for the specified numeric +variables to the specified format specification. Its syntax is identical to that of FORMATS (@pxref{FORMATS}), but @cmd{WRITE FORMATS} sets only write formats, not print formats. -@setfilename ignored