APPENDIX: VARIANT Qualified Type
Updated: Nov 14, 2005

Please see Statements > Dimension > Variables > VARIANT.

With VARIANTS in HotBasic,
(a) one can DIM variants and use them in HotBasic expressions transparently and
(b) the VariantRef() and VariantRef$() numeric and string functions
respectively may be used to read variants provided by external modules
(eg., a .dll) -- which create them and provide their pointer.

The new Run-Time Error "Variant type error" indicates an invalid variant type,
an unsupported variant type (eg., decimal) or failure to match numeric/string
type in an expression.

A variant may be read as a "numeric type" with

  defint i
  i = MyVariant  'or VariantRef(lpVariant)

Generally, all variant types that result in numbers and/or pointers work here
and the coder is responsible for further use of pointers, where applicable.
NOTE: The pointer may be to an array info structure or to a string of some
sort, etc, but the variant is deemed to be NUMERIC.

Type values 0 and 1 return numeric 0.  The invalid values are listed below for
strings.

  defstr s$
  s$ = MyVariant  'or VariantRef$(lpVariant)

should work for variant types 0 (empty), 1 (null), 8 (bstr), 30 (lpstr), 31
(lpwstr), 65 (blob), and 70 (blob_object).

0 and 1 return null strings; the rest return the data as a string for the coder
to examine.  If the data has 16-bit characters (eg., lpwstr), so will s$.

Note we say "string"; but think "memory".  The above syntax "captures" the
variant data in a MEMORY/STRING object, for further analysis or use.

vt_variant (12) is supported for both numeric and string types (where the
variant contains a pointer to another variant which HotBasic would proceed to
read).

Type qualifiers:
(a) vt_byref (&H4000) is supported for all types.
(b) vt_vector (&H1000) and vt_array (&H2000) both return pointers, and are
deemed to be numeric (to read the pointer) regardless of the type of data in
the vector/array.

The Type bits for a variant may be read with the .Type property of variants
created locally (by DIM; please see variant.bas in HotTrial).

The Type bits for a variant provided by an external module by its address can
be read with BYREF(lpVariant).

When variant Type bits are read, the VT value minus the qualifiers above may be
obtained with TYPE AND &HFFF.  This masked Type result may be used to determine
whether variant content may be "copied" to a numeric or string variable in
source code.

If TYPE AND &H3000 is true, then the variant is read as numeric (see "type
qualifiers" above).  Example using lpVariant:

  IF BYREF(lpVariant) AND &H3000 THEN Goto Read_As_Num
  'code
  Read_As_Num:
  x = VariantRef(lpVariant)


Copyright 2005 James J Keene PhD
Original Publication: Nov 14, 2005