LET statement (with Variants)  

Purpose

Assign a value or an object reference to a variant variable.

Syntax

[LET] variant = variant expression

Remarks

Although notoriously lacking in efficiency, Variant variables are commonly used as COM Object parameters due to their flexibility. You can think of a Variant as a kind of container, which can hold a variable of most any data type, numeric, string, or even an entire array.  This simplifies the process of calling procedures in a COM Object Server, as there is little need to worry about the myriad of possible data types for each parameter.

This flexibility comes at a great price in performance, so PowerBASIC limits their use to data storage and parameters only.  You may assign a numeric value, a string value, or even an entire array to a Variant with the LET statement, or its implied equivalent.  In the same way, you may assign one Variant value to another Variant variable, or even assign an array contained in a Variant to a compatible PowerBASIC array, or the reverse.

You may extract a simple scalar value from a Variant with the VARIANT# function for numeric values or with the VARIANT$ function for string values.

LET vrntvar = vrntvar

This form duplicates the contents of one variant variable, assigning it to a second variant variable.

LET vrntvar = expression [AS vartype]

The numeric or string expression is evaluated, and the result is assigned to the variant variable.  PowerBASIC automatically chooses an appropriate numeric or string data type for the internal representation of the Variant.  However, you can specify a particular preferred format by adding the optional AS vartype clause, which could be BYTE, WORD, DWORD, INTEGER, LONG, QUAD, SINGLE, DOUBLE, CURRENCY, or STRING.  In the case of a string value, PowerBASIC automatically handles Unicode conversions needed for the COM specification.

LET vrntvar = EMPTY

The variant variable is set to %VT_EMPTY, which means it contains no value of any kind.

LET vrntvar = ERROR numr

This form assigns a specific COM error number, which is usually a COM specific error, such as %E_NOINTERFACE, etc.

LET vrntvar = array()

An entire PowerBASIC array is assigned to a variant variable.  In the case of a string array, PowerBASIC automatically handles Unicode conversions needed for the COM specification.  Array assignment is limited to the following data types: BYTE, WORD, DWORD, INTEGER, LONG, QUAD, SINGLE, DOUBLE, CURRENCY, or STRING, as Windows does not support all PowerBASIC data forms.

LET array() = vrntvar

An entire array is assigned from a variant variable to a PowerBASIC array.  In the case of a string array, PowerBASIC automatically handles Unicode conversions.  You can not assign an array with more than eight dimensions to a PowerBASIC array.

LET vrntvar = BYREF variable

This form is used to allow a variant to contain a typed pointer to a specific variable.  Any changes to the variant will cause the variable to be changed, as it is the target of the pointer.  The variable may be of any data type which is supported by variants and COM objects: Byte, Word, Dword, Integer, Long, Quad, Single, Double, Currency, Variant, and Dynamic String.  If you attempt to use an unsupported variable type (like Extended, Bit, ASCIIZ, etc.),  PowerBASIC will  generate an error 482 (Data Type Mismatch).  Further, you may not use a register variable (automatic or explicit), or an error 491 (Invalid Register Variable) will be generated.  Note that strings used with COM objects are expected to be in Unicode format, rather than ANSI.  The ACODE$ and UCODE$ functions may be used to convert the strings as necessary.

LET objvar = vrnt

Attempts to open an interface of the specified class for objvar on the object of vrnt, and assigns a reference to objvar.  It assumes that vrnt contains a reference to an object of type %VT_UNKNOWN or %VT_DISPATCH.  If the desired interface can not be opened, the object variable objvar is set to NOTHING.  You can test for success/failure with the ISOBJECT(objvar) function.

LET vrnt = objvar

This may be used to assign an object reference from an object variable to a variant variable.  It attempts to open an IDispatch interface, else an IUnknown interface on the object of objvar, and assigns that reference to vrnt.  Variant variables can not contain references to custom interfaces, only IDispatch or IUnknown.  If the assignment is successful, VARIANTVT(vrnt) will return either %VT_UNKNOWN or %VT_DISPATCH.  If it is unsuccessful, vrnt is set to %VT_EMPTY.

See also

Just what is COM?, LET, LET (with Objects), LET (with Types), VARIANT#, VARIANT$, VARIANTVT