message: Make msg_emit() take full ownership of its argument.

[pspp] / doc / variables.texi

@c PSPP - a program for statistical analysis.
@c Copyright (C) 2017, 2020 Free Software Foundation, Inc.
@c Permission is granted to copy, distribute and/or modify this document
@c under the terms of the GNU Free Documentation License, Version 1.3
@c or any later version published by the Free Software Foundation;
@c with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
@c A copy of the license is included in the section entitled "GNU
@c Free Documentation License".
@c
@node Manipulating Variables
@chapter Manipulating Variables
@cindex Variables

Every value in a dataset is associated with a @dfn{variable}.
Variables describe what the values represent and properties of those values,
such as the format in which they should be displayed, whether they are numeric
or alphabetic and how missing values should be represented.
There are several utility commands for examining and adjusting variables.

@menu
* DISPLAY::                     Display information about the active dataset.
* NUMERIC::                     Create new numeric variables.
* STRING::                      Create new string variables.
* MODIFY VARS::                 Rename, reorder, and drop variables.
* RENAME VARIABLES::            Rename variables.
* SORT VARIABLES::              Reorder variables.
* DELETE VARIABLES::            Delete variables.
* VARIABLE LABELS::             Set variable labels for variables.
* PRINT FORMATS::               Set variable print formats.
* WRITE FORMATS::               Set variable write formats.
* FORMATS::                     Set print and write formats.
* VALUE LABELS::                Set value labels for variables.
* ADD VALUE LABELS::            Add value labels to variables.
* MISSING VALUES::              Set missing values for variables.
* VARIABLE ATTRIBUTE::          Set custom attributes on variables.
* VARIABLE ALIGNMENT::          Set the alignment for display.
* VARIABLE WIDTH::              Set the display width.
* VARIABLE LEVEL::              Set the measurement level.
* VARIABLE ROLE::               Set the role that a variable fills in analysis.
* VECTOR::                      Declare an array of variables.
* MRSETS::                      Add, modify, and list multiple response sets.
* LEAVE::                       Don't clear variables between cases.
@end menu

@node DISPLAY
@section DISPLAY
@vindex DISPLAY

The @cmd{DISPLAY} command displays information about the variables in the active dataset.
A variety of different forms of information can be requested.
By default, all variables in the active dataset are displayed.  However you can select
variables of interest using the @subcmd{/VARIABLES} subcommand.

@display
DISPLAY [SORTED] NAMES [[/VARIABLES=]@var{var_list}].
DISPLAY [SORTED] INDEX [[/VARIABLES=]@var{var_list}].
DISPLAY [SORTED] LABELS [[/VARIABLES=]@var{var_list}].
DISPLAY [SORTED] VARIABLES [[/VARIABLES=]@var{var_list}].
DISPLAY [SORTED] DICTIONARY [[/VARIABLES=]@var{var_list}].
DISPLAY [SORTED] SCRATCH [[/VARIABLES=]@var{var_list}].
DISPLAY [SORTED] ATTRIBUTES [[/VARIABLES=]@var{var_list}].
DISPLAY [SORTED] @@ATTRIBUTES [[/VARIABLES=]@var{var_list}].
DISPLAY [SORTED] VECTORS.
@end display

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 dataset, in the order that
variables occur in the active dataset dictionary.  The @subcmd{SORTED} keyword
causes output to be sorted alphabetically by variable name.

@table @asis
@item NAMES
The variables' names are displayed.

@item INDEX
The variables' names are displayed along with a value describing their
position within the active dataset dictionary.

@item LABELS
Variable names, positions, and variable labels are displayed.

@item VARIABLES
Variable names, positions, print and write formats, and missing values
are displayed.

@item DICTIONARY
Variable names, positions, print and write formats, missing values,
variable labels, and value labels are displayed.

@item SCRATCH
Variable names are displayed, for scratch variables only (@pxref{Scratch
Variables}).

@item ATTRIBUTES
@itemx @@ATTRIBUTES
Datafile and variable attributes are displayed.
The first form of the command omits those attributes
whose names begin with @code{@@} or @code{$@@}.
In the second for, all datafile and variable attributes are displayed.
@end table

With the @code{VECTOR} keyword, @cmd{DISPLAY} lists all the currently
declared vectors.  If the @subcmd{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.

For related commands, see @ref{DISPLAY DOCUMENTS} and @ref{DISPLAY
FILE LABEL}.

@node NUMERIC
@section NUMERIC
@vindex NUMERIC

@cmd{NUMERIC} explicitly declares new numeric variables, optionally
setting their output formats.

@display
NUMERIC @var{var_list} [(@var{fmt_spec})] [/@var{var_list} [(@var{fmt_spec})]]@dots{}
@end display

Specify the names of the new numeric variables as @var{var_list}.  If
you wish to set the variables' output formats, follow their names 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 STRING
@section STRING
@vindex STRING

@cmd{STRING} creates new string variables.

@display
STRING @var{var_list} (@var{fmt_spec}) [/@var{var_list} (@var{fmt_spec})] [@dots{}].
@end display

Specify a list of names for the variable you want to create,
followed by the desired output format specification in
parentheses (@pxref{Input and Output Formats}).
Variable widths are
implicitly derived from the specified output formats.
The created variables will be initialized to spaces.

If you want to create several variables with  distinct
output formats, you can either use two or more separate @cmd{STRING} commands,
or you can specify further variable list and format specification pairs, each separated
from the previous by a slash (@samp{/}).

The following example is one way to create three string variables; Two of the
variables have format A24 and the other A80:
@example
STRING firstname lastname (A24) / address (A80).
@end example

@noindent Here is another way to achieve the same result:
@example
STRING firstname lastname (A24).
STRING address (A80).
@end example

@noindent @dots{} and here is yet another way:

@example
STRING firstname (A24).
STRING lastname (A24).
STRING address (A80).
@end example

@node MODIFY VARS
@section MODIFY VARS
@vindex MODIFY VARS

You can use @cmd{MODIFY VARS} to reorder, rename, or delete variables.

@display
MODIFY VARS
        /REORDER=@{FORWARD,BACKWARD@} @{POSITIONAL,ALPHA@} (@var{var_list})@dots{}
        /RENAME=(@var{old_names}=@var{new_names})@dots{}
        /@{DROP,KEEP@}=@var{var_list}
        /MAP
@end display

At least one subcommand must be specified, and no subcommand may be
specified more than once.  @subcmd{DROP} and @subcmd{KEEP} may not both
be specified.

The @subcmd{REORDER} subcommand changes the order of variables in the active
dataset.  Specify one or more lists of variable names in parentheses.  By
default, each list of variables is rearranged into the specified order.
To put the variables into the reverse of the specified order, put
keyword @subcmd{BACKWARD} before the parentheses.  To put them into alphabetical
order in the dictionary, specify keyword @subcmd{ALPHA} before the parentheses.
@subcmd{BACKWARD} and @subcmd{ALPHA} may also be combined.

To rename variables in the active dataset, specify @subcmd{RENAME}, an equals sign
(@samp{=}), and lists of the old variable names and new variable names
separated by another equals sign within parentheses.  There must be the
same number of old and new variable names.  Each old variable is renamed to
the corresponding new variable name.  Multiple parenthesized groups of
variables may be specified.

The @subcmd{DROP} subcommand deletes a specified list of variables
from the active dataset.  @cmd{MODIFY VARS} may not be used to delete
all variables from the dictionary; use @cmd{NEW FILE} to do that
(@pxref{NEW FILE}).

The @subcmd{KEEP} subcommand keeps the specified list of variables in the active
dataset.  Any unlisted variables are deleted from the active dataset.

@subcmd{MAP} is currently ignored.

If either @subcmd{DROP} or @subcmd{KEEP} is specified, the data is read;
otherwise it is not.

@cmd{MODIFY VARS} may not be specified following @cmd{TEMPORARY}
(@pxref{TEMPORARY}).

@node RENAME VARIABLES
@section RENAME VARIABLES
@vindex RENAME VARIABLES

@cmd{RENAME VARIABLES} changes the names of variables in the active
dataset.

@display
RENAME VARIABLES (@var{old_names}=@var{new_names})@dots{} .
@end display

Specify lists of the old variable names and new
variable names, separated by an equals sign (@samp{=}), within
parentheses.  There must be the same number of old and new variable
names.  Each old variable is renamed to the corresponding new variable
name.  Multiple parenthesized groups of variables may be specified.
When the old and new variable names contain only a single variable name,
the parentheses are optional.

@cmd{RENAME VARIABLES} takes effect immediately.  It does not cause the data
to be read.

@cmd{RENAME VARIABLES} may not be specified following @cmd{TEMPORARY}
(@pxref{TEMPORARY}).

@node SORT VARIABLES
@section SORT VARIABLES
@vindex SORT VARIABLES

@cmd{SORT VARIABLES} reorders the variables in the active dataset's dictionary
according to a chosen sort key.

@display
SORT VARIABLES [BY]
    (NAME | TYPE | FORMAT | LABEL | VALUES | MISSING | MEASURE
     | ROLE | COLUMNS | ALIGNMENT | ATTRIBUTE @var{name})
    [(D)].
@end display

The main specification is one of the following identifiers, which
determines how the variables are sorted:

@table @asis
@item NAME
Sorts the variables according to their names, in a case-insensitive
fashion.  However, when variable names differ only in a number at the
end, they are sorted numerically.  For example, @code{VAR5} is sorted
before @code{VAR400} even though @samp{4} precedes @samp{5}.

@item TYPE
Sorts numeric variables before string variables, and shorter string
variables before longer ones.

@item FORMAT
Groups variables by print format; within a format, sorts narrower
formats before wider ones; with the same format and width, sorts fewer
decimal places before more decimal places.
@xref{FORMATS}.

@item LABEL
Sorts variables without a variable label before those with one.
@xref{VARIABLE LABELS}.

@item VALUES
Sorts variables without value labels before those with some.
@xref{VALUE LABELS}.

@item MISSING
Sorts variables without missing values before those with some.
@xref{MISSING VALUES}.

@item MEASURE
Sorts nominal variables first, followed by ordinal variables, followed
by scale variables.  @xref{VARIABLE LEVEL}.

@item ROLE
Groups variables according to their role.  @xref{VARIABLE ROLE}.

@item COLUMNS
Sorts variables in ascending display width.  @xref{VARIABLE WIDTH}.

@item ALIGNMENT
Sorts variables according to their alignment, first left-aligned, then
right-aligned, then centered.  @xref{VARIABLE ALIGNMENT}.

@item ATTRIBUTE @var{name}
Sorts variables according to the first value of their @var{name}
attribute.  Variables without attribute are sorted first.
@xref{VARIABLE ATTRIBUTE}.
@end table

Only one sort criterion can be specified.  The sort is ``stable,'' so
to sort on multiple criteria one may perform multiple sorts.  For
example, the following will sort primarily based on alignment, with
variables that have the same alignment ordered based on display width:

@example
SORT VARIABLES BY COLUMNS.
SORT VARIABLES BY ALIGNMENT.
@end example

Specify @code{(D)} to reverse the sort order.

@node DELETE VARIABLES
@section DELETE VARIABLES
@vindex DELETE VARIABLES

@cmd{DELETE VARIABLES} deletes the specified variables from the dictionary.

@display
DELETE VARIABLES @var{var_list}.
@end display

@cmd{DELETE VARIABLES} should not be used after defining transformations
but 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.

@cmd{DELETE VARIABLES} may not be used to delete all variables from the
dictionary; use @cmd{NEW FILE} to do that (@pxref{NEW FILE}).

@node VARIABLE LABELS
@section VARIABLE LABELS
@vindex VARIABLE LABELS

In addition to a variable's name, each variable can have a @dfn{label}.
Whereas the name is limited to certain constraints (@pxref{Attributes}) a variable's
label has no such constraints.
Typically, the names are concise, easy to type mnemonics for the variable
and the labels are longer, more verbose descriptions.

@display
VARIABLE LABELS
        @var{var_list} '@var{var_label}'
        [ /@var{var_list} '@var{var_label}']
        .
        .
        .
        [ /@var{var_list} '@var{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
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 PRINT FORMATS
@section PRINT FORMATS
@vindex PRINT FORMATS

@display
PRINT FORMATS @var{var_list} (@var{fmt_spec}) [@var{var_list} (@var{fmt_spec})]@dots{}.
@end display

@cmd{PRINT FORMATS} sets the print formats for the specified
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 WRITE FORMATS
@section WRITE FORMATS
@vindex WRITE FORMATS

@display
WRITE FORMATS @var{var_list} (@var{fmt_spec}) [@var{var_list} (@var{fmt_spec})]@dots{}.
@end display

@cmd{WRITE FORMATS} sets the write formats for the specified variables
to the specified format specification.  Its syntax is identical to
that of @cmd{FORMATS} (@pxref{FORMATS}), but @cmd{WRITE FORMATS} sets only
write formats, not print formats.

@node FORMATS
@section FORMATS
@vindex FORMATS

@display
FORMATS @var{var_list} (@var{fmt_spec}) [@var{var_list} (@var{fmt_spec})]@dots{}.
@end display

@cmd{FORMATS} set both print and write formats for the specified
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
will be changed.  All of the variables listed together must have
the same type and, for string variables, the same width.

Additional lists of variables and formats may be included following
the first one.

@cmd{FORMATS} takes effect immediately.  It is not affected by
conditional and looping structures such as @cmd{DO IF} or @cmd{LOOP}.

@node VALUE LABELS
@section VALUE LABELS
@vindex VALUE LABELS

The values of a variable can be associated with an arbitrary text string.
In this way, a short value can stand for a longer, more descriptive label.

Both numeric and string variables can be given labels.  For string
variables, the values are case-sensitive, so that, for example, a
capitalized value and its lowercase variant would have to be labeled
separately if both are present in the data.

@display
VALUE LABELS
        /@var{var_list} @var{value} '@var{label}' [@var{value} '@var{label}']@dots{}
@end display

@cmd{VALUE LABELS} allows values of variables to be associated with labels.

To set up value labels for one or more variables, specify the
variable names after a slash (@samp{/}), followed by a list of values
and their associated labels, separated by spaces.

Value labels in output are normally broken into lines automatically.
Put @samp{\n} in a label string to force a line break at that point.
The label may still be broken into lines at additional points.

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 ADD VALUE LABELS
@section ADD VALUE LABELS
@vindex ADD VALUE LABELS

@cmd{ADD VALUE LABELS} has the same syntax and purpose as @cmd{VALUE
LABELS} (@pxref{VALUE LABELS}), but it does not clear value
labels from the variables before adding the ones specified.

@display
ADD VALUE LABELS
        /@var{var_list} @var{value} '@var{label}' [@var{value} '@var{label}']@dots{}
@end display


@node MISSING VALUES
@section MISSING VALUES
@vindex MISSING VALUES

In many situations the data available for analysis is incomplete and a placeholder
must be used in place of a value to indicate that the value is unknown.  One way
that missing values are represented is through the $SYSMIS variable
(@pxref{System Variables}).  Another, more flexible way is through
@dfn{user-missing values} which are determined on a per variable basis.

The @cmd{MISSING VALUES} command sets user-missing values for variables.

@display
MISSING VALUES @var{var_list} (@var{missing_values}).

where @var{missing_values} takes one of the following forms:
        @var{num1}
        @var{num1}, @var{num2}
        @var{num1}, @var{num2}, @var{num3}
        @var{num1} THRU @var{num2}
        @var{num1} THRU @var{num2}, @var{num3}
        @var{string1}
        @var{string1}, @var{string2}
        @var{string1}, @var{string2}, @var{string3}
As part of a range, @subcmd{LO} or @subcmd{LOWEST} may take the place of @var{num1};
@subcmd{HI} or @subcmd{HIGHEST} may take the place of @var{num2}.
@end display

@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,
for numeric variables only, a range of values optionally accompanied by
a single discrete value.  Ranges may be open-ended on one end, indicated
through the use of the
keyword @subcmd{LO} or @subcmd{LOWEST} or @subcmd{HI} or @subcmd{HIGHEST}.

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 VARIABLE ATTRIBUTE
@section VARIABLE ATTRIBUTE
@vindex VARIABLE ATTRIBUTE

@cmd{VARIABLE ATTRIBUTE} adds, modifies, or removes user-defined
attributes associated with variables in the active dataset.  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.

@display
VARIABLE ATTRIBUTE
         VARIABLES=@var{var_list}
         ATTRIBUTE=@var{name}('@var{value}') [@var{name}('@var{value}')]@dots{}
         ATTRIBUTE=@var{name}@b{[}@var{index}@b{]}('@var{value}') [@var{name}@b{[}@var{index}@b{]}('@var{value}')]@dots{}
         DELETE=@var{name} [@var{name}]@dots{}
         DELETE=@var{name}@b{[}@var{index}@b{]} [@var{name}@b{[}@var{index}@b{]}]@dots{}
@end display

The required @subcmd{VARIABLES} subcommand must come first.  Specify the
variables to which the following @subcmd{ATTRIBUTE} or @subcmd{DELETE} subcommand
should apply.

Use the @subcmd{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 @subcmd{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 @subcmd{DELETE} subcommand to delete an attribute from the variable
specified on @subcmd{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 dataset, 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 ALIGNMENT
@section VARIABLE ALIGNMENT
@vindex VARIABLE ALIGNMENT

@cmd{VARIABLE ALIGNMENT} sets the alignment of variables for display editing
purposes.   It  does not affect the display of variables in the @pspp{} output.

@display
VARIABLE ALIGNMENT
        @var{var_list} ( LEFT | RIGHT | CENTER )
        [ /@var{var_list} ( LEFT | RIGHT | CENTER ) ]
        .
        .
        .
        [ /@var{var_list} ( LEFT | RIGHT | CENTER ) ]
@end display

@node VARIABLE WIDTH
@section VARIABLE WIDTH
@vindex VARIABLE WIDTH
@display
VARIABLE WIDTH
        @var{var_list} (width)
        [ /@var{var_list} (width) ]
        .
        .
        .
        [ /@var{var_list} (width) ]
@end display

@cmd{VARIABLE WIDTH} sets the column width of variables for display editing
purposes.   It does not affect the display of variables in the @pspp{} output.


@node VARIABLE LEVEL
@section VARIABLE LEVEL
@vindex VARIABLE LEVEL
@display
VARIABLE LEVEL
        @var{var_list} ( SCALE | NOMINAL | ORDINAL )
        [ /@var{var_list} ( SCALE | NOMINAL | ORDINAL ) ]
        .
        .
        .
        [ /@var{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 VARIABLE ROLE
@section VARIABLE ROLE
@vindex VARIABLE ROLE
@display
VARIABLE ROLE
        /@var{role} @var{var_list}
        [/@var{role} @var{var_list}]@dots{}
@end display

@cmd{VARIABLE ROLE} sets the intended role of a variable for use in
dialog boxes in graphical user interfaces.  Each @var{role} specifies
one of the following roles for the variables that follow it:

@table @code
@item INPUT
An input variable, such as an independent variable.

@item TARGET
An output variable, such as an dependent variable.

@item BOTH
A variable used for input and output.

@item NONE
No role assigned.  (This is a variable's default role.)

@item PARTITION
Used to break the data into groups for testing.

@item SPLIT
No meaning except for certain third party software.  (This role's
meaning is unrelated to @cmd{SPLIT FILE}.)
@end table

The PSPPIRE GUI does not yet use variable roles as intended.

@node VECTOR
@section VECTOR
@vindex VECTOR

@display
Two possible syntaxes:
        VECTOR @var{vec_name}=@var{var_list}.
        VECTOR @var{vec_name_list}(@var{count} [@var{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
to put in the vector.  The variables must be all numeric or all
string, and string variables must 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
create variables named @code{@var{vec}1} through
@code{@var{vec}@var{count}}.  By default, the new variables are
numeric with 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.  With a string format such as A8, the
variables will be string variables; with a numeric format, they will
be numeric.  Variable names including the 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
vectors remain, unless they are scratch variables (@pxref{Scratch
Variables}).

Variables within a vector may be referenced in expressions using
@code{vector(index)} syntax.

@node MRSETS
@section MRSETS
@vindex MRSETS

@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 survey question.

Multiple responses are represented 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

@display
MRSETS
    /MDGROUP NAME=@var{name} VARIABLES=@var{var_list} VALUE=@var{value}
     [CATEGORYLABELS=@{VARLABELS,COUNTEDVALUES@}]
     [@{LABEL='@var{label}',LABELSOURCE=VARLABEL@}]

    /MCGROUP NAME=@var{name} VARIABLES=@var{var_list} [LABEL='@var{label}']

    /DELETE NAME=@{[@var{names}],ALL@}

    /DISPLAY NAME=@{[@var{names}],ALL@}
@end display


Any number of subcommands may be specified in any order.

The @subcmd{MDGROUP} subcommand creates a new multiple dichotomy set or
replaces an existing multiple response set.  The @subcmd{NAME},
@subcmd{VARIABLES}, and
@subcmd{VALUE} specifications are required.  The others are optional:

@itemize @bullet
@item
@var{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
@subcmd{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
@subcmd{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
@subcmd{CATEGORYLABELS} optionally specifies the source of the labels for each
category in the set:

@itemize @minus
@item
@subcmd{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
@subcmd{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
@subcmd{LABEL} optionally specifies a label for the multiple response set.  If
neither @subcmd{LABEL} nor @subcmd{LABELSOURCE=VARLABEL} is specified, the set is
unlabeled.

@item
@subcmd{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.
@subcmd{LABELSOURCE=VARLABEL} must be used with @subcmd{CATEGORYLABELS=COUNTEDVALUES}.
It is mutually exclusive with @subcmd{LABEL}.
@end itemize

The @subcmd{MCGROUP} subcommand creates a new multiple category set or
replaces an existing multiple response set.  The @subcmd{NAME} and @subcmd{VARIABLES}
specifications are required, and @subcmd{LABEL} is optional.  Their meanings
are as described above in @subcmd{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 @subcmd{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 @subcmd{DISPLAY} subcommand displays information about defined multiple
response sets.  Its syntax is the same as the @subcmd{DELETE} subcommand.

Multiple response sets are saved to and read from system files by,
@i{e.g.}, the @cmd{SAVE} and @cmd{GET} command.  Otherwise, multiple
response sets are currently used only by third party software.

@node LEAVE
@section LEAVE
@vindex LEAVE

@cmd{LEAVE} prevents the specified variables from being
reinitialized whenever a new case is processed.

@display
LEAVE @var{var_list}.
@end display

Normally, when a data file is processed, every variable in the active
dataset is initialized to the system-missing value or spaces at the
beginning of processing for each case.  When a variable has been
specified on @cmd{LEAVE}, this is not the case.  Instead, that variable is
initialized to 0 (not system-missing) or spaces for the first case.
After that, it retains its value between cases.

This becomes useful for counters.  For instance, in the example below
the variable @code{SUM} maintains a running total of the values in the @code{ITEM}
variable.

@example
DATA LIST /ITEM 1-3.
COMPUTE SUM=SUM+ITEM.
PRINT /ITEM SUM.
LEAVE SUM
BEGIN DATA.
123
404
555
999
END DATA.
@end example

@noindent Partial output from this example:

@example
123   123.00
404   527.00
555  1082.00
999  2081.00
@end example

It is best to use @cmd{LEAVE} command immediately before invoking a
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.