.-
help for ^defv^                                             (STB-40: dm50)
.-

Defining variables and recording their definitions
--------------------------------------------------

   ^defv^ [^by^ varlist^:^] [type] newvar [^:^ lblname] ^=^ exp [^if^ exp] [^in^ range]

   ^defv^ [^by^ varlist^:^] oldvar ^=^ exp [^if^ exp] [^in^ range] [^, nop^romote]

   ^defv^ oldvar ?


Description
-----------

^defv^ creates a new variable or changes the contents of an existing variable,
whichever is appropriate, and records the operation it performed in a charac-
teristic attached to the variable.  The first syntax above is applicable in the
case of a new variable, the second and third apply to existing variables. Aside
from the positioning of a ^by^ clause (i.e., following rather than preceding the
command name), the first syntax is identical to that of the @generate@ command,
the second to that of the @replace@ command.

^defv^ is a wrapper for the built-in commands ^generate^ and ^replace^ which makes it
possible to define a variable and record its definition by repeatedly using a
single command (^defv^), regardless of whether the variable exists at the outset.
The definition is recorded in a series of ^characteristics^ associated with the
variable (one characteristic for each use of ^defv^); the third syntax above dis-
plays those characteristics, in the order recorded.

^defv^ may be freely used in place of ^generate^ and ^replace^, with one alteration
and one exception.  The alteration is that a ^by^ clause follows the name ^defv^,
whereas it precedes the names ^generate^ and ^replace^.  The exception is that the
the text following the name ^defv^ cannot contain the double-quote character (^"^);
this precludes most definitions involving string variables.


Options
-------

There are no options other than those associated with ^generate^ and ^replace^.

However, it is possible to alter the style in which ^defv^ records definitions.
By default, ^defv^ uses the same naming scheme as the command @notes@, so that re-
corded definitions will appear to have been created by ^notes^.  Definitions from
^defv^ and notes from ^notes^ may be freely intermingled.  If this is undesirable,
definitions can be rendered distinct from notes by altering a comment line near
the top of the file defv.ado.


Examples
--------

 . ^defv age2 = age*age^
 . ^defv income=. if income<=0^
 . ^defv byte biginc = income>100000 & income~=.^
 . ^defv xlag = x[_n-1] in 2/l^

 . ^replace sw = 1 if region=="SW"^     (OK)
 . ^defv sw = 1 if region=="SW"^        (Not allowed)

 . ^sort loc^
 . ^defv by loc: avgx = sum(x)/sum(x~=.)^
 . ^defv by loc: avgx = avgx[_N]^
 . ^defv avgx ?^


Author
------

      John R. Gleason
      Syracuse University
      email: loesljrg@@ican.net


Also see
--------

    STB:   STB-40 dm50
 Manual:   [U] 19 Data
           [U] 19.8 Characteristics
           [U] 20 Functions and expressions
           [R] generate
           [R] notes
 On-line:  help for @char@, @datatypes@, @exp@, @functions@, @generate@, @notes@, @operators@