|
|
|
| R2012a Documentation → MATLAB Builder EX | |
Learn more about MATLAB Builder EX |
|
| Contents | Index |
This topic describes the data conversion rules for the MATLAB Builder EX components. These components are dual interface Microsoft 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. |
When a method is invoked on a MATLAB Builder EX component, the input parameters are converted to the MATLAB internal array format and passed to the compiled MATLAB function. When the function exits, the output parameters are converted from the 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 application program interface (API) provides many functions for creating and manipulating VARIANTs in C/C++, and Visual Basic provides native language support for this type.
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 the 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.
The following table lists the VARIANT type codes supported by the MATLAB Builder EX components.
VARIANT Type Codes Supported
| VARIANT Type Code (C/C++) | C/C++ Type | Variant Type Code (Visual Basic) | Visual BasicType | 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 | — | An 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++. | ||||
The following table lists the rules for converting from MATLAB to COM.
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 Lin 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 .) |
| 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. (See .) |
| 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 VT_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. (See .) |
| 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. (See .) |
| 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. (See .) |
| 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. (See .) |
| 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. (See .) |
| 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. (See .) |
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 |
The following table lists the rules for conversion from COM to MATLAB.
COM VARIANT to MATLAB Conversion Rules
| VARIANT Type | MATLAB Data Type (scalar or array data) | Comments |
|---|---|---|
| VT_EMPTY | Not applicable | 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 | 1. VARIANT dates are stored as doubles
starting at midnight Dec. 31, 1899. The 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. |
| 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 upon the rules for the particular VARIANT obtained. Currently, support exists for Excel Range objects as well as the MATLAB Builder EX types MWStruct, MWComplex, MWSparse, and MWArg. See Utility Library for Microsoft COM Components for information on the MATLAB Builder EX types. |
| <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. |
 | Data Conversion | Array Formatting Flags |  |
Includes the most popular MATLAB recorded presentations with Q&A sessions led by MATLAB experts.
| © 1984-2012- The MathWorks, Inc. - Site Help - Patents - Trademarks - Privacy Policy - Preventing Piracy - RSS |
