Using Flags to Control Array Formatting and Data Conversion

Overview

Generally, you should write your application code so that it matches the arguments (input and output) of the MATLAB functions that are encapsulated in the COM objects that you are using. The mapping of arguments from the MATLAB product to Microsoft Visual Basic is fully described in MATLAB to COM VARIANT Conversion Rules and COM VARIANT to MATLAB Conversion Rules.

In some cases it is not possible to match the two kinds of arguments exactly; for example, when existing MATLAB code is used in conjunction with a third-party product such as Microsoft Excel. For these and other cases, the builder supports formatting and conversion flags that control how array data is formatted in both directions (input and output).

When it creates a component, the builder includes a component property named MWFlags. The MWFlags property is readable and writable.

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.

Back to Top

Array Formatting Flags

The following tables provide a quick overview of how to use array formatting flags to specify conversions for input and output arguments.

Back to Top

Using Array Formatting Flags

To use the following example, make sure that you reference the MWComUtil library in the current project:

1. Select Tools > References.

2. Click MWComUtil 7.5 Type Library.

Consider the following Microsoft Visual Basic function definition for foo:

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

The example has two Variant variables, var1 and var2. These two variables contain the same numerical data, but internally they are structured differently; one is a 2-by-2 array of variant and the other is a 1-by-1 array of variant. The variables are described in the following table.

11    12
21    22

11    12
21    22

The InputArrayFormat flag controls how the arrays are handled. In this example, the value for the InputArrayFormat flag is the default, which is mwArrayFormatMatrix. The default causes an array to be converted to a matrix. See the table for the result of the conversion of var2.

To specify a cell array (instead of a matrix) as input to the function call, set the InputArrayFormat flag to mwArrayFormatCell instead of the default. Do this in this example by adding the following line after creating the class and before the method call:

aClass .MWFlags.ArrayFormatFlags.InputArrayFormat = 
mwArrayFormatCell

Setting the flag to mwArrayFormatCell causes all array input to the encapsulated MATLAB function to be converted to cell arrays.

Modifying Output Format

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.

Output Format in VBScript

When calling a COM object in VBScript you need to make sure that you set MWFlags for the COM object to specify cell array for the output. Also, you must use an enumeration (the enumeration value for a cell array is 2) to make the specification (rather than specifying mwArrayFormatCell).

The following sample code shows how to accomplish this:

obj.MWFlags.ArrayFormatFlags.OutputArrayFormat = 2

Back to Top

Using Data Conversion Flags

Two data conversion flags, CoerceNumericToType and InputDateFormat, govern how numeric and date types are converted from Visual Basic to MATLAB.

To use the following example, make sure that you reference the MWComUtil library in the current project:

1. Select Tools > References.

2. Click MWComUtil 7.5 Type Library.

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

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

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. As an alternative, you can set the CoerceNumericToType flag to mwTypeDouble, causing the data converter to convert all numeric input to double. To do this, place the following line after creating the class and before calling the methods:

aClass .MWFlags.DataConversionFlags.CoerceNumericToType = 
mwTypeDouble

The next example shows how to use the InputDateFormat flag, which controls how the Visual Basic Date type is converted. The 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 ytemp = New MWArg
	ytemp.MWFlags.DataConversionFlags.OutputAsDate = True
	Call aClass.foo(2, ytemp, y2, today)
	y1 = ytemp
	Exit Sub
Handle_Error:
	MsgBox(Err.Description)
End Sub

Back to Top

Special Flags for Some Microsoft Visual Basic Types

In general, you use the MWFlags class property to change specified behaviors of the conversion from Microsoft Visual Basic Variant types to MATLAB types, and vice versa. There are some exceptions — some types generated by the builder have their own MWFlags property. When you use these particular types, the method call behaves according to the settings of the type and not of the class containing the method being called. The exceptions are for the following types generated by the builder:

• MWStruct

• MWField

• MWComplex

• MWSparse

• MWArg

Note   The MWArg class is supplied specifically for the case when a particular argument needs different settings from the default class properties.

Back to Top

Passing Arguments

Using MATLAB Global Variables in Microsoft Visual Basic

Recommended Products

• MATLAB
• Signal Processing Toolbox
• Optimization Toolbox
• Statistics Toolbox
• Control System Toolbox

Get MATLAB trial software

Includes the most popular MATLAB recorded presentations with Q&A sessions led by MATLAB experts.

Get the Interactive Kit