MATLAB External Interfaces - MathWorks

1068 Pages·2016·4.27 MB·English

®
MATLAB
External Interfaces
R2017a
How to Contact MathWorks
Latest news: www.mathworks.com
Sales and services: www.mathworks.com/sales_and_services
User community: www.mathworks.com/matlabcentral
Technical support: www.mathworks.com/support/contact_us
Phone: [phone]
The MathWorks, Inc.
3 Apple Hill Drive
Natick, MA 01760-2098
MATLAB® External Interfaces
© COPYRIGHT 1984–2017 by The MathWorks, Inc.
The software described in this document is furnished under a license agreement. The software may be used
or copied only under the terms of the license agreement. No part of this manual may be photocopied or
reproduced in any form without prior written consent from The MathWorks, Inc.
FEDERAL ACQUISITION: This provision applies to all acquisitions of the Program and Documentation
by, for, or through the federal government of the United States. By accepting delivery of the Program
or Documentation, the government hereby agrees that this software or documentation qualifies as
commercial computer software or commercial computer software documentation as such terms are used
or defined in FAR 12.212, DFARS Part 227.72, and DFARS 252.227-7014. Accordingly, the terms and
conditions of this Agreement and only those rights specified in this Agreement, shall pertain to and
govern the use, modification, reproduction, release, performance, display, and disclosure of the Program
and Documentation by the federal government (or other entity acquiring for or through the federal
government) and shall supersede any conflicting contractual terms or conditions. If this License fails
to meet the government's needs or is inconsistent in any respect with federal procurement law, the
government agrees to return the Program and Documentation, unused, to The MathWorks, Inc.
Trademarks
MATLAB and Simulink are registered trademarks of The MathWorks, Inc. See
www.mathworks.com/trademarks for a list of additional trademarks. Other product or brand
names may be trademarks or registered trademarks of their respective holders.
Patents
MathWorks products are protected by one or more U.S. patents. Please see
www.mathworks.com/patents for more information.
Revision History
December 1996 First printing New for MATLAB 5 (release 8)
July 1997 Online only Revised for MATLAB 5.1 (Release 9)
January 1998 Second printing Revised for MATLAB 5.2 (Release 10)
October 1998 Third printing Revised for MATLAB 5.3 (Release 11)
November 2000 Fourth printing Revised and renamed for MATLAB 6.0
(Release 12)
June 2001 Online only Revised for MATLAB 6.1 (Release 12.1)
July 2002 Online only Revised for MATLAB 6.5 (Release 13)
January 2003 Online only Revised for MATLAB 6.5.1 (Release 13SP1)
June 2004 Online only Revised for MATLAB 7.0 (Release 14)
October 2004 Online only Revised for MATLAB 7.0.1 (Release 14SP1)
September 2005 Online only Revised for MATLAB 7.1 (Release 14SP3)
March 2006 Online only Revised for MATLAB 7.2 (Release 2006a)
September 2006 Online only Revised for MATLAB 7.3 (Release 2006b)
March 2007 Online only Revised for MATLAB 7.4 (Release 2007a)
September 2007 Online only Revised for MATLAB 7.5 (Release 2007b)
March 2008 Online only Revised for MATLAB 7.6 (Release 2008a)
October 2008 Online only Revised for MATLAB 7.7 (Release 2008b)
March 2009 Online only Revised for MATLAB 7.8 (Release 2009a)
September 2009 Online only Revised for MATLAB 7.9 (Release 2009b)
March 2010 Online only Revised for MATLAB 7.10 (Release 2010a)
September 2010 Online only Revised for MATLAB 7.11 (Release 2010b)
April 2011 Online only Revised for MATLAB 7.12 (Release 2011a)
September 2011 Online only Revised for MATLAB 7.13 (Release 2011b)
March 2012 Online only Revised for MATLAB 7.14 (Release 2012a)
September 2012 Online only Revised for MATLAB 8.0 (Release 2012b)
March 2013 Online only Revised for MATLAB 8.1 (Release 2013a)
September 2013 Online only Revised for MATLAB 8.2 (Release 2013b)
March 2014 Online only Revised for MATLAB 8.3 (Release 2014a)
October 2014 Online only Revised for MATLAB 8.4 (Release 2014b)
March 2015 Online only Revised for MATLAB 8.5 (Release 2015a)
September 2015 Online only Revised for MATLAB 8.6 (Release 2015b)
March 2016 Online only Revised for MATLAB 9.0 (Release 2016a)
September 2016 Online only Revised for MATLAB 9.1 (Release 2016b)
March 2017 Online only Revised for MATLAB 9.2 (Release 2017a)

Contents
Using Java Libraries from MATLAB
1
Getting Started with Java Libraries . . . . . . . . . . . . . . . . . . . . 1-3
Platform Support for JVM Software . . . . . . . . . . . . . . . . . . . 1-3
Learn More About Java Programming Language . . . . . . . . . 1-3
Call Java Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5
Choose Class Constructor to Create Java Object . . . . . . . . . . 1-5
Shorten Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5
Create Array List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5
Pass MATLAB Data to add Method . . . . . . . . . . . . . . . . . . . 1-5
Add Elements to ArrayList . . . . . . . . . . . . . . . . . . . . . . . . 1-6
Java Objects Are References in MATLAB . . . . . . . . . . . . . . . 1-6
Use ArrayList Object in MATLAB . . . . . . . . . . . . . . . . . . . 1-7
Simplify Java Class Names Using import Function . . . . . . . 1-9
Java Class Path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-10
Static Path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-12
When to Use Static Path . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-12
Create javaclasspath.txt File . . . . . . . . . . . . . . . . . . . . 1-12
Add Individual (Unpackaged) Classes . . . . . . . . . . . . . . . . . 1-13
Add Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-13
Add JAR File Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-14
Load Java Class Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . 1-16
Locate Native Method Libraries . . . . . . . . . . . . . . . . . . . . . . 1-17
Load Class Using Java Class.forName Method . . . . . . . . . . 1-18
Dynamic Path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-19
v
Call Method in Your Own Java Class . . . . . . . . . . . . . . . . . . 1-20
How MATLAB Represents Java Arrays . . . . . . . . . . . . . . . . 1-21
Array Indexing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-21
Shape of Java Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-21
Interpret Size of Java Arrays . . . . . . . . . . . . . . . . . . . . . . . 1-22
Interpret Number of Dimensions of Java Arrays . . . . . . . . . 1-23
Create Array of Java Objects . . . . . . . . . . . . . . . . . . . . . . . . . 1-24
Create Array of Primitive Java Types . . . . . . . . . . . . . . . . . 1-24
Access Elements of Java Array . . . . . . . . . . . . . . . . . . . . . . . 1-26
MATLAB Array Indexing . . . . . . . . . . . . . . . . . . . . . . . . . . 1-26
Single Subscript Indexing . . . . . . . . . . . . . . . . . . . . . . . . . . 1-26
Colon Operator Indexing . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-27
Using END in a Subscript . . . . . . . . . . . . . . . . . . . . . . . . . . 1-29
Converting Object Array Elements to MATLAB Types . . . . 1-29
Assign Values to Java Array . . . . . . . . . . . . . . . . . . . . . . . . . 1-31
Single Subscript Indexing Assignment . . . . . . . . . . . . . . . . 1-31
Linear Array Assignment . . . . . . . . . . . . . . . . . . . . . . . . . . 1-32
Empty Matrix Assignment . . . . . . . . . . . . . . . . . . . . . . . . . 1-33
Subscripted Deletion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-33
Concatenate Java Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-35
Create Java Array References . . . . . . . . . . . . . . . . . . . . . . . . 1-37
Create Copy of Java Array . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-38
Construct and Concatenate Java Objects . . . . . . . . . . . . . . . 1-40
Create Java Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-40
Concatenate Objects of Same Class . . . . . . . . . . . . . . . . . . . 1-40
Concatenate Objects of Unlike Classes . . . . . . . . . . . . . . . . 1-40
Save and Load Java Objects to MAT-Files . . . . . . . . . . . . . . 1-42
Data Fields of Java Objects . . . . . . . . . . . . . . . . . . . . . . . . . . 1-43
Access Public and Private Data . . . . . . . . . . . . . . . . . . . . . . 1-43
Display Public Data Fields of Java Object . . . . . . . . . . . . . . 1-44
Access Static Field Data . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-44
Determine Class of Java Object . . . . . . . . . . . . . . . . . . . . . . . 1-46
vi Contents
Method Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-47
Display Method Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-47
Display Method Signatures . . . . . . . . . . . . . . . . . . . . . . . . . 1-47
Display Syntax in Figure Window . . . . . . . . . . . . . . . . . . . . 1-48
Determine What Classes Define Method . . . . . . . . . . . . . . . . 1-50
Java Methods That Affect MATLAB Commands . . . . . . . . . 1-51
Changing the Effect of disp and display . . . . . . . . . . . . . 1-51
Changing the Effect of isequal . . . . . . . . . . . . . . . . . . . . . 1-51
Changing the Effect of double, string, and char . . . . . . . 1-52
How MATLAB Handles Undefined Methods . . . . . . . . . . . . . 1-53
Executing Java main Methods in MATLAB . . . . . . . . . . . . . 1-54
Read URL Using java.net.URL . . . . . . . . . . . . . . . . . . . . . . . . 1-55
Pass Data to Java Methods . . . . . . . . . . . . . . . . . . . . . . . . . . 1-57
MATLAB Type to Java Type Mapping . . . . . . . . . . . . . . . . 1-57
How Array Dimensions Affect Conversion . . . . . . . . . . . . . . 1-59
Convert Numbers to Integer Arguments . . . . . . . . . . . . . . . 1-59
Pass String Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-60
Pass Java Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-60
Pass Empty Matrices and Nulls . . . . . . . . . . . . . . . . . . . . . 1-62
Overloaded Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-62
Handle Data Returned from Java Methods . . . . . . . . . . . . . 1-64
Primitive Return Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-64
java.lang.Object Return Types . . . . . . . . . . . . . . . . . . . 1-65
Functions to Convert Java Objects to MATLAB Types . . . . . 1-66
Java Heap Memory Preferences . . . . . . . . . . . . . . . . . . . . . . 1-70
Read and Write MATLAB MAT-Files in C/C++ and
Fortran
2
Custom Applications to Access MAT-Files . . . . . . . . . . . . . . . 2-2
Why Write Custom Applications? . . . . . . . . . . . . . . . . . . . . . 2-2
vii
MAT-File Interface Library . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3
Exchanging Data Files Between Platforms . . . . . . . . . . . . . . 2-4
MAT-File Library and Include Files . . . . . . . . . . . . . . . . . . . . 2-5
MAT-Function Include Files . . . . . . . . . . . . . . . . . . . . . . . . . 2-5
MAT-Function Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5
Example Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6
What You Need to Build Custom Applications . . . . . . . . . . . . 2-7
Copy External Data into MAT-File Format with Standalone
Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8
Overview of matimport.c Example . . . . . . . . . . . . . . . . . . . . 2-8
Declare Variables for External Data . . . . . . . . . . . . . . . . . . . 2-9
Create mxArray Variables . . . . . . . . . . . . . . . . . . . . . . . . . . 2-9
Create MATLAB Variable Names . . . . . . . . . . . . . . . . . . . . 2-10
Read External Data into mxArray Data . . . . . . . . . . . . . . . 2-10
Create and Open MAT-File . . . . . . . . . . . . . . . . . . . . . . . . . 2-11
Write mxArray Data to File . . . . . . . . . . . . . . . . . . . . . . . . 2-11
Clean Up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-11
Build the Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-11
Create the MAT-File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-11
Import Data into MATLAB . . . . . . . . . . . . . . . . . . . . . . . . . 2-12
Create MAT-File in C or C++ . . . . . . . . . . . . . . . . . . . . . . . . . 2-13
Create MAT-File in C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-13
Create MAT-File in C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-13
Read MAT-File in C/C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-14
Create MAT-File in Fortran . . . . . . . . . . . . . . . . . . . . . . . . . . 2-15
Read MAT-File in Fortran . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-16
Work with mxArrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-17
Read Structures from a MAT-File . . . . . . . . . . . . . . . . . . . . 2-17
Read Cell Arrays from a MAT-File . . . . . . . . . . . . . . . . . . . 2-18
Table of MAT-File Source Code Files . . . . . . . . . . . . . . . . . . 2-19
Build on Mac and Linux Operating Systems . . . . . . . . . . . . 2-21
Setting Run-Time Library Path . . . . . . . . . . . . . . . . . . . . . . 2-21
Building the Application . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-22
viii Contents
Build on Windows Operating Systems . . . . . . . . . . . . . . . . . 2-23
Share MAT-File Applications . . . . . . . . . . . . . . . . . . . . . . . . . 2-24
Calling C Shared Library Functions from MATLAB
3
Call Functions in Shared Libraries . . . . . . . . . . . . . . . . . . . . . 3-2
What Is a Shared Library? . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2
Load and Unload Library . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3
View Library Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4
Invoke Library Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6
Limitations to Shared Library Support . . . . . . . . . . . . . . . . . 3-8
MATLAB Supports C Library Routines . . . . . . . . . . . . . . . . . 3-8
Workarounds for Loading C++ Libraries . . . . . . . . . . . . . . . . 3-8
Limitations Using printf Function . . . . . . . . . . . . . . . . . . . 3-9
Bit Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-9
Enum Declarations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-10
Unions Not Supported . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-10
Compiler Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-11
Limitations Using Pointers . . . . . . . . . . . . . . . . . . . . . . . . . 3-11
Functions with Variable Number of Input Arguments Not
Supported . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-12
Limitations Using Structures . . . . . . . . . . . . . . . . . . . . . . . . . 3-13
MATLAB Returns Pointers to Structures . . . . . . . . . . . . . . 3-13
Structure Cannot Contain Pointers to Other Structures . . . 3-13
Requirements for MATLAB Structure Arguments . . . . . . . . 3-13
Requirements for C struct Field Names . . . . . . . . . . . . . . 3-13
Loading Library Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-15
No Matching Signature Error . . . . . . . . . . . . . . . . . . . . . . . . 3-16
MATLAB Terminates Unexpectedly When Calling Function in
Shared Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-17
Pass Arguments to Shared Library Functions . . . . . . . . . . . 3-18
C and MATLAB Equivalent Types . . . . . . . . . . . . . . . . . . . 3-18
ix
How MATLAB Displays Function Signatures . . . . . . . . . . . 3-20
NULL Pointer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-21
Manually Convert Data Passed to Functions . . . . . . . . . . . . 3-21
Shared Library shrlibsample . . . . . . . . . . . . . . . . . . . . . . . . 3-23
Pass String Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-24
stringToUpper Function . . . . . . . . . . . . . . . . . . . . . . . . . . 3-24
Convert MATLAB Character Array to Uppercase . . . . . . . . 3-24
Pass Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-26
addStructFields and addStructByRef Functions . . . . . 3-26
Add Values of Fields in Structure . . . . . . . . . . . . . . . . . . . . 3-27
Preconvert MATLAB Structure Before Adding Values . . . . . 3-28
Autoconvert Structure Arguments . . . . . . . . . . . . . . . . . . . . 3-29
Pass Pointer to Structure . . . . . . . . . . . . . . . . . . . . . . . . . . 3-29
Pass Enumerated Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-32
readEnum Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-32
Display Enumeration Values . . . . . . . . . . . . . . . . . . . . . . . . 3-32
Pass Pointers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-34
multDoubleRef Function . . . . . . . . . . . . . . . . . . . . . . . . . . 3-34
Pass Pointer of Type double . . . . . . . . . . . . . . . . . . . . . . . . 3-34
Create Pointer Offset from Existing lib.pointer Object . . . . . 3-35
Multilevel Pointers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-36
allocateStruct and deallocateStruct Functions . . . . 3-36
Pass Multilevel Pointer . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-37
Return Array of Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-37
Pass Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-39
print2darray Function . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-39
Convert MATLAB Array to C-Style Dimensions . . . . . . . . . 3-39
multDoubleArray Function . . . . . . . . . . . . . . . . . . . . . . . . 3-40
Preserve 3-D MATLAB Array . . . . . . . . . . . . . . . . . . . . . . . 3-41
Iterate Through an Array . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-43
Create Cell Array from lib.pointer Object . . . . . . . . . . . . . . 3-43
Perform Pointer Arithmetic on Structure Array . . . . . . . . . 3-44
Pointer Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-46
Pointer Arguments in C Functions . . . . . . . . . . . . . . . . . . . 3-46
Put String into Void Pointer . . . . . . . . . . . . . . . . . . . . . . . . 3-46
x Contents