Sign in today to find solutions:

Forgot your password?

Don't have an account? Sign up

 
®
MATLAB
Compiler™ 4
User's Guide

Summary of Contents

  • Page 1

    ® MATLAB Compiler™ 4 User’s Guide...

  • Page 2

    Program and Documentation, unused, to The MathWorks, Inc. Trademarks MATLAB and Simulink are registered trademarks of The MathWorks, Inc. See for a list of additional trademarks. Other product or brand www.mathworks.com/trademarks names may be trademarks or registered trademarks of their respective holders.

  • Page 3

    Revision History September 1995 First printing March 1997 Second printing January 1998 Third printing Revised for Version 1.2 January 1999 Fourth printing Revised for Version 2.0 (Release 11) September 2000 Fifth printing Revised for Version 2.1 (Release 12) October 2001 Online only Revised for Version 2.3 July 2002...

  • Page 5: Table Of Contents

    How Does This Product Work? ..What Is The MATLAB Compiler Runtime (MCR)? ....Before You Use MATLAB ®...

  • Page 6: Table Of Contents

    3-10 Compiled Applications Do Not Process MATLAB Files at ........

  • Page 7: Table Of Contents

    3-12 Working with MATLAB Data Files Using Load and ..........

  • Page 8: Table Of Contents

    ..About the MATLAB ® Compiler Runtime (MCR) 5-18 Installing the MCR and MATLAB on the Same Machine 5-19 ... . . Installing Multiple MCRs on One Machine 5-21 .

  • Page 9: Table Of Contents

    6-25 Converting Script MATLAB Files to Function MATLAB ......... .

  • Page 10: Table Of Contents

    6-33 Using the VER Function in a Compiled MATLAB ........

  • Page 11: Table Of Contents

    Print and Error Handling Functions 8-27 ... . . Functions Generated from MATLAB Files 8-29 Retrieving MCR State Information While Using Shared ........

  • Page 12: Table Of Contents

    Fixing Callback Problems: Missing Functions 10-3 ..Finding Missing Functions in an MATLAB File 10-5 ... Suppressing Warnings on the UNIX System 10-5 .

  • Page 13: Table Of Contents

    ..... . MATLAB ® Compiler Licensing 11-8 ..Using MATLAB ® Compiler Licenses for Development 11-8 ..Using MCR Installer Command Line Options 11-9 .

  • Page 14: Table Of Contents

    ® Compiler Quick Reference ....Common Uses of MATLAB ® Compiler .....

  • Page 15: Table Of Contents

    ....Running Your 64-Bit Mac Application ........Overview Installing the Macintosh Application Launcher Preference .

  • Page 16: Table Of Contents

    ....... . mwException Class D-20 ....... About mwException D-20 .

  • Page 17

    Getting Started • “Product Overview” on page 1-2 • “Before You Use MATLAB ® Compiler” on page 1-7 • “Deploying with the Magic Square Example” on page 1-11 • “For More Information” on page 1-24...

  • Page 18: Product Overview, What Does This Product Do?

    If you are building a standalone application, MATLAB Compiler produces an executable for your end users. If you integrate into C or C++, MATLAB Compiler provides an interface to use your code as a shared library. If you integrate into other development languages, MATLAB builder products (available separately) let you package your MATLAB applications as software components.

  • Page 19: When To Use Matlab ® Compiler, When Not To Use Matlab ® Compiler

    • Incorporate MATLAB-based algorithms into applications developed using other languages and technologies • Encrypt and protect MATLAB code When Not To Use MATLAB Compiler Do not use MATLAB Compiler and builder products for applications shown on the following table. Instead, use the recommended MathWorks™ product indicated. To...

  • Page 20: How Do I Use This Product?, How Does This Product Work?

    MCR and supporting files. The MCR is an engine for execution of compiled MATLAB code. As such, when a compiled application runs, there is sometimes a delay as the MCR...

  • Page 21

    An application or library generated by MATLAB Compiler has two parts: a platform-specific binary file and an archive file containing the encrypted MATLAB application and data. An application binary file consists of a main function. By contrast, a library binary consists of multiple functions for exporting.

  • Page 22: What Is The Matlab Compiler Runtime (mcr)?

    What Is The MATLAB Compiler Runtime (MCR)? The MATLAB Compiler Runtime is a standalone set of shared libraries that enable the execution of MATLAB files, even on computers without an installed version of MATLAB. You have the option to include the MCR with every package generated by the Deployment Tool ( ).

  • Page 23: Before You Use Matlab ® Compiler, Understand Your Role In The Application Deployment Process

    In smaller organizations, you find one person responsible for performing tasks associated with multiple roles. The table Application Deployment Roles, Tasks, and References on page 1-8 describes some of the different MATLAB Compiler roles or jobs. It also describes which tasks you would most likely perform when “Deploying with the Magic Square Example”...

  • Page 24

    • Understand “Magic Square Example: end-user business MATLAB Programmer requirements and Tasks” on page 1-11 the mathematical models they support • Write MATLAB code. • Build an executable component with MATLAB tools (usually with support from an IT programmer or Front-End Developer).

  • Page 25: Verify Your Knowledge Base, Install Required Products

    Using the MATLAB Compiler product requires the following knowledge: • If your job function is MATLAB programmer: A basic knowledge of MATLAB, and how to work with cell arrays and structures • If your job function is C or C++ developer:...

  • Page 26: Select Your C Or C++ Compiler With Mbuild -setup

    For more information about product installation and requirements, see Chapter 2, “Installation and Configuration”. Select Your C or C++ Compiler with mbuild -setup The first time you use MATLAB Compiler, after starting MATLAB, run the following command: mbuild -setup For more information about , see Chapter 2, “Installation and...

  • Page 27: Deploying With The Magic Square Example, About This Example, Magic Square Example: Matlab Programmer Tasks

    The Magic Square example in this section shows you how to: • Use MATLAB Compiler to create and package a simple standalone application that compiles a MATLAB file, magicsquare.m • Access the examples provided with MATLAB Compiler.

  • Page 28

    The class encapsulates a MATLAB function which computes a magic square. The client standalone application or shared library converts the array returned by the function to a native array and displays it on the screen. When...

  • Page 29

    Prepare to run the example by copying needed files into your work area as follows: Navigate to is the matlabroot\extern\examples\compiler matlabroot MATLAB root folder (where you installed MATLAB). To find the value of this variable on your system, type at a MATLAB command matlabroot prompt. Create a work folder named ).

  • Page 30

    You create a deployable standalone application or shared library by using the Deployment Tool GUI to build a wrapper. This wrapper encloses the sample MATLAB code discussed in “Testing the MATLAB File You Want To Deploy” on page 1-13. To run the Magic Square example, use the following...

  • Page 31

    Deploying with the Magic Square Example Click OK. Creating a C Shared Library Project On the Build tab: • Click Add files. Note You may optionally add supporting files. For examples of these files, see the Help. To add these files, in the Shared Resources deploytool and Helper Files area: Click Add files/directories...

  • Page 32

    Getting Started On the Package tab, add the MATLAB Compiler Runtime (the MCR) by clicking Add MCR. Next, add others files useful for end users. The file contains readme.txt important information about others files useful for end users. To package additional files or folders, click Add file/directories, select the file or folder you want to package, and click Open.

  • Page 33

    Note The Deployment Tool command line interface (CLI) can be run from the MATLAB command line window, the Windows command line, or a UNIX ® shell. Building Standalone Applications and Shared Libraries Using the Command Line. Instead of the GUI, you can use the command to run MATLAB Compiler.

  • Page 34

    Examines the input MATLAB files and the external dependency database to determine the complete list of all functions used by the application or component. As part of this process, MATLAB Compiler determines which files are not able to be compiled and automatically excludes them.

  • Page 35

    Deploying with the Magic Square Example Collects together the binary, the CTF archive, and the MCR installer (along with other optional, user-specified files) for the user. The deployment GUI ( ) automates many of the steps in the deploytool process for user convenience. 1-19...

  • Page 36

    Getting Started 1-20...

  • Page 37: Magic Square Example: C/c++ Programmer Tasks

    Before beginning, verify that you have access to the following files, packaged by the MATLAB Programmer in “Copy the Package You Created (Optional)” on page 1-16. End users who do not have a copy of MATLAB installed need the following: •...

  • Page 38

    The MATLAB Compiler Runtime (MCR) is an execution engine made up of the same shared libraries MATLAB uses to enable the execution of MATLAB files on systems without an installed version of MATLAB. In order to deploy a component, you package the MCR along with it. Before you utilize the MCR on a system without MATLAB, run the MCR installer.

  • Page 39

    ® application, you need to use the the Macintosh Application Launcher. See “Running Your 64-Bit Mac Application” on page B-7 in the MATLAB Compiler User Guide for more information. See Appendix B, “Using MATLAB ® Compiler on UNIX” in the MATLAB Compiler User Guide for complete information about building, deploying, and testing UNIX applications with MATLAB Compiler.

  • Page 40: For More Information

    Getting Started For More Information About This Look Here Detailed information on Chapter 7, “Standalone Applications” standalone applications Creating libraries Chapter 8, “Libraries” Using the command Chapter 6, “Compiler Commands” Troubleshooting Chapter 9, “Troubleshooting” 1-24...

  • Page 41

    Installation and Configuration • “Before You Install MATLAB ® Compiler” on page 2-2 • “Installing MATLAB ® Compiler” on page 2-5 • “Configuring Your Options File with mbuild” on page 2-6 • “If You Have Installation Problems” on page 2-12...

  • Page 42: Before You Install Matlab ® Compiler, Install Matlab, Install An Ansi C Or C++ Compiler

    To install MATLAB, refer to the MATLAB Installation Roadmap in the “Documentation Set”. See MATLAB Compiler Platform & Requirements for details. The memory and disk requirements to run MATLAB Compiler software are the same as the requirements for MATLAB. Install an ANSI C or C++ Compiler Install supported ANSI ®...

  • Page 43

    See the “Product Overview” in the MATLAB Builder NE documentation for a list of supported .NET Framework versions. Note For an up-to-date list of all the compilers supported by MATLAB and MATLAB Compiler, see the MathWorks™ Technical Support notes at: http://www.mathworks.com/support/compilers/current_release/...

  • Page 44

    Installation and Configuration Windows Operating System Issue Comment Installation options (Recommended) Full installation. Installing debugger files For the purposes of MATLAB Compiler, it is not necessary to install debugger (DBG) files. Microsoft Foundation Classes (MFC) Not needed. 16-bit DLLs Not needed. ActiveX ®...

  • Page 45: Installing Matlab ® Compiler, Compiler Options, On The Windows Operating System, On Unix Operating Systems

    Installation Guide for Windows documentation. If you have a license to install MATLAB Compiler, select the product as you proceed through the installation process. If MATLAB Compiler does not appear in your list of choices, contact The MathWorks to obtain an updated License File ( license.dat...

  • Page 46: Configuring Your Options File With Mbuild, What Is Mbuild?, When Not To Use Mbuild

    32-bit version of mbuild MATLAB. About mbuild and Linking Static linking is not an option for applications generated by MATLAB Compiler. Compiled applications all must link against . This shared MCLMCRRT library explicitly dynamically loads other shared libraries. You cannot change this behavior on any platform.

  • Page 47: Running Mbuild

    [3] Microsoft Visual C++ 2005 SP1 [4] Microsoft Visual C++ 2008 [5] Microsoft Visual C++ 2008 Express [0] None The preconfigured options files included with MATLAB for Windows appear in the following table. Note These options apply only to the 32-bit version of MATLAB.

  • Page 48

    To override the default options file, use the 'mbuild -f' command (see 'mbuild -help' for more information). The options files available for mbuild are: 1: matlabroot/bin/mbuildopts.sh : Build and link with MATLAB C-API or MATLAB Compiler-generated library via the system ANSI C/C++ compiler matlabroot/bin/mbuildopts.sh is being copied to /home/user/.matlab/ /mbuildopts.sh...

  • Page 49: Locating And Customizing The Options File

    Application Data\MathWorks\MATLAB\current_release Under Windows with user profiles enabled, your folder is user profile . However, with user profiles disabled, your %windir%\Profiles\username folder is . You can determine if user profiles are...

  • Page 50

    Changing the Options File Although it is common to use one options file for all of your MATLAB Compiler related work, you can change your options file at anytime. The option setup resets your default compiler to use the new compiler every time.

  • Page 51

    Configuring Your Options File with mbuild To modify your options file on the UNIX: to make a copy of the appropriate options file in your mbuild -setup local area. Edit your copy of the options file to correspond to your specific needs, and save the modified file.

  • Page 52: If You Have Installation Problems

    Installation and Configuration If You Have Installation Problems You can contact The MathWorks: • Via the Web at . On the MathWorks home page, www.mathworks.com click My Account to access your MathWorks Account, and follow the instructions. • Via e-mail at service@mathworks.com 2-12...

  • Page 53

    • “The MATLAB Application Deployment Products” on page 3-2 • “Building Your Application with the Application Deployment Products and the Deployment Tool” on page 3-4 • “Guidelines for Writing Deployable MATLAB Code” on page 3-10 • “Working with MATLAB Data Files Using Load and Save” on page 3-14...

  • Page 54: The Matlab Application Deployment Products

    MATLAB No access to IT systems business service developer Programmer The following tables summarizes the target applications supported by each product.: The MATLAB Suite of Application Deployment Products Target Create Create Create Product Create Web...

  • Page 55

    ® The MATLAB Application Deployment Products The MATLAB ® Application Deployment Products Each of the builder products uses the MATLAB Compiler core code to create deployable components.

  • Page 56: Building Your Application With The Application Deployment Products And The Deployment Tool

    The Deployment Tool interactive menus and dialogs build commands that are customized to your specification. As such, your MATLAB code is processed the same way as if you were compiling it using Using the Deployment Tool, you: • Perform related deployment tasks with a single intuitive GUI.

  • Page 57: What You Should Know About The Dependency Analysis Function (depfun)

    Deployability is affected by: • File type — MATLAB, Java, MEX, and so on. • File location — MATLAB, MATLAB toolbox, user code, and so on. • File deployability — Whether the file is deployable outside of MATLAB For more information about , see “What You Should Know About...

  • Page 58: Compiling Mex-files, Dlls, Or Shared Libraries

    Advanced tab in mcc -a the Deployment Tool under Settings. • Not all functions are compatible with MATLAB Compiler. Check the file after your build completes. This file lists all mccExcludedFiles.log functions called from your application that you cannot deploy.

  • Page 59

    MATLAB Compiler also embeds a CTF) archive in each generated binary. The CTF houses all deployable files. All MATLAB files encrypt in the CTF archive using the Advanced Encryption Standard (AES) cryptosystem. If you choose the extract the CTF archive as a separate file the files remain encrypted.

  • Page 60

    ® Writing Deployable MATLAB Code...

  • Page 61

    MATLAB files from multiple CTF archives into another CTF archive and distribute them. All the MATLAB files from a given CTF archive associate with a unique cryptographic key. MATLAB files with different keys, placed in the same CTF archive, do not execute.

  • Page 62: Guidelines For Writing Deployable Matlab Code, Compiled Applications Do Not Process Matlab Files At Runtime

    Compiled Applications Do Not Process MATLAB Files at Runtime The MATLAB Compiler was designed so that you can deploy locked down functionality. Deployable MATLAB files are suspended or frozen at the time MATLAB Compiler encrypts them—they do not change from that point onward.

  • Page 63: Do Not Rely On Changing Directory Or Path To Control The Execution Of Matlab Files

    EVAL FEVAL handles. If you require the ability to create MATLAB code for dynamic runtime processing, your end-users must have an installed copy of MATLAB. Do Not Rely on Changing Directory or Path to Control the Execution of MATLAB Files In general, good programming practices advise against redirecting a program search path dynamically within the code.

  • Page 64: Gradually Refactor Applications That Depend On Noncompilable Functions, Variables

    Standalone Application” on page 6-31. Gradually Refactor Applications That Depend on Noncompilable Functions Over time, refactor, streamline, and modularize MATLAB code containing non-compilable or non-deployable functions that use ismcc isdeployed Your eventual goal is “graceful degradation” of non-deployable code. In other words, the code must present the end user with as few obstacles to deployment as possible until it is practically eliminated.

  • Page 65

    Java class is preferable to defining the variable as static Note This guideline does not apply to MATLAB Builder EX customers. When programming with Microsoft Excel, you can assign global variables to large matrices that persist between calls.

  • Page 66: Working With Matlab Data Files Using Load And Save

    ® Writing Deployable MATLAB Code Working with MATLAB Data Files Using Load and Save If your deployed application uses MATLAB data files (MAT-files), it is helpful to code functions to manipulate the data and store it for later LOAD SAVE processing.

  • Page 67

    % structure included in the ctf archive file from root of the disk drive. % If a data file is outside of the main MATLAB file path, the absolute path will be % included in ctf and extracted under ctfroot. For example: Data file "c:\$matlabroot\examples\externdata\extern_data.mat"...

  • Page 68

    % LOADFILENAME2=which(fullfile(ctfroot,'userdata','extra_data.mat')); LOADFILENAME1=which(fullfile('user_data.mat')); LOADFILENAME2=which(fullfile('extra_data.mat')); % For external data file, full path will be added into ctf; % you don't need specify the full path to find the file. LOADFILENAME3=which(fullfile('extern_data.mat')); else %running the code in MATLAB LOADFILENAME1=fullfile(matlabroot,'extern','examples','compiler', 'Data_Handling','user_data.mat'); LOADFILENAME2=fullfile(matlabroot,'extern','examples','compiler', 'Data_Handling','userdata','extra_data.mat'); LOADFILENAME3=fullfile(matlabroot,'extern','examples','compiler', 'externdata','extern_data.mat');...

  • Page 69

    Working with MATLAB Data Files Using Load and Save %==== save the new data to a new file =========== SAVEPATH=strcat(pwd,filesep,'output'); if ( ~isdir(SAVEPATH)) mkdir(SAVEPATH); SAVEFILENAME=strcat(SAVEPATH,filesep,'saved_data.mat'); disp(['Save the A * B result to : ',SAVEFILENAME]); save(SAVEFILENAME, 'result'); 3-17...

  • Page 70

    ® Writing Deployable MATLAB Code 3-18...

  • Page 71

    Compilation Tasks • “Input and Output Files” on page 4-2 • “Dependency Analysis Function (depfun) and User Interaction with the Compilation Path” on page 4-8...

  • Page 72: Input And Output Files, Standalone Executable

    “C Shared Library” on page 4-3 “C++ Shared Library” on page 4-5 “Macintosh 64 (Maci64)” on page 4-7 Standalone Executable In this example, MATLAB Compiler takes the MATLAB files foo.m as input and generates a standalone called bar.m mcc -m foo.m bar.m...

  • Page 73: C Shared Library

    Input and Output Files C Shared Library In this example, MATLAB Compiler takes the MATLAB files foo.m as input and generates a C shared library called bar.m libfoo mcc -W lib:libfoo -T link:lib foo.m bar.m File Description The library wrapper C source file containing libfoo.c...

  • Page 74

    Compilation Tasks File Description Exports file used by the linker. The linker uses libname.exp the export file to build a program that contains exports, usually a dynamic-link library (. The import library is used to resolve references to those exports in other programs. Import library.

  • Page 75: C++ Shared Library

    Input and Output Files C++ Shared Library In this example, MATLAB Compiler takes the MATLAB files foo.m as input and generates a C++ shared library called bar.m libfoo mcc -W cpplib:libfoo -T link:lib foo.m bar.m File Description The library wrapper C++ source file containing libfoo.cpp...

  • Page 76

    Compilation Tasks File Description Exports file used by the linker. The linker uses libname.exp the export file to build a program that contains exports (usually a dynamic-link library (. The import library is used to resolve references to those exports in other programs. Import library.

  • Page 77: Macintosh 64 (maci64)

    Input and Output Files Macintosh 64 (Maci64) For 64-bit Macintosh, a Macintosh application bundle is created. File Description The bundle created for executable foo.app Execution of the bundle occurs through foo.app/Contents/MacOS/foo Application The generated shell script which executes the run_component.sh application through the bundle.

  • Page 78: Dependency Analysis Function (depfun) And User Interaction With The Compilation Path

    There are two disadvantages: • The path is modified for the current MATLAB session only. • If MATLAB Compiler is run outside of MATLAB, this doesn’t work unless a is done in MATLAB. savepath Note The path is also modified for any interactive work you are doing in the MATLAB environment as well.

  • Page 79

    • If a path is added with the option while this feature is active ( been passed) and it is already on the MATLAB path, it is added in the order-sensitive context as if it were included with . Otherwise, the folder...

  • Page 80

    Compilation Tasks 4-10...

  • Page 81

    Deployment Process This chapter tells you how to deploy compiled MATLAB code to programmers and to end users. • “Overview” on page 5-2 • “Deploying to Programmers” on page 5-3 • “Deploying to End Users” on page 5-9 • “Working with the MCR” on page 5-18 •...

  • Page 82: Overview

    • “Deploying to Programmers” on page 5-3 • “Deploying to End Users” on page 5-9 Note When you deploy, you provide the wrappers for the compiled MATLAB code and the software needed to support the wrappers, including the MCR. The MCR is version specific, so you must ensure that programmers as well as...

  • Page 83: Deploying To Programmers, Steps By The Programmer To Deploy To Programmers

    Create a package that contains the software necessary to support the compiled MATLAB code. It is frequently helpful to install the MCR on development machines, for testing purposes. See “What Software Does a Programmer Need?”...

  • Page 84: What Software Does A Programmer Need?

    What Software Does a Programmer Need? The software that you provide to a programmer who wants to use compiled MATLAB code depends on which of the following kinds of software the programmer will be using: • “Standalone Application” on page 5-4 •...

  • Page 85

    Note If you are using a non-Windows operating system, “console applications” are referred to as “standalone applications”. C or C++ Shared Library To distribute a shared library created with MATLAB Compiler to a development machine, create a package that includes the following files. Software Module Description MATLAB Compiler Runtime library archive;...

  • Page 86

    Description Software Module Utilities required for array processing. mwcomutil.dll Provides type definitions used in data conversion. Component that contains compiled MATLAB componentname_ code. version.dll Self-extracting MATLAB Compiler Runtime MCRInstaller.exe library utility; platform-dependent file that must correspond to the end user’s platform.

  • Page 87: Ensuring Memory For Deployed Applications

    <projectdir>\distrib Ensuring Memory for Deployed Applications If you are having trouble obtaining memory for your deployed application, use MATLAB Memory Shielding for deployed applications to ensure a maximum amount of contiguous allocated memory. See “Reserving Memory...

  • Page 88

    Deployment Process for Deployed Applications with MATLAB Memory Shielding” on page 5-42 for more information.

  • Page 89: Deploying To End Users, Steps By The Programmer To Deploy To End Users

    For an end user to run an application or use a library that contains compiled MATLAB code, there are two sets of tasks. Some tasks are for the programmer who developed the application or library, and some tasks are for the end user.

  • Page 90

    Be aware of the following with regards to preferences: • MATLAB preferences set at compile time are inherited by the compiled application. Therefore, include no files in your preferences folder that you do not want exposed to end users.

  • Page 91

    MCR and whether you want to install the MCR for just yourself or others. Click Next to continue. Note The Install MATLAB Compiler Runtime for yourself, or for anyone who uses this computer option is not implemented for this release.

  • Page 92: What Software Does The End User Need?

    • “Microsoft ® Excel Add-In” on page 5-14 Standalone Compiled Application That Accesses Shared Library To distribute a shared library created with MATLAB Compiler to end users, create a package that includes the following files. Component Description Self-extracting MATLAB Compiler Runtime MCRInstaller.exe...

  • Page 93

    MCR Installer (if not already installed on the MCRInstaller.exe target machine) Application application.exe COM Application To distribute a COM application that uses components created with MATLAB Builder NE or MATLAB Builder EX, create a package that includes the following files. 5-13...

  • Page 94

    To deploy the application on computers without componentname.jar MATLAB, you must include the MCR when creating your Java component. Microsoft Excel Add-In To distribute an Excel add-in created with MATLAB Builder EX, create a package that includes the following files. Software Module Description...

  • Page 95: Using Relative Paths With Project Files, Porting Generated Code To A Different Platform

    Using Relative Paths with Project Files Project files now support the use of relative paths as of R2007b of MATLAB Compiler, enabling you to share a single project file for convenient deployment over the network. Simply share your project folder and use relative paths to define your project location to your distributed computers.

  • Page 96: Extracting A Ctf Archive Without Executing The Component, Ensuring Memory For Deployed Applications

    Extracting a CTF Archive Without Executing the Component CTF archives contain content (MATLAB files and MEX-files) that need to be extracted from the archive before they can be executed. In order to extract the archive you must override the default CTF embedding option (see “Overriding Default CTF Archive Embedding Using the MCR Component Cache”...

  • Page 97

    Deploying to End Users for Deployed Applications with MATLAB Memory Shielding” on page 5-42 for more information. 5-17...

  • Page 98: Working With The Mcr, About The Matlab ® Compiler Runtime (mcr)

    MATLAB files on computers without an installed version of MATLAB. If you do not have MATLAB installed on the target machine and you want to run components created by MATLAB Compiler , you still need to install the MCR on the target machine, whether you are a developer or end user.

  • Page 99: Installing The Mcr And Matlab On The Same Machine

    MCR. mcrversion • The MATLAB and Java paths in an MCR instance are fixed and cannot be changed. To change them, you must first customize them within MATLAB. Performance Considerations and the MCR MATLAB Compiler was designed to work with a large range of applications that use the MATLAB programming language.

  • Page 100

    MCR and an installed MATLAB on the same machine. Modifying the Path If you install the MCR on a machine that already has MATLAB on it, you must adjust the library path according to your needs. Windows. To run deployed components against the MCR install,...

  • Page 101: Installing Multiple Mcrs On One Machine, Retrieving Mcr Attributes

    Mac OS X. When you receive a new version of MATLAB, you must recompile and redeploy all of your applications and components. Also, when you install a new MCR onto a target machine, you must delete the old version of the MCR and install the new one.

  • Page 102

    Deployment Process Function and Signature When to Use Return Value Boolean ( bool mclIsMCRInitialized() true false to determine whether or not Returns if MCR is already mclIsMCRInitialized() true the MCR has been properly initialized, else returns false initialized. Boolean ( bool mclIsJVMEnabled() mclIsJVMEnabled() true...

  • Page 103: Improving Data Access Using The Mcr User Data Interface

    Interface The MCR User Data Interface lets you easily access MCR data. It allows keys and values to be passed between an MCR instance, the MATLAB code running on the MCR, and the wrapper code that created the MCR. Through...

  • Page 104

    MATLAB Compiler or builder products. See Chapter 13, “Functions — Alphabetical List”, for more information. Caution These functions will produce an error when Unknown function called in MATLAB if the MCLMCR module cannot be located. This can be avoided by calling before calling isdeployed getmcruserdata .

  • Page 105

    Working with the MCR External C Functions Use the following C functions in deployed C/C++ applications. See Chapter 13, “Functions — Alphabetical List” for more information. • libname GetMcrID • mclSetMCRUserData • mclGetMCRUserData • mclSetCmdLineUserData Setting MCR Data for Standalone Executables MCR data can be set for a standalone executable with the -mcruserdata command line argument.

  • Page 106

    MCR data you want to update. In your code, Include the MCR header file and the library header generated by MATLAB Compiler. Properly initialize your application using mclInitializeApplication After creating your input data, write or “set” it to the MCR with , as appropriate.

  • Page 107

    #include <stdio.h> /* Include the MCR header file and the library specific header * file as generated by MATLAB Compiler */ #include "libmagicmatrix.h" /* This function is used to display a double matrix stored in * an mxArray */ void display(const mxArray* in);...

  • Page 108

    Deployment Process fprintf(stderr,"Could not initialize the library.\n"); return -2; else /* Declare an array to hold the inputs */ mxArray *key = 0, *inputValue = 0; /* Create the input data */ inputValue = mxCreateDoubleMatrix(3,3,mxREAL); /* key */ key = mxCreateString("MagicMatrix"); /* value */ memcpy(mxGetPr(inputValue), data, 9*sizeof(double));...

  • Page 109

    Working with the MCR /*DISPLAY This function will display the double matrix stored * in an mxArray. * This function assumes that the mxArray passed as * input contains double array. void display(const mxArray* in) int i=0, j=0; /* loop index variables */ int r=0, c=0;...

  • Page 110

    Configurations”. For information about using the MCR User Data Interface see “Improving Data Access Using the MCR User Data Interface” in the MATLAB Builder JA, MATLAB Builder NE, and MATLAB Builder EX user guides. For a complete working example describing how to use Parallel Computing Toolbox with MATLAB Builder JA, see “Example: Supplying Run-Time...

  • Page 111

    MDCS cluster. This step shows you how to export the configuration MAT file of your cluster. On the MATLAB desktop, click Parallel > Manage Configuration. The Manage Configuration dialog opens. Select your configuration file (representing the cluster), right click, and select Export to export the configuration file as a MAT file.

  • Page 112

    Deployment Process Step 3: Compile and Deploy Your Application Follow the steps in “Creating a Deployable Standalone Application or Shared Library” on page 1-14 to compile your application, adding in the Main File area. When the compilation finishes, a sample_pct.m new folder (with the same name as the project) is created.

  • Page 113

    Note It is not possible to compile and deploy applications using the LOCAL scheduler. You must have access to MDCS workers. Step 1: Write Your PCT Code Compile the following two files in MATLAB. Note that, in this example, calls and supplies the configuration MAT file run_sample_pct sample_pct directly as MCR user data.

  • Page 114

    Deployment Process setmcruserdata('ParallelConfigurationFile',matfile); speedup = sample_pct(n) function speedup = sample_pct (n) warning off all; if(ischar(n)) n=str2double(n); for ii = 1:n (cov(sin(magic(n)+rand(n,n)))); time1 =toc; matlabpool('open',4); parfor ii = 1:n (cov(sin(magic(n)+rand(n,n)))); time2 =toc; disp(['Normal loop times: ' num2str(time1) ', parallel loop time: ' num2str(time2) ]); disp(['parallel speedup: ' num2str(1/(time2/time1)) ' times faster than normal']);...

  • Page 115

    Working with the MCR Note The end-user’s target machine must have access to the cluster. To run the deployed application, do the following: On the end-user machine, navigate to directory containing the EXE file. Issue the following command. Note that, in this case, you are not supplying the MAT file explicitly, since it is included in the CTF archive.

  • Page 116

    Select a Microsoft compiler using . For more information mbuild -setup about selecting compilers, see Chapter 2, “Installation and Configuration”. Compile the following two files in MATLAB. Note that, in this example, calls and supplies the configuration MAT file run_sample_pct sample_pct directly as MCR user data.

  • Page 117: Messages For Users

    Working with the MCR time2 =toc; matlabpool('close','force'); speedup = (time1/time2); Step 2: Compile and Deploy Your Application Follow the steps in “Creating a Deployable Standalone Application or Shared Library” on page 1-14 to compile your application. Add in the Main File area and add run_sample_pct.m myconfig.mat in the Shared Resources and Helper Files area.

  • Page 118

    You have the following options: • Use the default start-up message only ( Initializing MATLAB Compiler Runtime version x.xx • Customize the start-up or completion message with text of your choice. The default start-up message will also display prior to displaying your customized start-up message.

  • Page 119

    If you are using MATLAB Builder EX, register mwcomutil.dll on every client machine. mwcommgr.dll If you are using MATLAB Builder NE (to create COM objects), register on every client machine. mwcomutil.dll To register the DLLs, at the DOS prompt enter mwregsvr <...

  • Page 120: Matlab ® Compiler Deployment Messages

    Deployment Process MATLAB Compiler Deployment Messages To enable display of MATLAB Compiler deployment messages, see “Enabling MATLAB Compiler Deployment Messages” in MATLAB Desktop Tools and Development Environment. 5-40...

  • Page 121: Using Matlab ® Compiler Generated Dlls In Windows Services

    -Xrs Save the file to: , where MCRROOT/version/runtime/win32|win64 MCRROOT is the installation folder of the MATLAB Compiler Runtime and version the MCR version (for example, for MATLAB Compiler 4.4 (R2006a)). Caution Failure to create the file using these steps may result in java.opts...

  • Page 122: Reserving Memory For Deployed Applications With Matlab Memory Shielding

    Reserving Memory for Deployed Applications with MATLAB Memory Shielding In this section... “What Is MATLAB Memory Shielding and When Should You Use It?” on page 5-42 “Requirements for Using MATLAB Memory Shielding” on page 5-43 “Invoking MATLAB Memory Shielding for Your Deployed Application”...

  • Page 123: Requirements For Using Matlab Memory Shielding, Application

    MATLAB Memory Shielding does not work with shared libraries, .NET components or Java components. • You have run the MCR Installer on your system to get the MATLAB Compiler Runtime (MCR). The memory shielding feature is installed with the MCR.

  • Page 124

    Deployment Process Using the Command Line Use the command line if you want to invoke memory shielding only with the various values (not specific address ranges). shield_level The base command-line syntax is: MemShieldStarter [-help] [-gui] [-shield shield_level fully-qualified_application_path user-defined_application_arguments Run your application using the default level of memory shielding. Use the command: MemShieldStarter fully-qualified_application_path...

  • Page 125

    , but protects the range until just after startup processes 0x70000000 . It ensures that there is at least approximately 500 MB of matlabrc contiguous memory up to this point. If MATLAB fails to start successfully with the option, use the default option ( -shield medium -shield ).

  • Page 126

    1.5 GB, until just after startup processes matlabrc The default memory shielding range for covers maximum 0x10000000 . If MATLAB fails to start successfully with the 0x78000000 -shield option, use the option. maximum -shield medium Note The shielding range may vary in various locales. Contact your system administrator for further details.

  • Page 127

    ® Reserving Memory for Deployed Applications with MATLAB Memory Shielding Enter the appropriate values as described in MemShieldStarter Options on page 5-45. Use the default Memory shielding level minimum You can specify a specific address range in the Memory address range fields.

  • Page 128

    Deployment Process 5-48...

  • Page 129

    • “Using Path Names” on page 6-8 • “Using Bundle Files” on page 6-9 • “Using Wrapper Files” on page 6-11 • “Interfacing MATLAB Code to C/C++ Code” on page 6-14 • “Overriding Default CTF Archive Embedding Using the MCR Component Cache” on page 6-20 •...

  • Page 130: Command Overview, Compiler Options, Combining Options

    “Conflicting Options on the Command Line” on page 6-3 “Using File Extensions” on page 6-3 Compiler Options is the MATLAB command that invokes MATLAB Compiler. You can issue command either from the MATLAB command prompt (MATLAB mode) or the DOS or UNIX command line (standalone mode).

  • Page 131: Conflicting Options On The Command Line, Using File Extensions

    C++ files. Conflicting Options on the Command Line If you use conflicting options, MATLAB Compiler resolves them from left to right, with the rightmost option taking precedence. For example, using the equivalencies in “Macro Options” on page 6-5, mcc -m -W none test.m...

  • Page 132

    Note P-files ( ) have precedence over MATLAB files, therefore if both P-files and MATLAB files reside in a folder, and a file name is specified without an extension, the P-file will be selected.

  • Page 133: Using Macros To Simplify Compilation, Macro Options, Working With Macro Options

    “Working With Macro Options” on page 6-5 Macro Options MATLAB Compiler, through its exhaustive set of options, gives you access to the tools you need to do your job. If you want a simplified approach to compilation, you can use one simple option, i.e., macro, that allows you to quickly accomplish basic compilation tasks.

  • Page 134

    Note This changes the meaning of for all users of this MATLAB installation. Specifying Default Macro Options As the functionality has been replaced by bundle file technology, MCCSTARTUP file that resides in...

  • Page 135

    Using Macros to Simplify Compilation mcc -v -W 'lib:libfoo' -T link:lib foo.m...

  • Page 136: Using Path Names

    MATLAB file during the dependency analysis phase. Note MATLAB Compiler produces a warning ( ) if specified_file_mismatch a file with a full path name is included on the command line and MATLAB Compiler finds it somewhere else.

  • Page 137: Using Bundle Files

    C shared libraries, , that consists of: csharedlib -W lib:%1% -T link:lib To invoke MATLAB Compiler to produce a C shared library using this bundle, you can use: mcc -B csharedlib:mysharedlib myfile.m myfile2.m In general, each in the bundle file will be replaced with the corresponding option specified to the bundle file.

  • Page 138

    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 See the following table for a list of bundle files available with MATLAB Compiler. Bundle File Creates...

  • Page 139: Using Wrapper Files, What Are Wrapper Files?, Main File Wrapper

    What Are Wrapper Files? Wrapper files encapsulate, or wrap, the MATLAB files in your application with an interface that enables the MATLAB files to operate in a given target environment. To provide the required interface, the wrapper does the following: •...

  • Page 140: C Library Wrapper

    DOS/UNIX shell, the return value is handled as the return status code. When you compile a function into a POSIX main application, the return status is set to 0 if the compiled MATLAB file is executed without errors and is nonzero if there are errors.

  • Page 141: C++ Library Wrapper

    C++ library wrapper file. This -W cpplib:libname option allows the inclusion of an arbitrary set of MATLAB files into a library. The generated header file contains all of the entry points for all of the compiled MATLAB functions.

  • Page 142: Interfacing Matlab Code To C/c++ Code, Overview

    C Example Suppose you have a C function that reads data from a measurement device. In MATLAB code, you want to simulate the device by providing a sine wave output, so you provide a function that returns the measurement obtained from the device.

  • Page 143

    = t+0.05; y = sin(t); Compile the function. collect When this file is compiled, MATLAB Compiler creates the additional header file , which contains the interface collect_one_external.h between MATLAB Compiler generated code and your code. In this example, it would contain: extern bool mlxCollect_one(int nlhs, mxArray *plhs[], int nrhs, mxArray *prhs[]);...

  • Page 144: C++ Example

    C++ Example Suppose you have a C function that reads data from a measurement device. In MATLAB code, you want to simulate the device by providing a sine wave output, so you provide a function that returns the measurement obtained from the device.

  • Page 145

    This function must conform to the same interface as code generated by MATLAB Compiler. MATLAB Compiler will generate the interface for any functions that contain the pragma into a separate file called %#external .

  • Page 146

    = t + 0.05; y = sin(t); Compile the function. collect When this file is compiled, MATLAB Compiler creates the additional header file , which contains the interface collect_one_external.h between MATLAB Compiler generated code and your code. In this...

  • Page 147

    Interfacing MATLAB Code to C/C++ Code double measure_from_device(void) static double t = 0.0; t = t + 0.05; return sin(t); To generate the application, use mcc -m collect.m measure.cpp 6-19...

  • Page 148: Overriding Default Ctf Archive Embedding Using The Mcr Component Cache

    Compiler Commands Overriding Default CTF Archive Embedding Using the MCR Component Cache As of R2008a, CTF data is automatically embedded directly in the C/C++, main and Winmain, shared libraries and standalones by default. In order to override this default functionality, you must compile using the option “-C Do Not Embed CTF Archive by Default”...

  • Page 149

    Overriding Default CTF Archive Embedding Using the MCR Component Cache Purpose Notes Environment Variable , which resides in .max_size the file designated by running command, mcrcachedir with the desired cache size limit. Note If you run specifying conflicting wrapper and target types, the CTF will not be embedded into the generated component.

  • Page 150: Using Pragmas, Using Feval, Example: Using %#function

    MATLAB Compiler dependency analysis detects it. Without this pragma, the MATLAB Compiler dependency analysis will not be able to locate and compile all MATLAB files used in your application. This pragma adds the top-level function as well as all the subfunctions in the file to the compilation.

  • Page 151

    Using Pragmas %#function bartlett, barthannwin, blackman, blackmanharris, bohmanwin, chebwin, flattopwin, gausswin, hamming, hann, kaiser, nuttallwin, parzenwin, rectwin, tukeywin, triang window = feval(filterName,N); % Apply the window to the data. ret = data.*window; 6-23...

  • Page 152: Using Mxarray

    For full documentation on the mxArray API, see “MX Matrix Library” in MATLAB C and Fortran API Reference. For a complete description of data types used with mxArray, see “MATLAB Data” in MATLAB External Interfaces. For general information on data handling, see MATLAB External Interfaces.

  • Page 153: Script Files, Converting Script Matlab Files To Function Matlab Files

    • Script MATLAB files Some things to remember about script and function MATLAB files: • Variables used inside function MATLAB files are local to that function; you cannot access these variables from the MATLAB interpreter’s workspace unless they are passed back by the function. By contrast, variables used inside script MATLAB files are shared with the caller’s workspace;...

  • Page 154: Including Script Files In Deployed Applications

    The second layer of MATLAB files in compiled applications includes those MATLAB files that are called by the functions in the top layer. You can include scripts in the second layer, but not in the top layer. For example, you can produce an application from the script houdini.m...

  • Page 155

    Script Files 6-27...

  • Page 156: Compiler Tips, Calling Built-in Functions From C Or C++

    To enable a C or C++ program to call a built-in function directly, you must write an MATLAB file wrapper around each built-in function you want to access outside of MATLAB. This is necessary because there are no C callable interfaces to built-in functions. For example, to use the...

  • Page 157: Calling A Function From The Command Line, Using Mat-files In Deployed Applications

    • Modify the original MATLAB function to test each argument and convert the strings to numbers. • Write a wrapper MATLAB function that does this test and then calls the original MATLAB function. For example: function x=foo(a, b) if (ischar(a)), a = str2num(a), end;...

  • Page 158: Debugging Matlab ® Compiler Generated Executables, Libraries, Locating .fig Files In Deployed Applications

    Debugging MATLAB Compiler Generated Executables As of MATLAB Compiler 4, it is no longer possible to debug your entire program using a C/C++ debugger; most of the application is MATLAB code, which can only be debugged in MATLAB. Instead, run your code in MATLAB and verify that it produces the desired results.

  • Page 159: Blocking Execution Of A Console Application That Creates Figures And Terminating Figures By Force, Application

    Execution of a Console Application that Creates Figures” in the MATLAB Builder NE User’s Guide and “Blocking Execution of a Console Application that Creates Figures” in the MATLAB Builder JA User’s Guide for more details and code fragment examples. Caution Use caution when calling the function.

  • Page 160

    For more information, see the MATLAB command. The things you should keep in mind for your MATLAB file before you compile are: • The input arguments you pass to your application from a system prompt are considered as string input. If, in your MATLAB code before compilation, you are expecting the data in different format, say double, you will need to convert the string input to the required format.

  • Page 161: Using Graphical Applications In Shared Library Targets, Application

    Application When you use the function in a compiled MATLAB application, it will perform with the same functionality as if you had called it from MATLAB. However, be aware that when using in a compiled MATLAB application, only version information for toolboxes which the compiled application uses will be displayed.

  • Page 162

    Compiler Commands 6-34...

  • Page 163

    Standalone Applications This chapter describes how to use MATLAB Compiler to code and build standalone applications. You can distribute standalone applications to users who do not have MATLAB software on their systems. • “Introduction” on page 7-2 • “C Standalone Application Target” on page 7-3...

  • Page 164: Introduction

    C or C++; however, this would require writing your own magic square, rank, and singular value routines. An easier way to create this application is to write it as one or more MATLAB files, taking advantage of the power of MATLAB and its tools.

  • Page 165: C Standalone Application Target, Compiling The Application, Testing The Application

    “Compiling the Application” on page 7-3 “Testing the Application” on page 7-3 “Deploying the Application” on page 7-4 “Running the Application” on page 7-6 Compiling the Application This example takes an MATLAB file, , and creates a magicsquare.m standalone C application, magicsquare...

  • Page 166: Deploying The Application

    For example, if you want to deploy an application to a Windows machine, you must use MATLAB Compiler to build the application on a Windows machine. If you want to deploy the same application to a UNIX machine, you must use MATLAB Compiler on the same UNIX platform and completely rebuild the application.

  • Page 167

    UNIX Distribute and package your standalone application on UNIX by packaging the following files and distributing them to the deployment machine. Component Description MATLAB Compiler Runtime library archive; MCRInstaller.bin platform-dependent file that must correspond to the end user’s platform Application...

  • Page 168: Running The Application

    . For more information on running the MCR MCRInstaller.exe C:\MCR Installer utility and modifying your system paths, see “Install the MCR on Target Computers Without MATLAB and Update System Paths” on page 1-22. Executing the Application Run the standalone application from the system prompt and...

  • Page 169

    For more information, see “Passing Arguments to and from a Standalone Application” on page 6-31. Note Before executing your MATLAB Compiler generated executable, set environment variable to LD_PRELOAD /lib/libgcc_s.so.1 Executing the Application on 64-Bit Macintosh (Maci64).

  • Page 170: Create A Standalone Application, Mixing Matlab Files And C Or C++, Examples Overview

    One way to create a standalone application is to code some of it as one or more function MATLAB files and to code other parts directly in C or C++. To write a standalone application this way, you must know how to do the following: •...

  • Page 171: Simple Example

    To perform these steps, enter the following on a single line: mcc -W lib:libPkg -T link:exe mrank printmatrix mrankp.c main_for_lib.c The following flow diagram shows the mixing of MATLAB files and C-files that forms this sample standalone application. The top part of the diagram shows the process and the lower part shows the process.

  • Page 172

    Standalone Applications MATLAB Compiler generates the following C source code files: • libPkg.c • libPkg.h • libPkg_mcc_component_data.c 7-10...

  • Page 173

    Mixing MATLAB Files and C or C++ This command invokes to compile the resulting MATLAB Compiler mbuild generated source files with the existing C source files ( mrankp.c ) and link against the required libraries. main_for_lib.c MATLAB Compiler provides two different versions of in the mrankp.c...

  • Page 174

    First, the code must initialize the MCR and the generated libPkg library. mclInitializeApplication(NULL,0); libPkgInitialize(); /* Initialize the library of MATLAB functions */ To understand how to call , examine its C function header, which is mlfMrank void mlfMrank(int nargout, mxArray** r, mxArray* n);...

  • Page 175: Advanced C Example

    /* Terminate the MCR */ Advanced C Example This section provides an advanced example that illustrates how to write C code that calls a compiled MATLAB file. Consider a standalone application whose source code consists of the files: , which contains a function named •...

  • Page 176

    #include <stdio.h> #include <string.h> #include <math.h> #include "libMultpkg.h" * Function prototype; MATLAB Compiler creates mlfMultarg * from multarg.m void PrintHandler( const char *text ) printf(text); int main( ) /* Programmer-written coded to call mlfMultarg */ #define ROWS #define COLS mclOutputHandlerFcn PrintHandler;...

  • Page 177

    Mixing MATLAB Files and C or C++ /* Initialize with a print handler to tell mlfPrintMatrix * how to display its output. mclInitializeApplication(NULL,0); libMultpkgInitializeWithHandlers(PrintHandler,PrintHandler); /* Create input matrix "x" */ x = mxCreateDoubleMatrix(ROWS, COLS, mxCOMPLEX); memcpy(mxGetPr(x), x_pr, ROWS * COLS * sizeof(double));...

  • Page 178

    50.2655 +28.2743i 18.8496 +18.8496i 37.6991 +37.6991i 56.5487 +28.2743i 143.4164 Explanation of This C Code Invoking MATLAB Compiler on generates the C function multarg.m prototype. extern void mlfMultarg(int nargout, mxArray** a, mxArray** b, mxArray* x, mxArray* y); This C function header shows two input arguments (...

  • Page 179

    Libraries This chapter describes how to use MATLAB Compiler to create libraries. • “Introduction” on page 8-2 • “Addressing mwArrays Above the 2 GB Limit” on page 8-3 • “C Shared Library Target” on page 8-4 • “C++ Shared Library Target” on page 8-18 •...

  • Page 180

    Libraries Introduction You can use MATLAB Compiler to create C or C++ shared libraries (DLLs on Microsoft Windows) from your MATLAB algorithms. You can then write C or C++ programs that can call the MATLAB functions in the shared library,...

  • Page 181: Addressing Mwarrays Above The 2 Gb Limit

    Addressing mwArrays Above the 2 GB Limit Addressing mwArrays Above the 2 GB Limit In R2007b, you had to define in the step to address MX_COMPAT_32_OFF mbuild s above the 2 GB limit on 64-bit architectures. If you did not define MWArray , the compile time variable was defined for...

  • Page 182: C Shared Library Target, C Shared Library Wrapper, C Shared Library Example

    MathWorks Support database and search for information on the MSVC shared library. C Shared Library Example This example takes several MATLAB files and creates a C shared library. It also includes a standalone driver application to call the shared library.

  • Page 183

    Note You must call once at the beginning mclInitializeApplication of your driver application. You must make this call before calling any other MathWorks functions or when linking to a MATLAB library such as (for example, before accessing an ). See “Calling a mclmcrrt.lib MWArray Shared Library”...

  • Page 184

    Invoke functions in the library, and process the results. (This is the main body of the program.) Note If your driver application displays MATLAB figure windows, you should include a call to before calling mclWaitForFiguresToDie(NULL)

  • Page 185

    C Shared Library Target will bring down enough of the MCR address Caution <lib>Terminate space that the same library (or any other library) cannot be initialized. Issuing a call after a call causes <lib>Initialize <lib>Terminate unpredictable results. Instead, use the following structure: code mclInitializeApplication();...

  • Page 186

    , on UNIX. matrixdriver Difference in the Exported Function Signature. The interface to the functions generated by MATLAB Compiler from your MATLAB file routines has changed from earlier versions of the product. The generic signature of the exported functions is •...

  • Page 187

    C Shared Library Target Note Testing your application on your development machine is an important step to help ensure that your application is compilable. To verify that your application compiled properly, you must test all functionality that is available with the application. If you receive an error message similar to Undefined , it function...

  • Page 188

    If you want to deploy the same application to a different platform, you must use MATLAB Compiler on the different platform and completely rebuild the application.

  • Page 189: Calling A Shared Library

    Calling a Shared Library At run-time, there is an MCR instance associated with each individual shared library. Consequently, if an application links against two MATLAB Compiler generated shared libraries, there will be two MCR instances created at run-time. You can control the behavior of each MCR instance by using MCR options.

  • Page 190

    These functions are necessary because some MCR options such as whether or not to start Java, whether or not to use the MATLAB JIT feature, and so on, are set when the first MCR instance starts and cannot be changed by subsequent instances of the MCR.

  • Page 191

    /* Destroy return value since this variable will be reused in next function call. Since we are going to reuse the variable, we have to set it to NULL. Refer to MATLAB Compiler documentation for more information on this. */ mxDestroyArray(out);...

  • Page 192

    Using a Shared Library To use a MATLAB Compiler generated shared library in your application, you must perform the following steps: Include the generated header file for each library in your application. Each MATLAB Compiler generated shared library has an associated header file...

  • Page 193

    Initialize the MATLAB libraries by calling the mclInitializeApplication API function. You must call this function once per application, and it must be called before calling any other MATLAB API functions, such as C-Mex functions or C MAT-file functions. must be...

  • Page 194

    API function. This mclTerminateApplication function frees application-level resources used by the MCR. Once you call this function, no further calls can be made to MATLAB Compiler generated libraries in the application. Loading Libraries in a Compiled Function With MATLAB Compiler version 4.0 (R14) and later, you can use MATLAB file prototypes as described below to load your library in a compiled application.

  • Page 195: Using C Shared Libraries On A Mac Os X System

    Note You can use your operating system’s function to call loadlibrary a MATLAB Compiler shared library function as long as you first call the initialization and termination functions mclInitializeApplication() mclTerminateApplication() Using C Shared Libraries On a Mac OS X System For information on using C shared libraries on a Macintosh system, see “Using C/C++ Shared Libraries on a Mac OS X System”...

  • Page 196: C++ Shared Library Target, C++ Shared Library Wrapper, C++ Shared Library Example

    C++ Shared Library Example This example rewrites the previous C shared library example using C++. The procedure for creating a C++ shared library from MATLAB files is identical to the procedure for creating a C shared library, except you use the cpplib wrapper.

  • Page 197

    . Every class mwArray mwArray object contains a pointer to a MATLAB array structure. For this reason, the attributes of an object are a superset of the attributes of a MATLAB mwArray array. Every MATLAB array contains information about the size and shape of the array (i.e., the number of rows, columns, and pages) and either one or...

  • Page 198

    Exported Function Signature The C++ shared library target generates two sets of interfaces for each MATLAB function. The first set of exported interfaces is identical to the signatures that are generated in C shared libraries. The second set of interfaces is the C++ function interfaces. The generic signature of the exported C++ functions is as follows: MATLAB Functions with No Return Values.

  • Page 199

    C++ interface functions. Using C/C++ Shared Libraries on a Mac OS X System To use a MATLAB Compiler generated library on a Mac OS X system, a separate thread needs to be created. The initialization of the shared library and subsequent calls to that library’s functions is performed by this thread.

  • Page 200

    Working with C++ Shared Libraries and Sparse Arrays The MATLAB Compiler API includes static factory methods for working with sparse arrays. For a complete list of the methods, see “Static Factory Methods for Sparse Arrays” on page D-31.

  • Page 201: Matlab ® Compiler Generated Interface Functions, Functions In The Shared Library, Type Of Application

    “Retrieving MCR State Information While Using Shared Libraries” on page 8-34 Functions in the Shared Library A shared library generated by MATLAB Compiler contains at least seven functions. There are three generated functions to manage library initialization and termination, one each for printed output and error messages, and two generated functions for each MATLAB file compiled into the library.

  • Page 202

    Libraries mbuild triangle.c main_for_lib.c -L. -ltriangle -I. For a C++ Application on Windows mcc -W cpplib:libtrianglep -T link:lib sierpinski.m mbuild triangle.cpp main_for_lib.c libtrianglep.lib For a C++ Application on UNIX mcc -W cpplib:libtriangle -T link:lib sierpinski.m mbuild triangle.cpp main_for_lib.c -L. -ltriangle -I. These commands create a main program named , and a shared triangle...

  • Page 203: Structure Of Programs That Call Shared Libraries

    ® MATLAB Compiler™ Generated Interface Functions In this example, MATLAB Compiler places all of the generated functions into the generated file libtriangle.c libtriangle.cpp Structure of Programs That Call Shared Libraries All programs that call MATLAB Compiler generated shared libraries have roughly the same structure: Declare variables and process/validate input arguments.

  • Page 204: Library Initialization And Termination Functions

    Libraries Call, once for each library, , to destroy the <libraryname>Terminate associated MCR. Call to free resources associated with the mclTerminateApplication global MCR state. Clean up variables, close files, etc., and exit. To see these steps in an actual example, review the main program in this example, triangle.c Library Initialization and Termination Functions...

  • Page 205: Print And Error Handling Functions

    By default, MATLAB Compiler generated applications and shared libraries send printed output to standard output and error messages to standard error. MATLAB Compiler generates a default print handler and a default error handler that implement this policy. If you’d like to change this behavior, you must write your own error and print handlers and pass them in to the appropriate generated initialization function.

  • Page 206

    “handled.” The MCR calls the print handler when an executing MATLAB file makes a request for printed output, e.g., via the MATLAB function . The print handler does not terminate the output disp with a carriage return or line feed.

  • Page 207: Functions Generated From Matlab Files

    (The “ ” in these argument names is short for “left-hand side” -- the output variables in a MATLAB expression are those on the 8-29...

  • Page 208

    It also implies that you must pass either NULL or a valid MATLAB array for all output variables or your program will fail because the memory manager cannot distinguish between a noninitialized (invalid) array pointer and a valid array. It will try to free a pointer that is not NULL -- freeing an invalid pointer usually causes a segmentation fault or similar fatal error.

  • Page 209

    As in the MATLAB software, the cell array representing has to be the last return variable (the variable preceding the first varagout...

  • Page 210

    ). However, calling nargin=0 with the C++ shared library interface causes the FOO((mwArray)NULL) compiled MATLAB code to see an empty array as the first input and interprets nargin=1 For example, compile some MATLAB code as a C++ shared library using as the MATLAB function’s list of input arguments.

  • Page 211

    Note For simplicity, only the relevant part of the generated C++ function signature is shown in the following examples. function varargout = foo(varargin) For this MATLAB function, the following C++ overloaded functions are generated: No input no output: void foo() Only inputs: void foo(const mwArray&...

  • Page 212: Libraries

    Libraries function [o1, o2, varargout] = foo(varargin) For this MATLAB function, the following C++ overloaded functions are generated: Most generic form that has all the outputs and inputs void foo(int nargout, mwArray& o1, mwArray& o2, mwArray& varargout, const mwArray& varargin) Only outputs: void foo(int nargout, mwArray&...

  • Page 213: About Memory Management And Cleanup, Overview, Passing Mxarrays To Shared Libraries

    If memory constraints are still present on your system, try preallocating arrays in MATLAB. This will reduce the number of calls to the memory manager, and the degree to which the heap fragments. Passing mxArrays to Shared Libraries...

  • Page 214

    Libraries 8-36...

  • Page 215

    Troubleshooting • “Introduction” on page 9-2 • “Common Issues” on page 9-3 • “Failure Points and Possible Solutions” on page 9-4 • “mbuild” on page 9-14 • “MATLAB ® Compiler” on page 9-16 • “Deployed Applications” on page 9-20...

  • Page 216

    Another use of MATLAB Compiler is to build C or C++ shared libraries (DLLs on Windows) from a set of MATLAB files. You can then write C or C++ programs that can call the functions in these libraries. The typical...

  • Page 217: Common Issues

    Common Issues Common Issues Some of the most common issues encountered when using MATLAB Compiler generated standalone executables or shared libraries are: • Compilation fails with an error message. This can indicate a failure during any one of the internal steps involved in producing the final output.

  • Page 218: Failure Points And Possible Solutions, How To Use This Section

    MATLAB Compiler software. Does the Failure Occur During Compilation? You typically compile your MATLAB code on a development machine, test the resulting executable on that machine, and deploy the executable and MATLAB Compiler Runtime (MCR) to a test or customer machine without MATLAB.

  • Page 219

    Failure Points and Possible Solutions Did you compile with the verbose flag? Compilation can fail in MATLAB because of errors encountered by the system compiler when the generated wrapper code is compiled into an executable. Additional errors and warnings are printed when you use the verbose flag as such: mcc -mv myApplication.m...

  • Page 220

    >>mcc -mv helloworld.m Have you tried to compile any of the examples in MATLAB Compiler help? The source code for all examples is provided with MATLAB Compiler and is located in , where matlabroot\extern\examples\compiler matlabroot the root folder of your MATLAB installation.

  • Page 221

    It will ensure that all MATLAB header files are found by the C/C++ compiler, and that all necessary libraries are specified and found by the linker. Are you trying to compile your driver application using Microsoft...

  • Page 222: Does The Failure Occur When Testing Your Application?

    Are you able to compile the matrixdriver example? Typically, if you cannot compile the examples in the documentation, it indicates an issue with the installation of MATLAB or your system compiler. See Chapter 8, “Libraries” for these examples. Do you get the...

  • Page 223

    On the development machine, you can test your application’s execution by issuing at the MATLAB prompt. If your application !application-name executes within MATLAB but not from outside, this can indicate an issue with the system variable. For more information, see “Directories Required for PATH Development and Testing”...

  • Page 224

    MCR? All shared libraries required for your standalone executable or shared library are contained in the MATLAB Compiler Runtime (MCR). Installing the MCR is required for any of the deployment targets. Do you receive an error message about a missing DLL? Error messages indicating missing DLLs such as mclmcrrt7x.dll...

  • Page 225: End Users?

    MCRInstaller their machines. The MCR includes a set of shared libraries that provides support for all features of MATLAB. If your application fails during end-user deployment, the following questions in the column to the right may help you isolate the problem.

  • Page 226

    The first operation attempted by a compiled application is extraction of the CTF archive. If the archive is not extracted, the application cannot access the compiled MATLAB code and the application fails. If the application has write access to the installation folder, a subfolder named application-name_mcr created the first time the application is run.

  • Page 227

    Failure Points and Possible Solutions folder and running the new executable will verify application-name_mcr that the application can expand the new CTF file. 9-13...

  • Page 228: Mbuild

    On UNIX, it may be necessary to matlabroot\bin rehash. mbuild Works from the Shell But Not from MATLAB (UNIX). If the command mcc -m hello works from the UNIX command prompt but not from the MATLAB prompt, you may have a problem with your file.

  • Page 229

    You can test this before starting MATLAB by performing the following: setenv SHELL /bin/sh If this works correctly, then you should check your file for problems .cshrc setting the environment variable. PATH Cannot Locate Your Compiler (Windows). If...

  • Page 230: Matlab ® Compiler

    Support page at the MathWorks Web site. libmwlapack: load error: stgsy2_. This error occurs when a customer has both the R13 and the R14 version of MATLAB or MCR/MGL specified in the folder path and the R14 version fails to load because of a lapack incompatability.

  • Page 231

    ODE solver, and this is the only place in your MATLAB file this function is called, MATLAB Compiler will not compile the function. MATLAB Compiler does not look in these text strings for the names of functions to compile.

  • Page 232

    <mcr_root> MCR folder, appears on your system path. To verify that the CTF file that MATLAB Compiler generated in the build process resides in the same folder as your program’s file, look at the folder containing the program’s file and make sure the corresponding file is also there.

  • Page 233

    ® MATLAB Compiler™ at the beginning of your code and after the statements, the warning include will not recur. No Info.plist file in application bundle or no..On 64-bit Macintosh, indicates the application is not being executed through the bundle.

  • Page 234: Deployed Applications

    *_mcr and then rerun the application. If the same failure occurs, you will likely need to recompile the application using MATLAB Compiler and copy both the application binary and the CTF archive into the installation folder. This application has requested the run time to terminate in an unusual way.

  • Page 235

    The file defines the MATLAB startup path. pathdef.m MATLAB Compiler does not include this file in the generated CTF archive because the MCR path is a subset of the full MATLAB path. This message can be ignored.

  • Page 236

    The MATLAB file <MATLAB file> cannot be executed. MATLAB:err_parse_cannot_run_m_file. This message is an indication that the MCR has found nonencrypted MATLAB files on its path and has attempted to execute them. This error is often caused by the use of...

  • Page 237

    • The machine on which you are trying to run the application an different, incompatible version of the MCR installed on it than the one the application was originally built with. • You are not running a version of MATLAB Compiler compatible with the MCR version the application was built with. 9-23...

  • Page 238

    Framework version your application is specifying (represented by ) is not supported by the current version of MATLAB Compiler. See the “Product Overview” in the MATLAB Builder NE documentation for a list of supported .NET Framework versions. . The warning message...

  • Page 239

    Limitations and Restrictions • “Limitations About What May Be Compiled” on page 10-2 • “Unsupported Functions” on page 10-9...

  • Page 240: Limitations About What May Be Compiled, Compiling Matlab And Toolboxes

    MATLAB. However, some limited MATLAB and toolbox functionality is not licensed for compilation. • Most of the prebuilt graphical user interfaces included in MATLAB and its companion toolboxes will not compile. • Functionality that cannot be called directly from the command line will not compile.

  • Page 241: Fixing Callback Problems: Missing Functions

    Fixing Callback Problems: Missing Functions When MATLAB Compiler creates a standalone application, it compiles the MATLAB file(s) you specify on the command line and, in addition, it compiles any other MATLAB files that your MATLAB file(s) calls. MATLAB Compiler uses a dependency analysis, which determines all the functions on which the supplied MATLAB files, MEX-files, and P-files depend.

  • Page 242

    %#function For example, the call to the function in the sample change_colormap application, , illustrates this problem. To make sure MATLAB my_test Compiler processes the MATLAB file, list the function change_colormap name in the pragma.

  • Page 243: Finding Missing Functions In An Matlab File, Suppressing Warnings On The Unix System

    Fundamentals documentation. Using the -a Option. Instead of using the pragma, you can %#function specify the name of the missing MATLAB file on the MATLAB Compiler command line using the option. Finding Missing Functions in an MATLAB File To find functions in your application that may need to be listed in a...

  • Page 244: Cannot Use Graphics With The -nojvm Option, Cannot Create The Output File

    • Lack of write permission for the folder where MATLAB Compiler is attempting to write the file (most likely the current working folder). • Lack of free disk space in the folder where MATLAB Compiler is attempting to write the file (most likely the current working folder).

  • Page 245: Older Neural Networks Not Deployable With Matlab Compiler

    'struct'. Error in ==> mynetworkapp at 30 Restrictions on Calling PRINTDLG with Multiple Arguments in Compiled Mode In compiled mode, only one argument can be present in a call to the MATLAB function (for example, printdlg printdlg(gcf)

  • Page 246: Compiling A Function With Which Does Not Search Current Working Directory

    This folder should not include any unencrypted MATLAB files, as these cannot be executed by the compiled application. Include your file using the Other Files area of your project using...

  • Page 247: Unsupported Functions

    Some functions are not supported in standalone mode; that is, you cannot compile them with MATLAB Compiler. These functions are in the following categories: • Functions that print or report MATLAB code from a function, for example, the MATLAB function or debug functions, will not work.

  • Page 248

    Limitations and Restrictions List of Unsupported Functions (Continued) applescript close_system colormapeditor createClassFromWsdl dbclear dbcont dbdown dbquit dbstack dbstatus dbstep dbstop dbtype dbup delete_block delete_line depfun echo edit fields figure_palette get_param help home inmem 10-10...

  • Page 249

    Unsupported Functions List of Unsupported Functions (Continued) keyboard linmod mislocked mlock more munlock new_system open_system pack plotbrowser plotedit plottools profile profsave propedit propertyeditor publish rehash restoredefaultpath segment set_param simget simset sldebug type 10-11...

  • Page 250

    Limitations and Restrictions 10-12...

  • Page 251

    Reference Information • “Directories Required for Development and Testing” on page 11-2 • “Directories Required for Run-Time Deployment” on page 11-5 • “MATLAB ® Compiler Licensing” on page 11-8 • “Using MCR Installer Command Line Options” on page 11-9...

  • Page 252: Directories Required For Development And Testing, Overview, Path For Java Development On All Platforms

    Overview The following information is for programmers developing applications that use libraries or components that contain compiled MATLAB code. These settings are required on the machine where you are developing your application. Other settings required by end users at run time are described in “Directories Required for Run-Time Deployment”...

  • Page 253: Windows Settings For Development And Testing, Unix Settings For Development And Testing

    Directories Required for Development and Testing Windows Settings for Development and Testing When programming with components that are generated with MATLAB Compiler, add the following folder to your system environment variable: PATH \runtime\win32|win64 matlabroot UNIX Settings for Development and Testing Add the following platform-specific folders to your dynamic library path.

  • Page 254

    Reference Information /bin/maci: matlabroot /sys/os/maci: matlabroot /System/Library/Frameworks/JavaVM.framework/JavaVM: /System/Library/Frameworks/JavaVM.framework/Libraries setenv XAPPLRESDIR /X11/app-defaults matlabroot Intel Mac (Maci64) setenv DYLD_LIBRARY_PATH /runtime/maci64: matlabroot matlabroot /bin/maci64: /sys/os/maci64: matlabroot /System/Library/Frameworks/JavaVM.framework/JavaVM: /System/Library/Frameworks/JavaVM.framework/Libraries setenv XAPPLRESDIR /X11/app-defaults matlabroot 11-4...

  • Page 255: Directories Required For Run-time Deployment, General Path Guidelines, Path For Java Applications On All Platforms

    Path for Java Applications on All Platforms When your users run applications that contain compiled MATLAB code, you must instruct them to set the path so that the system can find the MCR. Note When you deploy a Java application to end users, they must set the class path on the target machine.

  • Page 256: Unix Paths For Run-time Deployment

    Reference Information where refers to the complete path where the MCR library archive mcr_root files are installed on the machine where the application is to be run. is version specific; you must determine the path after you install mcr_root the MCR. Note If you are running the MCR Installer on a shared folder, be aware that other users of the share may need to alter their system configuration.

  • Page 257

    Directories Required for Run-Time Deployment /version/sys/java/jre/glnxa64/jre/lib/amd64/server: mcr_root /version/sys/java/jre/glnxa64/jre/lib/amd64: mcr_root setenv XAPPLRESDIR mcr_root /version/X11/app-defaults Intel Mac (Maci) setenv DYLD_LIBRARY_PATH /version/runtime/maci: mcr_root /version/bin/maci: mcr_root mcr_root /version/sys/os/maci: /System/Library/Frameworks/JavaVM.framework/JavaVM: /System/Library/Frameworks/JavaVM.framework/Libraries setenv XAPPLRESDIR /version/X11/app-defaults mcr_root Intel Mac (Maci64) setenv DYLD_LIBRARY_PATH mcr_root /version/runtime/maci64: /version/bin/maci64: mcr_root /version/sys/os/maci64: mcr_root /System/Library/Frameworks/JavaVM.framework/JavaVM: /System/Library/Frameworks/JavaVM.framework/Libraries...

  • Page 258: Matlab ® Compiler Licensing, Using Matlab ® Compiler Licenses For Development

    MATLAB Compiler license, exit MATLAB. Running MATLAB Compiler in Standalone Mode If you run MATLAB Compiler from a DOS or UNIX prompt, you are running from “outside” of MATLAB. In this case, MATLAB Compiler • Does not require MATLAB to be running on the system where MATLAB Compiler is running •...

  • Page 259: Using Mcr Installer Command Line Options, Overview, Information

    Overview If you distribute your compiled components to users who do not have MATLAB installed on their systems, they must install the MATLAB Compiler Runtime (MCR). To install the MCR, users of your component must run the MCR Installer for their platform: for Windows systems MCRInstaller.exe...

  • Page 260: Accessing Mcr Installer Command Line Options On Windows Systems

    Reference Information Accessing MCR Installer Command Line Options on Windows Systems The following table lists some frequently used command line options for the MCR Installer on Windows systems ( ). The MCR installer MCRInstaller.exe is implemented using both an InstallShield wizard and the Windows Installer tool, .

  • Page 261

    MCR. You only need to specify this if you don’t want to use the default installation folder: matlabroot\MATLAB Compiler , where is the root folder for the MATLAB Runtime\mcrversion matlabroot installation and is the version number of the MCR. The example...

  • Page 262: Accessing Mcr Installer Command Line Options On Unix And Linux Systems

    Reference Information Example: Requesting a Verbose Log of the Install Process The following command causes the installer to create a verbose log of the install process in . For information about the options C:\log.txt Msiexec passed with , see the documentation.

  • Page 263

    Using MCR Installer Command Line Options Frequently Used MCR Installer Options on UNIX or Linux Systems (Continued) Option Description Specifies file in which to write debug messages -log (run-time version) Turns off launcher disk space checking. -is:nospacecheck Specifies properties of a product bean, such as the bean ID.

  • Page 264

    Reference Information Run the program. If you want to run the uninstaller uninstaller.bin noninteractively, specify the option on the command line. -silent Example: Extracting the Jar File from the MCR Installer The MathWorks includes the JRE required by the MCR Installer. However, your Linux system might not support this version of the JRE.

  • Page 265: Pragmas, Command-line Tools, Api Functions

    Function Reference Pragmas (p. 12-2) Directives to MATLAB Compiler Command-Line Tools (p. 12-2) Deployment-related commands API Functions (p. 12-3) Deployment API-related commands...

  • Page 266

    Function Reference Pragmas %#external Pragma to help MATLAB Compiler %#function locate functions called through , or Handle Graphics® feval eval callback Command-Line Tools Root folder of application in deployed ctfroot mode Use to print (as substitute for deployprint MATLAB function) when...

  • Page 267

    Determine if MCR has been properly mclIsMCRInitialized initialized Determine if mode is mclIsNoDisplaySet -nodisplay enabled Associate MATLAB data value with mclSetCmdLineUserData string key of MCR instance uniquely identified by mcrID Associate MATLAB data value with mclSetMCRUserData string key of MCR instance uniquely...

  • Page 268

    Function Reference Enable deployed applications to mclWaitForFiguresToDie process Handle Graphics events, enabling figure windows to remain displayed Associate MATLAB data value with setmcruserdata string key 12-4...

  • Page 269

    Functions — Alphabetical List %#external %#function ctfroot deployprint deploytool GetMcrID getmcruserdata isdeployed ismcc <library>Initialize[WithHandlers] <library>Terminate mbuild mclGetLogFileName mclGetMCRUserData mclInitializeApplication mclIsJVMEnabled mclIsMCRInitialized mclIsNoDisplaySet mclSetCmdLineUserData mclSetMCRUserData mclTerminateApplication mclWaitForFiguresToDie mcrinstaller mcrversion setmcruserdata...

  • Page 270

    .cpp implementation to be passed in. This pragma is not executed in MATLAB. It is treated as a comment. Only the MATLAB code is executed. When you use this pragma, MATLAB Compiler generates an additional header file called .

  • Page 271

    (isempty(t)) t = 0; else t = t+0.05; y = sin(t); For complete examples, see “Interfacing MATLAB Code to C/C++ Code” on page 6-14. Related • “Interfacing MATLAB Code to C/C++ Code” on page 6-14 Links • External Interfaces documentation...

  • Page 272

    Without this pragma, the product’s dependency analysis will not be able to locate and compile all MATLAB files used in your application. This pragma adds the top-level function as well as all the subfunctions in the file to the compilation.

  • Page 273

    %#function feval('bar'); feval('foobar'); end %function foo In this example, multiple functions ( ) are included in foobar the compilation and are called through feval 13-5...

  • Page 274

    ctfroot Purpose Root folder of application in deployed mode Syntax ctfroot Description returns a string that is the name of the folder where root = ctfroot the CTF file for the deployed application is expanded. To determine the location of various toolbox folders in deployed mode, use the function.

  • Page 275

    Purpose Use to print (as substitute for MATLAB function) when working print with deployed Windows applications Syntax deployprint Description In cases where the command would normally be issued when print running MATLAB software, use when working with deployprint deployed applications.

  • Page 276

    deployprint • PaperUnits • Orientation • PrintHeader requires write access to the file system in order to Note deployprint write temporary files. Examples The following is a simple example of how to print a figure in your application, regardless of whether the application has been deployed or not: figure;...

  • Page 277

    Description command opens the Deployment Tool window, which deploytool is the graphical user interface (GUI) for MATLAB Compiler. See Chapter 1, “Getting Started”, to get started using the Deployment Tool to create standalone applications and libraries. Desired Result Command...

  • Page 278

    "C" long libnameGetMcrID the MCR instance associated with the software component libname It allows applications that use more than one MATLAB Compiler generated software component (and hence, have more than one MCR instance active in-process) to distinguish between MCR instances when setting or getting MCR instance specific data.

  • Page 279

    GetMcrID return -3; See Also mclGetMCRUserData mclSetMCRUserData 13-11...

  • Page 280

    Purpose Retrieve MATLAB array value associated with given string key Syntax function_value = getmcruserdata(key) Description command is part of the function_value = getmcruserdata(key) MCR User Data interface API. It returns an empty matrix if no such key exists. For information about this function, as well as complete examples of usage, see “Improving Data Access Using the MCR User...

  • Page 281

    (1) when the function is running in x = isdeployed deployed mode and false (0) if it is running in a MATLAB session. If you include this function in an application and compile the application with MATLAB Compiler, the function will return true when the application is run in deployed mode.

  • Page 282

    When this function is executed by the compilation process started by , it will return true. This function will return false when executed within MATLAB as well as in deployed mode. To test for deployed mode execution, use . This function should be used to guard...

  • Page 283

    <library>Initialize[WithHandlers] Purpose Initialize MCR instance associated with library Syntax bool Initialize(void) library bool InitializeWithHandlers( library mclOutputHandlerFcn error_handler, mclOutputHandlerFcn print_handler) Description Each generated library has its own MCR instance. These two functions, initialize libraryInitialize libraryInitializeWithHandlers the MCR instance associated with . Users must call one of these library functions after calling and before calling...

  • Page 284

    Free all resources allocated by MCR instance associated with library Syntax void Terminate(void) library Description This function should be called after you finish calling the functions in this MATLAB Compiler-generated library, but before is called. mclTerminateApplication Example Call to initialize library properly libmatrixInitialize...

  • Page 285

    Build an output file for architecture -<arch> -<arch> To determine the value for , type -<arch> at the MATLAB Command computer('arch') Prompt on the target machine. Note: Valid values for depend on the architecture -<arch> of the build platform.

  • Page 286

    -I<pathname> <pathname> files. #include Inline matrix accessor functions ( ). The -inline executable generated may not be compatible with future versions of MATLAB. Fully-qualified path name of product -install_name installation on Mac. 13-18...

  • Page 287

    mbuild Option Description Link with object library. On Windows -l<name> systems, expands to <name> <name>.lib and on UNIX systems, to lib<name>.lib . Do not lib<name>.so lib<name>.dylib add a space after this switch. Note When linking with a library, it is essential that you first specify the path (with , for example).

  • Page 288

    (Windows only) Use the program to -regsvr regsvr32 register the resulting shared library at the end of compilation. MATLAB Compiler uses this option whenever it produces a COM or .NET wrapper file. Interactively specify the compiler options file -setup to use as the default for future invocations of...

  • Page 289

    (e.g., on Windows COMPFLAGS="$COMPFLAGS opt2" on UNIX). CFLAGS='$CFLAGS opt2' Caution On Windows platforms, at either the MATLAB prompt or the DOS prompt, use double quotes ( ) when specifying command-line overrides " with . For example: mbuild mbuild -v COMPFLAGS="$COMPFLAGS -Wall"...

  • Page 290

    .exports files are exported. .exports Examples To set up or change the default C/C++ compiler for use with MATLAB Compiler, use mbuild -setup To compile and link an external C program against , use foo.c...

  • Page 291

    If more than one MATLAB file is specified on the command line, MATLAB Compiler generates a C or C++ function for each MATLAB file. If C or object files are specified, they are passed to...

  • Page 292

    ) that do not appear on the MATLAB path at the time of compilation will cause a path entry to be added to the deployed application’s run-time path so that they will appear on the path when the deployed application or component is executed.

  • Page 293

    Java class is not a member of a package. The same applies for JAR files. However, if the class being added is a member of a package, the MATLAB code will need to make an appropriate call to that will update the...

  • Page 294

    -C Do Not Embed CTF Archive by Default Overrides automatically embedding the CTF archive in C/C++ and main/Winmain shared libraries and standalone binaries by default. See “Overriding Default CTF Archive Embedding Using the MCR Component Cache” on page 6-20 for more information. -d Specified Directory for Output Place output in a specified folder.

  • Page 295

    . This option filename mbuild allows you to use different ANSI compilers for different invocations of MATLAB Compiler. This option is a direct pass-through to the mbuild script. Note The MathWorks recommends that you use mbuild -setup...

  • Page 296

    -l Generate a Function Library Macro to create a function library. This option generates a library wrapper function for each MATLAB file on the command line and calls your C compiler to build a shared library, which exports these functions.

  • Page 297

    • matlabroot/toolbox/compiler/deploy It also retains all subfolders of the above list that appear on the MATLAB path at compile time. Including on the command line allows you to replace folders from the original path, while retaining the relative ordering of the included folders. All subfolders of the included...

  • Page 298

    If a path is added with the option while this feature is active ( been passed) and it is already on the MATLAB path, it is added in the order-sensitive context as if it were included with . Otherwise, the...

  • Page 299

    Initialization Start-Up and Completion Messages For Users” on page 5-37. Note The option is available only for standalone applications. To override MCR options in the other MATLAB Compiler targets, use the functions. mclInitializeApplication mclTerminateApplication For more information on these functions, see “Calling a Shared Library”...

  • Page 300

    -S Create Singleton MCR Create a singleton MCR when compiling a COM object. Each instance of the component uses the same MCR. Requires MATLAB Builder NE. -v Verbose Display the compilation steps, including: • MATLAB Compiler version number •...

  • Page 301

    Controls the generation of function wrappers. Use the syntax type to control the generation of function wrappers for a collection of MATLAB files generated by MATLAB Compiler. You provide a list of functions and MATLAB Compiler generates the wrapper functions 13-33...

  • Page 302

    This option also produces a header file containing prototypes for all public functions in all MATLAB files specified. becomes the base (file) name <string>...

  • Page 303

    Linux mcc Cache Management Command Options The Bourne shell front-end interface to MATLAB Compiler uses a cache file to speed execution. The cache file contains precomputed values of critical environment variables. The cache is automatically built whenever the back-end interface is called, providing that the cache file doesn’t already exist and the...

  • Page 304

    See Also deploytool 13-36...

  • Page 305

    mclGetLogFileName Purpose Retrieve name of log file used by MCR Syntax const char* mclGetLogFileName() Description to retrieve the name of the log file used by mclGetLogFileName() the MCR. Returns a character string representing log file name used by MCR. For more information, see “Retrieving MCR Attributes” on page 5-21 in the user guide.

  • Page 306

    Purpose Retrieve MATLAB data associated with string key of MCR instance uniquely identified by mcrID Syntax extern "C" mxArray *mclGetMCRUserData( long mcrID const char * Description This external C function retrieves the MATLAB data associated with the string key of an MCR instance uniquely identified by...

  • Page 307

    (possibly of zero length) and a count containing the size of the string array. The string array may contain the following MATLAB command line switches, which have the same meaning as they do when used in MATLAB. : •...

  • Page 308

    mclInitializeApplication • -nodisplay • -noFigureWindows • -nojit • -nojvm • -noshelldde • -nosplash • • -Regserver • -shelldde • -student • -Unregserver • -useJavaFigures • -mwvisual • -xrm Caution must be called once only per process. mclInitializeApplication Calling more than once may cause your mclInitializeApplication application to exhibit unpredictable or undesirable behavior.

  • Page 309

    mclInitializeApplication Example To start all MCRs in a given process with the option, for -nodisplay example, use the following code: char *args[] = { "-nodisplay" }; bool success = mclInitializeApplication(args, 1); See Also “Initializing and Terminating Your Application with mclInitializeApplication and mclTerminateApplication” on page 8-11 mclTerminateApplication 13-41...

  • Page 310

    mclIsJVMEnabled Purpose Determine if MCR was launched with instance of Java Virtual Machine (JVM) Syntax bool mclIsJVMEnabled() Description to determine if the MCR was launched mclIsJVMEnabled() with an instance of a Java Virtual Machine (JVM). Returns true MCR is launched with a JVM instance, else returns .

  • Page 311

    mclIsMCRInitialized Purpose Determine if MCR has been properly initialized Syntax bool mclIsMCRInitialized() Description to determine whether or not the MCR has mclIsMCRInitialized() been properly initialized. Returns if MCR is already initialized; true else returns . For more information, see “Retrieving MCR false Attributes”...

  • Page 312

    mclIsNoDisplaySet Purpose Determine if mode is enabled -nodisplay Syntax bool mclIsNoDisplaySet() Description to determine if mode is enabled. mclIsNoDisplaySet() -nodisplay Returns is enabled, else returns . For more true -nodisplay false information, see “Retrieving MCR Attributes” on page 5-21 in the user guide.

  • Page 313

    Purpose Associate MATLAB data value with string key of MCR instance uniquely identified by mcrID Syntax extern "C" size_t mclSetCmdLineUserData( long mcrID int argc, const char **argv Description This external C function examines the arguments on the command line for the switch -...

  • Page 314

    mclSetCmdLineUserData Note The generated main function for a C/C++ application changes to call after initializing the MCR. Generated mclSetCmdLineUserData code for a software component or shared library does not change. It is the user’s responsibility to call after calling the mclSetMCRUserData library initialization function.

  • Page 315

    mclSetCmdLineUserData int run_main(int argc, const char **argv) int _retval; /* Generate and populate the path_to_component. */ char path_to_component[(PATH_MAX*2)+1]; separatePathName(argv[0], path_to_component, (PATH_MAX*2)+1); __MCC_tctf_component_data.path_to_component = path_to_component; if (!tctfInitialize()) { return -1; size_t dataCount = mclSetCmdLineUserData(_mcr_inst, argc, argv); _retval = mclMain(_mcr_inst, argc, argv, "tctf", 0); if (_retval == 0 /* no error */) mclWaitForFiguresToDie(NULL);...

  • Page 316

    Purpose Associate MATLAB data value with string key of MCR instance uniquely identified by mcrID Syntax extern "C" bool mclSetMCRUserData( long // Integer MCR instance identifier mcrID const char * // Store user data under this key mxArray *...

  • Page 317

    mclSetMCRUserData user data. \n"); return -3; See Also mclSetCmdLineUserData mclGetMCRUserData 13-49...

  • Page 318

    Call this function once at the end of your program to close down all MCR-internal application state. Call only once per process. After you have called this function, you cannot call any further MATLAB Compiler-generated functions or any functions in any MATLAB library.

  • Page 319

    mclTerminateApplication mclInitializeApplication 13-51...

  • Page 320

    <library>Terminate will block the calling program only for Note WaitForFiguresToDie MATLAB figures. It will not block any Java GUIs, ActiveX controls, and other non-MATLAB GUIs unless they are embedded in a MATLAB figure window. Example int run_main(int argc, const char** argv) int some_variable = 0;...

  • Page 321

    mclWaitForFiguresToDie application.\n"); return(-1); if (test_to_run == 1 || test_to_run == 0) /* Initialize ax1ks library */ if (!libax1ksInitialize()) fprintf(stderr,"Could not initialize the ax1ks library.\n"); return (-2); if (test_to_run == 2 || test_to_run == 0) /* Initialize simple library */ if (!libsimpleInitialize()) fprintf(stderr,"Could not initialize the simple library.\n");...

  • Page 322

    mclWaitForFiguresToDie return(0); See Also “Blocking Execution of a Console Application That Creates Figures and Terminating Figures by Force” on page 6-31 13-54...

  • Page 323

    This list is non-empty only in a multi-platform MATLAB installation. Note You must distribute the MATLAB Compiler Runtime library to your end users to enable them to run applications developed with MATLAB Compiler. Prebuilt MCR installers for all licensed platforms ship with MATLAB Compiler.

  • Page 324

    X:\user\buildversion\matlab\toolbox\compiler\ deploy\win32\MCRInstaller.exe MCR installers for other platforms are located in: X:\user\buildversion\matlab\toolbox\compiler\ deploy\<ARCH> <ARCH> is the value of COMPUTER('arch') on the target machine. For more information, read your local MCR Installer help. Or see the online documentation at The MathWorks' web site.

  • Page 325

    Purpose Determine version of installed MATLAB Compiler Runtime (MCR) Syntax [major, minor] = mcrversion; Description The MCR version number consists of two digits, separated by a decimal point. This function returns each digit as a separate output variable: Major and minor are returned as [major, minor] = mcrversion;...

  • Page 326

    Purpose Associate MATLAB data value with string key Syntax function setmcruserdata(key, value) Description command is part of the function setmcruserdata(key, value) MCR User Data interface API. For information about this function, as well as complete examples of usage, see “Improving Data Access Using the MCR User Data Interface”...

  • Page 327

    MATLAB Compiler Quick Reference • “Common Uses of MATLAB ® Compiler ” on page A-2 • “mcc” on page A-4...

  • Page 328: Create A Library

    ® MATLAB Compiler™ Quick Reference Common Uses of MATLAB Compiler In this section... “Create a Standalone Application” on page A-2 “Create a Library” on page A-2 Create a Standalone Application Example 1 To create a standalone application from , use mymfile.m...

  • Page 329

    ® Common Uses of MATLAB Compiler™ Example 2 To create a C shared library called from , use library_one foo1.m foo2.m mcc -W lib:library_one -T link:lib foo1 foo2 Note You can add the option to any of these for debugging purposes.

  • Page 330

    Option Description Comment/Options to the CTF None -a filename filename archive. Generate Excel compatible Requires MATLAB Builder EX formula function. Replace on the The file should contain only -B filename command line with the command-line options. These are filename[:arg[,arg]] contents of...

  • Page 331

    None Generate debugging information. Same as None Add folder to search path for MATLAB path is automatically -I directory MATLAB files. included when running from MATLAB, but not when running from a DOS/UNIX shell.

  • Page 332

    Specify run-time options for -R option option = MCR. -nojvm -nodisplay -logfile filename -startmsg -completemsg filename Create Singleton MCR. Requires MATLAB Builder NE Verbose; display compilation None steps. Display warning messages. -w option option list level level string...

  • Page 333

    Option Description Comment/Options when None -Y licensefile licensefile checking out a MATLAB Compiler license. None Specify path for library and -z path include files. Display help message. None...

  • Page 334

    ® MATLAB Compiler™ Quick Reference...

  • Page 335

    Using MATLAB Compiler on UNIX • “Overview” on page B-2 • “Installing MATLAB ® Compiler on UNIX” on page B-3 • “Building Your UNIX Application” on page B-4 • “Testing Your UNIX Application” on page B-5 • “Deploying Your UNIX Application” on page B-6...

  • Page 336

    ® ® Using MATLAB Compiler™ on UNIX Overview If you use MATLAB Compiler on UNIX, Linux or Macintosh systems, use this appendix as a quick reference to common tasks.

  • Page 337: Installing Matlab ® Compiler On Unix, Installing Matlab ® Compiler, Selecting Your Gcc Compiler

    ® ® Installing MATLAB Compiler™ on UNIX Installing MATLAB Compiler on UNIX In this section... “Installing MATLAB ® Compiler” on page B-3 “Selecting Your gcc Compiler” on page B-3 “Custom Configuring Your Options File” on page B-3 “Install X Code from DVD on Maci and Maci64” on page B-3 Installing MATLAB Compiler See “On UNIX Operating Systems”...

  • Page 338: Building Your Unix Application, Compiling Your Application With The Deployment Tool

    ® ® Using MATLAB Compiler™ on UNIX Building Your UNIX Application In this section... “Compiling Your Application with the Deployment Tool” on page B-4 “Compiling Your Application with the Command Line” on page B-4 Compiling Your Application with the Deployment Tool When running a graphical interface (such as XWindows) from your UNIX desktop, use “Deploying with the Magic Square Example”...

  • Page 339: Testing Your Unix Application

    Testing Your UNIX Application Testing Your UNIX Application When you test your UNIX application, understand that deployed applications in the Windows environment automatically modify the system variable. PATH On UNIX, however, you perform this step manually, based on what type of operating system you use.

  • Page 340: Deploying Your Unix Application, Installing The Mcr On Unix

    ® ® Using MATLAB Compiler™ on UNIX Deploying Your UNIX Application In this section... “Installing the MCR on UNIX” on page B-6 “Performing a Silent Installation of the MCR on Linux and Mac” on page B-6 “Using Run Script to Set MCR Paths” on page B-6 Installing the MCR on UNIX See “Working with the MCR”...

  • Page 341: Running Your 64-bit Mac Application, Overview, Installing The Macintosh Application Launcher Preference Pane

    Running Your 64-Bit Mac Application Running Your 64-Bit Mac Application In this section... “Overview” on page B-7 “Installing the Macintosh Application Launcher Preference Pane” on page “Configuring the Installation Area” on page B-7 “Launching the Application” on page B-10 Overview 64-bit Macintosh graphical applications which are launched through the Mac OS X finder utility require additional configuration if the compiler or MCR were not installed in the default locations.

  • Page 342

    ® ® Using MATLAB Compiler™ on UNIX Launch the preference pane by clicking on the apple logo in the upper left corner of the desktop. Click on System Preferences. The MW_App_Launch preference pane appears in the Other area. The Macintosh Application Launcher Click Add Install Area to define an installation area on your system.

  • Page 343

    Running Your 64-Bit Mac Application Modifying Your Installation Area Occasionally, you remove an installation area, define additional areas or change the order of installation area precedence. You can use the following options in The MathWorks™ Application Launcher to modify your installation area: •...

  • Page 344: Launching The Application

    ® ® Using MATLAB Compiler™ on UNIX • Move Up — After selecting an installation area, click this button to move the defined path up the list. Binaries defined in installation areas at the top of the list have precedence over all succeeding entries.

  • Page 345: About Error And Warning Messages

    Error and Warning Messages • “About Error and Warning Messages” on page C-2 • “Compile-Time Errors” on page C-3 • “Warning Messages” on page C-7 • “depfun Errors” on page C-10...

  • Page 346: Compile-time Errors

    MATLAB Compiler. Compile-time messages are generated during the compile or link phase. It is useful to note that most of these compile-time error messages should not occur if the MATLAB software can successfully execute the corresponding MATLAB file. Use this reference to: •...

  • Page 347

    For example: mcc -W lib:liba liba -t % Incorrect Error: Could not check out a Compiler license. No additional MATLAB Compiler licenses are available for your workgroup. Error: Could not find license file "filename". (Windows only) The file can not be found in license.dat...

  • Page 348

    Error and Warning Messages Error: File: "filename" is a script MATLAB file and cannot be compiled with the current Compiler. MATLAB Compiler cannot compile script MATLAB files. To learn how to convert script MATLAB files to function MATLAB files, see “Converting Script MATLAB Files to Function MATLAB Files”...

  • Page 349

    Error: The license manager failed to initialize (error code is errornumber). You do not have a valid MATLAB Compiler license or no additional MATLAB Compiler licenses are available. Error: The option -option is invalid in modename mode (specify -? for help).

  • Page 350: Warning Messages

    “Warning Messages” on page C-7. Error: Unrecognized option: -option. The option is not a valid option. See Chapter 12, “Function Reference”, for a complete list of valid options for MATLAB Compiler, or type at the command prompt. mcc -?

  • Page 351

    "directoryname" first. (specified_file_mismatch) MATLAB Compiler detected an inconsistency between the location of the MATLAB file as given on the command line and in the search path. MATLAB Compiler uses the location in the search path. This warning occurs when you specify a...

  • Page 352

    -t -W lib:a -T link:lib a0 a1 % Will generate a warning Warning: All warnings are disabled. (all_warnings) This warning displays all warnings generated by MATLAB Compiler. This warning is disabled. Warning: A line has num1 characters, violating the maximum page width (num2).

  • Page 353

    Warning Messages Note A link error is produced if a call to this function is made from standalone code. DEMO Compiler license. The generated application will expire 30 days from today, on date. (demo_license) This warning displays the date that the deployed application will expire. This warning is enabled.

  • Page 354: Depfun Errors, About Depfun Errors, Mcr/dispatcher Errors, Xml Parser Errors, Depfun-produced Errors

    “XML Parser Errors” on page C-10 “depfun-Produced Errors” on page C-11 About depfun Errors MATLAB Compiler uses a dependency analysis ( ) to determine the list depfun of necessary files to include in the CTF package. If this analysis encounters a problem, displays an error.

  • Page 355

    depfun Errors Where is a message returned by the XML parser. If this <message> error occurs, report it to Technical Support at The MathWorks at http://www.mathworks.com/contact_TS.html depfun-Produced Errors These errors originate directly from depfun depfun Error: Internal error. This error occurs if an internal error is encountered that is unexpected, for example, a memory allocation error or a system error of some kind.

  • Page 356

    Error and Warning Messages C-12...

  • Page 357

    C++ Utility Library Reference...

  • Page 358: Primitive Types

    C++ Utility Library Reference Primitive Types API supports all primitive types that can be stored in a MATLAB mwArray array. This table lists all the types. Type Description mxClassID Character type mxChar mxCHAR_CLASS Logical or Boolean type mxLogical mxLOGICAL_CLASS Double-precision...

  • Page 359: Utility Classes

    Utility Classes Utility Classes The following are C++ utility classes: • “mwString Class” on page D-4 • “mwException Class” on page D-20 • “mwArray Class” on page D-28...

  • Page 360: Mwstring Class, About Mwstring, Constructors, Methods, Operators

    C++ Utility Library Reference mwString Class In this section... “About mwString” on page D-4 “Constructors” on page D-4 “Methods” on page D-4 “Operators” on page D-4 About mwString class is a simple string class used by the API to pass mwString mwArray string data as output from certain methods.

  • Page 361

    mwString Class • bool operator>(const mwString& str) const • bool operator>=(const mwString& str) const • friend std::ostream& operator<<(std::ostream& os, const mwString& str)

  • Page 362

    mwString() Purpose Construct empty string #include "mclcppclass.h" Syntax mwString str; Arguments None Return None Value Description Use this constructor to create an empty string.

  • Page 363

    mwString(const char* str) Purpose Construct new string and initialize strings data with supplied char buffer #include "mclcppclass.h" Syntax mwString str("This is a string"); Arguments NULL-terminated char buffer to initialize the string. Return None Value Description Use this constructor to create a string from a NULL-terminated char buffer.

  • Page 364

    mwString(const mwString& str) Purpose Copy constructor for mwString #include "mclcppclass.h" Syntax mwString str("This is a string"); mwString new_str(str); // new_str contains a copy of the // characters in str. Arguments to be copied. mwString Return None Value Description Use this constructor to create an that is a copy of an existing mwString one.

  • Page 365

    int Length() const Purpose Return number of characters in string #include "mclcppclass.h" Syntax mwString str("This is a string"); int len = str.Length(); // len should be 16. Arguments None Return The number of characters in the string. Value Description Use this method to get the length of an .

  • Page 366

    operator const char* () const Purpose Return pointer to internal buffer of string #include "mclcppclass.h" Syntax mwString str("This is a string"); const char* pstr = (const char*)str; Arguments None Return A pointer to the internal buffer of the string. Value Description Use this operator to get direct read-only access to the string’s data buffer.

  • Page 367

    mwString& operator=(const mwString& str) Purpose assignment operator mwString #include "mclcppclass.h" Syntax mwString str("This is a string"); mwString new_str = str; // new_str contains a copy of // the data in str. Arguments String to make a copy of. Return A reference to the invoking object.

  • Page 368

    mwString& operator=(const char* str) Purpose assignment operator mwString #include "mclcppclass.h" Syntax const char* pstr = "This is a string"; mwString str = pstr; // str contains copy of data in pstr. Arguments buffer to make copy of. char Return A reference to the invoking object.

  • Page 369

    bool operator==(const mwString& str) const Purpose Test two s for equality mwString #include "mclcppclass.h" Syntax mwString str("This is a string"); mwString str2("This is another string"); bool ret = (str == str2);// ret should have value of false. Arguments String to compare. Return The result of the comparison.

  • Page 370

    bool operator!=(const mwString& str) const Purpose Test two s for inequality mwString #include "mclcppclass.h" Syntax mwString str("This is a string"); mwString str2("This is another string"); bool ret = (str != str2); // ret should have value of // true. Arguments String to compare.

  • Page 371

    bool operator<(const mwString& str) const Purpose Compare input string with this string and return if this string is true lexicographically less than input string #include "mclcppclass.h" Syntax mwString str("This is a string"); mwString str2("This is another string"); bool ret = (str < str2); // ret should have a value of true.

  • Page 372

    bool operator<=(const mwString& str) const Purpose Compare input string with this string and return if this string is true lexicographically less than or equal to input string #include "mclcppclass.h" Syntax mwString str("This is a string"); mwString str2("This is another string"); bool ret = (str <= str2);...

  • Page 373

    bool operator>(const mwString& str) const Purpose Compare input string with this string and return if this string is true lexicographically greater than input string #include "mclcppclass.h" Syntax mwString str("This is a string"); mwString str2("This is another string"); bool ret = (str > str2); // ret should have value // of false.

  • Page 374

    bool operator>=(const mwString& str) const Purpose Compare input string with this string and return if this string is true lexicographically greater than or equal to input string #include "mclcppclass.h" Syntax mwString str("This is a string"); mwString str2("This is another string"); bool ret = (str >= str2);//ret should have value of false.

  • Page 375

    friend std::ostream& operator<<(std::ostream& os, const mwString& str) Purpose Copy contents of input string to specified ostream #include "mclcppclass.h" Syntax #include <ostream> mwString str("This is a string"); std::cout << str << std::endl; //should print "This is a //string" to standard out. Arguments to copy string to.

  • Page 376: Mwexception Class, About Mwexception, Constructors, Methods, Operators

    About mwException class is the basic exception type used by the mwException mwArray API and the C++ interface functions. All errors created during calls to the API and to MATLAB Compiler generated C++ interface functions mwArray are thrown as mwExceptions Constructors •...

  • Page 377

    mwException() Purpose Construct new with default error message mwException #include "mclcppclass.h" Syntax throw mwException(); Arguments None Return None Value Description Use this constructor to create an without specifying an mwException error message. D-21...

  • Page 378

    mwException(const char* msg) Purpose Construct new with specified error message mwException #include "mclcppclass.h" Syntax throw mwException("This is an error"); catch (const mwException& e) std::cout << e.what() << std::endl // Displays "This // is an error" to // standard out. Arguments Error message.

  • Page 379

    mwException(const mwException& e) Purpose Copy constructor for class mwException #include "mclcppclass.h" Syntax throw mwException("This is an error"); catch (const mwException& e) throw mwException(e); // Rethrows same error. Arguments to create copy of. mwException Return None Value Description Use this constructor to create a copy of an .

  • Page 380

    mwException(const std::exception& e) Purpose Create new from existing mwException std::exception #include "mclcppclass.h" Syntax catch (const std::exception& e) throw mwException(e); // Rethrows same error. Arguments to create copy of. std::exception Return None Value Description Use this constructor to create a new and initialize the mwException error message with the error message from the given...

  • Page 381

    const char *what() const throw() Purpose Return error message contained in this exception #include "mclcppclass.h" Syntax catch (const std::exception& e) std::cout << e.what() << std::endl; // Displays error // message to // standard out. Arguments None Return A pointer to a NULL-terminated character buffer containing the error message.

  • Page 382

    mwException& operator=(const mwException& e) Purpose Assignment operator for class mwException #include "mclcppclass.h" Syntax catch (const mwException& e) mwException e2 = e; throw e2; Arguments to create copy of. mwException Return A reference to the invoking mwException Value Description Use this operator to create a copy of an .

  • Page 383

    mwException& operator=(const std::exception& e) Purpose Assignment operator for class mwException #include "mclcppclass.h" Syntax catch (const std::exception& e) mwException e2 = e; throw e2; Arguments to initialize copy with. std::exception Return A reference to the invoking mwException Value Description Use this operator to create a copy of an .

  • Page 384: Mwarray Class, About Mwarray, Constructors

    C++ interface functions. This class consists of a thin wrapper around a MATLAB array. As explained in further detail in the MATLAB documentation, all data in MATLAB is represented by matrices (in other words, even a simple data structure should be declared as a 1-by-1 matrix).

  • Page 385: Methods

    mwArray Class • mwArray(mwSize num_rows, mwSize num_cols, int num_fields, const char** fieldnames) • mwArray(mwSize num_dims, const mwSize* dims, int num_fields, const char** fieldnames) • mwArray(const mwArray& arr) • mwArray(<type> re) • mwArray(<type> re, <type> im) Methods • mwArray Clone() const •...

  • Page 386: Operators

    C++ Utility Library Reference • int HashCode() const • mwString ToString() const • mwArray RowIndex() const • mwArray ColumnIndex() const • void MakeComplex() • mwArray Get(mwSize num_indices, ...) • mwArray Get(const char* name, mwSize num_indices, ...) • mwArray Get(mwSize num_indices, const mwIndex* index) •...

  • Page 387: Static Methods

    mwArray Class Static Methods • static mwArray Deserialize(const mwArray& arr) • static double GetNaN() • static double GetEps() • static double GetInf() • static bool IsFinite(double x) • static bool IsInf(double x) • static bool IsNaN(double x) Static Factory Methods for Sparse Arrays •...

  • Page 388

    mwArray() Purpose Construct empty array of type mxDOUBLE_CLASS #include "mclcppclass.h" Syntax mwArray a; Return None Value Description Use this constructor to create an empty array of type mxDOUBLE_CLASS D-32...

  • Page 389

    mwArray(mxClassID mxID) Purpose Construct empty array of specified type #include "mclcppclass.h" Syntax mwArray a(mxDOUBLE_CLASS); Return None Value Description Use this constructor to create an empty array of the specified type. You can use any valid . See the External Interfaces mxClassID documentation for more information on mxClassID...

  • Page 390

    mwArray(mwSize num_rows, mwSize num_cols, mxClassID mxID, mxComplexity cmplx = mxREAL) Purpose Construct 2-D matrix of specified type and dimensions #include "mclcppclass.h" Syntax mwArray a(2, 2, mxDOUBLE_CLASS); mwArray b(3, 3, mxSINGLE_CLASS, mxCOMPLEX); mwArray c(2, 3, mxCELL_CLASS); Arguments num_rows The number of rows. num_cols The number of columns.

  • Page 391

    mwArray(mwSize num_dims, const mwSize* dims, mxClassID mxID, mxComplexity cmplx = mxREAL) Purpose Construct -dimensional array of specified type and dimensions #include "mclcppclass.h" Syntax mwSize dims[3] = {2,3,4}; mwArray a(3, dims, mxDOUBLE_CLASS); mwArray b(3, dims, mxSINGLE_CLASS, mxCOMPLEX); mwArray c(3, dims, mxCELL_CLASS); Arguments num_dims Size of the...

  • Page 392

    mwArray(const char* str) Purpose Construct character array from supplied string #include "mclcppclass.h" Syntax mwArray a("This is a string"); Arguments NULL-terminated string Return None Value Description Use this constructor to create a 1-by-n array of type , with mxCHAR_CLASS , and initialize the array’s data with the characters in n = strlen(str) the supplied string.

  • Page 393

    mwArray(mwSize num_strings, const char** str) Purpose Construct character matrix from list of strings #include "mclcppclass.h" Syntax const char* str[] = {"String1", "String2", "String3"}; mwArray a(3, str); Arguments num_strings Number of strings in the input array Array of NULL-terminated strings Return None Value Description...

  • Page 394

    Purpose Construct 2-D MATLAB structure matrix of specified dimensions and field names #include "mclcppclass.h" Syntax const char* fields[] = {"a", "b", "c"}; mwArray a(2, 2, 3, fields); Arguments num_rows Number of rows in the matrix.

  • Page 395

    Purpose Construct -dimensional MATLAB structure array of specified dimensions and field names #include "mclcppclass.h" Syntax const char* fields[] = {"a", "b", "c"}; mwSize dims[3] = {2, 3, 4} mwArray a(3, dims, 3, fields);...

  • Page 396

    mwArray(const mwArray& arr) Purpose Constructs new from existing array mwArray #include "mclcppclass.h" Syntax mwArray a(2, 2, mxDOUBLE_CLASS); mwArray b(a); Arguments to copy. mwArray Return None Value Description Use this constructor to create a copy of an existing array. The new array contains a deep copy of the input array.

  • Page 397

    mwArray(<type> re) Purpose Construct real scalar array of type of the input argument and initialize data with input argument’s value #include "mclcppclass.h" Syntax double x = 5.0; mwArray a(x); // Creates 1X1 double array with value 5.0 Arguments Scalar value to initialize array with. Return None Value...

  • Page 398

    mwArray(<type> re, <type> im) Purpose Construct complex scalar array of type of input arguments and initialize real and imaginary parts of data with input argument’s values #include "mclcppclass.h" Syntax double re = 5.0; double im = 10.0; mwArray a(re, im); // Creates 1X1 complex array with // value 5+10i Arguments Scalar value to initialize real part with.

  • Page 399

    mwArray(<type> re, <type> im) • mxUint64 • mxLogical The scalar array is created with the type of the input arguments. D-43...

  • Page 400

    mwArray Clone() const Purpose Return new array representing deep copy of array #include "mclcppclass.h" Syntax mwArray a(2, 2, mxDOUBLE_CLASS); mwArray b = a.Clone(); Arguments None Return representing a deep copy of the original. mwArray Value Description Use this method to create a copy of an existing array. The new array contains a deep copy of the input array.

  • Page 401

    mwArray SharedCopy() const Purpose Return new array representing shared copy of array #include "mclcppclass.h" Syntax mwArray a(2, 2, mxDOUBLE_CLASS); mwArray b = a.SharedCopy(); Arguments None Return representing a reference counted version of the original. mwArray Value Description Use this method to create a shared copy of an existing array. The new array and the original array both point to the same data.

  • Page 402

    mwArray Serialize() const Purpose Serialize underlying array into byte array, and return data in new array of type mxUINT8_CLASS #include "mclcppclass.h" Syntax mwArray a(2, 2, mxDOUBLE_CLASS); mwArray s = a.Serialize(); Arguments None Return of type containing the serialized data. mwArray mxUINT8_CLASS Value Description...

  • Page 403

    mxClassID ClassID() const Purpose Return type of array #include "mclcppclass.h" Syntax mwArray a(2, 2, mxDOUBLE_CLASS); mxClassID id = a.ClassID();// Should return mxDOUBLE_CLASS Arguments None Return of the array. mxClassID Value Description Use this method to determine the type of the array. Consult the External Interfaces documentation for more information on mxClassID D-47...

  • Page 404

    int ElementSize() const Purpose Return size in bytes of element of array #include "mclcppclass.h" Syntax mwArray a(2, 2, mxDOUBLE_CLASS); int size = a.ElementSize();// Should return sizeof(double) Arguments None Return The size in bytes of an element of this type of array. Value Description Use this method to determine the size in bytes of an element of array...

  • Page 405

    size_t ElementSize() const Purpose Return size in bytes of element in array #include "mclcppclass.h" Syntax mwArray a(2, 2, mxDOUBLE_CLASS); int size = a.ElementSize();// Should return sizeof(double) Arguments None Return The size in bytes of an element of this type of array. Value Description Use this method to determine the size in bytes of an element of array...

  • Page 406

    mwSize NumberOfElements() const Purpose Return number of elements in array #include "mclcppclass.h" Syntax mwArray a(2, 2, mxDOUBLE_CLASS); int n = a.NumberOfElements();// Should return 4 Arguments None Return Number of elements in array. Value Description Use this method to determine the total size of the array. D-50...

  • Page 407

    mwSize NumberOfNonZeros() const Purpose Return number of nonzero elements for sparse array #include "mclcppclass.h" Syntax mwArray a(2, 2, mxDOUBLE_CLASS); int n = a.NumberOfNonZeros();// Should return 4 Arguments None Return Actual number of nonzero elements in array. Value Description Use this method to determine the size of the of the array’s data. If the underlying array is not sparse, this returns the same value as NumberOfElements() Note This method does not analyze the actual values of the array...

  • Page 408

    mwSize MaximumNonZeros() const Purpose Return maximum number of nonzero elements for sparse array #include "mclcppclass.h" Syntax mwArray a(2, 2, mxDOUBLE_CLASS); int n = a.MaximumNonZeros();// Should return 4 Arguments None Return Number of allocated nonzero elements in array. Value Description Use this method to determine the allocated size of the of the array’s data.

  • Page 409

    mwSize NumberOfDimensions() const Purpose Return number of dimensions in array #include "mclcppclass.h" Syntax mwArray a(2, 2, mxDOUBLE_CLASS); int n = a.NumberOfDimensions();// Should return 2 Arguments None Return Number of dimensions in array. Value Description Use this method to determine the dimensionality of the array. D-53...

  • Page 410

    int NumberOfFields() const Purpose Return number of fields in array struct #include "mclcppclass.h" Syntax const char* fields[] = {"a", "b", "c"}; mwArray a(2, 2, 3, fields); int n = a.NumberOfFields(); // Should return 3 Arguments None Return Number of fields in the array. Value Description Use this method to determine the number of fields in a...

  • Page 411

    mwString GetFieldName(int index) Purpose Return string representing name of (zero-based) field in array struct #include "mclcppclass.h" Syntax const char* fields[] = {"a", "b", "c"}; mwArray a(2, 2, 3, fields); mwString tempname = a.GetFieldName(1); const char* name = (const char*)tempname; // Should // return "b"...

  • Page 412

    mwArray GetDimensions() const Purpose Return array of type representing dimensions of array mxINT32_CLASS #include "mclcppclass.h" Syntax mwArray a(2, 2, mxDOUBLE_CLASS); mwArray dims = a.GetDimensions(); Arguments None Return type containing the dimensions of the array. mwArray mxINT32_CLASS Value Description Use this method to determine the size of each dimension in the array. The size of the returned array is 1-by- NumberOfDimensions() D-56...

  • Page 413

    bool IsEmpty() const Purpose Return if underlying array is empty true #include "mclcppclass.h" Syntax mwArray a; bool b = a.IsEmpty(); // Should return true Arguments None Return Boolean indicating if the array is empty. Value Description Use this method to determine if an array is empty. D-57...

  • Page 414

    bool IsSparse() const Purpose Return if underlying array is sparse true #include "mclcppclass.h" Syntax mwArray a(2, 2, mxDOUBLE_CLASS); bool b = a.IsSparse(); // Should return false Arguments None Return Boolean indicating if the array is sparse. Value Description Use this method to determine if an array is sparse. D-58...

  • Page 415

    bool IsNumeric() const Purpose Return if underlying array is numeric true #include "mclcppclass.h" Syntax mwArray a(2, 2, mxDOUBLE_CLASS); bool b = a.IsNumeric(); // Should return true. Arguments None Return Boolean indicating if the array is numeric. Value Description Use this method to determine if an array is numeric. D-59...

  • Page 416

    bool IsComplex() const Purpose Return if underlying array is complex true #include "mclcppclass.h" Syntax mwArray a(2, 2, mxDOUBLE_CLASS, mxCOMPLEX); bool b = a.IsComplex(); // Should return true. Arguments None Return Boolean indicating if the array is complex. Value Description Use this method to determine if an array is complex. D-60...

  • Page 417

    bool Equals(const mwArray& arr) const Purpose Test two arrays for equality #include "mclcppclass.h" Syntax mwArray a(1, 1, mxDOUBLE_CLASS); mwArray b(1, 1, mxDOUBLE_CLASS); a = 1.0; b = 1.0; bool c = a.Equals(b); // Should return true. Arguments Array to compare to array. Return Boolean value indicating the equality of the two arrays.

  • Page 418

    int CompareTo(const mwArray& arr) const Purpose Compare two arrays for order #include "mclcppclass.h" Syntax mwArray a(1, 1, mxDOUBLE_CLASS); mwArray b(1, 1, mxDOUBLE_CLASS); a = 1.0; b = 1.0; int n = a.CompareTo(b); // Should return 0 Arguments Array to compare to this array. Return Returns a negative integer, zero, or a positive integer if this array is less than, equal to, or greater than the specified array.

  • Page 419

    int HashCode() const Purpose Return hash code for array #include "mclcppclass.h" Syntax mwArray a(1, 1, mxDOUBLE_CLASS); int n = a.HashCode(); Arguments None Return An integer value representing a unique hash code for the array. Value Description This method constructs a unique hash value form the underlying bytes in the array.

  • Page 420

    Value Description This method returns a string representation of the underlying array. The string returned is the same string that is returned by typing a variable’s name at the MATLAB command prompt. D-64...

  • Page 421

    mwArray RowIndex() const Purpose Return array containing row indices of each element in array #include <stdio.h> Syntax #include "mclcppclass.h" mwArray a(1, 1, mxDOUBLE_CLASS); mwArray rows = a.RowIndex(); Arguments None Return containing the row indices. mwArray Value Description Returns an array of type representing the row indices mxINT32_CLASS (first dimension) of this array.

  • Page 422

    mwArray ColumnIndex() const Purpose Return array containing column indices of each element in array #include "mclcppclass.h" Syntax mwArray a(1, 1, mxDOUBLE_CLASS); mwArray rows = a.ColumnIndex(); Arguments None Return containing the column indices. mwArray Value Description Returns an array of type representing the column mxINT32_CLASS indices (second dimension) of this array.

  • Page 423

    void MakeComplex() Purpose Convert real numeric array to complex #include "mclcppclass.h" Syntax double rdata[4] = {1.0, 2.0, 3.0, 4.0}; double idata[4] = {10.0, 20.0, 30.0, 40.0}; mwArray a(2, 2, mxDOUBLE_CLASS); a.SetData(rdata, 4); a.MakeComplex(); a.Imag().SetData(idata, 4); Arguments None Return None Value Description Use this method to convert a numeric array that has been previously allocated as...

  • Page 424

    mwArray Get(mwSize num_indices, ...) Purpose Return single element at specified 1-based index #include "mclcppclass.h" Syntax double data[4] = {1.0, 2.0, 3.0, 4.0}; double x; mwArray a(2, 2, mxDOUBLE_CLASS); a.SetData(data, 4); x = a.Get(1,1); // x = 1.0 x = a.Get(2, 1, 2); // x = 3.0 x = a.Get(2, 2, 2);...

  • Page 425

    mwArray Get(const char* name, mwSize num_indices, ...) Purpose Return single element at specified field name and 1-based index in struct array #include "mclcppclass.h" Syntax const char* fields[] = {"a", "b", "c"}; mwArray a(1, 1, 3, fields); mwArray b = a.Get("a", 1, 1); // b=a(1).a;...

  • Page 426

    mwArray Get(const char* name, mwSize num_indices, ...) is thrown if an invalid number of indices is passed in mwException or if any index is out of bounds. D-70...

  • Page 427

    mwArray Get(mwSize num_indices, const mwIndex* index) Purpose Return single element at specified 1-based index #include "mclcppclass.h" Syntax double data[4] = {1.0, 2.0, 3.0, 4.0}; int index[2] = {1, 1}; double x; mwArray a(2, 2, mxDOUBLE_CLASS); a.SetData(data, 4); x = a.Get(1, index); // x = 1.0 x = a.Get(2, index);...

  • Page 428

    mwArray Get(const char* name, mwSize num_indices, const mwIndex* index) Purpose Return single element at specified field name and 1-based index in array struct #include "mclcppclass.h" Syntax const char* fields[] = {"a", "b", "c"}; int index[2] = {1, 1}; mwArray a(1, 1, 3, fields); mwArray b = a.Get("a", 1, index);...

  • Page 429

    mwArray Get(const char* name, mwSize num_indices, const mwIndex* index) thrown if an invalid number of indices is passed in or if any index is out of bounds. D-73...

  • Page 430

    2+4i, 7-3i, 8+6i would be represented as . Complex numbers (2,4i) (7,3i) (8,6i) have two components, real and imaginary. The MATLAB functions can be applied to an array of Real Imag Complex numbers. These functions extract the corresponding part of the Complex number.

  • Page 431

    2+4i, 7-3i, 8+6i would be represented as . Complex numbers (2,4i) (7,3i) (8,6i) have two components, real and imaginary. The MATLAB functions can be applied to an array of Real Imag Complex numbers. These functions extract the corresponding part of the Complex number.

  • Page 432

    void Set(const mwArray& arr) Purpose Assign shared copy of input array to currently referenced cell for arrays of type mxCELL_CLASS mxSTRUCT_CLASS #include "mclcppclass.h" Syntax mwArray a(2, 2, mxDOUBLE_CLASS); mwArray b(2, 2, mxINT16_CLASS); mwArray c(1, 2, mxCELL_CLASS); c.Get(1,1).Set(a); // Sets c(1) = a c.Get(1,2).Set(b);...

  • Page 433

    void GetData(<numeric-type>* buffer, mwSize len) const Purpose Copy array’s data into supplied numeric buffer #include "mclcppclass.h" Syntax double rdata[4] = {1.0, 2.0, 3.0, 4.0}; double data_copy[4] ; mwArray a(2, 2, mxDOUBLE_CLASS); a.SetData(rdata, 4); a.GetData(data_copy, 4); Arguments buffer Buffer to receive copy. Maximum length of buffer.

  • Page 434

    void GetData(<numeric-type>* buffer, mwSize len) const The data is copied in column-major order. If the underlying array is not of the same type as the input buffer, the data is converted to this type as it is copied. If a conversion cannot be made, an is thrown.

  • Page 435

    void GetLogicalData(mxLogical* buffer, mwSize len) const Purpose Copy array’s data into supplied buffer mxLogical #include "mclcppclass.h" Syntax mxLogical data[4] = {true, false, true, false}; mxLogical data_copy[4] ; mwArray a(2, 2, mxLOGICAL_CLASS); a.SetData(data, 4); a.GetData(data_copy, 4); Arguments buffer Buffer to receive copy. Maximum length of buffer.

  • Page 436

    void GetCharData(mxChar* buffer, mwSize len) const Purpose Copy array’s data into supplied buffer mxChar #include "mclcppclass.h" Syntax mxChar data[6] = {'H', 'e' , `l' , 'l' , 'o' , '\0'}; mxChar data_copy[6] ; mwArray a(1, 6, mxCHAR_CLASS); a.SetData(data, 6); a.GetData(data_copy, 6); Arguments buffer Buffer to receive copy.

  • Page 437

    void SetData(<numeric-type>* buffer, mwSize len) Purpose Copy data from supplied numeric buffer into array #include "mclcppclass.h" Syntax double rdata[4] = {1.0, 2.0, 3.0, 4.0}; double data_copy[4] ; mwArray a(2, 2, mxDOUBLE_CLASS); a.SetData(rdata, 4); a.GetData(data_copy, 4); Arguments buffer Buffer containing data to copy. Maximum length of buffer.

  • Page 438

    void SetLogicalData(mxLogical* buffer, mwSize len) Purpose Copy data from supplied buffer into array mxLogical #include "mclcppclass.h" Syntax mxLogical data[4] = {true, false, true, false}; mxLogical data_copy[4] ; mwArray a(2, 2, mxLOGICAL_CLASS); a.SetData(data, 4); a.GetData(data_copy, 4); Arguments buffer Buffer containing data to copy. Maximum length of buffer.

  • Page 439

    void SetCharData(mxChar* buffer, mwSize len) Purpose Copy data from supplied buffer into array mxChar #include "mclcppclass.h" Syntax mxChar data[6] = {'H', 'e' , 'l' , 'l' , 'o' , '\0'}; mxChar data_copy[6] ; mwArray a(1, 6, mxCHAR_CLASS); a.SetData(data, 6); a.GetData(data_copy, 6); Arguments buffer Buffer containing data to copy.

  • Page 440

    mwArray operator()(mwIndex i1, mwIndex i2, mwIndex i3, ..., ) Purpose Return single element at specified 1-based index #include "mclcppclass.h" Syntax double data[4] = {1.0, 2.0, 3.0, 4.0}; double x; mwArray a(2, 2, mxDOUBLE_CLASS); a.SetData(data, 4); x = a(1,1); // x = 1.0 x = a(1,2);...

  • Page 441

    mwArray operator()(const char* name, mwIndex i1, mwIndex i2, mwIndex i3, ..., ) Purpose Return single element at specified field name and 1-based index in array struct #include "mclcppclass.h" Syntax const char* fields[] = {"a", "b", "c"}; int index[2] = {1, 1}; mwArray a(1, 1, 3, fields);...

  • Page 442

    mwArray& operator=(const <type>& x) Purpose Assign single scalar value to array #include "mclcppclass.h" Syntax mwArray a(2, 2, mxDOUBLE_CLASS); a(1,1) = 1.0; // assigns 1.0 to element (1,1) a(1,2) = 2.0; // assigns 2.0 to element (1,2) a(2,1) = 3.0; // assigns 3.0 to element (2,1) a(2,2) = 4.0;...

  • Page 443

    operator <type>() const Purpose Fetch single scalar value from array #include "mclcppclass.h" Syntax double data[4] = {1.0, 2.0, 3.0, 4.0}; double x; mwArray a(2, 2, mxDOUBLE_CLASS); a.SetData(data, 4); x = (double)a(1,1); // x = 1.0 x = (double)a(1,2); // x = 3.0 x = (double)a(2,1);...

  • Page 444

    static mwArray Deserialize(const mwArray& arr) Purpose Deserialize array that was serialized with mwArray::Serialize #include "mclcppclass.h" Syntax double rdata[4] = {1.0, 2.0, 3.0, 4.0}; mwArray a(1,4,mxDOUBLE_CLASS); a.SetData(rdata, 4); mwArray b = a.Serialize(); a = mwArray::Deserialize(b);// a should contain same // data as original Arguments that has been obtained by calling mwArray...

  • Page 445

    static mwArray NewSparse(rowindex_size, mwIndex* rowindex, colindex_size, mwIndex* colindex, data_size, mxDouble* rData, num_rows, num_cols, nzmax) Purpose Creates real sparse matrix of type with specified number of double rows and columns. static mwArray NewSparse(mwSize rowindex_size, Signature const mwIndex* rowindex, mwSize colindex_size, const mwIndex* colindex, mwSize data_size, const mxDouble* rData, mwSize num_rows,...

  • Page 446

    static mwArray NewSparse(rowindex_size, mwIndex* rowindex, colindex_size, mwIndex* colindex, data_size, mxDouble* rData, num_rows, num_cols, nzmax) nzmax Reserved storage for sparse matrix. If is zero, storage will nzmax be set to max{rowindex_size, colindex_size, data_size} Outputs mwArray containing the sparse array. mwArray Description The lengths of input row, column index, and data arrays must all be the same or equal to 1.

  • Page 447

    static mwArray NewSparse(rowindex_size, mwIndex* rowindex, colindex_size, mwIndex* colindex, data_size, mxDouble* rData, num_rows, num_cols, nzmax) will display the following output to the screen: (1,1) (2,1) (1,2) (2,2) (3,2) (2,3) (3,3) (4,3) (3,4) (4,4) D-91...

  • Page 448

    static mwArray NewSparse(rowindex_size, mwIndex* rowindex, colindex_size, mwIndex* colindex, data_size, mxDouble* rdata, nzmax) Purpose Creates real sparse matrix of type with number of rows and double columns inferred (not explicitly specified) from input data. static mwArray NewSparse(mwSize rowindex_size, Signature const mwIndex* rowindex, mwSize colindex_size, const mwIndex* colindex, mwSize data_size,...

  • Page 449

    static mwArray NewSparse(rowindex_size, mwIndex* rowindex, colindex_size, mwIndex* colindex, data_size, mxDouble* rdata, nzmax) Description The lengths of input row and column index and data arrays must all be the same or equal to 1. In the case where any of these arrays are equal to 1, the value is repeated through out the construction of the matrix.

  • Page 450

    static mwArray NewSparse(rowindex_size, mwIndex* rowindex, colindex_size, mwIndex* colindex, data_size, mxDouble* rdata, nzmax) double one = 1.0; mwIndex row_diag[] = {1, 2, 3, 4}; mwIndex col_diag[] = {1, 2, 3, 4}; mwArray mysparse = mwArray::NewSparse(4, row_diag, 4, col_diag, 1, &one, std::cout << mysparse << std::endl; (1,1) (2,2) (3,3)

  • Page 451

    static mwArray NewSparse(rowindex_size, mwIndex* rowindex, colindex_size, mwIndex* colindex, data_size, mxDouble* rdata, mxDouble* idata, num_rows, num_cols, nzmax) Purpose Creates complex sparse matrix of type with specified number of double rows and columns. static mwArray NewSparse(mwSize rowindex_size, Signature const mwIndex* rowindex, mwSize colindex_size, const mwIndex* colindex, mwSize data_size, const mxDouble* rData,...

  • Page 452

    static mwArray NewSparse(rowindex_size, mwIndex* rowindex, colindex_size, mwIndex* colindex, data_size, mxDouble* rdata, mxDouble* idata, num_rows, num_cols, nzmax) num_cols Number of columns in matrix. nzmax Reserved storage for sparse matrix. If is zero, storage will nzmax be set to max{rowindex_size, colindex_size, data_size} Outputs mwArray containing the sparse array...

  • Page 453

    static mwArray NewSparse(rowindex_size, mwIndex* rowindex, colindex_size, mwIndex* colindex, data_size, mxDouble* rdata, mxDouble* idata, num_rows, num_cols, nzmax) It displays the following output to the screen: (1,1) 2.0000 +20.0000i (2,1) -1.0000 -10.0000i (1,2) -1.0000 -10.0000i (2,2) 2.0000 +20.0000i (3,2) -1.0000 -10.0000i (2,3) -1.0000 -10.0000i (3,3) 2.0000 +20.0000i...

  • Page 454

    static mwArray NewSparse(rowindex_size, mwIndex* rowindex, colindex_size, mwIndex* colindex, data_size, mxDouble* rdata, mxDouble* idata, mwsize, nzmax) Purpose Creates complex sparse matrix of type with number of rows and double columns inferred (not explicitly specified) from input data. static mwArray NewSparse(mwSize rowindex_size, Signature const mwIndex* rowindex, mwSize colindex_size,...

  • Page 455

    static mwArray NewSparse(rowindex_size, mwIndex* rowindex, colindex_size, mwIndex* colindex, data_size, mxDouble* rdata, mxDouble* idata, mwsize, nzmax) Outputs mwArray containing the sparse array. mwArray Description The lengths of input row and column index and data arrays must all be the same or equal to 1. In the case where any of these arrays are equal to 1, the value is repeated through out the construction of the matrix.

  • Page 456

    static mwArray NewSparse(rowindex_size, mwIndex* rowindex, colindex_size, mwIndex* colindex, data_size, mxLogical* rdata, num_rows, num_cols, nzmax) Purpose Creates logical sparse matrix with specified number of rows and columns. static mwArray NewSparse(mwSize rowindex_size, Signature const mwIndex* rowindex, mwSize colindex_size, const mwIndex* colindex, mwSize data_size, const mxLogical* rData, mwSize num_rows, mwSize num_cols,...

  • Page 457

    static mwArray NewSparse(rowindex_size, mwIndex* rowindex, colindex_size, mwIndex* colindex, data_size, mxLogical* rdata, num_rows, num_cols, nzmax) nzmax Reserved storage for sparse matrix. If is zero, storage will nzmax be set to max{rowindex_size, colindex_size, data_size} Outputs mwArray containing the sparse array. mwArray Description The lengths of input row and column index and data arrays must all be the same or equal to 1.

  • Page 458

    static mwArray NewSparse(rowindex_size, mwIndex* rowindex, colindex_size, mwIndex* colindex, data_size, mxLogical* rdata, num_rows, num_cols, nzmax) (2,3) (3,3) (4,3) (3,4) (4,4) D-102...

  • Page 459

    static mwArray NewSparse(rowindex_size, mwIndex* rowindex, colindex_size, mwIndex* colindex, data_size, mxLogical* rData, nzmax) Purpose Creates logical sparse matrix with number of rows and columns inferred (not explicitly specified) from input data. static mwArray NewSparse(mwSize rowindex_size, Signature const mwIndex* rowindex, mwSize colindex_size, const mwIndex* colindex, mwSize data_size, const mxLogical* rData,...

  • Page 460

    static mwArray NewSparse(rowindex_size, mwIndex* rowindex, colindex_size, mwIndex* colindex, data_size, mxLogical* rData, nzmax) Description The lengths of input row and column index and data arrays must all be the same or equal to 1. In the case where any of these arrays are equal to 1, the value is repeated through out the construction of the matrix.

  • Page 461

    static mwArray NewSparse (num_rows, num_cols, nzmax, mxClassID mxID, mxComplexity cmplx = mxREAL) Purpose Creates an empty sparse matrix static mwArray NewSparse (mwSize num_rows, Signature mwSize num_cols, mwSize nzmax, mxClassID mxID, mxComplexity cmplx = mxREAL) Arguments Inputs num_rows Number of rows in matrix. num_cols Number of columns in matrix.

  • Page 462

    static mwArray NewSparse (num_rows, num_cols, nzmax, mxClassID mxID, mxComplexity cmplx = mxREAL) Example This example constructs a real 3 X 3 empty sparse matrix of type with reserved storage for 4 non-zero elements: double mwArray mysparse = mwArray::NewSparse(3, 3, 4, mxDOUBLE_CLASS); std::cout <<...

  • Page 463

    static double GetNaN() Purpose Get value of (Not-a-Number) #include "mclcppclass.h" Syntax double x = mwArray::GetNaN(); Arguments None Return The value of (Not-a-Number) on your system. Value Description Call to return the value of for your system. mwArray::GetNaN is the IEEE arithmetic representation for Not-a-Number. Certain mathematical operations return as a result, for example: •...

  • Page 464

    The value of the MATLAB variable. Value Description Call to return the value of the MATLAB variable. mwArray::GetEps This variable is the distance from 1.0 to the next largest floating-point number. Consequently, it is a measure of floating-point accuracy. The...

  • Page 465

    Return The value of (infinity) on your system. Value Description Call to return the value of the MATLAB internal mwArray::GetInf variable. is a permanent variable representing IEEE arithmetic positive infinity. The value of is built into the system; you cannot modify it.

  • Page 466

    static bool IsFinite(double x) Purpose Test if value is finite and return if value is finite true #include "mclcppclass.h" Syntax bool x = mwArray::IsFinite(1.0); // Returns true Arguments Value to test for finiteness. Return Result of test. Value Description Call to determine whether or not a value is finite.

  • Page 467

    Description Call to determine whether or not a value is equal to mwArray::IsInf infinity or minus infinity. MATLAB stores the value of infinity in a permanent variable named , which represents IEEE arithmetic positive infinity. The value of the variable, , is built into the system;...

  • Page 468

    The system understands a family of bit patterns as representing . In other words, is not a single value, rather it is a family of numbers that the MATLAB software (and other IEEE-compliant applications) use to represent an error condition or missing data. D-112...

  • Page 469

    10-3 application callback strings POSIX main 6-11 searching MATLAB files for 10-5 application coding with code MATLAB files and C/C++ files 7-8 porting 5-15 Applications command line running with the Mac Application differences between command-line and Launcher B-7 GUI 3-4...

  • Page 470

    Index directory compopts.bat configuring user profile using DLL. See shared library 8-2 mbuild conflicting options DLLs 3-6 resolving 6-3 depfun 3-6 CTF (Component Technology File) archive 3-7 double-clickable application determining files to include 4-8 passing arguments 6-33 extracting without executing 5-16 CTF Archive Controlling management and storage error messages...

  • Page 471

    8-21 installation area B-7 B-9 Macintosh Application Launcher installation modifying the B-9 area interfacing configuring the B-7 MATLAB code to C/C++ code 6-14 Macintosh Application Launcher preference internal error C-2 pane B-7 9-16 13-13 macros 6-5 isdeployed...

  • Page 472

    MATLAB ® on same machine 5-19 on Microsoft Windows 2-5 instance 8-11 on UNIX 2-5 options 8-11 MATLAB Compiler license 11-8 MCR Component Cache MATLAB ® Compiler™ Runtime (MCR) 5-18 How to use MATLAB data files 3-14 Overriding CTF embedding 6-20...

  • Page 473

    2-9 conflicting options 6-3 modifying on rmpath UNIX 2-10 Windows 2-10 UNIX 2-9 Save function 3-14 Windows 2-7 script file 6-25 including in deployed applications 6-26 script MATLAB file 6-25 pass through converting to function MATLAB files 6-25 Index-5...

  • Page 474

    Index security 3-7 objects 10-5 uimenu setmcruserdata function 13-58 UNIX shared libraries 3-6 options file 2-9 depfun 3-6 locating 2-9 shared library 3-6 8-4 supported compilers 2-3 calling structure 8-25 system requirements 2-2 header file 6-12 UNIX Deployment B-1 using on Mac OS X 8-21 unsupported functions 10-9 wrapper 6-12 user messages...

Comments to this Manuals

Symbols: 0

Latest comments:

×

Select the desired size and copy embed code

Copy your embed code and put on your site: