User Variables

Naming Conventions

The following are the naming conventions for local variables:

• MVBasic does not, strictly speaking, have reserved words. Therefore, a local variable may have the same name as a function or a command. For clarity of code, it is strongly suggested that you avoid the names listed in the Reserved Words table in the MultiValue Basic Quick Reference.

• The first character of a local variable name must be a letter, dollar ($), or percent (%) character. Names beginning with $SYSTEM. (in any letter case) are reserved as system elements. Certain names beginning with $ are used as command or function names in MVBasic (for example, $DATA, $GET, $KILL, $LIST, $MERGE, $ORDER) and should be avoided. Names beginning with a % character (except those beginning with %Z or %z) are reserved as system elements. For further details, refer to “Rules and Guidelines for Identifiers” in the Caché Programming Orientation Guide.

• The second and subsequent characters a local variable name may be letters, numbers, the period (.), dollar ($), underscore (_), and percent (%) characters. The last character cannot be an underscore (_) character.

• Letters in local variable names are case-sensitive in Caché and in all MultiValue emulations except D3. D3 only uses all-uppercase variable names. A local variable name defined with lowercase letters in Caché mode is considered undefined in D3 mode. A local variable name defined with lowercase letters in D3 mode is converted to all capital letters. Case sensitivity can be configured using $OPTIONS CASE (to turn on case sensitivity) and $OPTIONS -CASE (to turn off case sensitivity).

• Local variable names are limited to 31 characters. You may specify a name longer than 31 characters, but only the first 31 characters are used. Therefore, a local variable name must be unique within its first 31 characters.

Be aware valid local variable names in MVBasic may not be valid in ObjectScript. For example, in ObjectScript all variable names that begin with a dollar ($) character are system-supplied special variables. For this reason, MVBasic local variable names containing punctuation characters should be avoided whenever possible.

You can use the ObjectScript $ZNAME function to validate an MVBasic local variable name. If you specify $ZNAME(string,0,11), $ZNAME validates string using the MultiValue Basic naming conventions for local variables.

A global variable begins with the caret (^) character, indicating that it is a global variable. A global variable follows the ObjectScript naming conventions, not the MultiValue variable naming conventions. For further details, see the Variables chapter of Using Caché ObjectScript.

A process-private global variable begins with the ^|| characters (or the ^|"^"| characters), indicating that it is a process-private global. The two syntactic forms are equivalent. A process-private global follows the ObjectScript naming conventions, not the MultiValue variable naming conventions. For further details, see the Variables chapter of Using Caché ObjectScript.

Note that in D3 emulation, global variable names and process-private global variable names are case-sensitive, but local variable names are not case-sensitive.

Assignment of Values

A variable is assigned a value by using the equal sign (=), as shown in the following examples. Spaces can be included or omitted before or after the equal sign.

x="fred"
y=+1234.5
z=x:y

A variable can be assigned multiple values as a dynamic array. For details on defining a dynamic array, refer to Dynamic Arrays.

Common Storage Areas

Caché MVBasic allows you to group user variables into common storage areas. This permits you to set, limit access to, or clear multiple variables with a single command. For further details, refer to the COMMON, CLEARCOMMON, and CLEAR commands.

Undefined Variables

By default, if an MVBasic routine references an undefined variable, the system generates an <UNDEFINED> error. That is, MVBasic undefined variables are handled the same as Caché undefined variables. They are subject to the current settings of the Management Portal UndefVarBehavior configuration setting, and the UndefinedOpens in a new tab property of the Config.MiscellaneousOpens in a new tab class and Undefined()Opens in a new tab method of the %SYSTEM.ProcessOpens in a new tab class settings. All of these default to generating an <UNDEFINED> error. Go to the Management Portal, select System, Configuration, Compatibility Settings. View and edit the current setting of Undefined. The default is 0 (always throw an error).

You can change this MVBasic default behavior to substitute an empty string for an undefined variable, without signalling an error. You can do this in either of two ways:

• You can use the Caché MVDefinedOpens in a new tab property of the Config.MiscellaneousOpens in a new tab class to set this behavior on a system wide basis, or the MVUndefined()Opens in a new tab method of the %SYSTEM.ProcessOpens in a new tab class to set this behavior for the current process. Setting these values affects only the handling of MVBasic undefined functions; the handling of Caché undefined functions is unchanged.

• You can use the ObjectScript Undefined()Opens in a new tab method of the %SYSTEM.ProcessOpens in a new tab class to change undefined variable behavior for the current process. This causes all variables (both Caché variables and MVBasic variables) to substitute an empty string.

To set these ObjectScript functions, use the MVBasic $XECUTE statement, as shown in the following example:

$XECUTE "DO $ZUTIL(68,72,1)"

Maximum Number of Variables

A Caché MVBasic routine can contain a maximum of 32,759 private variables, and a maximum of 65,280 public variables. Exceeding these limits results in a compile error.