matlab-use-spreadsheet-link

# Spreadsheet Link

Spreadsheet Link connects Excel to MATLAB, enabling users to exchange data between Excel and MATLAB, run MATLAB commands, using MATLAB as the compute engine from Excel.

## When to Use

- User wants to export Excel data into MATLAB workspace variables
- User wants to import MATLAB variables back into Excel cells or VBA variables
- User wants to execute MATLAB commands from an Excel VBA macro or worksheet cell
- User wants to import MATLAB figures into Excel as images
- User is building a workflow that uses Excel as the data interface and MATLAB as the compute engine

## When NOT to Use

- MATLAB-only workflows with no Excel involvement
- Python or .NET integration with MATLAB (use MATLAB Engine API instead)
- Deploying MATLAB as a web service (use MATLAB Production Server instead)

## Architecture

Spreadsheet Link uses VBA macros or worksheet functions in Excel to communicate with a locally running MATLAB instance via COM.

```
┌─────────────────────┐         VBA / COM          ┌─────────────────────┐
│   Excel             │  ◄─────────────────────►   │  MATLAB             │
│   (VBA or cells)    │                            │  (workspace)        │
└─────────────────────┘                            └─────────────────────┘
```

- Windows only (requires MATLAB COM Server)
- MATLAB must be running locally
- Two usage modes: VBA macros or worksheet functions (cell formulas)
- Two data exchange styles: range-based (MLPutMatrix/MLGetMatrix) or VBA-variable-based (MLPutVar/MLGetVar)

## Key Functions

| Function | Mode | Purpose | Queued? |
|----------|------|---------|---------|
| `MLPutMatrix` | Both | Export worksheet range to MATLAB variable | No |
| `MLPutVar` | VBA only | Export VBA variable to MATLAB variable | No |
| `MLGetMatrix` | Both | Import MATLAB variable to worksheet cells | **Yes** |
| `MLGetVar` | VBA only | Import MATLAB variable into VBA variable | No |
| `MLPutRanges` | Both | Export ALL named ranges to MATLAB | No |
| `MLEvalString` | Both | Execute a MATLAB command | No |
| `MLGetFigure` | Both | Import current MATLAB figure as image | **Yes** |
| `MatlabRequest` | VBA only | Process all queued MLGetMatrix/MLGetFigure | — |
| `MLAppendMatrix` | Both | Append worksheet range to existing MATLAB variable | No |

## Function Reference

### MLPutMatrix

Export an Excel range into MATLAB as a workspace variable.

**VBA macro syntax:**
```vba
MLPutMatrix "varName", Range("A1:B10")
```

**Worksheet function syntax:**
```
=MLPutMatrix("varName", A1:B10)
```

- First argument: MATLAB variable name (string)
- Second argument: Excel range containing the data
- Dates in Excel are sent as Excel serial date numbers

### MLPutVar

Export a VBA variable to the MATLAB workspace. VBA only — not available as a worksheet function.

```vba
Dim myData As Variant
myData = Range("A1:B100").Value
MLPutVar "matlabVar", myData
```

- First argument: MATLAB variable name (string)
- Second argument: VBA variable (the variable itself, not a string name)
- Executes immediately (not queued)
- Use when data needs VBA manipulation before sending to MATLAB

### MLGetMatrix

Queue a MATLAB variable to be written into Excel starting at a cell location.

```vba
MLGetMatrix "varName", "A1"
```

- First argument: MATLAB variable name (string)
- Second argument: destination cell address (**string**, not a Range object)
- Does NOT execute immediately — queued until `MatlabRequest` is called
- Supports all MATLAB data types; `datetime` values are converted to strings in Excel
- As worksheet function: `=MLGetMatrix("varName", "E1")`

### MLGetVar

Import a MATLAB variable into a VBA variable. VBA only — not available as a worksheet function.

```vba
Dim result As Variant
MLGetVar "matlabVar", result
```

- First argument: MATLAB variable name (string)
- Second argument: VBA variable to receive the data
- Executes **immediately** — does NOT require `MatlabRequest`
- Supports all MATLAB data types; `datetime` values are converted to strings
- Use when results need VBA manipulation before writing to worksheet

### MLPutRanges

Export ALL Excel named ranges to MATLAB in a single call. Each named range becomes a MATLAB variable with the same name.

```vba
MLPutRanges
```

- No arguments — exports every named range in the workbook
- Range name becomes the MATLAB variable name (e.g., named range "prices" → MATLAB variable `prices`)
- As worksheet function: `=MLPutRanges()`

### MLEvalString

Execute a MATLAB command in the connected MATLAB session.

```vba
MLEvalString "x = magic(3);"
```

- Argument: MATLAB code as a string
- Executes synchronously — the next VBA line runs after MATLAB completes
- Can call any MATLAB function, script, or expression
- As worksheet function: `=MLEvalString("x = magic(3);")`

### MLAppendMatrix

Append an Excel range to an existing MATLAB variable. The new data is concatenated as additional rows.

**VBA macro syntax:**
```vba
MLAppendMatrix "varName", Range("A101:B200")
```

**Worksheet function syntax:**
```
=MLAppendMatrix("varName", A101:B200)
```

- First argument: MATLAB variable name (string) — must already exist in workspace
- Second argument: Excel range to append
- Appends rows to the bottom of the existing variable
- Use when building up a variable incrementally (e.g., streaming data)

### MLGetFigure

Import the current MATLAB figure into Excel as an image.

```vba
Range("I1").Select
MLGetFigure 1, 1
```

- **Select the destination cell first** with `Range(...).Select`
- First argument: horizontal size scaling factor (1 = full size, 0.5 = half width)
- Second argument: vertical size scaling factor (1 = full size, 0.5 = half height)
- Only two arguments — do NOT pass a cell address
- Retrieves whatever figure is currently active in MATLAB
- Queued until `MatlabRequest` is called (like `MLGetMatrix`)
- As worksheet function: `=MLGetFigure(1, 1)` — places figure at the formula cell

### MatlabRequest

Process all pending `MLGetMatrix` and `MLGetFigure` commands