Changing variable base names


 Changes made to the VARIABLE.UDT file will affect the default
 variable names Rescue5 uses when creating the <.EXE name>.VAR
 file.

 The VARIABLE.UDT file contains two sections:

   The first section is a list of generic variable base names,
   prefixed with the identifier GenericBaseNames: (which must be
   the first entry in the list).

   There is a generic base name for each of the data types that
   Rescue5 recognises.  These are the default base names used
   for variables that are created when other variables of the
   same type but different qualifiers are combined.

   Each generic base name has two parts; a short description and
   a variable base name composed of a one character type
   identifier followed by up to *six characters of qualifier.

   Rescue5 builds variable names from base names according to
   the following rules:

     If the variable is a static or a code-block parameter a
     scope identifier is inserted after the type prefix.

     If a variable with the same type prefix, scope identifier
     (if applicable) and qualifier already exists, an ordinal
     number is appended to the qualifier.

     If neither a scope identifier nor ordinal number is
     required the base name is used unchanged.

   *Qualifiers may be longer, but Rescue5 will overwrite part of
   the qualifier if the total variable length would otherwise
   exceed ten characters.

 To change generic variable base names, edit the first section:

   To change a generic base name, edit the variable base name on
   the right (*do not edit the description on the left of any of
   the fundamental generic base names supplied with Rescue5).

   To remove a generic base name either delete the entire entry
   from the list or comment it out with a '#' (*do not remove or
   comment out any of the fundamental generic base names
   supplied with Rescue5).

   To add a new generic base name append a description and base
   name to the list.  Be careful to avoid defining more than one
   generic base name with the same type prefix.

 *Rescue5 expects certain generic base names to exist, which it
 locates by using the description on the left.  These
 fundamental generic base names are listed below and are clearly
 marked in VARIABLE.UDT.  You can edit the type prefix and
 qualifiers of these names, but do not edit or remove the
 descriptions:

   Array        aArr
   Block        bBlk
   Date         dDte
   Logical      lLog
   Macro        xMac
   Nil          uNil
   Number       nNum
   Object       oObj
   String       cStr
   Undefined    _Def
   Variable     vVar

 All other predefined types may be edited or removed.  Please
 note that if you change a type prefix in the generic variable
 base names section, you must also change the type of all
 entries in the function base names section that are affected.

   The second section of VARIABLE.UDT consists of a list of
   function names, prefixed with the identifier
   FunctionBaseNames: (which must be the first entry in the
   list).

   Each function name is followed by a variable base name that
   defines the default name applied to a variable created as a
   result of that function being called.

   The VARIABLE.UDT file supplied with Rescue5 has definitions
   for every function in CA-Clipper. You can extend or modify
   this list:

     To change an existing function base name, *edit the
     variable base name on the right.

     To remove a function base name from the list either delete
     the entire line or comment it out with a '#'.

     To *add a new function base name append it to the list,
     following the same rules.

   *The new base name must use a type prefix that is defined in
   the predefined generic base name list; if a new type prefix
   is used a generic base name of the same type must be declared
   (otherwise Rescue5 will fail to complete the decompilation).

   If Rescue5 encounters duplicate definitions in VARIABLE.UDT
   it will use the first definition found and write a warning
   into the ERROR file.

 Additional user defined generic base name files can be
 'included' in VARIABLE.UDT with the @ command:

   @funcky.udt                 
   @\dev\clipper5\lib\mylib.udt

 @commands may be placed anywhere in user defined type files and
 can be nested.  Unless a directory is specified, Rescue5
 searches the current directory first for @ included files, then
 the /i directory (if one has been specified), then the /o
 directory (if one has been specified) and finally the directory
 Rescue5 was started from.  The first file encountered with the
 correct name is read.

 User defined type files should follow the same format as
 VARIABLE.UDT:

    If a generic base name section is declared it must appear
    before the function base name section and start with the
    identifier GenericBaseNames:

    If a function base name section is declared it must start
    with the identifier FunctionBaseNames:

 Be careful where you @ include user defined type files; generic
 base names must be processed before function base names.  The
 safest approach is to add generic base names directly into
 VARIABLE.UDT, reserving user defined type files for function
 base name declarations (the user defined type files would then
 be @ included in VARIABLE.UDT after the generic base name
 section).

 If you do not want to change VARIABLE.UDT, edit a copy and use
 the /u switch to force Rescue5 to use the new file in place of
 VARIABLE.UDT.

 For example, here is a modified and extended generic base name
 list:

   Array        aArr
   Block        bExp
   Date         dDate
   Logical      lBool
   Macro        xExp
   Nil          uNil
   Number       nNum
   Object       oObj
   String       cStr
   Undefined    _Nil
   Variable     vChanges

   Handle       hHnd
   Time         tTime
   Integer      iNum
   Float        fNum

 To use the new base names, change the default variable names
 for the functions that are affected:

   fcreate      hCreate
   time         tNow
   getBonus     iPercent
   getSalary    fSalary
   etc.

 Rescue5 resolves type conflicts (variables that are created
 when two or more expressions of different types are combined)
 by using the generic base names defined for the v type.  Using
 the definitions above:

   vChanges := fBonus * iPercent

 Rescue5 used vChanges because the user defined base names
 specify f and i to be of different data types (the code
 produced after running Rescue5 a second time with an unedited
 <.EXE name>.VAR file is shown for clarity).

 The following illustrates how Rescue5 uses generic and function
 base names to construct variable names:

   nRow := row()         // Base name defined for row() used
   nRow1 := row() + nRow // Type & qualifier retained
   nNum := row() + col() // Generic base name used

 The initial call to row() caused Rescue5 to use the base name
 defined for the row() function in the FunctionBaseNames:
 section.  In the first arithmetic expression the expressions
 being operated on are of the same type and qualifier, so
 Rescue5 uses the base name common to both of them.  In the
 second expression the qualifiers are different and Rescue5 used
 the generic base name for 'n' type operations in the
 GenericBaseNames:  section.

 This behaviour means that it is better to give functions that
 logically return the same, or very similar, values the same
 base names.  The definitions:

   row       nRow
   maxrow   nRow

 Produce:

   nRow := maxrow() - row()

 The definitions:

   row      nRow
   maxrow   nMaxRow

 Produce:

   nNum := maxrow() - row()

 In the examples above the code produced after running Rescue5 a
 second time with an unedited <.EXE name>.VAR file is shown for
 clarity.