Learn more about MATLAB

Handling COM Data in MATLAB Software

On this page…
Passing Data to a COM Object Handling Data from a COM Object Unsupported Types Passing MATLAB Data to ActiveX Objects Passing MATLAB SAFEARRAY to COM Object Reading SAFEARRAY from a COM Object in MATLAB Applications Displaying MATLAB Syntax for COM Objects

Passing Data to a COM Object

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 arguments are converted by MATLAB 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 Handling Data from a COM Object.

MATLAB Argument	Closest COM Type	Allowed Types
handle	VT_DISPATCH VT_UNKNOWN	VT_DISPATCH VT_UNKNOWN
string	VT_BSTR	VT_LPWSTR VT_LPSTR VT_BSTR VT_FILETIME VT_ERROR VT_DECIMAL VT_CLSID VT_DATE
int16	VT_I2	VT_UINT VT_I2 VT_UI2
int32	VT_I4	VT_I4 VT_UI4 VT_INT
single	VT_R4	VT_R4
double	VT_R8	VT_R8 VT_CY
bool	VT_BOOL	VT_BOOL
char	VT_I1	VT_I1 VT_UI1

Variant Data

variant is any data type except a structure or a sparse array. (Refer to the Data Type Summary table in the MATLAB Programming Fundamentals documentation.)

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

MATLAB Argument	Closest COM Type	Allowed Types
variant	VT_VARIANT	VT_VARIANT VT_USERDEFINED VT_ARRAY
variant(pointer)	VT_VARIANT	VT_VARIANT | VT_BYREF

SAFEARRAY Data

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

MATLAB Argument	Closest COM Type	Allowed Types
SAFEARRAY	VT_SAFEARRAY	VT_SAFEARRAY
SAFEARRAY(pointer)	VT_SAFEARRAY	VT_SAFEARRAY | VT_BYREF

Back to Top

Handling Data from a COM Object

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 VT_UNKNOWN	IDispatch * IUnknown *	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	string
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_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)

Back to Top

Unsupported Types

MATLAB does not support the following COM interface types and displays the warning ActiveX - unsupported VARIANT type encountered.

• VT_I8 (signed 64-bit int)

• VT_UI8 (unsigned 64-bit int)

• Structure

• Sparse array

• Unsigned integer

• Multidimensional SAFEARRAYs

• Write-only properties

• Enumerated types

Back to Top

Passing MATLAB Data to ActiveX Objects

The tables also show the mapping of MATLAB types to COM types that you must use to pass data from MATLAB to an Microsoft ActiveX object. For all other types, MATLAB displays the warning ActiveX - invalid argument type or value.

Back to Top

Passing 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 Software

• Examples

• How to Pass a Single-Dimension SAFEARRAY

• Passing SAFEARRAY By Reference

Default Behavior in MATLAB Software

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

How to Pass a Single-Dimension SAFEARRAY

For information about passing arguments as one-dimensional arrays to a COM object, see the Technical Support solution 1-SKYP9 at http://www.mathworks.com/support/solutions/data/1-SKYP9.html.

Passing SAFEARRAY By Reference

For information about passing arguments by reference to a COM object, see the Technical Support solution 1-SKYPY at http://www.mathworks.com/support/solutions/data/1-SKYPY.html.

Back to Top

Reading SAFEARRAY from a COM Object 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. For example, using methods from the MATLAB sample control mwsamp, type:

h=actxcontrol('mwsamp.mwsampctrl.1')
a = h.GetI4Vector

MATLAB displays:

a =
           1           2           3

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

a = h.GetR8Array

MATLAB displays:

a =
     1     2     3
     4     5     6

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

a = h.GetBSTRArray

MATLAB displays:

a(:,:,1) = 

    '1 1 1'    '1 2 1'
    '2 1 1'    '2 2 1'

a(:,:,2) = 

    '1 1 2'    '1 2 2'
    '2 1 2'    '2 2 2'

Back to Top

Displaying 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.

In the following example, a server called MyApp has a 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. To display the MATLAB syntax for calling the method, type:

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

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.

Using the variable var, which is of type double, type:

var = h.TestMeth1;

or:

var = TestMeth1(h);

While 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);

Type the commands:

h = actxserver('MyApp1');
h.invoke

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, as well as returning a variable dret of type double. Some 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 equals sign, and returns multiple output arguments, as indicated within the brackets on the left side of the equals 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.

Back to Top

Saving Your Work

Examples of MATLAB Software as an Automation Client

© 1984-2009- The MathWorks, Inc.    -   Site Help   -   Patents   -   Trademarks   -   Privacy Policy   -   Preventing Piracy   -   RSS