Utility Library (MATLAB COM Builder)

MATLAB COM Builder

Class MWFlags

The MWFlags class contains a set of array formatting and data conversion flags (See Data Conversion Rules for more information on conversion between MATLAB and COM Automation types). All MATLAB COM Builder components contain a reference to an MWFlags object that can modify data conversion rules at the object level. This class contains these properties:

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 COM Builder class methods. The default value is mwArrayFormatMatrix. The behaviors indicated by this flag are listed in the next table.

Table D-1: Array Formatting Rules for Input Arrays
Value
Behavior

mwArrayFormatAsIs
Converts arrays according to the default conversion rules listed in Table B-3, COM VARIANT to MATLAB Conversion Rules,.

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.

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.

**Table D-1: Array Formatting Rules for Input Arrays**
Value	Behavior
`mwArrayFormatAsIs`	Converts arrays according to the default conversion rules listed in Table B-3, COM VARIANT to MATLAB Conversion Rules,.
`mwArrayFormatMatrix`	Coerces all arrays into matrices. When an input argument is encountered that is an array of `Variant`s (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.
`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.

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 COM Builder class methods. The default value is mwArrayFormatAsIs. The behaviors indicated by this flag are listed in the next table.

Table D-2: Array Formatting Rules for Output Arrays
Value
Behavior

mwArrayFormatAsIs
Converts arrays according to the default conversion rules listed in Table B-2, MATLAB to COM VARIANT Conversion Rules,.

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.

**Table D-2: Array Formatting Rules for Output Arrays**
Value	Behavior
`mwArrayFormatAsIs`	Converts arrays according to the default conversion rules listed in Table B-2, MATLAB to COM VARIANT Conversion Rules,.
`mwArrayFormatMatrix`	Coerces all arrays into matrices. When an output cell array argument is encountered (the default behavior converts it to an array of `Variant`s), 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 `Variant`s is created.
`mwArrayFormatCell`	Coerces all output arrays into arrays of `Variant`s. Output scalar or numeric array arguments are converted to arrays of `Variant`s, 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 an COM Builder component, where the MATLAB function returns outputs as row vectors, and you desire 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 COM VARIANT to MATLAB Conversion Rules.

Property InputDateFormat As mwDateFormat. This property converts dates passed as input parameters to method calls on COM Builder classes. The default value is mwDateFormatNumeric. The behaviors indicated by this flag are shown in Table D-3, Conversion Rules for Input Dates.

Table D-3: Conversion Rules for Input Dates
Value
Behavior

mwDateFormatNumeric
Convert dates to numeric values as indicated by the rule listed in Table B-3, COM VARIANT to MATLAB Conversion Rules,.

mwDateFormatString
Convert input dates to strings.

**Table D-3: Conversion Rules for Input Dates**
Value	Behavior
`mwDateFormatNumeric`	Convert dates to numeric values as indicated by the rule listed in Table B-3, COM VARIANT to MATLAB Conversion Rules,.
`mwDateFormatString`	Convert input dates to strings.

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

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

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.

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 Builder components. To process dates with such code, set this property to 0.

Sub Clone(ppFlags As MWFlags)

Creates a copy of an MWFlags object.

Parameters.

Argument
Type
Description

ppFlags
MWFlags
Reference to an uninitialized MWFlags object that receives the copy.

Argument	Type	Description
`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.

Class MWUtil Class MWStruct