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 compiler supports formatting and conversion flags that control how array data is formatted in both directions (input and output).

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

The MWFlags property consists of two sets of constants: arrayformattingflags and dataconversionflags. Array formatting flags affect the transformation of arrays, whereas data conversion flags deal with type conversions of individual array elements.

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.

Name of Flag	Possible Values of Flag	Results of Conversion
`InputArrayFormat`	`mwArrayFormatMatrix` (default)	MATLAB matrix from general `Variant` data.
	`mwArrayFormatCell`	MATLAB cell array from general `Variant` data.
	Array data from an Excel `range` is coded in Visual Basic as an array of `Variant`. Since MATLAB functions typically have matrix arguments, using the default setting makes sense when you are dealing with data from Excel.
`OutputArrayFormat`	`mwArrayFormatAsIs`	Array of `Variant`
	Converts arrays according to the default conversion rules listed in MATLAB to COM VARIANT Conversion Rules.
	`mwArrayFormatMatrix`	A `Variant` containing an array of a basic type.
	`mwArrayFormatCell`	MATLAB cell array from general `Variant` data.
`AutoResizeOutput`	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. Use this flag for Excel `Range` objects passed directly as output parameters.
`TransposeOutput`	Transposes all array output. Use this flag when dealing with an encapsulated MATLAB function whose output is a one-dimensional array. By default, the MATLAB product handles one-dimensional arrays as 1-by-`n` matrices (that is, as row vectors). Change this default with the `TransposeOutput` flag if you prefer column output.

Using Array Formatting Flags

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.

Scenario	var1	var2
Numerical data	11 12 21 22	11 12 21 22
Internal structure in Visual Basic	2-by-2 array of `Variant`. Each `variant` is a 1-by-1 array of `Double`.	1-by-1 `Variant`, which contains a 2-by-2 array of `Double`
Result of conversion by the compiler according to the default data conversion rules	2-by-2 cell array. Each element is a 1-by-1 array of `double`.	2-by-2 matrix. Each element is a `Double`.

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

Using Data Conversion Flags

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

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

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 compiler 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 compiler:

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.