ucDefineVariable

See Also: ucEvaluate, ucReleaseItem

Declares a variable and either allocates space for it, or attaches it to a given address.

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

Parameters

Definition

Required. Definition is a string argument of the following form:

VarName [As Type] [= Value]

At minimum, a variable name is required. You can specify a data type by following the variable name with " As " and the type you want to specify. If no type is specified then the default type (Extended, unless you have changed the default) is used. You can also optionally give the variable a starting value following an equal sign. Value can be any expression that evaluates to the given type.

Address

Optional. You can attach a variable defined by 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 ucSetValueDbl. See the VB.NET demo for that.

If you use this 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.

tHandle

Optional. Allows your variable to be visible only within the specified thread. See Thread Handling.

Remarks

The value returned by ucDefineVariable is a handle that can later be used to inspect or change the variable's properties, or to release it.

If an explicit data type is not specified, and the definition includes an equal sign followed by something within quotes (either single quotes or double quotes), then the variable defaults to string type. Otherwise, when the type is not specified, it defaults to Extended (or whatever other type you may have set the default to).

To define a constant, use ucDefine with Const: . For instance:

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

ucDefine("Const: MyConst As Long = 123")

If you define a variable with a name that was already defined, the old definition continues to hold for previous definitions. However, for new definitions the new definition is the one used. If you release the new definition, it will revert back to the old one. This concept can be used to temporary localize a variable for a given context. So for instance:

xHandle1 = ucDefineVariable("b = 25")

Print ucEval("b") ' returns 25

ucDefineFunction("f(x) = x + b")

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

xHandle2 = ucDefineVariable("b = 100")

Print ucEval("f(5)") ' still returns 30 as before

Print ucEval("b") ' returns 100

ucReleaseItem(xHandle2)

Print ucEval("b") ' returns 25 again

Examples:

ucDefineVariable("x = 25")

ucDefineVariable("MyString = 'Hello' ")

ucDefineVariable("MyVar As Long = 10 / 3") ' Stores 3

For examples of attaching a variable to an address, see ucParse.

New or Enhanced

• Instead of using a generic numeric or string type, actual data types can be specified.
• A uCalc variable can be attached to the address of a variable in your source code.
• You can specify a thread handle.
• Variable definitions can be temporary localized.

Issues for users migrating from version 2.0

• This alternative syntax: ucDefineVariable(VariableName, VariableStringValue) is no longer supported.

• A dot (.) can no longer be used as part of a variable name. What constitutes the set of alphanumeric characters is not hard-coded in the DLL. You can reconfigure the set of alphanumeric characters if necessary by modifying the appropriate lines in the include file.

• ucDefineVariable is now merely a wrapper for ucDefine("Var: ..."). Advanced users may be able to do more using ucDefine.