Main Content

Class MWFlags

The MWFlags class contains a set of array formatting and data conversion flags. For more information on conversion between MATLAB® and COM Automation types, see Rules for Data Conversion Between .NET and MATLAB (MATLAB Compiler SDK). All MATLAB Compiler SDK™ COM components contain a reference to an MWFlags object that can modify data conversion rules at the object level. This class contains these properties and method:

Property ArrayFormatFlags As MWArrayFormatFlags

The ArrayFormatFlags property controls array formatting (as a matrix or a cell array) and the application of these rules to nested arrays. The MWArrayFormatFlags class is a noncreatable class accessed through an MWFlags class instance. This class contains six properties:

Property InputArrayFormat As mwArrayFormat

This property of type mwArrayFormat controls the formatting of arrays passed as input parameters to MATLAB Compiler SDK class methods. The default value is mwArrayFormatMatrix. The behaviors indicated by this flag are listed in the next table.

Array Formatting Rules for Input Arrays

ValueBehavior

mwArrayFormatAsIs

Converts arrays according to the default conversion rules listed in Rules for Data Conversion Between .NET and MATLAB (MATLAB Compiler SDK).

mwArrayFormatCell

Coerces all arrays into cell arrays. Input scalar or numeric array arguments are converted to cell arrays with each cell containing a scalar value for the respective index.

mwArrayFormatMatrix

Coerces all arrays into matrices. When an input argument is encountered that is an array of Variants (the default behavior is to convert it to a cell array), the data converter converts this array to a matrix if each Variant is single valued, and all elements are homogeneous and of a numeric type. If this conversion is not possible, creates a cell array.

Property InputArrayIndFlag As Long

This property governs the level at which to apply the rule set by the InputArrayFormat property for nested arrays (an array of Variants is passed and each element of the array is an array itself). It is not necessary to modify this flag for varargin parameters. The data conversion code automatically increments the value of this flag by 1 for varargin cells, thus applying the InputArrayFormat flag to each cell of a varargin parameter. The default value is 0.

Property OutputArrayFormat As mwArrayFormat

This property of type mwArrayFormat controls the formatting of arrays passed as output parameters to class methods. The default value is mwArrayFormatAsIs. The behaviors indicated by this flag are listed in the next table.

Array Formatting Rules for Output Arrays

ValueBehavior

mwArrayFormatAsIs

Converts arrays according to the default conversion rules listed in Rules for Data Conversion Between .NET and MATLAB (MATLAB Compiler SDK).

mwArrayFormatMatrix

Coerces all arrays into matrices. When an output cell array argument is encountered (the default behavior converts it to an array of Variants), the data converter converts this array to a Variant that contains a simple numeric array if each cell is single valued, and all elements are homogeneous and of a numeric type. If this conversion is not possible, an array of Variants is created.

mwArrayFormatCell

Coerces all output arrays into arrays of Variants. Output scalar or numeric array arguments are converted to arrays of Variants, each Variant containing a scalar value for the respective index.

Property OutputArrayIndFlag As Long

This property is similar to the InputArrayIndFalg property, as it governs the level at which to apply the rule set by the OutputArrayFormat property for nested arrays. As with the input case, this flag is automatically incremented by 1 for a varargout parameter. The default value of this flag is 0.

Property AutoResizeOutput As Boolean

This flag applies to Excel® ranges only. When the target output from a method call is a range of cells in an Excel worksheet, and the output array size and shape is not known at the time of the call, setting this flag to True instructs the data conversion code to resize each Excel range to fit the output array. Resizing is applied relative to the upper left corner of each supplied range. The default value for this flag is False.

Property TransposeOutput As Boolean

Setting this flag to True transposes the output arguments. This flag is useful when processing an output parameter from a method call on a COM component, where the MATLAB function returns outputs as row vectors, and you want to place the data into columns. The default value for this flag is False.

Property DataConversionFlags As MWDataConversionFlags

The DataConversionFlags property controls how input variables are processed when type coercion is needed. The MWDataConversionFlags class is a noncreatable class accessed through an MWFlags class instance. This class contains these properties:

Property CoerceNumericToType As mwDataType

This property converts all numeric input arguments to one specific MATLAB type. This flag is useful is when variables maintained within the Visual Basic® code are different types, e.g., Long, Integer, etc., and all variables passed to the compiled MATLAB code must be doubles. The default value for this property is mwTypeDefault, which uses the default rules in Rules for Data Conversion Between .NET and MATLAB (MATLAB Compiler SDK).

PropertyDateBias As Long

This property sets the date bias for performing COM to MATLAB numeric date conversions. The default value of this property is 693960, representing the difference between the COM Date type and MATLAB numeric dates. This flag allows existing MATLAB code that already performs the increment of numeric dates by 693960 to be used unchanged with COM components. To process dates with such code, set this property to 0.

This example uses data conversion flags to reshape the output from a method compiled from a MATLAB function that produces an output vector of unknown length. 

function p = myprimes(n)
if length(n)~=1, error('N must be a scalar'); end
if n < 2, p = zeros(1,0); return, end
p = 1:2:n;
q = length(p);
p(1) = 2;
for k = 3:2:sqrt(n)
    if p((k+1)/2)
        p(((k*k+1)/2):k:q) = 0;
    end
end
p = (p(p>0));

This function produces a row vector of all the prime numbers between 0 and n. Assume that this function is included in a class named myclass that is included in a component named mycomponent with a version of 1.0. The subroutine takes an Excel range and a Double as inputs, and places the generated prime numbers into the supplied range. The MATLAB function produces a row vector, although you want the output in column format. It also produces an unknown number of outputs, and you do not want to truncate any output. To handle these issues, set the TransposeOutput flag and the AutoResizeOutput flag to True. In previous examples, the Visual Basic CreateObject function creates the necessary classes. This example uses an explicit type declaration for the aClass variable. As with previous examples, this function assumes that MWInitApplication has been previously called.

Sub GenPrimes(R As Range, n As Double)
    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.myprimes(1, R, n)
    Exit Sub
Handle_Error:
    MsgBox (Err.Description)
End Sub

Property InputDateFormat As mwDateFormat

This property converts dates passed as input parameters to method calls on MATLAB Compiler SDK classes. The default value is mwDateFormatNumeric. The behaviors indicated by this flag are shown in the following table.

Conversion Rules for Input Dates

ValueBehavior

mwDateFormatNumeric

Convert dates to numeric values as indicated by the rule listed in Rules for Data Conversion Between .NET and MATLAB (MATLAB Compiler SDK).

mwDateFormatString

Convert input dates to strings.

PropertyOutputAsDate As Boolean

This property processes an output argument as a date. By default, numeric dates that are output parameters from compiled MATLAB functions are passed as Doubles that need to be decremented by the COM date bias (693960) as well as coerced to COM dates. Set this flag to True to convert all output values of type Double.

ReplaceMissing As mwReplaceMissingData

This property is an enumeration and can have two possible values: mwReplaceNaN and mwReplaceZero.

To treat empty cells referenced by input parameters as zeros, set the value to mwReplaceZero. To treat empty cells referenced by input parameters as NaNs (Not a Number), set the value to mwReplaceNaN.

By default, the value is mwReplaceZero.

Sub Clone(ppFlags As MWFlags)

Creates a copy of an MWFlags object.

Parameters

ArgumentTypeDescription

ppFlags

MWFlags

Reference to an uninitialized MWFlags object that receives the copy

Return Value

None

Remarks

Clone allocates a new MWFlags object and creates a deep copy of the object's contents. Call this function when a separate object is required instead of a shared copy of an existing object reference.