MATLAB Compiler

COM Components

The COM wrapper file allows you to create COM components from MATLAB M-files. The Compiler options that generate the COM wrappers are

• -W com:<component_name>[,<class_name>[,<major>.<minor>]]
  -W comhg:<component_name>[,<class_name>[,<major>.<minor>]]
  -W excel:<component_name>[,<class_name>[,<major>.<minor>]]
  -W excelhg:<component_name>[,<class_name>[,<major>.<minor>]]
  

The COM wrapper options create a superset of the files created when producing a C or C++ library wrapper. In addition to the C or C++ library files, the COM wrapper creates the files shown in the following table.

File	Description
<component_name>_idl.idl	Interface description file for COM
<component_name>_com.hpp	C++ header file for the COM class
<component_name>_com.cpp	C++ source file for the COM class
<component_name>_dll.cpp	DLL interface for the COM object
<component_name>.def	Definition file for the COM DLL
<component_name>.rc	Resource file for the COM DLL

If the <class_name> is not specified, it defaults to <component_name>. If the version number is not specified, it defaults to the latest version built or 1.0, if there is no previous version.

The COM wrapper option creates all the required code and files to create a single COM object that contains all of the compiler-generated interfaces. It creates a single COM class with the same name as the specified <class_name> and a corresponding interface class called I<class_name>. It uses the major and minor version numbers to control the major and minor version numbers of the COM interface that is produced.

The Compiler can generate either C or C++ code for the compiler M-files, but the created COM interface will always require C++. This is a requirement of COM and not particular to the MATLAB Compiler.

All of the extra files generated by the MATLAB Compiler that are required for producing the COM objects are added to the mbuild command line. The details of how mbuild processes the new file types (.def, .rc, and .idl) are specified in How mbuild Processes the File Types.

If the major and minor version numbers are specified, the Compiler replaces any existing type library with the specified new version number. If no version numbers are specified and there is an existing type library, the Compiler replaces the current version.

When calling mbuild to link a library, the .dll file will be <component_name>_<major>_<minor>.dll. This will prevent new versions from conflicting with each other. The user never uses the DLL name. It is not necessary to specify this name to the system because COM locates component DLLs using the Window's registry.

The MATLAB Compiler uses the -b option to generate a Visual Basic (.bas) file that contains the Microsoft Excel Formula Function interface to the compiler-generated COM object. When imported into the workbook, this Visual Basic code allows the MATLAB function to be seen as a cell formula function.

The -i option causes the Compiler to include only the M-files that are specified on the command line as exported interfaces. If additional M-files are compiled as a result of being located by the -h option, they are not included in the exported interface that is produced by the MATLAB Compiler.

The bundle option (-B) provides a means to replace its expression on the mcc command line with the contents of the specified file. Also, it lets you include replacement parameters so that any Compiler options that accept names and version numbers will be expanded properly.

For more information on the bundle option including the available bundle files, see -B <filename>:[<a1>,<a2>,...,<an>] (Bundle of Compiler Settings).

Note    You can use the -B option with a replacement expression as is at the DOS or UNIX prompt. To use -B with a replacement expression at the MATLAB prompt, you must enclose the expression that follows the -B in single quotes when there is more than one parameter passed. For example,     >>mcc -B csharedlib:libtimefun weekday data tic calendar toc can be used as is at the MATLAB prompt because libtimefun is the only parameter being passed. If the example had two or more parameters, then the quotes would be necessary as in     >>mcc -B 'cexcel:component,class,1.0' weekday data tic calendar toc

How mbuild Processes the File Types

The mbuild option, -regsvr, uses the mwregsvr32 program to register the resulting shared library at the end of compilation. The Compiler uses this option whenever it produces a COM wrapper file.

<filename>.idl.   You can specify IDL source files on the mbuild command line. These files are compiled using the MIDL Compiler. The compiler adds any generated .idl files to the mbuild command line.

<filename>.def.   You can specify DEF files on the mbuild command line to indicate the symbols exported from a given shared library. It is an error to have more than one .def file specified on the command line.

<filename>.rc.   You can specify an RC file on the MATLAB Compiler command line and it is added into the DLL as required. It is an error to have more than one .rc file specified on the command line.

COM Signature

When using the MATLAB Compiler and its COM wrapper option with an M-file, the Compiler produces and registers a COM-compatible DLL.

The Compiler produces the necessary function calls in accordance with these signatures.

M-Function Signature.   

• [Y1, Y2, ..., Varargout] = f(X1, X2, ..., Varargin)
  

C Signature.   

• void mlxF(int nlhs, mxArray* plhs[], 
      int nrhs, const mxArray* prhs[]);
  
      mxArray *mlfNF( int nargout, 
                   mxArray ** y1, 
                   mxArray **y2,
                  .
                  .
                   mxArray *x1,
                  mxArray *x2,
                  .
                   .
                   ... );
  

COM/IDL Signature.   

• HRESULT f([in] long nargout,
            [in,out] VARIANT* Y1,
            [in,out] VARIANT* Y2,
            .
            .
            [in,out] VARIANT* varargout,
            [in] VARIANT X1,
            [in] VARIANT X2,
            .
            .
            [in] VARIANT varargin);
  

The COM run-time performs all of the conversion between the COM types and MATLAB arrays. For details on this conversion, see the MATLAB Excel Builder or MATLAB COM Builder documentation.

C++ Libraries

Porting Generated Code to a Different Platform