Data Conversion

Conversion Rules

This section describes the data conversion rules for COM components created with the MATLAB^® Compiler SDK™ product. These components are dual interface COM objects that support data types compatible with Automation.

Note

Automation (formerly called OLE Automation) is a technology that allows software packages to expose their unique features to scripting tools and other applications. Automation uses the Component Object Model (COM), but may be implemented independently from other OLE features, such as in-place activation.

Caution

Be aware that IIS (Internet Information Service) usually prevents most COM automation on the basis that it may pose a security risk. Therefore, XLSREAD and other Automation services may fail when served by IIS, leading to errors such as object reference not set.

When a method is invoked on a MATLAB Compiler SDK component, the input parameters are converted to MATLAB internal array format and passed to the compiled MATLAB function. When the function exits, the output parameters are converted from MATLAB internal array format to COM Automation types.

The COM client passes all input and output arguments in the compiled MATLAB functions as type VARIANT. The COM VARIANT type is a union of several simple data types. A type VARIANT variable can store a variable of any of the simple types, as well as arrays of any of these values.

The Win32 API provides many functions for creating and manipulating VARIANTs in C/C++, and Microsoft^® Visual Basic^® provides native language support for this type. See the Microsoft Visual Studio^® documentation for definitions and API support for COM VARIANTs. VARIANT variables are self describing and store their type code as an internal field of the structure.

Note

This discussion of data refers to both VARIANT and Variant data types. VARIANT is the C++ name and Variant is the corresponding data type in Visual Basic.

See VARIANT Type Codes Supported for a list of the VARIANT type codes supported by compiler components.

See MATLAB to COM VARIANT Conversion Rules and COM VARIANT to MATLAB Conversion Rules for conversion rules between COM VARIANTs and MATLAB arrays.

VARIANT Type Codes Supported

VARIANT Type Code (C/C++)	C/C++ Type	Variant Type Code (Visual Basic)	Visual Basic Type	Definition
`VT_EMPTY`	`-`	`vbEmpty`	`-`	Uninitialized `VARIANT`
`VT_I1`	`char`	`-`	`-`	Signed one-byte character
`VT_UI1`	unsigned `char`	`vbByte`	`Byte`	Unsigned one-byte character
`VT_I2`	`short`	`vbInteger`	`Integer`	Signed two-byte integer
`VT_UI2`	`unsigned short`	-	-	Unsigned two-byte integer
`VT_I4`	`long`	`vbLong`	`Long`	Signed four-byte integer
`VT_UI4`	`unsigned long`	-	-	Unsigned four-byte integer
`VT_R4`	`float`	`vbSingle`	`Single`	IEEE^® four-byte floating-point value
`VT_R8`	`double`	`vbDouble`	`Double`	IEEE eight-byte floating-point value
`VT_CY`	`CY`⁺	`vbCurrency`	`Currency`	Currency value (64-bit integer, scaled by 10,000)
`VT_BSTR`	`BSTR`⁺	`vbString`	`String`	String value
`VT_ERROR`	`SCODE`⁺	`vbError`	-	`HRESULT` (signed four-byte integer representing a COM error code)
`VT_DATE`	`DATE`⁺	`vbDate`	`Date`	Eight-byte floating-point value representing date and time
`VT_INT`	`int`	-	-	Signed integer; equivalent to type `int`
`VT_UINT`	`unsigned int`	-	-	Unsigned integer; equivalent to type `unsigned int`
`VT_DECIMAL`	`DECIMAL`⁺	`vbDecimal`	-	96-bit (12-byte) unsigned integer, scaled by a variable power of 10
`VT_BOOL`	`VARIANT_BOOL`⁺	`vbBoolean`	`Boolean`	Two-byte Boolean value (0xFFFF = True; 0x0000 = False)
`VT_DISPATCH`	`IDispatch*`	`vbObject`	`Object`	`IDispatch*` pointer to an object
`VT_VARIANT`	`VARIANT`⁺	`vbVariant`	`Variant`	`VARIANT` (can only be specified if combined with `VT_BYREF` or `VT_ARRAY`)
<anything`>\|VT_ARRAY`				Bitwise combine `VT_ARRAY` with any basic type to declare as an array
<anything`>\|VT_BYREF`				Bitwise combine `VT_BYREF` with any basic type to declare as a reference to a value
⁺Denotes Windows^® specific type. Not part of standard C/C++.

MATLAB to COM VARIANT Conversion Rules

MATLAB Data Type	VARIANT Type for Scalar Data	VARIANT Type for Array Data	Comments
`cell`	A 1-by-1 cell array converts to a single `VARIANT` with a type conforming to the conversion rule for the MATLAB data type of the cell contents.	A multidimensional cell array converts to a `VARIANT` of type `VT_VARIANT\|VT_ARRAY` with the type of each array member conforming to the conversion rule for the MATLAB data type of the corresponding cell.
`structure`	`VT_DISPATCH`	`VT_DISPATCH`	A MATLAB `struct` array is converted to an `MWStruct` object. (See Class MWStruct.) This object is passed as a `VT_DISPATCH` type.
`char`	A 1-by-1 `char` matrix converts to a `VARIANT` of type `VT_BSTR` with string length = 1.	A 1-by-L `char` matrix is assumed to represent a string of length L in MATLAB. This case converts to a `VARIANT` of type `VT_BSTR` with a string length = L. `char` matrices of more than one row, or of a higher dimensionality convert to a `VARIANT` of type `VT_BSTR\|VT_ARRAY`. Each string in the converted array is of length 1 and corresponds to each character in the original matrix.	Arrays of strings are not supported as `char` matrices. To pass an array of strings, use a cell array of 1-by-L `char` matrices.
`sparse`	`VT_DISPATCH`	`VT_DISPATCH`	A MATLAB sparse array is converted to an `MWSparse` object. (See Class MWSparse.) This object is passed as a `VT_DISPATCH` type.
`double`	A real 1-by-1 double matrix converts to a `VARIANT` of type `VT_R8`. A complex 1-by-1 double matrix converts to a `VARIANT` of type `VT_DISPATCH`.	A real multidimensional double matrix converts to a `VARIANT` of type `VT_R8\|VT_ARRAY`. A complex multidimensional double matrix converts to a `VARIANT` of type `VT_DISPATCH`.	Complex arrays are passed to and from compiled MATLAB functions using the `MWComplex` class. See Class MWComplex
`single`	A real 1-by-1 single matrix converts to a `VARIANT` of type `VT_R4`. A complex 1-by-1 single matrix converts to a `VARIANT` of type `VT_DISPATCH`.	A real multidimensional single matrix converts to a `VARIANT` of type `VT_R4\|VT_ARRAY`. A complex multidimensional single matrix converts to a `VARIANT` of type `VT_DISPATCH`.	Complex arrays are passed to and from compiled MATLAB functions using the `MWComplex` class.
`int8`	A real 1-by-1 `int8` matrix converts to a `VARIANT` of type `VT_I1`. A complex 1-by-1 `int8` matrix converts to a `VARIANT` of type `VT_DISPATCH`.	A real multidimensional `int8` matrix converts to a `VARIANT` of type V`T_I1\|VT_ARRAY`. A complex multidimensional `int8` matrix converts to a `VARIANT` of type `VT_DISPATCH`.	Complex arrays are passed to and from compiled MATLAB functions using the `MWComplex` class.
`uint8`	A real 1-by-1 `uint8` matrix converts to a `VARIANT` of type `VT_UI1`. A complex 1-by-1 `uint8` matrix converts to a `VARIANT` of type `VT_DISPATCH`.	A real multidimensional `uint8` matrix converts to a `VARIANT` of type `VT_UI1\|VT_ARRAY`.A complex multidimensional `uint8` matrix converts to a `VARIANT` of type `VT_DISPATCH`.	Complex arrays are passed to and from compiled MATLAB functions using the `MWComplex` class.
`int16`	A real 1-by-1 `int16` matrix converts to a `VARIANT` of type `VT_I2`. A complex 1-by-1 `int16` matrix converts to a `VARIANT` of type `VT_DISPATCH`.	A real multidimensional `int16` matrix converts to a `VARIANT` of type `VT_I2\|VT_ARRAY`. A complex multidimensional `int16` matrix converts to a `VARIANT` of type `VT_DISPATCH`.	Complex arrays are passed to and from compiled MATLAB functions using the `MWComplex` class.
`uint16`	A real 1-by-1 `uint16` matrix converts to a `VARIANT` of type `VT_UI2`. A complex 1-by-1 `uint16` matrix converts to a `VARIANT` of type `VT_DISPATCH`.	A real multidimensional `uint16` matrix converts to a `VARIANT` of type `VT_UI2\|VT_ARRAY`. A complex multidimensional `uint16` matrix converts to a `VARIANT` of type `VT_DISPATCH`.	Complex arrays are passed to and from compiled MATLAB functions using the `MWComplex` class.
`int32`	A 1-by-1 `int32` matrix converts to a `VARIANT` of type `VT_I4`. A complex 1-by-1 `int32` matrix converts to a `VARIANT` of type `VT_DISPATCH`.	A multidimensional `int32` matrix converts to a `VARIANT` of type `VT_I4\|VT_ARRAY`. A complex multidimensional `int32` matrix converts to a `VARIANT` of type `VT_DISPATCH`.	Complex arrays are passed to and from compiled MATLAB functions using the `MWComplex` class.
`uint32`	A 1-by-1 `uint32` matrix converts to a `VARIANT` of type `VT_UI4`. A complex 1-by-1 `uint32` matrix converts to a `VARIANT` of type `VT_DISPATCH`.	A multidimensional `uint32` matrix converts to a `VARIANT` of type `VT_UI4\|VT_ARRAY`. A complex multidimensional `uint32` matrix converts to a `VARIANT` of type `VT_DISPATCH`.	Complex arrays are passed to and from compiled MATLAB functions using the `MWComplex` class.
Function handle	`VT_EMPTY`	`VT_EMPTY`	Not supported
Java^® class	`VT_EMPTY`	`VT_EMPTY`	Not supported
User class	`VT_EMPTY`	`VT_EMPTY`	Not supported
logical	`VT_Bool`	`VT_Bool\|VT_ARRAY`

COM VARIANT to MATLAB Conversion Rules

VARIANT Type	MATLAB Data Type (Scalar or Array Data)	Comments
`VT_EMPTY`	N/A	Empty array created.
`VT_I1`	`int8`
`VT_UI1`	`uint8`
`VT_I2`	`int16`
`VT_UI2`	`uint16`
`VT_I4`	`int32`
`VT_UI4`	`uint32`
`VT_R4`	`single`
`VT_R8`	`double`
`VT_CY`	`double`
`VT_BSTR`	`char`	A `VARIANT` of type `VT_BSTR` converts to a 1-by-L MATLAB `char` array, where L = the length of the string to be converted. A `VARIANT` of type `VT_BSTR\|VT_ARRAY` converts to a MATLAB cell array of 1-by-L `char` arrays.
`VT_ERROR`	`int32`
`VT_DATE`	`double`	`VARIANT` dates are stored as doubles starting at midnight Dec. 31, 1899. MATLAB dates are stored as doubles starting at 0/0/00 00:00:00. Therefore, a `VARIANT` date of 0.0 maps to a MATLAB numeric date of 693960.0. `VARIANT` dates are converted to MATLAB double types and incremented by 693960.0. `VARIANT` dates can be optionally converted to strings. See Data Conversion Flags for more information on type coercion.
`VT_INT`	`int32`
`VT_UINT`	`uint32`
`VT_DECIMAL`	`double`
`VT_BOOL`	`logical`
`VT_DISPATCH`	`Varies`	`IDispatch*` pointers are treated within the context of what they point to. Objects must be supported types with known data extraction and conversion rules, or expose a generic `Value` property that points to a single `VARIANT` type. Data extracted from an object is converted based on the rules for the particular `VARIANT` obtained. Currently, support exists for Excel^® `Range` objects as well as the types `MWStruct`, `MWComplex`, `MWSparse`, and `MWArg`. See Reference Utility Classes for information on the types to use with COM components.
`anything``\|VT_BYREF`	`Varies`	Pointers to any of the basic types are processed according to the rules for what they point to. The resulting MATLAB array contains a deep copy of the values.
`anything``\|VT_ARRAY`	`Varies`	Multidimensional `VARIANT` arrays convert to multidimensional MATLAB arrays, each element converted according to the rules for the basic types. Multidimensional `VARIANT` arrays of type `VT_VARIANT\|VT_ARRAY` convert to multidimensional cell arrays, each cell converted according to the rules for that specific type.

Array Formatting Flags

The components have flags that control how array data is formatted in both directions. Generally, you should develop client code that matches the intended inputs and outputs of the MATLAB functions with the corresponding methods on the compiled COM objects, in accordance with the rules listed in MATLAB to COM VARIANT Conversion Rules and COM VARIANT to MATLAB Conversion Rules. In some cases this is not possible, for example, when existing MATLAB code is used in conjunction with a third-party product like Excel.

The following table shows the array formatting flags.

Array Formatting Flags

Flag	Description
`InputArrayFormat`	Defines the array formatting rule used on input arrays. An input array is a `VARIANT` array, created by the client, sent as an input parameter to a method call on a compiled COM object. Valid values for this flag are `mwArrayFormatAsIs`, `mwArrayFormatMatrix`, and `mwArrayFormatCell`. `mwArrayFormatAsIs` passes the array unchanged. `mwArrayFormatMatrix` (default) formats all arrays as matrices. When the input `VARIANT` is of type `VT_ARRAY`\| `type`, where `type` is any numeric type, this flag has no effect. When the input `VARIANT` is of type `VT_VARIANT\|VT_ARRAY`, `VARIANT`s in the array are examined. If they are single-valued and homogeneous in type, a MATLAB matrix of the appropriate type is produced instead of a cell array. `mwArrayFormatCell` interprets all arrays as MATLAB cell arrays.
`InputArrayIndFlag`	Sets the input array indirection level used with the `InputArrayFormat` flag (applicable only to nested arrays, i.e., `VARIANT` arrays of `VARIANT`s, which themselves are arrays). The default value for this flag is zero, which applies the `InputArrayFormat` flag to the outermost array. When this flag is greater than zero, e.g., equal to N, the formatting rule attempts to apply itself to the Nth level of nesting.
`OutputArrayFormat`	Defines the array formatting rule used on output arrays. An output array is a MATLAB array, created by the compiled COM object, sent as an output parameter from a method call to the client. The values for this flag, `mwArrayFormatAsIs`, `mwArrayFormatMatrix`, and `mwArrayFormatCell`, cause the same behavior as the corresponding `InputArrayFormat` flag values.
`OutputArrayIndFlag`	(Applies to nested cell arrays only.) Output array indirection level used with the `OutputArrayFormat` flag. This flag works exactly like `InputArrayIndFlag`.
`AutoResizeOutput`	(Applies to Excel ranges only.) When the target output from a method call is a range of cells in an Excel worksheet and the output array size and shape is not known at the time of the call, set this flag to `True` to resize each Excel range to fit the output array.
`TransposeOutput`	Set this flag to `True` to transpose the output arguments. Useful when calling a component from Excel where the MATLAB function returns outputs as row vectors, and you want the data in columns.

Data Conversion Flags

MATLAB Compiler SDK components contain flags to control the conversion of certain VARIANT types to MATLAB types. These flags are as follows:

CoerceNumericToType
InputDateFormat
OutputAsDate As Boolean
DateBias As Long

CoerceNumericToType

This flag tells the data converter to convert all numeric VARIANT data to one specific MATLAB type. VARIANT type codes affected by this flag are VT_I1, VT_UI1, VT_I2, VT_UI2, VT_I4, VT_UI4, VT_R4, VT_R8, VT_CY, VT_DECIMAL, VT_INT, VT_UINT, VT_ERROR, VT_BOOL, and VT_DATE. Valid values for this flag are mwTypeDefault, mwTypeChar, mwTypeDouble, mwTypeSingle, mwTypeLogical, mwTypeInt8, mwTypeUint8, mwTypeInt16, mwTypeUint16, mwTypeInt32, and mwTypeUint32.

The default for this flag, mwTypeDefault, converts numeric data according to the rules listed in Data Conversion.

InputDateFormat

This flag tells the data converter how to convert VARIANT dates to MATLAB dates. Valid values for this flag are mwDateFormatNumeric (default) and mwDateFormatString. The default converts VARIANT dates according to the rule listed in VARIANT Type Codes Supported. The mwDateFormatString flag converts a VARIANT date to its string representation. This flag only affects VARIANT type code VT_DATE.

OutputAsDate As Boolean

This flag instructs the data converter to process an output argument as a date. By default, numeric dates that are output parameters from compiled MATLAB functions are passed as Doubles that need to be decremented by the COM date bias (693960) as well as coerced to COM dates. Set this flag to True to convert all output values of type Double.

DateBias As Long

This flag sets the date bias for performing COM to MATLAB numeric date conversions. The default value of this property is 693960, which represents the difference between the COM Date type and MATLAB numeric dates. This flag allows existing MATLAB code that already performs the increment of numeric dates by 693960 to be used unchanged with the components. To process dates with such code, set this property to 0.