Caché MultiValue Basic Reference
User-defined variables used for storing data values.
A variable is a unique named entity used to store and retrieve a data value. The following are the available types of variables in Caché MVBasic:
Local variables, the scope of which is the current process.
Process-private global variables, the scope of which is the current process.
Global variables, systemwide in scope.
Four user-defined @ variables: @USER1, @USER2, @USER3, and @USER4. The scope of these variables is the current process. By default they contain the empty string.
System variables, identified by an @ character as the first character. These variables are generally not user-modifiable. For further details, refer to the System Variables
page in this manual.
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 Caché ObjectScript. For example, in Caché 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 Caché ObjectScript $ZNAME
function to validate an MVBasic local variable name. If you specify $ZNAME(string,0,11)
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 Caché 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 Caché 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.
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.
A variable can be assigned multiple values as a dynamic array. For details on defining a dynamic array, refer to Dynamic Arrays
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
, and CLEAR
By default, if an MVBasic routine references an undefined variable, Caché 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 Undefined
property of the Config.Miscellaneous
class and Undefined()
method of the %SYSTEM.Process
class settings. All of these default to generating an <UNDEFINED> error. Go to the Management Portal
, select [Home] > [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:
To set these Caché 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.