Documentation

Where Is the Example Code?

See Example File Copying for information about accessing the example code from within the product.

Overview

This feature provides a lightweight interface for easily accessing the MATLAB Runtime data. It allows data to be shared between the MATLAB Runtime instance, the MATLAB code running on that the MATLAB Runtime, and the wrapper code that created the MATLAB Runtime. Through calls to the MATLAB Runtime User Data interface API, you access the MATLAB Runtime data by creating a per MATLAB Runtime instance associative array of mxArrays, consisting of a mapping from string keys to mxArray values. Reasons for doing this include, but are not limited to:

MATLAB Compiler™ supports per the MATLAB Runtime instance state access through an object-oriented API. Unlike MATLAB Compiler, access to per the MATLAB Runtime instance state is optional, rather than on by default. You can access this state by adding setmcruserdata.m and getmcruserdata.m to your deployment project or by specifying them on the command line. Alternately, you use a helper function to call these methods, as shown in Supply Run-Time Profile Information for Parallel Computing Toolbox Applications.

For more information, see the MATLAB Compiler User's Guide.

Supply Run-Time Profile Information for Parallel Computing Toolbox Applications

Following is a complete example of how you can use the MATLAB Runtime User Data Interface as a mechanism to specify a profile for Parallel Computing Toolbox applications.

Step 1: Write Your Parallel Computing Toolbox Code

Step 2: Set the Parallel Computing Toolbox Profile.  In order to compile MATLAB code to a COM component and utilize the Parallel Computing Toolbox, the mcruserdata must be set directly from MATLAB. There is no API available to access the MCRUserdata as there is for C and C++ applications built with MATLAB Compiler.

To set the mcruserdata from MATLAB, create an init function in your COM class. This is a separate MATLAB function that uses setmcruserdata to set the Parallel Computing Toolbox profile once. You then call your other functions to utilize the Parallel Computing Toolbox functions.

Create the following init function:

function init_sample_pct
% Set the Parallel Profile:
if(isdeployed)
    [profile] = uigetfile('*.settings'); 
                          % let the USER select file
    setmcruserdata('ParallelProfile',[profile]);
end

Step 3: Compile Your Function with the Deploytool or the Command Line.  You can compile your function from the command line by entering the following:

mcc -B 'cexcel:exPctComp,exPctClass,1.0' init_sample_pct.m sample_pct.m

Alternately, you can use the deploytool as follows:

Step 4: Modify the generated VBA Driver Application (the BAS File).   After registering the COM DLL on the deployment machine and importing the BAS file into Excel, modify the generated BAS file code as needed.

Dim MCLUtil As Object
Dim bModuleInitialized As Boolean
Dim exPctClass As Object
 
Private Sub InitModule()
  If Not bModuleInitialized Then
    On Error GoTo Handle_Error
    If MCLUtil Is Nothing Then
      Set MCLUtil = CreateObject("MWComUtil.MWUtil7.10")
    End If
    Call MCLUtil.MWInitApplication(Application)
    bModuleInitialized = True
    Exit Sub
Handle_Error:
    bModuleInitialized = False
  End If
End Sub
 
Function init_sample_pct() As Variant
 
  On Error GoTo Handle_Error
  Call InitModule
  If exPctClass Is Nothing Then
    Set exPctClass = CreateObject("exPctComp.exPctClass.1_0")
  End If
  Call exPctClass.init_sample_pct
  init_sample_pct = Empty
 
  Exit Function
Handle_Error:
  init_sample_pct = "Error in " & 
                         Err.Source & ": " & Err.Description
End Function
 
 
Function sample_pct(Optional pelle As Variant) As Variant
  Dim speedup As Variant
 
  On Error GoTo Handle_Error
  Call InitModule
  If exPctClass Is Nothing Then
    Set exPctClass = CreateObject("exPctComp.exPctClass.1_0")
  End If
  Call exPctClass.sample_pct(1, speedup, pelle)
  sample_pct = speedup
 
  Exit Function
Handle_Error:
  sample_pct = "Error in " & Err.Source 
                         & ": " & Err.Description
End Function

The output is as follows:

Overriding Default Behavior

To extract the deployable archive in a manner prior to R2008b, alongside the compiled COM component, compile using the mcc -c option.

You can also implement this override by adding the -c flag in the Settings section of the compiler app.

You might want to use this option to troubleshoot problems with the deployable archive, for example, as the log and diagnostic messages are much more visible.

For More Information

For more information about the deployable archive, see Deployable Archive.

What MATLAB Runtime Options are Supported by MATLAB Compiler?

How Do I Specify MATLAB Runtime Options?

If You Compiled the Add-In in MATLAB or used mcc.  If you are building your add-in using the MATLAB Library Compiler, select Create log file under Additional Runtime Settings.

If you are building your add-in using mcc, simply specify -logfile with the mcc -R command

If You Created a Function From Scratch Using the Function Wizard.  If you created a function from scratch using the Function Wizard, and want to specify MATLAB Runtime options, you have to manually modify the .bas file code.

You do this by invoking the following MWUtil API calls, detailed with examples in Class MWUtil: