Learn more about MATLAB Builder EX

Modifying Flags

On this page…
Overview Array Formatting Flags Data Conversion Flags

Overview

Each MATLAB Builder EX component exposes a single read/write property named MWFlags of type MWFlags. The MWFlags property consists of two sets of constants: array formatting flags and data conversion flags. Array formatting flags affect the transformation of arrays, whereas data conversion flags deal with type conversions of individual array elements.

The data conversion flags change selected behaviors of the data conversion process from Variants to MATLAB types and vice versa. By default, the MATLAB Builder EX components allow setting data conversion flags at the class level through the MWFlags class property. This holds true for all Visual Basic types, with the exception of the MATLAB Builder EX MWStruct, MWField, MWComplex, MWSparse, and MWArg types. Each of these types exposes its own MWFlags property and ignores the properties of the class whose method is being called. The MWArg class is supplied specifically for the case when a particular argument needs different settings from the default class properties.

This section provides a general discussion of how to set these flags and what they do. See Class MWFlags for a detailed discussion of the MWFlags type, as well as additional code samples.

Back to Top

Array Formatting Flags

Array formatting flags guide the data conversion to produce either a MATLAB cell array or matrix from general Variant data on input or to produce an array of Variants or a single Variant containing an array of a basic type on output.

The following examples assume that you have referenced the MWComUtil library in the current project by selecting Tools > References and selecting MWComUtil 7.5 Type Library from the list:

Sub foo( )
   Dim aClass As mycomponent.myclass
   Dim var1(1 To 2, 1 To 2), var2 As Variant
   Dim x(1 To 2, 1 To 2) As Double
   Dim y1,y2 As Variant
   
   On Error Goto Handle_Error
   var1(1,1) = 11#
   var1(1,2) = 12#
   var1(2,1) = 21#
   var1(2,2) = 22#
   x(1,1) = 11
   x(1,2) = 12
   x(2,1) = 21
   x(2,2) = 22
   var2 = x
   Set aClass = New mycomponent.myclass
   Call aClass.foo(1,y1,var1)
   Call aClass.foo(1,y2,var2)
   Exit Sub
Handle_Error:
   MsgBox(Err.Description)
End Sub

In addition, these examples assume you have referenced the COM object created with Builder EX (mycomponent) as mentioned in New Operator.

Here, two Variant variables, var1 and var2 are constructed with the same numerical data, but internally they are structured differently: var1 is a 2-by-2 array of Variants with each element containing a 1-by-1 Double, while var2 is a 1-by-1 Variant containing a 2-by-2 array of Doubles.

In MATLAB Builder EX , when using the default settings, both of these arrays will be converted to 2-by-2 arrays of doubles. This does not follow the general convention listed in COM VARIANT to the MATLAB Conversion Rules. According to these rules, var1 converts to a 2-by-2 cell array with each cell occupied by a 1-by-1 double, and var2 converts directly to a 2-by-2 double matrix.

The two arrays both convert to double matrices because the default value for the InputArrayFormat flag is mwArrayFormatMatrix. The InputArrayFormat flag controls how arrays of these two types are handled. This default is used because array data originating from Excel ranges is always in the form of an array of Variants (like var1 of the previous example), and MATLAB functions most often deal with matrix arguments.

But what if you want a cell array? In this case, you set the InputArrayFormat flag to mwArrayFormatCell. Do this by adding the following line after creating the class and before the method call:

aClass.MWFlags.ArrayFormatFlags.InputArrayFormat = 
mwArrayFormatCell

Setting this flag presents all array input to the compiled MATLAB function as cell arrays.

Similarly, you can manipulate the format of output arguments using the OutputArrayFormat flag. You can also modify array output with the AutoResizeOutput and TransposeOutput flags.

AutoResizeOutput is used for Excel Range objects passed directly as output parameters. When this flag is set, the target range automatically resizes to fit the resulting array. If this flag is not set, the target range must be at least as large as the output array or the data is truncated.

The TransposeOutput flag transposes all array output. This flag is useful when dealing with MATLAB functions that output one-dimensional arrays. By default, MATLAB realizes one-dimensional arrays as 1-by-n matrices (row vectors) that become rows in an Excel worksheet.

You may prefer worksheet columns from row vector output. This example auto-resizes and transposes an output range:

Sub foo(Rout As Range, Rin As Range )
   Dim aClass As mycomponent.myclass

   On Error Goto Handle_Error
   Set aClass = New mycomponent.myclass
   aClass.MWFlags.ArrayFormatFlags.AutoResizeOutput = True
   aClass.MWFlags.ArrayFormatFlags.TransposeOutput = True
   Call aClass.foo(1,Rout,Rin)
   Exit Sub
Handle_Error:
   MsgBox(Err.Description)
End Sub

Back to Top

Data Conversion Flags

Data conversion flags deal with type conversions of individual array elements. The two data conversion flags, CoerceNumericToType and InputDateFormat, govern how numeric and date types are converted from VBA to MATLAB. Consider the example:

Sub foo( )
   Dim aClass As mycomponent.myclass
   Dim var1, var2 As Variant
   Dim y As Variant
   
   On Error Goto Handle_Error
   var1 = 1
   var2 = 2#
   Set aClass = New mycomponent.myclass
   Call aClass.foo(1,y,var1,var2)
   Exit Sub
Handle_Error:
   MsgBox(Err.Description)
End Sub

This example converts var1 of type Variant/Integer to an int16 and var2 of type Variant/Double to a double.

If the original MATLAB function expects doubles for both arguments, this code might cause an error. One solution is to assign a double to var1, but this may not be possible or desirable. In such a case set the CoerceNumericToType flag to mwTypeDouble, causing the data converter to convert all numeric input to double. In the previous example, place the following line after creating the class and before calling the methods:

aClass.MWFlags.DataConversionFlags.CoerceNumericToType = 
mwTypeDouble

The InputDateFormat flag controls how the VBA Date type is converted. This example sends the current date and time as an input argument and converts it to a string:

Sub foo( )
   Dim aClass As mycomponent.myclass
   Dim today As Date
   Dim y As Variant
   
   On Error Goto Handle_Error
   today = Now
   Set aClass = New mycomponent.myclass
   aClass. MWFlags.DataConversionFlags.InputDateFormat = 
mwDateFormatString
   Call aClass.foo(1,y,today)
   Exit Sub
Handle_Error:
   MsgBox(Err.Description)
End Sub

The next example uses an MWArg object to modify the conversion flags for one argument in a method call. In this case the first output argument (y1) is coerced to a Date, and the second output argument (y2) uses the current default conversion flags supplied by aClass.

Sub foo(y1 As Variant, y2 As Variant)
    Dim aClass As mycomponent.myclass
    Dim ytemp As MWArg
	Dim today As Date

	On Error Goto Handle_Error
	today = Now
	Set aClass = New mycomponent.myclass
	Set y1 = New MWArg
	y1.MWFlags.DataConversionFlags.OutputAsDate = True
	Call aClass.foo(2, ytemp, y2, today)
	y1 = ytemp.Value
	Exit Sub
Handle_Error:
	MsgBox(Err.Description)
End Sub

Back to Top

Handling Errors During a Method Call

Improving Data Access Using the MCR User Data Interface, COM Components, and MATLAB Builder EX

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