-@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
@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.
* MODIFY VARS:: Rename, reorder, and drop variables.
+* MRSETS:: Add, modify, and list multiple response sets.
* NUMERIC:: Create new numeric variables.
* PRINT FORMATS:: Set variable print formats.
* 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
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
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
@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
@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
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
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,
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
@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
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 MRSETS
+@section MRSETS
+@vindex MRSETS
+
+@display
+MRSETS
+ /MDGROUP NAME=name VARIABLES=var_list VALUE=value
+ [CATEGORYLABELS=@{VARLABELS,COUNTEDVALUES@}]
+ [@{LABEL='label',LABELSOURCE=VARLABEL@}]
+
+ /MCGROUP NAME=name VARIABLES=var_list [LABEL='label']
+
+ /DELETE NAME=@{[names],ALL@}
+
+ /DISPLAY NAME=@{[names],ALL@}
+@end display
+
+@cmd{MRSETS} creates, modifies, deletes, and displays multiple
+response sets. A multiple response set is a set of variables that
+represent multiple responses to a single survey question in one of the
+two following ways:
+
+@itemize @bullet
+@item
+A @dfn{multiple dichotomy set} is analogous to a survey question with
+a set of checkboxes. Each variable in the set is treated in a Boolean
+fashion: one value (the "counted value") means that the box was
+checked, and any other value means that it was not.
+
+@item
+A @dfn{multiple category set} represents a survey question where the
+respondent is instructed to list up to @var{n} choices. Each variable
+represents one of the responses.
+@end itemize
+
+Any number of subcommands may be specified in any order.
+
+The MDGROUP subcommand creates a new multiple dichotomy set or
+replaces an existing multiple response set. The NAME, VARIABLES, and
+VALUE specifications are required. The others are optional:
+
+@itemize @bullet
+@item
+NAME specifies the name used in syntax for the new multiple dichotomy
+set. The name must begin with @samp{$}; it must otherwise follow the
+rules for identifiers (@pxref{Tokens}).
+
+@item
+VARIABLES specifies the variables that belong to the set. At least
+two variables must be specified. The variables must be all string or
+all numeric.
+
+@item
+VALUE specifies the counted value. If the variables are numeric, the
+value must be an integer. If the variables are strings, then the
+value must be a string that is no longer than the shortest of the
+variables in the set (ignoring trailing spaces).
+
+@item
+CATEGORYLABELS optionally specifies the source of the labels for each
+category in the set:
+
+@itemize @minus
+@item
+VARLABELS, the default, uses variable labels or, for variables without
+variable labels, variable names. PSPP warns if two variables have the
+same variable label, since these categories cannot be distinguished in
+output.
+
+@item
+COUNTEDVALUES instead uses each variable's value label for the counted
+value. PSPP warns if two variables have the same value label for the
+counted value or if one of the variables lacks a value label, since
+such categories cannot be distinguished in output.
+@end itemize
+
+@item
+LABEL optionally specifies a label for the multiple response set. If
+neither LABEL nor LABELSOURCE=VARLABEL is specified, the set is
+unlabeled.
+
+@item
+LABELSOURCE=VARLABEL draws the multiple response set's label from the
+first variable label among the variables in the set; if none of the
+variables has a label, the name of the first variable is used.
+LABELSOURCE=VARLABEL must be used with CATEGORYLABELS=COUNTEDVALUES.
+It is mutually exclusive with LABEL.
+@end itemize
+
+The MCGROUP subcommand creates a new multiple category set or
+replaces an existing multiple response set. The NAME and VARIABLES
+specifications are required, and LABEL is optional. Their meanings
+are as described above to MDGROUP. PSPP warns if two variables in the
+set have different value labels for a single value, since each of the
+variables in the set should have the same possible categories.
+
+The DELETE subcommand deletes multiple response groups. A list of
+groups may be named within a set of required square brackets, or ALL
+may be used to delete all groups.
+
+The DISPLAY subcommand displays information about defined multiple
+response sets. Its syntax is the same as the DELETE subcommand.
+
+Multiple response sets are saved to and read from system files by,
+e.g., the @cmd{SAVE} and @cmd{GET} command. Otherwise, multiple
+response sets are currently used only by third party software.
+
+@node PRINT FORMATS
@section PRINT FORMATS
@vindex PRINT FORMATS
@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
@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
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
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
+
+@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 VECTOR, WRITE FORMATS, VARIABLE LABELS, Variable Attributes
+@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
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
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
projects / pspp-builds.git / blobdiff