ucDefineVariable

ucDefineVariable

Defines a user variable.

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

Parameters

Definition

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]

Address

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))

tHandle

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)");

MessageBox.Show(System.Convert.ToString(x));

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)

Delphi

var

x: Extended;

begin

x := 123;

ucDefineVariable('x', @x);

ShowMessage(ucEvalStr('x'));

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

ShowMessage(FloatToStr(x));

end;

PowerBASIC

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