User Tools

Site Tools


parameter_passing_to_ole_ocx_methods.htm
Navigation:  Language Reference > App A - DDE, OLE, and OCX > Calling OLE Object Methods >====== Parameter Passing to OLE/OCX Methods ====== Previous pageReturn to chapter overviewNext page

Just as in Clarion, there are two ways to pass parameters in VB: by value, or by address (by reference). The VB keywords ByVal and ByRef specify these two methods in VB code. These terms mean the same thing in VB as in Clarion–passing a parameter by value passes a copy of the contents of the variable, while passing a parameter by reference (VB's default) passes the address of the variable itself so the receiving method can modify its contents.

Using Parentheses

VB syntax can either use parentheses surrounding the parameter list or not. If the VB method does not return a value, or you don't care about the returned value, the parameters are passed in VB without parentheses, like this:

VtChart1.InsertColumns 6,3

If you do want the returned value, then the parameters are passed in VB within parentheses, like this:

ReturnValue = VtChart1.InsertColumns (6,3)

In Clarion syntax, parameters are always passed within parentheses. Therefore, these two examples translate to:

?Ole{'InsertColumns(6,3)'}

ReturnValue = ?Ole{'InsertColumns(6,3)'}

Passing Parameters By Value

Value parameters are passed to OLE/OCX objects as strings (except Boolean parameters). Since OLE/OCX objects are supposed to cast their input to the correct data types using a VARIANT mechanism (similar to Clarion's data type conversion), this allows the most compatibility with the least work. Any string whcih requires a double quote mark (“) needs to include two (”“).

Value parameters may be passed to OLE/OCX object methods as constants or variables. The examples above pass parameters as constants. You may not have blank spaces in the constant unless the parameter is contained in double quotes (for example, “Value with blanks”).

There are two ways to pass a Clarion variable to an OLE/OCX method by value: concatenated into the string constant that calls the method, or by using BIND on the variable name and placing the name of the variable directly in the string constant that calls the method. For example, to re-write the above example passing the variable values in a concatenated string:

ColumnNumber = 6

NumberOfColumns = 3

?Ole{'InsertColumns(' & ColumnNumber & ',' & NumberOfColumns & ')'}

!Same as ?Ole{'InsertColumns(6,3)'}

The second way to pass variables by value is to BIND them and name them in the string constant, like this:

BIND('ColumnNumber',ColumnNumber)

BIND('NumberOfColumns',NumberOfColumns)

?Ole{'InsertColumns(ColumnNumber,NumberOfColumns)'}

!Same as ?Ole{'InsertColumns(6,3)'}

This method makes the code more easily readable, but you must first BIND the variables to pass.

Passing Parameters By Address (Reference)

Parameters passed by address may be passed to OLE/OCX object methods only as named variables in the constant string. Therefore, you must use BIND on the variable name and place the name of the variable directly in the string constant that calls the method with an ampersand prepended to the variable name to signal that the variable is being passed by reference. For example, to re-write the above example to pass the variables by address:

ColumnNumber = 6

NumberOfColumns = 3

BIND('ColumnNumber',ColumnNumber)

BIND('NumberOfColumns',NumberOfColumns)

?Ole{'InsertColumns(&ColumnNumber,&NumberOfColumns)'}

Parameters passed by address are passed to OLE/OCX objects as the data type of the bound variable (except Boolean parameters). The variables are actually passed as temporary string variables which the Clarion library automatically dereferences so that any modifications to the passed variable by the OLE/OCX method are carried back to the original variable passed.

Boolean Parameters

Boolean parameters (1/0 or True/False) are passed either by value or by address. When passing by value, you may either pass a constant (a 1 or 0, or the words TRUE or FALSE), like this:

?Ole{'ODBCConnect(&DataSource,1,&RetVal)'}

?Ole{'ODBCConnect(&DataSource,TRUE,&RetVal)'}

or pass a variable name (after BINDing it) within a “bool()” call , like this:

BoolParm = 1

BIND('BoolParm',BoolParm)

?Ole{'ODBCConnect(&DataSource,bool(BoolParm),&RetVal)'}

Bool() is a construct that tells the property expression parser to pass it as a Boolean value. Bool() is only valid within an OLE/OCX method call string.

To pass by reference, simply prepend an ampersand to the variable name within the bool() construct, like this:

BIND('BoolParm',BoolParm)

?Ole{'ODBCConnect(&DataSource,bool(&BoolParm),&RetVal)'}

Named Parameters

In VB, there are two ways to pass parameters: positionally, or as “named arguments.” Positional parameters imply that you must either pass a parameter or place a comma place-holder for any omitted parameters in the method call. Since some methods can receive a large number of parameters, this can result in a long string of comma place-holders when you simply want to pass one or two parameters to the method. VB solves this problem by allowing programmers to “name” the parameters, which allows the programmer calling the method to only pass the few parameters they choose to without regard to their position or order within the parameter list.

Named parameters are not universally supported in VB, so the OLE/OCX vendor needs to have written their methods specifically to support them. The OLE/OCX help file should state whether named parameters are supported, or you can use VB's Object Browser to determine whether thay are supported and the parameter names to use.

The VB syntax for named parameters uses := to assign the value to the parameter's name. For example, for the following VB statement:

OpenIt(Name:=, [Exclusive]:=, [ReadOnly]:=, [Connect]:=)

you can call the method in VB using positional parameters, like this:

Db = OpenIt(“MyFile”,False,False,”ODBC;UID=Fred“)

which translates to Clarion (using positional parameters) as:

Db = ?Ole{'OpenIt(“MyFile”,False,False,”ODBC;UID=Fred“)'}

You can call the same method in VB using named parameters, like this (the underscore character is VB's line continuation character):

Db = OpenIt(Name:=“MyFile”,Exclusive:=False,ReadOnly:=False, _ Connect:=“ODBC;UID=Fred”)

which translates to Clarion as:

Db = ?Ole{'OpenIt(Name=“MyFile”,Exclusive=False,ReadOnly=False, ' & | 'Connect=“ODBC;UID=Fred”)'}

or you can pass the parameters in VB in a different order:

Db = OpenIt(Connect:=“ODBC;UID=Fred”, _

Name:=“MyFile”, _

ReadOnly:=False, _

Exclusive:=False”)

which translates to Clarion as:

Db = ?Ole{'OpenIt(Connect=“ODBC;UID=Fred”,Name=“MyFile”,' & |

'Exclusive=False,ReadOnly=False')'}

parameter_passing_to_ole_ocx_methods.htm.txt · Last modified: 2021/04/15 15:57 (external edit)