Fortran MEX-Files 4
Total Page:16
File Type:pdf, Size:1020Kb
MATLAB The Language of Technical Computing Computation Visualization Programming Application Program Interface Guide Version 5 How to Contact The MathWorks: ☎ 508-647-7000 Phone 508-647-7001 Fax FAX The MathWorks, Inc. Mail ✉ 24 Prime Park Way Natick, MA 01760-1500 http://www.mathworks.com Web ftp.mathworks.com Anonymous FTP server comp.soft-sys.matlab Newsgroup @ [email protected] Technical support [email protected] Product enhancement suggestions [email protected] Bug reports [email protected] Documentation error reports [email protected] Subscribing user registration [email protected] Order status, license renewals, passcodes [email protected] Sales, pricing, and general information Application Program Interface Guide COPYRIGHT 1984 - 1998 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 repro- duced in any form without prior written consent from The MathWorks, Inc. U.S. GOVERNMENT: If Licensee is acquiring the Programs on behalf of any unit or agency of the U.S. Government, the following shall apply: (a) For units of the Department of Defense: the Government shall have only the rights specified in the license under which the commercial computer software or commercial software documentation was obtained, as set forth in subparagraph (a) of the Rights in Commercial Computer Software or Commercial Software Documentation Clause at DFARS 227.7202-3, therefore the rights set forth herein shall apply; and (b) For any other unit or agency: NOTICE: Notwithstanding any other lease or license agreement that may pertain to, or accompany the delivery of, the computer software and accompanying documentation, the rights of the Government regarding its use, reproduction, and disclo- sure are as set forth in Clause 52.227-19 (c)(2) of the FAR. MATLAB, Simulink, Handle Graphics, and Real-Time Workshop are registered trademarks and Stateflow and Target Language Compiler are trademarks of The MathWorks, Inc. Other product or brand names are trademarks or registered trademarks of their respective holders. Printing History: December 1996 First printing July 1997 Revised for 5.1 January 1998 Revised for 5.2 Contents Introducing the MATLAB API 1 Introduction to MATLAB API . 1-2 MEX-Files . 1-2 MAT-File Applications . 1-2 Engine Applications . 1-3 MATLAB Data . 1-4 The MATLAB Array . 1-4 Data Storage . 1-4 Data Types in MATLAB . 1-5 Complex Double-Precision Matrices . 1-5 Numeric Matrices . 1-5 MATLAB Strings . 1-5 Sparse Matrices . 1-5 Cell Arrays . 1-6 Structures . 1-6 Objects . 1-6 Multidimensional Arrays . 1-6 Logical Arrays . 1-6 Empty Arrays . 1-7 Using Data Types . 1-7 The explore Example . 1-7 API Documentation . 1-8 The API Documentation Set . 1-8 API Tutorial Files . 1-8 How This Book Is Organized . 1-9 i Getting Started 2 Introducing MEX-Files . 2-2 Using MEX-Files . 2-2 The Distinction Between mx and mex Prefixes . 2-3 mx Routines . 2-3 mex Routines . 2-3 Building MEX-Files . 2-4 Testing Your Configuration . 2-4 On UNIX . 2-5 On Windows . 2-6 On Macintosh . 2-8 Special Considerations for Macintosh Users . 2-9 Using –f to Specify an Options File . 2-12 Preconfigured Options Files . 2-13 Troubleshooting Your Configuration . 2-16 Search Path Problem on Windows . 2-16 MATLAB Pathnames Containing Spaces on Windows . 2-16 DLLs Not on Path on Windows . 2-16 Non-ANSI Compiler on UNIX . 2-16 General Configuration Problem . 2-16 Creating C Language MEX-Files 3 C MEX-Files . 3-2 Directory Organization . 3-2 The Parts of a MEX-File . 3-2 Required Arguments to a MEX-File . 3-5 Examples of C MEX-Files . 3-7 A First Example . 3-7 Manipulating Strings . 3-11 Passing Two or More Inputs or Outputs . 3-14 ii Contents Manipulating Structures and Cell Arrays . 3-16 Handling Complex Data . 3-20 Handling 8-,16-, and 32-Bit Data . 3-23 Manipulating Multidimensional Numerical Arrays . 3-25 Handling Sparse Arrays . 3-28 Calling MATLAB Functions and Other User-Defined Functions from Within a MEX-File . 3-30 Advanced Topics . 3-33 Help Files . 3-33 Linking Multiple Files . 3-33 Variable Scope . 3-33 Memory Management . 3-34 Automatic Cleanup of Temporary Arrays . 3-34 Persistent Arrays . 3-34 Hybrid Arrays . 3-36 How to Debug C Language MEX-Files . 3-37 Debugging on UNIX . 3-37 Debugging on Windows . 3-38 Debugging on Macintosh . 3-39 Creating Fortran MEX-Files 4 Fortran MEX-Files . 4-2 Directory Organization . 4-2 MEX-Files and Data Types . 4-2 The Components of a Fortran MEX-File . 4-2 The Pointer Concept . 4-5 The Gateway Routine . 4-6 The %val Construct . 4-8 Examples of Fortran MEX-Files . 4-9 A First Example — Passing a Scalar . 4-9 Passing Strings . 4-12 Passing Arrays of Strings . 4-14 iii Passing Matrices . 4-17 Passing Two or More Inputs or Outputs . 4-19 Handling Complex Data . 4-22 Dynamic Allocation of Memory . 4-26 Handling Sparse Matrices . 4-28 Calling MATLAB Functions from Fortran MEX-Files . 4-32 Advanced Topics . 4-36 Help Files . 4-36 Linking Multiple Files . 4-36 Variable Scope . 4-36 Memory Management . 4-37 How to Debug Fortran Language MEX-Files . 4-38 Debugging on UNIX . 4-38 Debugging on Windows.