Data Conversion (MATLAB COM Builder)

MATLAB COM Builder

Array Formatting Flags

MATLAB COM Builder components have flags that control how array data is formatted in both directions. Generally, you should develop client code that matches the intended inputs and outputs of the MATLAB functions with the corresponding methods on the compiled COM objects, in accordance with the rules listed in Table B-2 and Table B-3. In some cases this is not possible, e.g., when existing MATLAB code is used in conjunction with a third party product like Excel.

Table B-4 shows the array formatting flags.

Table B-4: Array Formatting Flags
Flag
Description

InputArrayFormat
Defines the array formatting rule used on input arrays. An input array is a VARIANT array, created by the client, sent as an input parameter to a method call on a compiled COM object. Valid values for this flag are mwArrayFormatAsIs, mwArrayFormatMatrix, and mwArrayFormatCell.
mwArrayFormatAsIs passes the array unchanged.
mwArrayFormatMatrix (default) formats all arrays as matrices. When the input VARIANT is of type VT_ARRAY|<type>, where <type> is any numeric type, this flag has no effect. When the input VARIANT is of type VT_VARIANT|VT_ARRAY, VARIANTs in the array are examined. If they are single-valued and homogeneous in type, a MATLAB matrix of the appropriate type is produced instead of a cell array.
mwArrayFormatCell interprets all arrays as MATLAB cell arrays.

InputArrayIndFlag
Sets the input array indirection level used with the InputArrayFormat flag (applicable only to nested arrays, i.e., VARIANT arrays of VARIANTs, which themselves are arrays). The default value for this flag is zero, which applies the InputArrayFormat flag to the outermost array. When this flag is greater than zero, e.g., equal to N, the formatting rule attempts to apply itself to the Nth level of nesting.

OutputArrayFormat
Defines the array formatting rule used on output arrays. An output array is a MATLAB array, created by the compiled COM object, sent as an output parameter from a method call to the client. The values for this flag, mwArrayFormatAsIs, mwArrayFormatMatrix, and mwArrayFormatCell, cause the same behavior as the corresponding InputArrayFormat flag values.

OutputArrayIndFlag
(Applies to nested cell arrays only.) Output array indirection level used with the OutputArrayFormat flag. This flag works exactly like InputArrayIndFlag.

AutoResizeOutput

(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, set this flag to True to resize each Excel range to fit the output array.

TransposeOutput
Set this flag to True to transpose the output arguments. Useful when calling an COM Builder component from Excel where the MATLAB function returns outputs as row vectors, and you want the data in columns.

**Table B-4: Array Formatting Flags**
Flag	Description
`InputArrayFormat`	Defines the array formatting rule used on input arrays. An input array is a VARIANT array, created by the client, sent as an input parameter to a method call on a compiled COM object. Valid values for this flag are `mwArrayFormatAsIs`, `mwArrayFormatMatrix`, and `mwArrayFormatCell`. `mwArrayFormatAsIs` passes the array unchanged. `mwArrayFormatMatrix` (default) formats all arrays as matrices. When the input VARIANT is of type `VT_ARRAY\|<`type`>`, where <type> is any numeric type, this flag has no effect. When the input `VARIANT` is of type `VT_VARIANT\|VT_ARRAY`, `VARIANT`s in the array are examined. If they are single-valued and homogeneous in type, a MATLAB matrix of the appropriate type is produced instead of a cell array. `mwArrayFormatCell` interprets all arrays as MATLAB cell arrays.
`InputArrayIndFlag`	Sets the input array indirection level used with the `InputArrayFormat` flag (applicable only to nested arrays, i.e., VARIANT arrays of VARIANTs, which themselves are arrays). The default value for this flag is zero, which applies the `InputArrayFormat` flag to the outermost array. When this flag is greater than zero, e.g., equal to N, the formatting rule attempts to apply itself to the Nth level of nesting.
`OutputArrayFormat`	Defines the array formatting rule used on output arrays. An output array is a MATLAB array, created by the compiled COM object, sent as an output parameter from a method call to the client. The values for this flag, `mwArrayFormatAsIs`, `mwArrayFormatMatrix`, and `mwArrayFormatCell`, cause the same behavior as the corresponding `InputArrayFormat` flag values.
`OutputArrayIndFlag`	(Applies to nested cell arrays only.) Output array indirection level used with the `OutputArrayFormat` flag. This flag works exactly like `InputArrayIndFlag`.
`AutoResizeOutput`	(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, set this flag to `True` to resize each Excel range to fit the output array.
`TransposeOutput`	Set this flag to `True` to transpose the output arguments. Useful when calling an COM Builder component from Excel where the MATLAB function returns outputs as row vectors, and you want the data in columns.

Data Conversion Rules Data Conversion Flags