End-to-End Deployment of MATLAB Function

Warning

The option to build and package MATLAB® code from within the Function Wizard for Excel® add-ins has been removed in R2022a. To create an Excel add-in, see Create Excel Add-In from MATLAB.

Not recommended starting in R2020a

If you are still in the process of developing a MATLAB function that is not yet ready to be deployed, you may find this example to be an appropriate introduction to using MATLAB Compiler™ for Excel add-ins.

Developing your function in an interactive environment ensures that it works in an expected manner, prior to deployment to larger-scale applications. Usually, these applications are programmed by the Excel Developer using an enterprise language like Microsoft® Visual Basic®.

Similar to the Magic Square example, the Prototyping and Debugging example develops a function named `mymagic`, which wraps a MATLAB function, `magic`, which computes a magic square, a function with a single multidimensional matrix output.

If your MATLAB function is ready to be deployed and you have already built your add-in and COM component with the Deployment Tool, see Install and Use Function Wizard.

mymagic Testing

In this example, you test a MATLAB file (`mymagic.m`) containing the predefined MATLAB function `magic`. You test to have a baseline to compare to the results of the function when it is ready to deploy.

1. In MATLAB, examine `mymagic.m`.

```function y = mymagic(x) %MYMAGIC Magic square of size x. % Y = MYMAGIC(X) returns a magic square of size x. % This file is used as an example for the MATLAB Compiler product. % Copyright 2001-2012 The MathWorks, Inc. y = magic(x) ```

2. At the MATLAB command prompt, enter `mymagic(5)`. View the resulting output, which appears as follows:

``````17 24  1  8 15 23  5  7 14 16  4  6 13 20 22 10 12 19 21  3 11 18 25  2  9``````

Function Wizard Start-Up

Start the Function Wizard in one of the following ways. When the wizard has initialized, the Function Wizard Start Page dialog box displays.

Using Excel 2007 or newer versions of Excel

In Microsoft Excel, on the Microsoft Office ribbon, on the Home tab, select Function Wizard.

The Home Tab of the Microsoft Office Ribbon with Function Wizard Installed

You can also access Function Wizard from the File tab.

1. Select File > Options > Add-Ins from the Excel main menu.

2. Select Function Wizard.

Workflow Selection for Prototyping and Debugging MATLAB Functions

1. The Function Wizard Control Panel displays with the Add Function button enabled.

Keep in mind the following information about project files when working with the Function Wizard:

• The project files created by the Function Wizard are the same project files created and used by the Deployment Tool (`deploytool`).

• The Function Wizard prompts you to specify a location for your project files when you open your first new project. Project files are auto-saved to this location and may be opened in the future through either the Deployment Tool or the Function Wizard.

• If you previously built a component using the Function Wizard, the wizard will prompt you to load it.

New MATLAB Function Definition

1. Add the function you want to deploy to the Function Wizard. Click Add in the Set Up Functions area of the Function Wizard Control Panel. The New MATLAB Function dialog box appears.

2. Browse to locate your MATLAB function. Select the function and click Open.

3. In the New MATLAB Function dialog box, click Add. The Function Properties dialog box appears.

Tip

The Function Syntax and Help area, in the Function Properties dialog box, displays the first help text line (sometimes called the H1 line) in a MATLAB function. Displaying these comments in the Function Properties dialog box can be helpful when deploying new or unfamiliar MATLAB functions to end-users.

4. Define input argument properties as follows.

1. On the Input tab, click Set Input Data. The Input Data for `x` dialog box appears.

2. Specify a Range or Value by selecting the appropriate option and entering the value.

Caution

Avoid selecting ranges using arrow keys. If you must use arrow keys to select ranges, apply the necessary fix from the Microsoft site: https://mskb.pkisolutions.com/kb/291110.

3. Click Done.

5. Define output argument properties as follows.

1. On the Output tab, click Set Output Data. The Output Data for `y` dialog box appears, where `x` is the name of the output variable you are defining properties of.

Tip

You can also specify MATLAB Compiler to Auto Resize, Transpose or output your data in date format (Output as date). To do so, select the appropriate option in the Argument Properties For `y` dialog box.

2. Specify a Range. Alternately, select a range of cells on your Excel sheet; the range will be entered for you in the Range field.

Caution

Avoid selecting ranges using arrow keys. If you must use arrow keys to select ranges, apply the necessary fix from the Microsoft site: https://mskb.pkisolutions.com/kb/291110.

3. Select Auto Resize if it is not already selected.

4. Click Done in the Argument Properties For `y` dialog box.

5. Click Done in the Function Properties dialog box. `mymagic` now appears in the Active Functions list of the Function Wizard Control Panel.

MATLAB Function Prototyping and Debugging

Use the Function Wizard to interactively prototype and debug a MATLAB function.

Since `mymagic` calls the prewritten MATLAB `magic` function directly, it does not provide an illustrative example of how to use the prototyping and debugging feature of MATLAB Compiler.

Following is an example of how you might use this feature with `myprimes`, a function containing multiple lines of code.

Prototyping and Debugging with myprimes

For example, say you are in the process of prototyping code that uses the equation `P = myprimes(n)`. This equation returns a row vector of prime numbers less than or equal to `n` (a prime number has no factors other than 1 and the number itself).

Your code uses `P = myprimes(n)` as follows:

```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)); ```

In designing your code, you want to handle various use cases. For example, you want to experiment with scenarios that may assign a column vector value to the output variable `p` ( (`myprimes` only returns a row vector, as stated previously). You follow this general workflow:

1. Set a breakpoint in `myprimes` at the first `if` statement, using the GUI or `dbstop`, for instance.

2. On the Function Wizard Control Panel, in the Execute Functions area, click Execute. Execution will stop at the previously set breakpoint. Note the value of `p`. Step-through and debug your code as you normally would using the MATLAB Editor.

Function Execution from MATLAB

Test your deployable MATLAB function by executing it in MATLAB:

1. From the Function Wizard Control Panel, in the Execute Functions area, select Execute MATLAB Functions in MATLAB.

2. Click Execute. In Excel, the Magic Square function executes, producing results similar to the following.

Microsoft Excel Add-In and Macro Creation Using the Function Wizard

The Function Wizard can automatically create a deployable Microsoft Excel add-in and macro. To create your add-in in this manner, use one of the following procedures.

Creating an Add-In and Associated Excel Macro

To create both a deployable add-in and an associated Excel macro:

1. In the Function Wizard Control Panel dialog box, in the Create Component area, select Create Both Excel Add-in Component and Excel Macro.

2. Enter `mymagic` in the Macro Name field.

3. Select the location of where to store the macro, using the Store Macro In drop-down box.

4. Enter a brief description of the macro's functionality in the Description field.

5. Click Create to build both the add-in (as well as the underlying COM component) and the associated macro. The Deployment Tool Build dialog box appears, indicating the status of the add-in and COM component compilation (build).

The Build Dialog

Creating a COM Component or a Macro Only Without Creating an Add-In

To create either a COM component or a macro without also creating the Excel add-in, do the following

1. In the Function Wizard Control Panel dialog box, in the Create Component area, select either MATLAB Excel Add-in Component Only or Create Excel Macro Only.

2. Enter `mymagic` in the Macro Name field.

3. Select the location of where to store the macro, using the Store Macro In drop-down box.

4. Enter a brief description of the macro's functionality in the Description field.

5. Click Create.

Function Execution from the Deployed Component

Execute your function as you did similarly in Function Execution from MATLAB, but this time execute it from the deployed component to ensure it matches your previous output.

1. From the Function Wizard Control Panel, in the Execute Functions area, select Execute MATLAB Functions from Deployed Component.

2. Click Execute. In Excel, the Magic Square function executes, producing results similar to the following.

Microsoft Excel Add-In and Macro Packaging using the Function Wizard

The Function Wizard can automatically package a deployable Microsoft Excel add-in and macro for sharing. To package your add-in in this manner, use one of the following procedures.

1. After successfully building your component and add-in, in the Share Component area of the Function Wizard Control Panel dialog box, review the files listed in the Files to include in packaging field. Add Files or Remove Files to and from the package by clicking the appropriate buttons.

2. To add access to the MATLAB Runtime installer to your package, select one of the options in the MATLAB Runtime area. For information about the MATLAB Runtime and the MATLAB Runtime installer, see Install and Configure MATLAB Runtime.

3. When you are ready to create your package, click Create Package.