Add OUTPUT MODIFY command
[pspp] / doc / variables.texi
1 @node Variable Attributes
2 @chapter Manipulating variables
3
4 The variables in the active dataset dictionary are important.  There are
5 several utility functions for examining and adjusting them.
6
7 @menu
8 * ADD VALUE LABELS::            Add value labels to variables.
9 * DELETE VARIABLES::            Delete variables.
10 * DISPLAY::                     Display information about the active dataset.
11 * FORMATS::                     Set print and write formats.
12 * LEAVE::                       Don't clear variables between cases.
13 * MISSING VALUES::              Set missing values for variables.
14 * MODIFY VARS::                 Rename, reorder, and drop variables.
15 * MRSETS::                      Add, modify, and list multiple response sets.
16 * NUMERIC::                     Create new numeric variables.
17 * PRINT FORMATS::               Set variable print formats.
18 * RENAME VARIABLES::            Rename variables.
19 * VALUE LABELS::                Set value labels for variables.
20 * STRING::                      Create new string variables.
21 * VARIABLE ATTRIBUTE::          Set custom attributes on variables.
22 * VARIABLE LABELS::             Set variable labels for variables.
23 * VARIABLE ALIGNMENT::          Set the alignment for display.
24 * VARIABLE WIDTH::              Set the display width.
25 * VARIABLE LEVEL::              Set the measurement level.
26 * VARIABLE ROLE::               Set the role that a variable fills in analysis.
27 * VECTOR::                      Declare an array of variables.
28 * WRITE FORMATS::               Set variable write formats.
29 @end menu
30
31 @node ADD VALUE LABELS
32 @section ADD VALUE LABELS
33 @vindex ADD VALUE LABELS
34
35 @display 
36 ADD VALUE LABELS
37         /@var{var_list} @var{value} '@var{label}' [@var{value} '@var{label}']@dots{}
38 @end display
39
40 @cmd{ADD VALUE LABELS} has the same syntax and purpose as @cmd{VALUE
41 LABELS} (@pxref{VALUE LABELS}), but it does not clear value
42 labels from the variables before adding the ones specified.
43
44 @node DELETE VARIABLES
45 @section DELETE VARIABLES
46 @vindex DELETE VARIABLES
47
48 @display
49 DELETE VARIABLES @var{var_list}.
50 @end display
51
52 @cmd{DELETE VARIABLES} deletes the specified variables from the
53 dictionary.  It may not be used to delete all variables from the
54 dictionary; use @cmd{NEW FILE} to do that (@pxref{NEW FILE}).
55
56 @cmd{DELETE VARIABLES} should not be used after defining transformations
57 but before executing a procedure.  If it is used in such a context, it
58 causes the data to be read.  If it is used while @cmd{TEMPORARY} is in
59 effect, it causes the temporary transformations to become permanent.
60
61 @node DISPLAY
62 @section DISPLAY
63 @vindex DISPLAY
64
65 @display
66 DISPLAY [SORTED] NAMES [[/VARIABLES=]@var{var_list}].
67 DISPLAY [SORTED] INDEX [[/VARIABLES=]@var{var_list}].
68 DISPLAY [SORTED] LABELS [[/VARIABLES=]@var{var_list}].
69 DISPLAY [SORTED] VARIABLES [[/VARIABLES=]@var{var_list}].
70 DISPLAY [SORTED] DICTIONARY [[/VARIABLES=]@var{var_list}].
71 DISPLAY [SORTED] SCRATCH [[/VARIABLES=]@var{var_list}].
72 DISPLAY [SORTED] ATTRIBUTES [[/VARIABLES=]@var{var_list}].
73 DISPLAY [SORTED] @@ATTRIBUTES [[/VARIABLES=]@var{var_list}].
74 DISPLAY [SORTED] VECTORS.
75 @end display
76
77 @cmd{DISPLAY} displays information about the active dataset.  A variety
78 of different forms of information can be requested.
79
80 The following keywords primarily cause information about variables to
81 be displayed.  With these keywords, by default information is
82 displayed about all variable in the active dataset, in the order that
83 variables occur in the active dataset dictionary.  The @subcmd{SORTED} keyword
84 causes output to be sorted alphabetically by variable name.  The
85 @subcmd{VARIABLES} subcommand limits output to the specified variables.
86
87 @table @asis
88 @item NAMES
89 The variables' names are displayed.
90
91 @item INDEX
92 The variables' names are displayed along with a value describing their
93 position within the active dataset dictionary.
94
95 @item LABELS
96 Variable names, positions, and variable labels are displayed.
97
98 @item VARIABLES
99 Variable names, positions, print and write formats, and missing values
100 are displayed.
101
102 @item DICTIONARY
103 Variable names, positions, print and write formats, missing values,
104 variable labels, and value labels are displayed.
105
106 @item SCRATCH
107 Variable names are displayed, for scratch variables only (@pxref{Scratch
108 Variables}).
109
110 @item ATTRIBUTES
111 @itemx @@ATTRIBUTES
112 Datafile and variable attributes are displayed.
113 The first form of the command omits those attributes 
114 whose names begin with @code{@@} or @code{$@@}.
115 In the second for, all datafile and variable attributes are displayed.
116 @end table
117
118 With the @code{VECTOR} keyword, @cmd{DISPLAY} lists all the currently
119 declared vectors.  If the @subcmd{SORTED} keyword is given, the vectors are
120 listed in alphabetical order; otherwise, they are listed in textual
121 order of definition within the @pspp{} syntax file.
122
123 For related commands, see @ref{DISPLAY DOCUMENTS} and @ref{DISPLAY
124 FILE LABEL}.
125
126 @node FORMATS
127 @section FORMATS
128 @vindex FORMATS
129
130 @display
131 FORMATS @var{var_list} (@var{fmt_spec}) [@var{var_list} (@var{fmt_spec})]@dots{}.
132 @end display
133
134 @cmd{FORMATS} set both print and write formats for the specified
135 variables to the specified format specification.
136 @xref{Input and Output Formats}.
137
138 Specify a list of variables followed by a format specification in
139 parentheses.  The print and write formats of the specified variables
140 will be changed.  All of the variables listed together must have
141 the same type and, for string variables, the same width.
142
143 Additional lists of variables and formats may be included following
144 the first one.
145
146 @cmd{FORMATS} takes effect immediately.  It is not affected by
147 conditional and looping structures such as @cmd{DO IF} or @cmd{LOOP}.
148
149 @node LEAVE
150 @section LEAVE
151 @vindex LEAVE
152
153 @display
154 LEAVE @var{var_list}.
155 @end display
156
157 @cmd{LEAVE} prevents the specified variables from being
158 reinitialized whenever a new case is processed.
159
160 Normally, when a data file is processed, every variable in the active
161 dataset is initialized to the system-missing value or spaces at the
162 beginning of processing for each case.  When a variable has been
163 specified on @cmd{LEAVE}, this is not the case.  Instead, that variable is
164 initialized to 0 (not system-missing) or spaces for the first case.
165 After that, it retains its value between cases.
166
167 This becomes useful for counters.  For instance, in the example below
168 the variable @code{SUM} maintains a running total of the values in the @code{ITEM}
169 variable.
170
171 @example
172 DATA LIST /ITEM 1-3.
173 COMPUTE SUM=SUM+ITEM.
174 PRINT /ITEM SUM.
175 LEAVE SUM
176 BEGIN DATA.
177 123
178 404
179 555
180 999
181 END DATA.
182 @end example
183
184 @noindent Partial output from this example:
185
186 @example
187 123   123.00
188 404   527.00
189 555  1082.00
190 999  2081.00
191 @end example
192
193 It is best to use @cmd{LEAVE} command immediately before invoking a
194 procedure command, because the left status of variables is reset by
195 certain transformations---for instance, @cmd{COMPUTE} and @cmd{IF}.
196 Left status is also reset by all procedure invocations.
197
198 @node MISSING VALUES
199 @section MISSING VALUES
200 @vindex MISSING VALUES
201
202 @display
203 MISSING VALUES @var{var_list} (@var{missing_values}).
204
205 where @var{missing_values} takes one of the following forms:
206         @var{num1}
207         @var{num1}, @var{num2}
208         @var{num1}, @var{num2}, @var{num3}
209         @var{num1} THRU @var{num2}
210         @var{num1} THRU @var{num2}, @var{num3}
211         @var{string1}
212         @var{string1}, @var{string2}
213         @var{string1}, @var{string2}, @var{string3}
214 As part of a range, @subcmd{LO} or @subcmd{LOWEST} may take the place of @var{num1};
215 @subcmd{HI} or @subcmd{HIGHEST} may take the place of @var{num2}.
216 @end display
217
218 @cmd{MISSING VALUES} sets user-missing values for numeric and string
219 variables.  Long string variables may have missing values, but
220 characters after the first 8 bytes of the missing value must be
221 spaces.
222
223 Specify a list of variables, followed by a list of their user-missing
224 values in parentheses.  Up to three discrete values may be given, or,
225 for numeric variables only, a range of values optionally accompanied by
226 a single discrete value.  Ranges may be open-ended on one end, indicated
227 through the use of the 
228 keyword @subcmd{LO} or @subcmd{LOWEST} or @subcmd{HI} or @subcmd{HIGHEST}.
229
230 The @cmd{MISSING VALUES} command takes effect immediately.  It is not
231 affected by conditional and looping constructs such as @cmd{DO IF} or
232 @cmd{LOOP}.
233
234 @node MODIFY VARS
235 @section MODIFY VARS
236 @vindex MODIFY VARS
237
238 @display 
239 MODIFY VARS
240         /REORDER=@{FORWARD,BACKWARD@} @{POSITIONAL,ALPHA@} (@var{var_list})@dots{}
241         /RENAME=(@var{old_names}=@var{new_names})@dots{}
242         /@{DROP,KEEP@}=@var{var_list}
243         /MAP    
244 @end display
245
246 @cmd{MODIFY VARS} reorders, renames, and deletes variables in the
247 active dataset.
248
249 At least one subcommand must be specified, and no subcommand may be
250 specified more than once.  @subcmd{DROP} and @subcmd{KEEP} may not both
251 be specified.
252
253 The @subcmd{REORDER} subcommand changes the order of variables in the active
254 dataset.  Specify one or more lists of variable names in parentheses.  By
255 default, each list of variables is rearranged into the specified order.
256 To put the variables into the reverse of the specified order, put
257 keyword @subcmd{BACKWARD} before the parentheses.  To put them into alphabetical
258 order in the dictionary, specify keyword @subcmd{ALPHA} before the parentheses.
259 @subcmd{BACKWARD} and @subcmd{ALPHA} may also be combined.
260
261 To rename variables in the active dataset, specify @subcmd{RENAME}, an equals sign
262 (@samp{=}), and lists of the old variable names and new variable names
263 separated by another equals sign within parentheses.  There must be the
264 same number of old and new variable names.  Each old variable is renamed to
265 the corresponding new variable name.  Multiple parenthesized groups of
266 variables may be specified.
267
268 The @subcmd{DROP} subcommand deletes a specified list of variables from the
269 active dataset.
270
271 The @subcmd{KEEP} subcommand keeps the specified list of variables in the active
272 dataset.  Any unlisted variables are deleted from the active dataset.
273
274 @subcmd{MAP} is currently ignored.
275
276 If either @subcmd{DROP} or @subcmd{KEEP} is specified, the data is read;
277 otherwise it is not.
278
279 @cmd{MODIFY VARS} may not be specified following @cmd{TEMPORARY}
280 (@pxref{TEMPORARY}).
281
282 @node MRSETS
283 @section MRSETS
284 @vindex MRSETS
285
286 @display
287 MRSETS 
288     /MDGROUP NAME=@var{name} VARIABLES=@var{var_list} VALUE=@var{value}
289      [CATEGORYLABELS=@{VARLABELS,COUNTEDVALUES@}]
290      [@{LABEL='@var{label}',LABELSOURCE=VARLABEL@}]
291
292     /MCGROUP NAME=@var{name} VARIABLES=@var{var_list} [LABEL='@var{label}']
293
294     /DELETE NAME=@{[@var{names}],ALL@}
295
296     /DISPLAY NAME=@{[@var{names}],ALL@}
297 @end display
298
299 @cmd{MRSETS} creates, modifies, deletes, and displays multiple
300 response sets.  A multiple response set is a set of variables that
301 represent multiple responses to a single survey question in one of the
302 two following ways:
303
304 @itemize @bullet
305 @item
306 A @dfn{multiple dichotomy set} is analogous to a survey question with
307 a set of checkboxes.  Each variable in the set is treated in a Boolean
308 fashion: one value (the "counted value") means that the box was
309 checked, and any other value means that it was not.
310
311 @item
312 A @dfn{multiple category set} represents a survey question where the
313 respondent is instructed to list up to @var{n} choices.  Each variable
314 represents one of the responses.
315 @end itemize
316
317 Any number of subcommands may be specified in any order.
318
319 The @subcmd{MDGROUP} subcommand creates a new multiple dichotomy set or
320 replaces an existing multiple response set.  The @subcmd{NAME},
321 @subcmd{VARIABLES}, and
322 @subcmd{VALUE} specifications are required.  The others are optional:
323
324 @itemize @bullet
325 @item
326 @var{NAME} specifies the name used in syntax for the new multiple dichotomy
327 set.  The name must begin with @samp{$}; it must otherwise follow the
328 rules for identifiers (@pxref{Tokens}).
329
330 @item
331 @subcmd{VARIABLES} specifies the variables that belong to the set.  At least
332 two variables must be specified.  The variables must be all string or
333 all numeric.
334
335 @item
336 @subcmd{VALUE} specifies the counted value.  If the variables are numeric, the
337 value must be an integer.  If the variables are strings, then the
338 value must be a string that is no longer than the shortest of the
339 variables in the set (ignoring trailing spaces).
340
341 @item
342 @subcmd{CATEGORYLABELS} optionally specifies the source of the labels for each
343 category in the set:
344
345 @itemize @minus
346 @item
347 @subcmd{VARLABELS}, the default, uses variable labels or, for variables without
348 variable labels, variable names.  @pspp{} warns if two variables have the
349 same variable label, since these categories cannot be distinguished in
350 output.
351
352 @item 
353 @subcmd{COUNTEDVALUES} instead uses each variable's value label for the counted
354 value.  @pspp{} warns if two variables have the same value label for the
355 counted value or if one of the variables lacks a value label, since
356 such categories cannot be distinguished in output.
357 @end itemize
358
359 @item
360 @subcmd{LABEL} optionally specifies a label for the multiple response set.  If
361 neither @subcmd{LABEL} nor @subcmd{LABELSOURCE=VARLABEL} is specified, the set is
362 unlabeled.
363
364 @item
365 @subcmd{LABELSOURCE=VARLABEL} draws the multiple response set's label from the
366 first variable label among the variables in the set; if none of the
367 variables has a label, the name of the first variable is used.
368 @subcmd{LABELSOURCE=VARLABEL} must be used with @subcmd{CATEGORYLABELS=COUNTEDVALUES}.
369 It is mutually exclusive with @subcmd{LABEL}.
370 @end itemize
371
372 The @subcmd{MCGROUP} subcommand creates a new multiple category set or
373 replaces an existing multiple response set.  The @subcmd{NAME} and @subcmd{VARIABLES}
374 specifications are required, and @subcmd{LABEL} is optional.  Their meanings
375 are as described above in @subcmd{MDGROUP}.  @pspp{} warns if two variables in the
376 set have different value labels for a single value, since each of the
377 variables in the set should have the same possible categories.
378
379 The @subcmd{DELETE} subcommand deletes multiple response groups.  A list of
380 groups may be named within a set of required square brackets, or ALL
381 may be used to delete all groups.
382
383 The @subcmd{DISPLAY} subcommand displays information about defined multiple
384 response sets.  Its syntax is the same as the @subcmd{DELETE} subcommand.
385
386 Multiple response sets are saved to and read from system files by,
387 e.g., the @cmd{SAVE} and @cmd{GET} command.  Otherwise, multiple
388 response sets are currently used only by third party software.
389
390 @node NUMERIC
391 @section NUMERIC
392 @vindex NUMERIC
393
394 @display
395 NUMERIC /@var{var_list} [(@var{fmt_spec})].
396 @end display
397
398 @cmd{NUMERIC} explicitly declares new numeric variables, optionally
399 setting their output formats.
400
401 Specify a slash (@samp{/}), followed by the names of the new numeric
402 variables.  If you wish to set their output formats, follow their names
403 by an output format specification in parentheses (@pxref{Input and Output
404 Formats}); otherwise, the default is F8.2.
405
406 Variables created with @cmd{NUMERIC} are initialized to the
407 system-missing value.
408
409 @node PRINT FORMATS
410 @section PRINT FORMATS
411 @vindex PRINT FORMATS
412
413 @display
414 PRINT FORMATS @var{var_list} (@var{fmt_spec}) [@var{var_list} (@var{fmt_spec})]@dots{}.
415 @end display
416
417 @cmd{PRINT FORMATS} sets the print formats for the specified
418 variables to the specified format specification.
419
420 Its syntax is identical to that of @cmd{FORMATS} (@pxref{FORMATS}),
421 but @cmd{PRINT FORMATS} sets only print formats, not write formats.
422
423 @node RENAME VARIABLES
424 @section RENAME VARIABLES
425 @vindex RENAME VARIABLES
426
427 @display
428 RENAME VARIABLES (@var{old_names}=@var{new_names})@dots{} .
429 @end display
430
431 @cmd{RENAME VARIABLES} changes the names of variables in the active
432 dataset.  Specify lists of the old variable names and new
433 variable names, separated by an equals sign (@samp{=}), within
434 parentheses.  There must be the same number of old and new variable
435 names.  Each old variable is renamed to the corresponding new variable
436 name.  Multiple parenthesized groups of variables may be specified.
437
438 @cmd{RENAME VARIABLES} takes effect immediately.  It does not cause the data
439 to be read.
440
441 @cmd{RENAME VARIABLES} may not be specified following @cmd{TEMPORARY}
442 (@pxref{TEMPORARY}).
443
444 @node VALUE LABELS
445 @section VALUE LABELS
446 @vindex VALUE LABELS
447
448 @display 
449 VALUE LABELS
450         /@var{var_list} @var{value} '@var{label}' [@var{value} '@var{label}']@dots{}
451 @end display
452
453 @cmd{VALUE LABELS} allows values of numeric and short string
454 variables to be associated with labels.  In this way, a short value can
455 stand for a long value.
456
457 To set up value labels for a set of variables, specify the
458 variable names after a slash (@samp{/}), followed by a list of values
459 and their associated labels, separated by spaces.
460
461 Value labels in output are normally broken into lines automatically.
462 Put @samp{\n} in a label string to force a line break at that point.
463 The label may still be broken into lines at additional points.
464
465 Before @cmd{VALUE LABELS} is executed, any existing value labels
466 are cleared from the variables specified.  Use @cmd{ADD VALUE LABELS}
467 (@pxref{ADD VALUE LABELS}) to add value labels without clearing those
468 already present.
469
470 @node STRING
471 @section STRING
472 @vindex STRING
473
474 @display
475 STRING @var{var_list} (@var{fmt_spec}) [/@var{var_list} (@var{fmt_spec})] [@dots{}].
476 @end display
477
478 @cmd{STRING} creates new string variables for use in
479 transformations.
480
481 Specify a list of names for the variable you want to create,
482 followed by the desired output format specification in
483 parentheses (@pxref{Input and Output Formats}).  
484 Variable widths are
485 implicitly derived from the specified output formats.
486 The created variables will be initialized to spaces.
487
488 If you want to create several variables with  distinct
489 output formats, you can either use two or more separate @cmd{STRING} commands,
490 or you can specify further variable list and format specification pairs, each separated
491 from the previous by a slash (@samp{/}).
492
493 The following example is one way to create three string variables; Two of the
494 variables have format A24 and the other A80:
495 @example
496 STRING firstname lastname (A24) / address (A80).
497 @end example
498
499 @noindent Here is another way to achieve the same result:
500 @example
501 STRING firstname lastname (A24).
502 STRING address (A80).
503 @end example
504
505 @noindent @dots{} and here is yet another way:
506
507 @example
508 STRING firstname (A24).
509 STRING lastname (A24).
510 STRING address (A80).
511 @end example
512
513
514
515
516 @node VARIABLE ATTRIBUTE
517 @section VARIABLE ATTRIBUTE
518 @vindex VARIABLE ATTRIBUTE
519
520 @display
521 VARIABLE ATTRIBUTE
522          VARIABLES=@var{var_list}
523          ATTRIBUTE=@var{name}('@var{value}') [@var{name}('@var{value}')]@dots{}
524          ATTRIBUTE=@var{name}@b{[}@var{index}@b{]}('@var{value}') [@var{name}@b{[}@var{index}@b{]}('@var{value}')]@dots{}
525          DELETE=@var{name} [@var{name}]@dots{}
526          DELETE=@var{name}@b{[}@var{index}@b{]} [@var{name}@b{[}@var{index}@b{]}]@dots{}
527 @end display
528
529 @cmd{VARIABLE ATTRIBUTE} adds, modifies, or removes user-defined
530 attributes associated with variables in the active dataset.  Custom
531 variable attributes are not interpreted by @pspp{}, but they are saved as
532 part of system files and may be used by other software that reads
533 them.
534
535 The required @subcmd{VARIABLES} subcommand must come first.  Specify the
536 variables to which the following @subcmd{ATTRIBUTE} or @subcmd{DELETE} subcommand
537 should apply.
538
539 Use the @subcmd{ATTRIBUTE} subcommand to add or modify custom variable
540 attributes.  Specify the name of the attribute as an identifier
541 (@pxref{Tokens}), followed by the desired value, in parentheses, as a
542 quoted string.  The specified attributes are then added or modified in
543 the variables specified on @subcmd{VARIABLES}.  Attribute names that begin with
544 @code{$} are reserved for @pspp{}'s internal use, and attribute names
545 that begin with @code{@@} or @code{$@@} are not displayed by most @pspp{}
546 commands that display other attributes.  Other attribute names are not
547 treated specially.
548
549 Attributes may also be organized into arrays.  To assign to an array
550 element, add an integer array index enclosed in square brackets
551 (@code{[} and @code{]}) between the attribute name and value.  Array
552 indexes start at 1, not 0.  An attribute array that has a single
553 element (number 1) is not distinguished from a non-array attribute.
554
555 Use the @subcmd{DELETE} subcommand to delete an attribute from the variable
556 specified on @subcmd{VARIABLES}.  Specify an attribute name by itself to delete
557 an entire attribute, including all array elements for attribute
558 arrays.  Specify an attribute name followed by an array index in
559 square brackets to delete a single element of an attribute array.  In
560 the latter case, all the array elements numbered higher than the
561 deleted element are shifted down, filling the vacated position.
562
563 To associate custom attributes with the entire active dataset, instead of
564 with particular variables, use @cmd{DATAFILE ATTRIBUTE} (@pxref{DATAFILE ATTRIBUTE}) instead.
565
566 @cmd{VARIABLE ATTRIBUTE} takes effect immediately.  It is not affected
567 by conditional and looping structures such as @cmd{DO IF} or
568 @cmd{LOOP}.
569
570 @node VARIABLE LABELS
571 @section VARIABLE LABELS
572 @vindex VARIABLE LABELS
573
574 @display
575 VARIABLE LABELS
576         @var{var_list} '@var{var_label}' 
577         [ /@var{var_list} '@var{var_label}']
578         .
579         .
580         .
581         [ /@var{var_list} '@var{var_label}']
582 @end display
583
584 @cmd{VARIABLE LABELS} associates explanatory names
585 with variables.  This name, called a @dfn{variable label}, is displayed by
586 statistical procedures.
587
588 To assign a variable label to a group of variables, specify a 
589 list of variable names and the variable label as a string.
590 To assign different labels to different variables in the same command, 
591 precede the subsequent variable list with a slash (@samp{/}).
592
593
594 @node VARIABLE ALIGNMENT
595 @section VARIABLE ALIGNMENT
596 @vindex VARIABLE ALIGNMENT
597
598 @display
599 VARIABLE ALIGNMENT
600         @var{var_list} ( LEFT | RIGHT | CENTER )
601         [ /@var{var_list} ( LEFT | RIGHT | CENTER ) ]
602         .
603         .
604         .
605         [ /@var{var_list} ( LEFT | RIGHT | CENTER ) ]
606 @end display
607
608 @cmd{VARIABLE ALIGNMENT} sets the alignment of variables for display editing 
609 purposes.   This only has effect for third party software.  It does not affect 
610 the display of variables in the @pspp{} output.
611
612
613
614
615 @node VARIABLE WIDTH
616 @section VARIABLE WIDTH
617 @vindex VARIABLE WIDTH
618 @display
619 VARIABLE WIDTH
620         @var{var_list} (width)
621         [ /@var{var_list} (width) ] 
622         .
623         .
624         .
625         [ /@var{var_list} (width) ] 
626 @end display
627
628 @cmd{VARIABLE WIDTH} sets the column width of variables for display editing
629 purposes.   This only affects third party software.  It does not affect 
630 the display of variables in the @pspp{} output.
631
632
633 @node VARIABLE LEVEL
634 @section VARIABLE LEVEL
635 @vindex VARIABLE LEVEL
636 @display
637 VARIABLE LEVEL
638         @var{var_list} ( SCALE | NOMINAL | ORDINAL )
639         [ /@var{var_list} ( SCALE | NOMINAL | ORDINAL ) ]
640         .
641         .
642         .
643         [ /@var{var_list} ( SCALE | NOMINAL | ORDINAL ) ]
644 @end display
645
646 @cmd{VARIABLE LEVEL} sets the measurement level of  variables.
647 Currently, this has no effect except for certain third party software.
648
649
650 @node VARIABLE ROLE
651 @section VARIABLE ROLE
652 @vindex VARIABLE ROLE
653 @display
654 VARIABLE ROLE
655         /@var{role} @var{var_list}
656         [/@var{role} @var{var_list}]@dots{}
657 @end display
658
659 @cmd{VARIABLE ROLE} sets the intended role of a variable for use in
660 dialog boxes in graphical user interfaces.  Each @var{role} specifies
661 one of the following roles for the variables that follow it:
662
663 @table @code
664 @item INPUT
665 An input variable, such as an independent variable.
666
667 @item TARGET
668 An output variable, such as an dependent variable.
669
670 @item BOTH
671 A variable used for input and output.
672
673 @item NONE
674 No role assigned.  (This is a variable's default role.)
675
676 @item PARTITION
677 Used to break the data into groups for testing.
678
679 @item SPLIT
680 No meaning except for certain third party software.  (This role's
681 meaning is unrelated to @cmd{SPLIT FILE}.)
682 @end table
683
684 The PSPPIRE GUI does not yet use variable roles as intended.
685
686 @node VECTOR
687 @section VECTOR
688 @vindex VECTOR
689
690 @display
691 Two possible syntaxes:
692         VECTOR @var{vec_name}=@var{var_list}.
693         VECTOR @var{vec_name_list}(@var{count} [@var{format}]).
694 @end display
695
696 @cmd{VECTOR} allows a group of variables to be accessed as if they
697 were consecutive members of an array with a vector(index) notation.
698
699 To make a vector out of a set of existing variables, specify a name
700 for the vector followed by an equals sign (@samp{=}) and the variables
701 to put in the vector.  All the variables in the vector must be the same
702 type.  String variables in a vector must all have the same width.
703
704 To make a vector and create variables at the same time, specify one or
705 more vector names followed by a count in parentheses.  This will cause
706 variables named @code{@var{vec}1} through @code{@var{vec}@var{count}}
707 to be created as numeric variables.  By default, the new variables
708 have print and write format F8.2, but an alternate format may be
709 specified inside the parentheses before or after the count and
710 separated from it by white space or a comma.  Variable names including
711 numeric suffixes may not exceed 64 characters in length, and none of
712 the variables may exist prior to @cmd{VECTOR}.
713
714 Vectors created with @cmd{VECTOR} disappear after any procedure or
715 procedure-like command is executed.  The variables contained in the
716 vectors remain, unless they are scratch variables (@pxref{Scratch
717 Variables}).
718
719 Variables within a vector may be referenced in expressions using
720 @code{vector(index)} syntax.
721
722 @node WRITE FORMATS
723 @section WRITE FORMATS
724 @vindex WRITE FORMATS
725
726 @display
727 WRITE FORMATS @var{var_list} (@var{fmt_spec}) [@var{var_list} (@var{fmt_spec})]@dots{}.
728 @end display
729
730 @cmd{WRITE FORMATS} sets the write formats for the specified variables
731 to the specified format specification.  Its syntax is identical to
732 that of @cmd{FORMATS} (@pxref{FORMATS}), but @cmd{WRITE FORMATS} sets only
733 write formats, not print formats.