MATLAB Excel Builder

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

• Sub MWInitApplication(pApp As Object)
• Sub MWPack(pVarArg, [Var0], [Var1], ... ,[Var31])
• Sub MWUnpack(VarArg, [nStartAt As Long], [bAutoResize As Boolean = False], [pVar0], [pVar1], ..., [pVar31])
• Sub MWDate2VariantDate(pVar)

The function prototypes use Visual Basic syntax.

Sub MWInitApplication(pApp As Object)

Initializes the library with the current instance of 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 Excel Builder components. An error is generated if a method call is made to a member class of any Excel Builder 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
  

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 added to the array only if it is nonempty and nonmissing. (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 Variants 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 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 string. 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 Variants 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 Variants 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 (See Data Conversion Rules for more information on conversion between MATLAB and COM date values). 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 string 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
  

Utility Library Classes

Class MWFlags