See Also: ucEvaluate, ucReleaseItem, ucSetVariableValue, SetVar, Local Variables


Defines a user variable.


ucDefineVariable(Definition [, Address [, tHandle]])




Required.  Definition is a string argument of the following form for ordinary scalar variables:


VarName [As Type] [= Value]


At minimum, a variable name is required.  You may specify a data type by following the variable name with " As " and the data type you want to specify.  If no type is specified then the default type (Extended or Double depending on the compiler) is used.  You may also optionally give the variable a starting value following an equal sign.  Value can be any expression that evaluates to a value of the same data type as the variable being defined (or a type that is convertible to it).


To define an array, VarName must be followed by parentheses, which enclose the maximum index of the array.  The index of the first element is 0.  The array definition syntax is:


VarName(MaxIndex) [As Type]



Optional.  You can attach a variable declared with uCalc to a non-uCalc variable from your source code.  To do this, supply the address of the variable in your code.  If you are attaching to a variable in your code called x, then in PowerBASIC, or Visual Basic classic, you would pass VarPtr(x) for the Address argument.  In C++ it would be &x.  In Delphi, it would be @x.  You cannot use this feature in VB.NET, since the .NET garbage collector may change a variable's actual address at any moment.  .NET users should instead define a regular uCalc variable without the Address argument, and update the variable using ucSetVariableValue.  The C# .NET compiler gives you the option of declaring a block of code as unsafe, in which case you can attach a uCalc variable to a host variable with (int)&x.


If you use the Address argument, you must make sure that the data type you use in the uCalc definition corresponds with the actual data type of the variable in your code.


If you are defining an array, then Address should be the address of the first array element.  For instance, in VB:


Dim MyArray(10) As Double

ucDefineVariable "MyArray(10) As Double", VarPtr(MyArray(0))



Optional.  Makes your variable available only within the specified thread.  See Thread Handling.



Example 1: Self-contained variables


This example demonstrates a variety of definitions.   For the first one, since a data type is not specified, x is the default numeric type (Double or Extended, depending on the compiler).  y is defined as a string.  abc is defined implicitly as a Double, and starts with a value of 25.5.  MyString starts with "Hello".  If a variable is set equal to a literal string within quotes, then the variable is implicitly defined as a String.  As String is optional in this context so it wasn't used in defining MyString.  The result of evaluating 10 / 3 (which is 3.333...) is stored in MyDblVar.  For MyLongVar, since it is an integer, the floating point result is converted to in integer first before it is stored.  MyArray is defined as an array.  Since no type is supplied, it is Double or Extended (depending on the compiler).


Visual Basic

ucDefineVariable "x"

ucDefineVariable "y As String"

ucDefineVariable "abc = 25.5"

ucDefineVariable "MyString = 'Hello' "

ucDefineVariable "MyDblVar As Double = 10 / 3"

ucDefineVariable "MyLongVar As Long = 10 / 3"

ucDefineVariable "MyArray(10)"


ucEvalStr "SetVar(y, ' World')"

ucEvalStr "uc_For(x, 1, 10, 1, SetVar(MyArray(x), x^2))"


Print ucEvalStr("MyString + y")  ' Returns "Hello World"

Print ucEvalStr("abc * 10")      ' Returns 255

Print ucEvalStr("MyDblVar")      ' Returns 3.33333333...

Print ucEvalStr("MyLongVar")     ' Returns 3

Print ucEvalStr("MyArray(5)")    ' Returns 25

Print ucEvalStr("MyArray(9)")    ' Returns 81



Example 2:  Attached variables


This example demonstrates how a uCalc variable can be attached to the address of a variable in your source code.  Once attached, whatever value is set in your source code will be reflected in the attached uCalc variable, and vice-versa.  So here, x is defined in the language of your compiler, and set with a value of 123.  When you evaluate x within uCalc, this same value of 123 will be displayed.  Now, from within uCalc we set x to 456, and when you print the x from your source code 456 will be displayed.  You will find the demonstration of a variable attachment in a more meaningful context in Example 2 of the Overview topic.


Note: Some compilers may not directly support attached variables in managed mode.  An alternative to using attached variables is to update the variable with ucSetVariableValue as you go along.  This works with any compiler, and the speed difference in the current version of uCalc FMP is negligible.


C++ Builder

long double x = 123;


ucDefineVariable("x", &x);

ShowMessage(ucEvalStr("x"));  // Displays 123


ucEvalStr("SetVar(x, 456)");

ShowMessage(FloatToStr(x));   // Displays 456



double x = 123;  


uCalc.ucDefineVariable("x", (int)&x);

MessageBox.Show(uCalc.ucEvalStr("x"));   // Displays 123


uCalc.ucEvalStr("SetVar(x, 456)");


Note: In order to use pointers in C#, a routine that contains a pointer must use the keyword unsafe.  For instance, the first line of the command button might look like this:

unsafe private void button1_Click(object sender, System.EventArgs e)




   x: Extended;


   x := 123;

   ucDefineVariable('x', @x);



   ucEvalStr('SetVar(x, 456)');





Dim x As Extended


x = 123  

ucDefineVariable "x", VarPtr(x)

MsgBox ucEvalStr("x")


ucEvalStr "SetVar(x, 456)"

MsgBox Str$(x)


Visual Basic (classic)

Dim x As Double


x = 123  

ucDefineVariable "x", VarPtr(x)

MsgBox ucEvalStr("x")


ucEvalStr "SetVar(x, 456)"

MsgBox Str$(x)


Visual Basic .NET

You cannot do variable attachments with VB.NET.  The alternative is to update the uCalc variable with the value of the variable in your code, using ucSetVariableValue.  To do the reverse the variable in your code can retrieve the value of a uCalc variable using ucEval(), like this:


Dim x As Double, xHandle As Integer


x = 123

xHandle = ucDefineVariable("x")

ucSetVariableValue(xHandle, x)

MsgBox ucEvalStr("x")


ucEvalStr("SetVar(x, 456)")

x = ucEval("x")

MsgBox Str(x)


Visual C++

double x = 123;

char xString[80];


ucDefineVariable("x", &x);

MessageBox(ucEvalStr("x"));  // returns 123


ucEvalStr("SetVar(x, 456)");

gcvt(x, 15, xString);

MessageBox(xString);   // returns 456



Example 3:  Attaching array variables


This example demonstrates how to attach uCalc arrays to arrays in your source code.  Note that the uCalc array generally should be attached to the address of the first element (element 0), of the array.


Visual Basic

Dim x As Long

Dim LngArray(10) As Long, DblArray(10) As Double


For x = 1 to 10: LngArray(x) = x*10: Next

For x = 1 to 10: DblArray(x) = x^2: Next


ucDefineVariable "LngArray(10) As Long", VarPtr(LngArray(0))

ucDefineVariable "DblArray(10)", VarPtr(DblArray(0))


Print ucEvalStr("LngArray(5)")   ' Returns 50

Print ucEvalStr("DblArray(5)")   ' Returns 25



Example 4:  Localized variables


See Also: Local variables


Note: The behavior of this example has changed since version 2.96, and is subject to further change in the future.  Notice that "Overhead ~~" was prepended to the function definition in order for it to work the same way as the example in version 2.95.


If you define a variable named x when there was already a variable named x, the old x continues to be linked with previous functions (if you add "~~ Overhead" to the definition) or expressions that used it.  However, subsequent definitions and expressions with x in it will be linked to the new x definition.  If you release the new x, it will revert back to the old one for definitions and expressions after that.  This concept can be used to temporary localize a variable for a given context.


Visual Basic

Dim Local_x_Handle As Long


ucDefineVariable "x = 25"

Print ucEval("x")             ' returns 25


ucDefineFunction("Overhead ~~ f(xyz) = xyz + x")

Print ucEval("f(5)")          ' returns 30


Local_x_Handle = ucDefineVariable("x = 100")

Print ucEval("x")             ' returns 100

Print ucEval("f(5)")          ' still returns 30; f() not affected



Print ucEval("x")         ' returns 25 again





ucDefine "Const: Pi = Atan(1) * 4"

ucDefine "Const: MyConst As Long = 123"



New or enhanced in version 3.0

·         Nothing related to this topic.

·         See What’s New.


New or enhanced in version 2.96


Issues related to version 2.96


New or enhanced in version 2.9+


Issues for users migrating from version 2.0