Class MWUtil

The MWUtil class contains a set of static utility methods used in array processing and application initialization. This class is implemented internally as a singleton (only one global instance of this class per instance of Microsoft^® Excel^®). It is most efficient to declare one variable of this type in global scope within each module that uses it. The methods of MWUtil are listed below.

The function prototypes use Visual Basic^® syntax.

Sub MWInitApplication(pApp As Object)

Initializes the library with the current instance of Microsoft Excel.

Parameters

Argument	Type	Description
`pApp`	`Object`	A valid reference to the current Excel application

Return Value

None.

Remarks

This function must be called once for each session of Excel that uses COM components created by MATLAB^® Compiler™. An error is generated if a method call is made to a member class of any MATLAB Compiler SDK™ COM component, and the library has not been initialized.

Example

This Visual Basic sample initializes the MWComUtil library with the current instance of Excel. A global variable of type Object named MCLUtil holds an instance of the MWUtil class, and another global variable of type Boolean named bModuleInitialized stores the status of the initialization process. The private subroutine InitModule() creates an instance of the MWComUtil class and calls the MWInitApplication method with an argument of Application. Once this function succeeds, all subsequent calls exit without recreating the object.

Dim MCLUtil As Object
Dim bModuleInitialized As Boolean

Private Sub InitModule()
    If Not bModuleInitialized Then
        On Error GoTo Handle_Error
        If MCLUtil Is Nothing Then
            Set MCLUtil = CreateObject("MWComUtil.MWUtil")
        End If
        Call MCLUtil.MWInitApplication(Application)
        bModuleInitialized = True
        Exit Sub
Handle_Error:
        bModuleInitialized = False
    End If
End Sub

Note

If you are developing concurrently with multiple versions of MATLAB and MWComUtil.dll, for example, using the following syntax requires you to recompile your COM modules every time you upgrade.

Set MCLUtil = CreateObject("MWComUtil.MWUtil")

To avoid this, make your call to the MWUtil module version-specific, where x.x is the specific version number.

Set MCLUtil = CreateObject("MWComUtil.MWUtilx.x")

Sub MWInitApplicationWithMCROptions(pApp As Object, [mcrOptionList])

Start MATLAB Runtime with MATLAB Runtime options. Similar to mclInitializeApplication.

Parameters

Argument Type Description

Argument	Type	Description
`pApp`	`Object`	A valid reference only when called from an Excel application Non Excel COM clients pass in `Empty`.

pApp

Object

A valid reference only when called from an Excel application

Non Excel COM clients pass in Empty.

Return Value

None.

Remarks

Call this function to pass in MATLAB Runtime options (nojvm, logfile, etc.). Call this function once per process.

Example

This Visual Basic sample initializes the MWComUtil library with the current instance of Excel. A global variable of type Object named MCLUtil holds an instance of the MWUtil class, and another global variable of type Boolean named bModuleInitialized stores the status of the initialization process. The private subroutine InitModule() creates an instance of the MWComUtil class and calls the MWInitApplicationWithMCROptions method with an argument of Application and a string array that contains the options. Once this function succeeds, all subsequent calls exit without recreating the object. When this function successfully executes, the MATLAB Runtime starts up with no JVM^® and a logfile named logfile.txt.

Dim MCLUtil As Object
Dim bModuleInitialized As Boolean

Private Sub InitModule()
    If Not bModuleInitialized Then
        On Error GoTo Handle_Error
        If MCLUtil Is Nothing Then
            Set MCLUtil = CreateObject("MWComUtil.MWUtil")
        End If
			 Dim mcrOptions(1 To 3) as String
			 mcrOptions(1) = "-nojvm"
			 mcrOptions(2) = "-logfile"
			 mcrOptions(3) = "logfile.txt"
        Call MCLUtil.MWInitApplicationWithMCROptions(Application, mcrOptions)
        bModuleInitialized = True
        Exit Sub
Handle_Error:
        bModuleInitialized = False
    End If
End Sub

Note

If you are not using Excel, pass in Nothing instead of Application to MWInitApplicationWithMCROptions.

Function IsMCRJVMEnabled() As Boolean

Returns true if MATLAB Runtime is launched with JVM; otherwise returns false.

Parameters

None.

Return Value

Boolean

Function IsMCRInitialized() As Boolean

Returns true if MATLAB Runtime is initialized; otherwise returns false

Parameters

None.

Return Value

Boolean

Sub MWPack(pVarArg, [Var0], [Var1], ... ,[Var31])

Packs a variable length list of Variant arguments into a single Variant array. This function is typically used for creating a varargin cell from a list of separate inputs. Each input in the list is only added to the array if it is not empty or missing. (In Visual Basic, a missing parameter is denoted by a Variant type of vbError with a value of &H80020004.)

Parameters

Argument	Type	Description
`pVarArg`	`Variant`	Receives the resulting array
`[Var0], [Var1], ...`	`Variant`	Optional list of `Variant`s to pack into the array. From 0 to 32 arguments can be passed.

Return Value

None.

Remarks

This function always frees the contents of pVarArg before processing the list.

Example

This example uses MWPack in a formula function to produce a varargin cell to pass as an input parameter to a method compiled from a MATLAB function with the following signature:

function y = mysum(varargin)
    y = sum([varargin{:}]);

The function returns the sum of the elements in varargin. Assume that this function is a method of a class named myclass that is included in a component named mycomponent with a version of 1.0. The Visual Basic function allows up to 10 inputs, and returns the result y. If an error occurs, the function returns the error message. This function assumes that MWInitApplication has been previously called.

Function mysum(Optional V0 As Variant, _
               Optional V1 As Variant, _
               Optional V2 As Variant, _
               Optional V3 As Variant, _
               Optional V4 As Variant, _
               Optional V5 As Variant, _
               Optional V6 As Variant, _
               Optional V7 As Variant, _
               Optional V8 As Variant, _
               Optional V9 As Variant) As Variant
Dim y As Variant
Dim varargin As Variant
Dim aClass As Object
Dim aUtil As Object
    
    On Error Goto Handle_Error
    Set aClass = CreateObject("mycomponent.myclass.1_0")
    Set aUtil = CreateObject("MWComUtil.MWUtil")
    Call aUtil.MWPack(varargin,V0,V1,V2,V3,V4,V5,V6,V7,V8,V9)
    Call aClass.mysum(1, y, varargin)
    mysum = y
    Exit Function
Handle_Error:
    mysum = Err.Description
End Function

Sub MWUnpack(VarArg, [nStartAt As Long], [bAutoResize As Boolean = False], [pVar0], [pVar1], ..., [pVar31])

Unpacks an array of Variants into individual Variant arguments. This function provides the reverse functionality of MWPack and is typically used to process a varargout cell into individual Variants.

Parameters

Argument	Type	Description
`VarArg`	`Variant`	Input array of `Variant`s to be processed
`nStartAt`	`Long`	Optional starting index (zero-based) in the array to begin processing. Default = `0`.
`bAutoResize`	`Boolean`	Optional auto-resize flag. If this flag is `True`, any Excel range output arguments are resized to fit the dimensions of the `Variant` to be copied. The resizing process is applied relative to the upper left corner of the supplied range. Default = `False`.
`[pVar0],[pVar1], ...`	`Variant`	Optional list of `Variant`s to receive the array items contained in `VarArg`. From 0 to 32 arguments can be passed.

Return Value

None.

Remarks

This function can process a Variant array in one single call or through multiple calls using the nStartAt parameter.

Example

This example uses MWUnpack to process a varargout cell into several Excel ranges, while auto-resizing each range. The varargout parameter is supplied from a method that has been compiled from the MATLAB function.

function varargout = randvectors
    for i=1:nargout
        varargout{i} = rand(i,1);
    end

This function produces a sequence of nargout random column vectors, with the length of the ith vector equal to i. 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 Visual Basic subroutine takes no arguments and places the results into Excel columns starting at A1, B1, C1, and D1. If an error occurs, a message box displays the error text. This function assumes that MWInitApplication has been previously called.

Sub GenVectors()
    Dim aClass As Object
    Dim aUtil As Object
    Dim v As Variant
    Dim R1 As Range
    Dim R2 As Range
    Dim R3 As Range
    Dim R4 As Range
    
    On Error GoTo Handle_Error
    Set aClass = CreateObject("mycomponent.myclass.1_0")
    Set aUtil = CreateObject("MWComUtil.MWUtil")
    Set R1 = Range("A1")
    Set R2 = Range("B1")
    Set R3 = Range("C1")
    Set R4 = Range("D1")
    Call aClass.randvectors(4, v)
    Call aUtil.MWUnpack(v,0,True,R1,R2,R3,R4)
    Exit Sub
Handle_Error:
    MsgBox (Err.Description)
End Sub

Sub MWDate2VariantDate(pVar)

Converts output dates from MATLAB to Variant dates.

Parameters

Argument	Type	Description
`pVar`	`Variant`	`Variant` to be converted

Return Value

None.

Remarks

MATLAB handles dates as double-precision floating-point numbers with 0.0 representing 0/0/00 00:00:00. 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 as well as coerced to COM dates. The MWDate2VariantDate method performs this transformation and additionally converts dates in character vector form to COM date types.

Example

This example uses MWDate2VariantDate to process numeric dates returned from a method compiled from the following MATLAB function.

function x = getdates(n, inc)
    y = now;
    for i=1:n
        x(i,1) = y + (i-1)*inc;
    end

This function produces an n-length column vector of numeric values representing dates starting from the current date and time with each element incremented by inc days. 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 dates into the supplied range. If an error occurs, a message box displays the error text. This function assumes that MWInitApplication has been previously called.

Sub GenDates(R As Range, inc As Double)
    Dim aClass As Object
    Dim aUtil As Object
    
    On Error GoTo Handle_Error
    Set aClass = CreateObject("mycomponent.myclass.1_0")
    Set aUtil = CreateObject("MWComUtil.MWUtil")
    Call aClass.getdates(1, R, R.Rows.Count, inc)
    Call aUtil.MWDate2VariantDate(R)
    Exit Sub
Handle_Error:
    MsgBox (Err.Description)
End Sub