MATLAB New Features Guide | Help Desk |
Upgrading from MATLAB 4 to MATLAB 5
MATLAB 5 is a major upgrade to MATLAB. Although The MathWorks endeavors to maintain full upwards compatibility between subsequent releases of MATLAB, inevitably there are situations where this is not possible. In the case of MATLAB 5, there are a number of changes that you need to know about in order to migrate your code from MATLAB 4 to MATLAB 5. It is useful to introduce two terms in discussing this migration. The first step in converting your code to MATLAB 5 is to make it MATLAB 5 compatible. This involves a rather short list of possible changes that let your M-files run under MATLAB 5. The second step is to make it MATLAB 5 compliant. This means making further changes so that your M-file is not using obsolete, but temporarily supported, features of MATLAB. It also can mean taking advantage of MATLAB 5 features like the new data constructs, graphics, and so on. There are a relatively small number of things that are likely to be in your code that you will have to change to make your M-files MATLAB 5 compatible. Most of these are in the graphics area. There are a somewhat larger number of things you can do (but don't have to) to make your M-files fully MATLAB 5 compliant. To help you gradually make your code compliant, MATLAB 5 displays warning messages when you use functions that are obsolete, even though they still work correctly.Converting M-Files from MATLAB 4 to MATLAB 5
This section describes some changes you can make to your MATLAB 4 code to eliminate error messages and warnings due to incompatible and noncompliant statements.
Converting MEX-Files from MATLAB 4 to MATLAB 5
MATLAB 5 may or may not run existing MATLAB 4 MEX-files and binaries. If your binaries or source files are not compatible with the MATLAB 5 API, you must convert your MATLAB 4 MEX-file source code to MATLAB 5.MEX-File Binary Incompatibility
MATLAB 4 binaries will not run in MATLAB 5 if they:-V3.5
compile switch.
Macintosh-Specific Considerations
MEX-File Source Incompatibility
-V3.5
compile switch will not compile.
mexdebug
is now called dbmex
. Only the name has changed; in all other respects dbmex
behaves exactly like mexdebug
.
mexrc.sh
file is no longer supported. The new options file, mexopts.sh
, contains the same information, but in a different format. $MATLAB/bin/mexopts.sh
is the default UNIX options file.
cmex
and fmex
Bourne shell scripts have been superseded by mex
, a new Bourne shell script that includes both C and Fortran support, as well as additional support for C++.
cmex
and fmex
batch files have been superseded by mex
, a PERL script.
MEX-File Conversion Techniques
If your existing MEX-file binaries do not run, you must convert MATLAB 4 MEX-file sources to MATLAB 5 by:mex
with the -V4
option, or
-v4
option of mex
mex
filename
Rebuilding with the -V4 Option
The simplest strategy for converting C MEX-file programs is to rebuild them with the special-V4
option of mex
. This option uses mex
to include MATLAB 4 header files. Therefore, any C MEX-file source code that compiled cleanly under MATLAB 4 should compile cleanly with the -V4
option. The resulting MEX-file should run under MATLAB 5 just as it ran under MATLAB 4. For example, given C MEX-file MATLAB 4 source code in file MyEig.c
, recompiling under UNIX with
mex -V4 myeig.cyields a MEX-file that MATLAB 5 can execute. It is also possible to use
cmex
and fmex
for compiling C and Fortran source code, but both of these functions simply call mex
.
Even with the -V4
option, you need to recode if your source code manipulates string matrices. The -V4
option cannot handle the different ways in which MATLAB 4 and MATLAB 5 represent string data. The MATLAB 4 Matrix
structure held each "character" in a string matrix as a double-precision, floating-point number. MATLAB 5 represents each "character" in a string matrix as an mxChar
, a 16-bit unsigned integer data type.
The obvious advantage to the -V4
strategy is that it requires very little work on your part. However, this strategy provides only a temporary solution to the conversion problem; there is no guarantee that future releases of MATLAB will continue to support the -V4
option. If you have the time, recoding for MATLAB 5 compliance is a better strategy.
Recoding for MATLAB 5 Compliance
Recoding your MATLAB 4 C or Fortran code for MATLAB 5 compliance involves:Matrix
variables to mxArray
variables.
The MATLAB 4 Matrix
data type is obsolete; you must change all Matrix
variables to mxArray
variables. For example, the mxCreateSparse
function returns a Matrix pointer in MATLAB 4:
Matrix *MySparse; MySparse = mxCreateSparse(10, 10, 110, REAL);
To be MATLAB 5 compliant, change the code to:
mxArray *MySparse; MySparse = mxCreateSparse(10, 10, 110, mxREAL);
The function prototype of almost every MATLAB 4 mx
and mex
function is different in MATLAB 5. The two primary prototype changes are
Matrix
arguments are now mxArray
arguments.
const *
.
REAL
to mxREAL
and COMPLEX
to mxCOMPLEX
.
In any function that requires the specification of real or complex data types, instead of REAL
and COMPLEX
, use mxREAL
and mxCOMPLEX
. For example, in MATLAB 4 you would write
mxCreateSparse(m,n,nzmax,REAL);
nzmax
nonzero real elements. In MATLAB 5, the correct syntax for this same function is:
mxCreateSparse(m,n,nzmax,mxREAL);
A number of functions have become obsolete. However, MATLAB 5 offers replacements for nearly all of the obsolete functions. See "How to Convert Each MATLAB 4 Function" for details.
If your code identifies a data type by a process of elimination, you must rewrite it in MATLAB 5. For example, if your code checks a variable and finds that it is neither a double nor a sparse matrix, you can no longer assume that the variable must be a string.
In MATLAB 4, if one argument to a MEX-function was complex, all arguments were considered complex. This is not true in MATLAB 5. For example, consider a MEX-function myeig(A,B,C)
that calculates eigenvalues of three matrices. In MATLAB 4 if matrix A
is complex, B
and C
are assumed to be complex matrices as well. In this instance additional memory is allocated for the complex part of B
and C
, whether or not these matrices are complex. In MATLAB 5, B
and C
are assumed to be real unless otherwise specified.
In MATLAB 4, the Matrix
structure held each "character" in a string matrix as a double-precision, floating-point number. If the string flag was set, then MATLAB displayed each double-precision, floating-point number as an ASCII value.
MATLAB 5 represents each "character" in a string matrix as an mxChar
, a 16-bit unsigned integer data type. The mxArray
does not provide a string flag; if the mxArray
's class is mxCHAR_CLASS
, MATLAB treats each number in the mxArray
as an element from the current character set. Character sets are platform specific.
If your MATLAB 4 source code created string matrices by calling mxCreateString
, you do not have to recode sections that create strings. However, if your MATLAB 4 source code called mxSetString
to create string matrices, you must recode. mxSetString
is obsolete in MATLAB 5; if you used mxSetString
to create a two-dimensional string matrix, call mxCreateCharMatrixFromStrings
instead.
If your MATLAB 4 source code used something other than mxGetString
to copy string data into a C string, you must recode. As you recode, don't forget that each character in a string mxArray
is now stored as a 16-bit integer rather than as a double-precision, floating-point number.
How to Convert Each MATLAB 4 Function
This table shows each MATLAB 4 function along with a description of how to port that function to MATLAB 5.