compiler.build.excelClientForProductionServer

Create Microsoft Excel add-in for MATLAB Production Server

Since R2021b

Syntax

compiler.build.excelClientForProductionServer(Results)

compiler.build.excelClientForProductionServer(FunctionFiles,ServerArchive)

compiler.build.excelClientForProductionServer(FunctionFiles,ServerArchive,Name,Value)

compiler.build.excelClientForProductionServer(opts)

results = compiler.build.excelClientForProductionServer(___)

Description

Caution

This function is only supported on Windows^® operating systems.

compiler.build.excelClientForProductionServer(Results) creates an Excel^® add-in for MATLAB^® Production Server™ using the compiler.build.Results object Results created from the compiler.build.productionServerArchive function. Before creating Excel add-ins, install a supported compiler.

compiler.build.excelClientForProductionServer(FunctionFiles,ServerArchive) creates an Excel add-in using MATLAB functions specified by FunctionFiles and the MATLAB Production Server archive specified by ServerArchive.

compiler.build.excelClientForProductionServer(FunctionFiles,ServerArchive,Name,Value) creates an Excel add-in with options specified using one or more name-value arguments. Options include the add-in name, output directory, and how to handle the Excel date data type.

compiler.build.excelClientForProductionServer(opts) creates an Excel add-in with options specified using a compiler.build.ExcelClientForProductionServerOptions object opts. You cannot specify any other options using name-value arguments.

results = compiler.build.excelClientForProductionServer(___) returns build information as a compiler.build.Results object using any of the input argument combinations in previous syntaxes. The build information consists of the build type, paths to the compiled files, and build options.

Examples

Create Excel Add-In Using Results

Create an Excel add-in for MATLAB Production Server on a Windows system using the results from the compiler.build.productionServerArchive function.

Ensure that you have the following installed:

• The Windows 10 SDK kit. For details, see Windows 10 SDK.

• MinGW-w64. To install it from the MathWorks File Exchange, see MATLAB Support for MinGW-w64 C/C++ Compiler.

  Use mbuild -setup -client mbuild_com to ensure that MATLAB is able to create Excel add-ins.

In MATLAB, locate the MATLAB function that you want to deploy as an Excel add-in. For this example, use the file magicsquare.m located in matlabroot\extern\examples\compiler.

appFile = fullfile(matlabroot,'extern','examples','compiler','magicsquare.m');

Build a MATLAB Production Server archive using the compiler.build.productionServerArchive command. Save the output as a compiler.build.Results object serverBuildResults.

serverBuildResults = compiler.build.productionServerArchive(appFile);

Build an Excel add-in for MATLAB Production Server archive using the compiler.build.excelClientForProductionServer command.

excelBuildResults = compiler.build.excelClientForProductionServer(serverBuildResults);

The function generates the following files within a folder named magicsquareexcelClientForProductionServer in your current working directory:

• includedSupportPackages.txt

• magicsquare.bas (Only if you enable the 'GenerateVisualBasicFile' option)

• magicsquare.dll

• magicsquare.reg

• magicsquare.xla (Only if you enable the 'GenerateVisualBasicFile' option)

• magicsquareClass.cs

• readme.txt

• requiredMCRProducts.txt

Create Excel Add-In Using Files

Create an Excel add-in for MATLAB Production Server on a Windows system using MATLAB function files and a MATLAB Production Server archive.

Create a MATLAB Production Server archive using a MATLAB function file. For this example, use the file magicsquare.m located in matlabroot\extern\examples\compiler as an input to the compiler.build.productionServerArchive function.

mpsFile = fullfile(matlabroot,'extern','examples','compiler','magicsquare.m');
compiler.build.productionServerArchive(mpsFile);

The function generates the file magicsquare.ctf in the magicsquareproductionServerArchive folder.

Build an Excel add-in for MATLAB Production Server archive using the compiler.build.excelClientForProductionServer command. Specify the function file and the CTF file as inputs.

excelBuildResults = compiler.build.excelClientForProductionServer(mpsFile,'magicsquareproductionServerArchive\magicsquare.ctf');

Customize Excel Add-In

Create an Excel add-in and customize it using name-value arguments.

Create a MATLAB Production Server archive using a MATLAB function file. For this example, use the file magicsquare.m located in matlabroot\extern\examples\compiler as an input to the compiler.build.productionServerArchive function.

mpsFile = fullfile(matlabroot,'extern','examples','compiler','magicsquare.m');
compiler.build.productionServerArchive(mpsFile);

Build an Excel add-in for MATLAB Production Server using the compiler.build.excelClientForProductionServer command. Use name-value arguments to specify the add-in name, generate a Microsoft^® Visual Basic^® file, and enable verbose output.

compiler.build.excelClientForProductionServer(mpsFile,...
    'magicsquareproductionServerArchive\magicsquare.ctf',...
    'AddInName','MyMagicSquare',...
    'GenerateVisualBasicFile','on',...
    'Verbose','on');

The function generates the following files within a folder named MyMagicSquareexcelClientForProductionServer in your current working directory:

• includedSupportPackages.txt

• MyMagicSquare.bas

• MyMagicSquare.dll

• MyMagicSquare.reg

• MyMagicSquare.xla

• MyMagicSquareClass.cs

• readme.txt

• requiredMCRProducts.txt

Create Multiple Add-Ins Using Options Object

Create multiple Excel add-ins for MATLAB Production Server on a Windows system using a compiler.build.ExcelClientForProductionServerOptions object.

Create a MATLAB Production Server archive using a MATLAB function file. For this example, use the file magicsquare.m located in matlabroot\extern\examples\compiler as an input to the compiler.build.productionServerArchive function.

mpsFile = fullfile(matlabroot,'extern','examples','compiler','magicsquare.m');
compiler.build.productionServerArchive(mpsFile);

Create an ExcelClientForProductionServerOptions object using the file houdini.m located in matlabroot\extern\examples\compiler. Use name-value arguments to specify a common output directory, generate a Visual Basic file, and enable verbose output.

appFile = fullfile(matlabroot,'extern','examples','compiler','houdini.m');
opts = compiler.build.ExcelClientForProductionServerOptions(appFile,...
    'magicsquareproductionServerArchive\magicsquare.ctf',...
    'OutputDir','D:\Documents\MATLAB\work\MPSExcelAddInBatch',...
    'GenerateVisualBasicFile','on',...
    'Verbose','on')

opts = 

  ExcelClientForProductionServerOptions with properties:

                         AddInName: 'houdini'
                      AddInVersion: '1.0.0.0'
                         ClassName: 'houdiniClass'
                        DebugBuild: off
                     FunctionFiles: {'C:\Program Files\MATLAB\R2023b\extern\examples\compiler\houdini.m'}
           GenerateVisualBasicFile: on
                     ServerArchive: 'magicsquareproductionServerArchive\magicsquare.ctf'
          ReplaceExcelBlankWithNaN: off
          ConvertExcelDateToString: off
           ReplaceNaNToZeroInExcel: off
    ConvertNumericOutToDateInExcel: off
                           Verbose: on
                         OutputDir: 'D:\Documents\MATLAB\work\MPSExcelAddInBatch'

Build the add-in using the ExcelAddInOptions object.

compiler.build.excelClientForProductionServer(opts);

To create a new add-in using the function file houdini.m with the same options, use dot notation to modify the FunctionFiles argument of the existing ExcelAddInOptions object before running the build function again.

appFile2 = fullfile(matlabroot,'extern','examples','compiler','houdini.m');
opts.FunctionFiles = appFile2;
compiler.build.excelClientForProductionServer(opts);

By modifying the FunctionFiles argument and recompiling, you can create multiple add-ins using the same options object.

Get Build Information from Excel Add-In for MATLAB Production Server

Create an Excel add-in for MATLAB Production Server and save information about the build type, generated files, included support packages, and build options to a compiler.build.Results object.

Build a MATLAB Production Server archive using the file magicsquare.m. Save the output as a compiler.build.Results object serverBuildResults.

serverBuildResults = compiler.build.productionServerArchive('magicsquare.m');

Build the Excel add-in using the serverBuildResults object.

results = compiler.build.excelClientForProductionServer(serverBuildResults)

results = 

  Results with properties:

              BuildType: 'excelClientForProductionServer'
                  Files: {1×1 cell}
IncludedSupportPackages: {}
                Options: [1×1 compiler.build.ExcelClientForProductionServerOptions]

The Files property contains the paths to the following compiled files:

• magicsquare.dll

• magicsquare.bas

• magicsquare.xla

Note

The files magicsquare.bas and magicsquare.xla are included in Files only if you enable the 'GenerateVisualBasicFile' option in the compiler.build.excelClientForProductionServer command.

Input Arguments

FunctionFiles — Files implementing MATLAB functions

character vector | string scalar | cell array of character vectors | string array

Files implementing MATLAB functions, specified as a character vector, a string scalar, a string array, or a cell array of character vectors. File paths can be relative to the current working directory or absolute. Files must have a .m extension.

Example: ["myfunc1.m","myfunc2.m"]

Data Types: char | string | cell

opts — Excel add-in build options

compiler.build.ExcelClientForProductionServerOptions object

Excel add-in build options, specified as a compiler.build.ExcelClientForProductionServerOptions object.

Results — Build results object

Results object

Build results, specified as a compiler.build.Results object. Create the Results object by saving the output from the compiler.build.productionServerArchive function.

ServerArchive — Excel add-in build options

character vector | string scalar

MATLAB Production Server archive deployed on the Production Server, specified as a character vector or a string scalar.

Example: 'mpsArchive.ctf'

Data Types: char | string

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: 'Verbose','on'

AddInName — Name of Excel add-in

character vector | string scalar

Name of the Excel add-in, specified as a character vector or string scalar. The default name of the generated add-in is the first entry of the FunctionFiles argument. The name must begin with a letter and contain only alphabetic characters and underscores.

Example: 'AddInName','myAddIn'

Data Types: char | string

AddInVersion — Add-in version

'1.0.0.0' (default) | character vector | string scalar

Add-in version, specified as a character vector or a string scalar.

Example: 'AddInVersion','4.0'

Data Types: char | string

ClassName — Name of class

character vector | string scalar

Name of the generated class, specified as a character vector or a string scalar. You cannot specify this option if you use a ClassMap input. Class names must meet the Excel class name requirements.

The default value is the AddInName argument appended with Class.

Example: 'ClassName','MagicSquareClass'

Data Types: char | string

ConvertExcelDateToString — Flag to convert date to string

'off' (default) | on/off logical value

Flag to convert Excel date to string, specified as 'on' or 'off', or as numeric or logical 1 (true) or 0 (false). A value of 'on' is equivalent to true, and 'off' is equivalent to false. Thus, you can use the value of this property as a logical value. The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState.

• If you set this property to 'on', then the compiler converts the Excel date datatype to MATLAB string.

• If you set this property to 'off', then dates are not converted.

Example: 'ConvertExcelDateToString','On'

Data Types: logical

ConvertNumericOutToDateInExcel — Flag to convert numeric data to Excel date

'off' (default) | on/off logical value

Flag to convert numeric data to Excel date, specified as 'on' or 'off', or as numeric or logical 1 (true) or 0 (false). A value of 'on' is equivalent to true, and 'off' is equivalent to false. Thus, you can use the value of this property as a logical value. The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState.

• If you set this property to 'on', then the compiler converts numeric data to the Excel date datatype.

• If you set this property to 'off', then numeric data is not converted.

Example: 'ConvertNumericOutToDateInExcel','On'

Data Types: logical

DebugBuild — Flag to enable debug symbols

'on' (default) | on/off logical value

Flag to enable debug symbols, specified as 'on' or 'off', or as numeric or logical 1 (true) or 0 (false). A value of 'on' is equivalent to true, and 'off' is equivalent to false. Thus, you can use the value of this property as a logical value. The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState.

• If you set this property to 'on', then the add-in is compiled with debug symbols.

• If you set this property to 'off', then the add-in is not compiled with debug symbols.

Example: 'DebugSymbols','On'

Data Types: logical

GenerateVisualBasicFile — Flag to generate Visual Basic file

'off' (default) | on/off logical value

Flag to generate a Visual Basic file (.bas) and an Excel add-in file (.xla), specified as 'on' or 'off', or as numeric or logical 1 (true) or 0 (false). A value of 'on' is equivalent to true, and 'off' is equivalent to false. Thus, you can use the value of this property as a logical value. The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState.

• If you set this property to 'on', then the function generates an Excel add-in XLA file and a Visual Basic BAS file containing the Microsoft Excel Formula Function interface to the add-in.

• If you set this property to 'off', then the function does not generate a Visual Basic file or an Excel add-in file.

Example: 'GenerateVisualBasicFile','On'

Data Types: logical

OutputDir — Path to output directory

character vector | string scalar

Path to the output directory where the build files are saved, specified as a character vector or a string scalar. The path can be relative to the current working directory or absolute.

The default name of the build folder is the add-in name appended with excelAddIn.

Example: 'OutputDir','D:\Documents\MATLAB\work\mymagicexcelAddIn'

Data Types: char | string

ReplaceExcelBlankWithNaN — Flag to convert blank Excel cells to NaN

'off' (default) | on/off logical value

Flag to convert blank Excel cells to NaN, specified as 'on' or 'off', or as numeric or logical 1 (true) or 0 (false). A value of 'on' is equivalent to true, and 'off' is equivalent to false. Thus, you can use the value of this property as a logical value. The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState.

• If you set this property to 'on', then the compiler converts blank Excel cells to NaN in the compiled artifact.

• If you set this property to 'off', then blank Excel cells are not converted.

Example: 'ReplaceExcelBlankWithNaN','On'

Data Types: logical

ReplaceNaNToZeroInExcel — Flag to convert NaN entries to zero

'off' (default) | on/off logical value

Flag to convert NaN entries to zero, specified as 'on' or 'off', or as numeric or logical 1 (true) or 0 (false). A value of 'on' is equivalent to true, and 'off' is equivalent to false. Thus, you can use the value of this property as a logical value. The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState.

• If you set this property to 'on', then the compiler converts NaN entries from the compiled artifact to zero in Excel.

• If you set this property to 'off', then NaN entries are not converted.

Example: 'ReplaceNaNToZeroInExcel','On'

Data Types: logical

Verbose — Flag to control build verbosity

'off' (default) | on/off logical value

Flag to control build verbosity, specified as 'on' or 'off', or as numeric or logical 1 (true) or 0 (false). A value of 'on' is equivalent to true, and 'off' is equivalent to false. Thus, you can use the value of this property as a logical value. The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState.

• If you set this property to 'on', then the MATLAB command window displays progress information indicating compiler output during the build process.

• If you set this property to 'off', then the command window does not display progress information.

Example: 'Verbose','On'

Data Types: logical

Output Arguments

results — Build results

compiler.build.Results object

Build results, returned as a compiler.build.Results object. The Results object contains:

• Build type, which is 'excelClientForProductionServer'

• Paths to the following files:

  • AddInName.dll

  • AddInName.bas (if you enable the 'GenerateVisualBasicFile' option)

  • AddInName.xla (if you enable the 'GenerateVisualBasicFile' option)

• A list of included support packages

• Build options, specified as an ExcelClientForProductionServerOptions object

Limitations

• This function is only supported on Windows operating systems.

Version History

Introduced in R2021b