ucParam

ucParamStr

See Also: ucDefineFunction, ucDefineOperator, ucParamCount, ucParamHandle, ucReturn

Retrieves the argument(s) or operand(s) of a callback routine.

ucParam(ExpressionHandle, ParamIndex)

- or -

ucParamStr(ExpressionHandle, ParamIndex)

Parameters

ExpressionHandle

All Native callback routines receive one argument, which is ExpressionHandle. This handle is required as the first argument of ucParam().

ParamIndex

This represents the index of the parameter you want. If a callback routine has three parameters, and Expr is the expression handle, then ucParam(Expr, 1) represents the first parameter, ucParam(Expr, 2) the second, and ucParam(Expr, 3) the third. For an infix operator, ucParam(Expr, 1) is the left operand, and ucParam(Expr, 2) is the right operand. For a unary operator, ucParam(Expr, 1) is the operand.

Remarks

• ucParam() retrieves numeric arguments, while ucParamStr() retrieves string arguments.
• Native routines (which are significantly faster than ordinary callbacks) are intended for Standard License customers (though you can still test it, just like all other features, in the demo).
• ucParam was considered an important part of callbacks in version 2.0. In the completely redesigned version 2.9, ucParam was considered obsolete. ucParam (or a variant of it) continued to be available until v2.95 but remained undocumented, and its use was discouraged. ucParam was re-instated in version 2.96 as part of an implementation for native callbacks which is now much faster than callbacks in version 2.0 and non-native callbacks in 2.95. Native callbacks with ucParam are now recommended. Non-native callbacks require no uCalc code at all. You can simply attach a uCalc definition to the address of such a routine. This is ideal for API routines that weren't originally designed with uCalc in mind. However, that kind of callback uses extra overhead and is slower.
• The double precision version of ucParam is a wrapper for the following code (in PB):

Function ucParamDbl Alias "ucParamDbl" (ByVal Expr As ExpressionType Ptr, ByVal index As Long) Export As Double

Function = @Expr.@ArgList[index].@ValueDbl

End Function

There's another similar one for extended precision. Depending on the compiler, ucParam is mapped to ucParamDbl for double precision, or ucParamExt for extended precision. In the PB include file, the above code is defined as a macro instead of a function, thus having less overhead. Although you may use pointers directly with other compilers, details for that are beyond the scope of this help file.

.Example 1: Using ucParam with a function definition

The following routine defines a function named Add, which returns the result of adding its two arguments. So Add(5, 4) would return 9. For more details on defining a function, see ucDefineFunction.

Visual Basic

' The line below can go in Form_Load()

ucDefineFunction "Native: Add(a, b)", AddressOf MyAdd

' The line below goes in a separate module

Sub MyAdd(ByVal Expr As Long)

ucReturn Expr, ucParam(Expr, 1) + ucParam(Expr, 2)

End Sub

Examples for other compilers

Example 2: Using ucParam with an operator definition

The following routine defines an operator named Plus, which returns the result of adding its two operands. So 5 Plus 4 would return 9. Note that the MyAdd callback is identical to the one in Example 1. The only code that is different is the first line (ucDefineOperator ...). The number 20 that comes after the word Native is the precedence level. For more details on defining an operator, see ucDefineOperator.

Visual Basic

' The line below can go in Form_Load()

ucDefineOperator "Native: 20 {a} Plus {b}", AddressOf MyAdd

' The line below goes in a separate module

Sub MyAdd(ByVal Expr As Long)

ucReturn Expr, ucParam(Expr, 1) + ucParam(Expr, 2)

End Sub

Example 3: Using ucParamStr for a string argument

This example demonstrates the use of ucParamStr. Myleft is a function that returns the left-most characters of a string, which is supplied as the first argument. The second argument determines the number of characters to return. It is based on VB's Left$() function. For instance MyLeft("Hello World", 2) would return "He".

Visual Basic

' The line below can go in Form_Load()

ucDefineFunction "Native: MyLeft(Text As String, Count) As String", AddressOf MyLeft

' The line below goes in a separate module

Sub MyLeft(ByVal Expr As Long)

ucReturnStr Expr, Left$(ucParamStr(Expr, 1), ucParam(Expr, 2))

End Sub

Additional examples can be found in the help topics for ucDefineFunction, and ucDefineOperator.

New or enhanced in version 2.96

• The use of ucParam was discouraged in version 2.9. ucParam was optimized in 2.96 for speed and is now recommended for use with native callbacks. You should now use ucParam instead of ucParamDbl or ucParamExt.