compiler.build.ExcelClientForProductionServerOptions

Options for building Excel add-ins

Since R2021b

Syntax

opts = compiler.build.ExcelClientForProductionServerOptions(Results)

opts = compiler.build.ExcelClientForProductionServerOptions(FunctionFiles,ServerArchive)

opts = compiler.build.ExcelClientForProductionServerOptions(FunctionFiles,ServerArchive,Name,Value)

Description

opts = compiler.build.ExcelClientForProductionServerOptions(Results) creates an ExcelClientForProductionServerOptions object using the compiler.build.Results object Results created from the compiler.build.productionServerArchive function. Use the ExcelClientForProductionServerOptions object as an input to the compiler.build.excelClientForProductionServer function.

opts = compiler.build.ExcelClientForProductionServerOptions(FunctionFiles,ServerArchive) creates an ExcelClientForProductionServerOptions object using MATLAB^® functions specified by FunctionFiles and the MATLAB Production Server™ archive specified by ServerArchive.

opts = compiler.build.ExcelClientForProductionServerOptions(FunctionFiles,ServerArchive,Name,Value) creates an ExcelClientForProductionServerOptions object 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.

Examples

Create Excel Add-In Options Object Using Results

Create an ExcelClientForProductionServerOptions object using the results from the compiler.build.productionServerArchive function.

In MATLAB, locate the MATLAB function that you want to deploy to MATLAB Production Server. 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 function. Save the output as a compiler.build.Results object serverBuildResults.

serverBuildResults = compiler.build.productionServerArchive(appFile);

Create an ExcelClientForProductionServerOptions object using serverBuildResults and the compiler.build.excelClientForProductionServer function.

opts = compiler.build.ExcelClientForProductionServerOptions(serverBuildResults)

opts = 

  ExcelClientForProductionServerOptions with properties:

                         AddInName: 'magicsquare'
                      AddInVersion: '1.0.0.0'
                         ClassName: 'magicsquareClass'
                        DebugBuild: off
                     FunctionFiles: {'C:\Program Files\MATLAB\R2024b\extern\
                                    examples\compiler\magicsquare.m'}
           GenerateVisualBasicFile: on
                     ServerArchive: '.\magicsquareproductionServerArchive\magicsquare.ctf'
          ReplaceExcelBlankWithNaN: off
          ConvertExcelDateToString: off
           ReplaceNaNToZeroInExcel: off
    ConvertNumericOutToDateInExcel: off
                           Verbose: off
                         OutputDir: '.\magicsquareexcelClientForProductionServer'

Use the ExcelClientForProductionServerOptions object as an input to the compiler.build.excelClientForProductionServer function to build an Excel add-in for MATLAB Production Server.

buildResults = compiler.build.excelClientForProductionServer(opts);

Create Excel Add-In Options Object Using Files

Create an ExcelClientForProductionServerOptions object using a MATLAB function file and a MATLAB Production Server archive.

Build a MATLAB Production Server archive using the compiler.build.productionServerArchive function. For this example, use the file houdini.m located in matlabroot\extern\examples\compiler.

appFile = fullfile(matlabroot,'extern','examples','compiler','houdini.m');
compiler.build.productionServerArchive(appFile);

Create an ExcelClientForProductionServerOptions object using the MATLAB Production Server archive file houdini.ctf.

opts = compiler.build.ExcelClientForProductionServerOptions(appFile,...
    'houdiniproductionServerArchive\houdini.ctf')

opts = 

  ExcelClientForProductionServerOptions with properties:

                         AddInName: 'houdini'
                      AddInVersion: '1.0.0.0'
                         ClassName: 'houdiniClass'
                        DebugBuild: off
                     FunctionFiles: {'C:\Program Files\MATLAB\R2024b\extern\examples\compiler\houdini.m'}
           GenerateVisualBasicFile: off
                     ServerArchive: 'houdiniproductionServerArchive\houdini.ctf'
          ReplaceExcelBlankWithNaN: off
          ConvertExcelDateToString: off
           ReplaceNaNToZeroInExcel: off
    ConvertNumericOutToDateInExcel: off
                           Verbose: off
                         OutputDir: '.\houdiniexcelClientForProductionServer'

Use the ExcelClientForProductionServerOptions object as an input to the compiler.build.excelClientForProductionServer function to build an Excel add-in for MATLAB Production Server.

buildResults = compiler.build.excelClientForProductionServer(opts);

Customize Excel Add-In Options Object

Create an ExcelClientForProductionServerOptions object and customize it using name-value arguments.

Build a MATLAB Production Server archive using the compiler.build.productionServerArchive function. For this example, use the file houdini.m located in matlabroot\extern\examples\compiler.

appFile = fullfile(matlabroot,'extern','examples','compiler','houdini.m');
compiler.build.productionServerArchive(appFile);

Create an ExcelClientForProductionServerOptions object using the MATLAB Production Server archive file houdini.ctf. Use name-value arguments to specify the output directory and generate a Visual Basic^® file.

opts = compiler.build.ExcelClientForProductionServerOptions(appFile,...
    'houdiniproductionServerArchive\houdini.ctf',...
    'OutputDir','D:\Documents\MATLAB\work\HoudiniMPSAddIn',...
    'GenerateVisualBasicFile','on')

opts = 

  ExcelClientForProductionServerOptions with properties:

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

You can modify the property values of an existing ExcelClientForProductionServerOptions object using dot notation. For example, enable verbose output.

opts.Verbose = 'on'

opts = 

  ExcelClientForProductionServerOptions with properties:

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

Use the ExcelClientForProductionServerOptions object as an input to the compiler.build.excelClientForProductionServer function to build an Excel add-in for MATLAB Production Server.

buildResults = compiler.build.excelClientForProductionServer(opts);

Input Arguments

FunctionFiles — MATLAB function files

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

List of files implementing MATLAB functions, specified as a character vector, a string scalar, a string array, or a cell array of character vectors. Files must have a .m extension.

Example: {'myFunction1.m','myFunction2.m'}

Data Types: char | string | cell

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

opts — Excel add-in build options

ExcelClientForProductionServerOptions object

Excel add-in build options, returned as an ExcelClientForProductionServerOptions object.

Version History

Introduced in R2021b