Main Content

Handle COM Data in MATLAB

Pass Data to COM Objects

When you use a COM object in a MATLAB® command, the MATLAB types you pass in the call are converted to types native to the COM object. MATLAB performs this conversion on each argument that is passed. This section describes the conversion.

MATLAB converts MATLAB arguments into types that best represent the data to the COM object. The following table shows all the MATLAB base types for passed arguments and the COM types defined for input arguments. Each row shows a MATLAB type followed by the possible COM argument matches. For a description of COM variant types, see the table in Handle Data from COM Objects.

MATLAB ArgumentClosest COM TypeAllowed Types
handleVT_DISPATCH
VT_UNKNOWN
VT_DISPATCH
VT_UNKNOWN
character vector VT_BSTRVT_LPWSTR
VT_LPSTR
VT_BSTR
VT_FILETIME
VT_ERROR
VT_DECIMAL
VT_CLSID
VT_DATE
int16 VT_I2VT_I2
uint16VT_UI2VT_UI2
int32VT_I4VT_I4
VT_INT
uint32VT_UI4VT_UI4
VT_UINT
int64VT_I8VT_I8
uint64VT_UI8VT_UI8
singleVT_R4VT_R4
double VT_R8VT_R8
VT_CY
logicalVT_BOOL VT_BOOL
char VT_I1VT_I1
VT_UI1

Variant Data

variant is any data type except a structure or a sparse array. (For more information, see Fundamental MATLAB Classes.)

When used as an input argument, MATLAB treats variant and variant(pointer) the same way.

If you pass an empty array ([]) of type double, MATLAB creates a variant(pointer) set to VT_EMPTY. Passing an empty array of any other numeric type is not supported.

MATLAB ArgumentClosest COM TypeAllowed Types
variant VT_VARIANTVT_VARIANT
VT_USERDEFINED
VT_ARRAY
variant(pointer)VT_VARIANTVT_VARIANT | VT_BYREF

SAFEARRAY Data

When a COM method identifies a SAFEARRAY or SAFEARRAY(pointer), the MATLAB equivalent is a matrix.

MATLAB ArgumentClosest COM TypeAllowed Types
SAFEARRAYVT_SAFEARRAYVT_SAFEARRAY
SAFEARRAY(pointer) VT_SAFEARRAYVT_SAFEARRAY | VT_BYREF

Handle Data from COM Objects

Data returned from a COM object is often incompatible with MATLAB types. When this occurs, MATLAB converts the returned value to a data type native to the MATLAB language. This section describes the conversion performed on the various types that can be returned from COM objects.

The following table shows how MATLAB converts data from a COM object into MATLAB variables.

COM Variant Type

Description

MATLAB Representation

VT_DISPATCH

IDispatch *

handle
VT_LPWSTR
VT_LPSTR
VT_BSTR
VT_FILETIME
VT_ERROR
VT_DECIMAL
VT_CLSID
VT_DATE

wide null terminated string
null terminated string
OLE Automation string
FILETIME
SCODE
16-byte fixed point
Class ID
date

character vector
VT_INT
VT_UINT
VT_I2
VT_UI2
VT_I4
VT_UI4
VT_R4
VT_R8
VT_CY

signed machine int
unsigned machine int
2-byte signed int
unsigned short
4-byte signed int
unsigned long
4-byte real
8-byte real
currency

double
VT_I8

signed int64

int64
VT_UI8

unsigned int64

uint64
VT_BOOL  logical
VT_I1
VT_UI1
signed char
unsigned char
char
VT_VARIANT
VT_USERDEFINED
VT_ARRAY

VARIANT *
user-defined type
SAFEARRAY*

variant
VT_VARIANT | VT_BYREF

VARIANT *
void* for local use

variant(pointer)
VT_SAFEARRAY

use VT_ARRAY in VARIANT

SAFEARRAY
VT_SAFEARRAY | VT_BYREF SAFEARRAY(pointer)

Unsupported Types

MATLAB does not support the following COM interface types.

  • Structure

  • Sparse array

  • Multidimensional SAFEARRAYs (greater than two dimensions)

  • Write-only properties

Pass MATLAB SAFEARRAY to COM Object

The SAFEARRAY data type is a standard way to pass arrays between COM objects. This section explains how MATLAB passes SAFEARRAY data to a COM object.

Default Behavior in MATLAB

MATLAB represents an m-by-n matrix as a two-dimensional SAFEARRAY, where the first dimension has m elements and the second dimension has n elements. MATLAB passes the SAFEARRAY by value.

Examples

The following examples use a COM object that expects a SAFEARRAY input parameter.

When MATLAB passes a 1-by-3 array:

B = [2 3 4]
B =
     2     3     4

the object reads:

No. of dimensions: 2
Dim: 1, 	 No. of elements: 1 
Dim: 2, 	 No. of elements: 3 
	 	 Elements: 
	 	 2.0 
	 	 3.0 
	 	 4.0

When MATLAB passes a 3-by-1 array:

C = [1;2;3]
C =
     1
     2
     3

the object reads:

No. of dimensions: 2
Dim: 1, 	 No. of elements: 3 
Dim: 2, 	 No. of elements: 1 
Elements: 
	 	 1.0 
	 	 2.0 
	 	 3.0

When MATLAB passes a 2-by-4 array:

D = [2 3 4 5;5 6 7 8]

D =
     2     3     4     5
     5     6     7     8

the object reads:

No. of dimensions: 2
Dim: 1, 	 No. of elements: 2 
Dim: 2, 	 No. of elements: 4 
Elements: 
	 	 2.0 
	 	 3.0 
	 	 4.0 
	 	 5.0 
	 	 5.0 
	 	 6.0 
	 	 7.0 
	 	 8.0

Pass Single-Dimension SAFEARRAY

For information, see How can I pass arguments to an ActiveX server from MATLAB 7.0 (R14) as one-dimensional arrays?

Pass SAFEARRAY by Reference

For information, see How can I pass arguments by reference to an ActiveX server from MATLAB 7.0 (R14)?

Read SAFEARRAY from COM Objects in MATLAB Applications

This section explains how MATLAB reads SAFEARRAY data from a COM object.

MATLAB reads a one-dimensional SAFEARRAY with n elements from a COM object as a 1-by-n matrix.

MATLAB reads a two-dimensional SAFEARRAY with n elements as a 2-by-n matrix.

MATLAB reads a three-dimensional SAFEARRAY with two elements as a 2-by-2-by-2 cell array.

Display MATLAB Syntax for COM Objects

To determine which MATLAB types to use when passing arguments to COM objects, use the invoke or methodsview functions. These functions list all the methods found in an object, along with a specification of the types required for each argument.

Consider a server called MyApp, which has a single method TestMeth1 with the following syntax:

HRESULT TestMeth1 ([out, retval] double* dret);

This method has no input argument, and it returns a variable of type double. The following pseudo-code displays the MATLAB syntax for calling the method.

h = actxserver('MyApp');
invoke(h)

MATLAB displays:

ans = 
   TestMeth1 = double TestMeth1 (handle)

The signature of TestMeth1 is:

double TestMeth1(handle)

MATLAB requires you to use an object handle as an input argument for every method, in addition to any input arguments required by the method itself.

Use one of the following pseudo-code commands to create the variable var, which is of type double.

var = h.TestMeth1;

or:

var = TestMeth1(h);

Although the following syntax is correct, its use is discouraged:

var = invoke(h,'TestMeth1');

Now consider the server called MyApp1 with the following methods:

HRESULT TestMeth1 ([out, retval] double* dret);
HRESULT TestMeth2 ([in] double* d, [out, retval] double* dret);
HRESULT TestMeth3 ([out] BSTR* sout,
                   [in, out] double* dinout,
                   [in, out] BSTR* sinout,
                   [in] short sh,
                   [out] long* ln,
                   [in, out] float* b1,
                   [out, retval] double* dret);

Using the invoke function, MATLAB displays the list of methods:

ans = 
   TestMeth1 = double TestMeth1 (handle)
   TestMeth2 = double TestMeth2 (handle, double)
   TestMeth3 = [double, string, double, string, int32, single] ...
               TestMeth3(handle, double, string, int16, single)

TestMeth2 requires an input argument d of type double, and returns a variable dret of type double. Some pseudo-code examples of calling TestMeth2 are:

var = h.TestMeth2(5);

or:

var = TestMeth2(h, 5);

TestMeth3 requires multiple input arguments, as indicated within the parentheses on the right side of the equal sign, and returns multiple output arguments, as indicated within the brackets on the left side of the equal sign.

[double, string, double, string, int32, single]  %output arguments
TestMeth3(handle, double, string, int16, single) %input arguments

The first input argument is the required handle, followed by four input arguments.

TestMeth3(handle, in1, in2, in3, in4)

The first output argument is the return value retval, followed by five output arguments.

[retval, out1, out2, out3, out4, out5]

This is how the arguments map into a MATLAB command:

[dret, sout, dinout, sinout, ln, b1] = TestMeth3(handle, ...
                                       dinout, sinout, sh, b1)

where dret is double, sout is string, dinout is double and is both an input and an output argument, sinout is string (input and output argument), ln is int32, b1 is single (input and output argument), handle is the handle to the object, and sh is int16.