MATLAB New Features Guide

Upgrading 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 to MATLAB 5

Language Changes
`Function`	`Change`	`Action`
`bessel`	The `bessel` functions no longer produce a table for vector arguments of the same orientation.	In `besselj(nu,x)`, specify `nu` as a row and `x` as a column to produce a table.
`case`, `otherwise`, `switch`	`case`, `otherwise`, and `switch` cannot be used as variable names.	Rename your variables.
`dialog`	`dialog.m` now creates a modal dialog.	Use the `msgbox` function instead.
`end`	extra `end` statements	Remove redundant `end` statements.
`eps`	`eps` is a function	`eps = 0` no longer redefines `eps` for other functions (it makes a local variable called `eps` in the current workspace). Functions that base their tolerance on externally defined `eps` won't work. Change code accordingly.
`global`	Undefined globals	Define globals before they are used. Always put the `global` statement at the top of the M-file (just below the help comments).
`gradient`	`gradient` no longer produces complex output.	Use two outputs in the two-dimensional case.
`input`	`input('prompt','s')` no longer outputs an initial line feed. Prompts now show up on the same line.	Update code accordingly if this causes a display problem. Add `\n` in the prompt string to force a line feed.
`interp1`	The old `interp1` syntax (`interp1(x,n)`) no longer calls `interpft`. A warning was in place in MATLAB 4.	Update code accordingly.
`interp1` now returns a row vector when given a row vector. It used to return a column vector.	Transpose the output of `interp1` to produce the MATLAB 4 result when `xi` is a row vector.
`interp1('spline')` returns `NaN's for out of range values.`	Use `spline` directly.
`interp2`	The old `interp2` syntax (`interp2(x,y,xi)`) no longer calls `interp1`. A warning was in place in MATLAB 4.	Update code accordingly.
`interp3`	The old `interp3` syntax (`interp3(z,m,n)` or `interp3(x,y,z,xi,yi)`) no longer calls `griddata`. A warning was in place in MATLAB 4. `interp3` is now three-dimensional interpolation.	Update code accordingly.
`isempty`	`A == []` and `A ~= []` as a check for an empty matrix produce warning messages.	Use `isempty(A)` or `~isempty(A)`. In a future version `A == []` will produce an empty result.
`isspace`	`isspace` only returns `true` (`1`) on strings. `isspace(32)` is `0` (it was `1` in MATLAB 4).	Wrap your calls to `isspace` with `char`.
`logical`	Some masking operations where the mask isn't defined using a logical expression now produce an out of range index error.	Wrap the subscript with a call to `logical` or use the logical expression `A~=0` to produce MATLAB 4 behavior.
Boolean indexing is no longer directly supported.	Use `logical` to create the index array.
`matlabrc`	On the PC, MATLAB no longer stores the path in `matlabrc`.	All platforms except the Macintosh now use `pathdef.m`. The Macintosh still stores its path in the MATLAB `Settings` file (usually in the `Preferences` folder).
`max`	`max(size(v))`, as a means to determine the number of elements in a vector `v`, fails when `v` is empty.	Use `length(v)` in place of `max(size(v))`.
`nargin`,`nargout`	`nargin` and `nargout` are functions.	`nargout = nargout-1` (and any similar construction) is an error. To work around this change, assign `nargin` to a local variable and increment that variable. Rename all occurrences of `nargin` to the new variable. The same holds true for all functions.
`ones`	`A(ones(size(A)))` no longer produces `A`.	This statement produces copies of the first element of `A`. Use `A(ones(size(A))~=0)` or just `A` to produce the MATLAB 4 behavior.
Functions such as `ones`, `eye`, `rand`, and `zeros` give an error if supplied with a matrix argument (such as `zeros(A)`).	Use the syntax `ones(size(A))` instead.
print	`-ocmyk` is now `-cmyk`. `-psdefcset` is now `-adobecset`. GIF format no longer supported. Texture mapped surfaces do not print with painter's algorithm.	Update code accordingly. Update code accordingly. Use alternate format. Use `-zbuffer`.
`rand`	`rand('normal')` and `rand('uniform')` no longer supported.	Use `randn` for normally distributed and `rand` for uniformly distributed random numbers.
`round`	Subscripts must be integers.	To reproduce MATLAB 4 behavior, wrap noninteger subscripts with `round()`. Strings are no longer valid subscripts (since they are not integers in the strict sense).
`slice`	`slice` no longer requires the number of columns (`ncols`) argument.	Update code accordingly.
`strcmp strncmp`	`strcmp` and `strncmp` now return `false` (`0`) when any argument is numeric. They used to perform an `isequal`.	Call `isequal` for all nonstrings you want to compare.
	`a(:) = b` where `a` doesn't exist creates an error. This used to do the same thing as `a = b(:)` when `a` didn't exist.	Either initialize `a` or use `a = b(:)` instead.
	Must use an explicitly empty matrix to delete elements of an array, as in `a(i) = []` or `a(i,:) = []`.	This syntax works for all built-in data types (including cell arrays and structures).
	The syntax `a(i) = B`, when `B` is empty, no longer deletes elements.	Use `a(i) = []` instead.
	An attempt to delete elements of an array outside its range is no longer (incorrectly) ignored.	An error is generated.
	Undefined variables	To reproduce MATLAB 4 behavior, initialize your variable to the empty matrix (`[]`) or empty string (`''`).
	Undefined outputs	To reproduce MATLAB 4 behavior, initialize your outputs to the empty matrix (`[]`).

This section describes some changes you can make to your code to eliminate error messages and warnings due to incompatible and noncompliant statements.

Language Changes
Function Change Action
bessel
The bessel functions no longer produce a table for vector arguments of the same orientation.
In besselj(nu,x), specify nu as a row and x as a column to produce a table.

case,
otherwise,
switch
case, otherwise, and switch cannot be used as variable names.
Rename your variables.

dialog
dialog.m now creates a modal dialog.
Use the msgbox function instead.

end
extra end statements
Remove redundant end statements.

eps
eps is a function
eps = 0 no longer redefines eps for other functions (it makes a local variable called eps in the current workspace). Functions that base their tolerance on externally defined eps won't work. Change code accordingly.

global
Undefined globals
Define globals before they are used. Always put the global statement at the top of the M-file (just below the help comments).

gradient
gradient no longer produces complex output.
Use two outputs in the two-dimensional case.

input
input('prompt','s') no longer outputs an initial line feed. Prompts now show up on the same line.
Update code accordingly if this causes a display problem. Add \n in the prompt string to force a line feed.

interp1
The old interp1 syntax (interp1(x,n)) no longer calls interpft. A warning was in place in MATLAB 4.
Update code accordingly.

interp1 now returns a row vector when given a row vector. It used to return a column vector.
Transpose the output of interp1 to produce the MATLAB 4 result when xi is a row vector.

interp1('spline') returns NaN's for out of range values.
Use spline directly.

interp2
The old interp2 syntax (interp2(x,y,xi)) no longer calls interp1. A warning was in place in MATLAB 4.
Update code accordingly.

interp3
The old interp3 syntax (interp3(z,m,n) or interp3(x,y,z,xi,yi)) no longer calls griddata. A warning was in place in MATLAB 4. interp3 is now three-dimensional interpolation.
Update code accordingly.

isempty
A == [] and A ~= [] as a check for an empty matrix produce warning messages.
Use isempty(A) or ~isempty(A). In a future version A == [] will produce an empty result.

isspace
isspace only returns true (1) on strings. isspace(32) is 0 (it was 1 in MATLAB 4).
Wrap your calls to isspace with char.

logical

Some masking operations where the mask isn't defined using a logical expression now produce an out of range index error.
Wrap the subscript with a call to
logical or use the logical expression A~=0 to produce MATLAB 4 behavior.

Boolean indexing is no longer directly supported.
Use logical to create the index array.

matlabrc
On the PC, MATLAB no longer stores the path in matlabrc.
All platforms except the Macintosh now use pathdef.m. The Macintosh still stores its path in the MATLAB Settings file (usually in the
Preferences folder).

max
max(size(v)), as a means to determine the number of elements in a vector v, fails when v is empty.
Use length(v) in place of max(size(v)).

nargin,nargout
nargin and nargout are functions.
nargout = nargout-1 (and any similar construction) is an error. To work around this change, assign nargin to a local variable and increment that variable. Rename all occurrences of nargin to the new variable. The same holds true for all functions.

ones
A(ones(size(A))) no longer produces A.

This statement produces copies of the first element of A. Use A(ones(size(A))~=0) or just A to produce the MATLAB 4 behavior.

Functions such as ones, eye, rand, and zeros give an error if supplied with a matrix argument (such as zeros(A)).
Use the syntax ones(size(A)) instead.

print
-ocmyk is now -cmyk.
-psdefcset is now -adobecset.
GIF format no longer supported.
Texture mapped surfaces do not print with painter's algorithm.
Update code accordingly.
Update code accordingly.
Use alternate format.
Use -zbuffer.

rand
rand('normal') and rand('uniform') no longer supported.
Use randn for normally distributed and rand for uniformly distributed random numbers.

round
Subscripts must be integers.
To reproduce MATLAB 4 behavior, wrap noninteger subscripts with round(). Strings are no longer valid subscripts (since they are not integers in the strict sense).

slice
slice no longer requires the number of columns (ncols) argument.
Update code accordingly.

strcmp strncmp
strcmp and strncmp now return false (0) when any argument is numeric. They used to perform an isequal.
Call isequal for all nonstrings you want to compare.

a(:) = b where a doesn't exist creates an error. This used to do the same thing as a = b(:) when a didn't exist.
Either initialize a or use a = b(:) instead.

Must use an explicitly empty matrix to delete elements of an array, as in a(i) = [] or
a(i,:) = [].
This syntax works for all built-in data types (including cell arrays and structures).

The syntax a(i) = B, when B is empty, no longer deletes elements.
Use a(i) = [] instead.

An attempt to delete elements of an array outside its range is no longer (incorrectly) ignored.
An error is generated.

Undefined variables
To reproduce MATLAB 4 behavior, initialize your variable to the empty matrix ([]) or empty string ('').

Undefined outputs
To reproduce MATLAB 4 behavior, initialize your outputs to the empty matrix ([]).

Obsolete Language Functions
Obsolete Function Action
csvread, csvwrite
Use dlmread(filename,',') and dlmwrite(filename,',').

ellipk
Replace with ellipke.

extent
Replaced by Extent property.

figflag
Use findobj.

finite
Rename to isfinite. finite will continue to work for MATLAB 5 but will probably be removed in a later release.

fwhich
Use which.

hthelp
hthelp works in MATLAB 5, but will not be further developed or supported.Use helpwin .

htpp
Use helpwin .

inquire
Use set and get to obtain the current state of an object or of MATLAB.

inverf
Rename to erfinv.

isdir
Use dir.

layout
No replacement in MATLAB 5.

loadhtml
Use helpwin or doc.

matq2ws
Replaced by assignin and evalin.

matqdlg
Replaced by assignin and evalin.

matqparse
Replaced by assignin and evalin.

matqueue
Replaced by assignin and evalin.

menulabel
Bug in Handle Graphics is now fixed.

mexdebug
Rename to dbmex.

ode23p
Use ode23 with no lefthand arguments or set an output function with odeset.

polyline, polymark
Use the line object or plot.

printmenu
No replacement in MATLAB 5.

saxis
Use soundsc.

ws2matq
Replaced by assignin and evalin.

Obsolete Language Functions
`Obsolete Function`	`Action`
`csvread, csvwrite`	Use `dlmread(filename,',')` and `dlmwrite(filename,',').`
`ellipk`	Replace with `ellipke`.
`extent`	Replaced by Extent property.
`figflag`	Use `findobj.`
`finite`	Rename to `isfinite`. `finite` will continue to work for MATLAB 5 but will probably be removed in a later release.
`fwhich`	Use `which`.
`hthelp`	`hthelp` works in MATLAB 5, but will not be further developed or supported.Use `helpwin` .
`htpp`	Use `helpwin` .
`inquire`	Use `set` and `get` to obtain the current state of an object or of MATLAB.
`inverf`	Rename to `erfinv.`
`isdir`	Use `dir`.
`layout`	No replacement in MATLAB 5.
`loadhtml`	Use `helpwin` or `doc`.
`matq2ws`	Replaced by `assignin` and `evalin`.
`matqdlg`	Replaced by `assignin` and `evalin`.
`matqparse`	Replaced by `assignin` and `evalin`.
`matqueue`	Replaced by `assignin` and `evalin`.
`menulabel`	Bug in Handle Graphics is now fixed.
`mexdebug`	Rename to `dbmex.`
`ode23p`	Use `ode23` with no lefthand arguments or set an output function with `odeset`.
`polyline, polymark`	Use the `line` object o`r` `plo`t.
`printmenu`	No replacement in MATLAB 5.
`saxis`	Use `soundsc`.
`ws2matq`	Replaced by `assignin` and `evalin`.

Graphics Function Changes
`Function`	`Change`	`Action`
`get`	`get(h,'currentfigure')` and `get(h,'currentaxes')` no longer create an Axes if one doesn't exist. They return `[]` in that case.	`gcf` and `gca` always return a valid handle. Use `gcf` and `gca` instead of the `get` function in this context.
	In MATLAB 4 you could determine if a graphics object had a default value set by passing its handle in a query like `get(gca,'DefaultAxesColor')`.	In MATLAB 5 make the query on the object's ancestor, e.g.: `get(gcf,'DefaultAxesColor')` or `get(0,'DefaultAxesColor')`
`plot`	MATLAB 4 plots may have elements that are the wrong color.	MATLAB 5 defaults to a white background on all platforms. (MATLAB 4 defaulted to white on the Macintosh and black everywhere else.) Use `colordef` to control your color defaults. Typically, you will put a call to `colordef` in `startup.m` . To get the MATLAB 4 defaults, use `colordef none`.
	`plot` line styles `c1` through `c15` and `i` are no longer supported	Use a 1-by-3 RGB ColorSpec instead. `i` is the same as `get(gca,'color')` or `get(gcf,'color')` when the Axes color is `'none'`.
`uicontrol`	The default uicontrol text horizontal alignment is centered in MATLAB 5. (In MATLAB 4 we used to left align text and ignore the alignment property.)	Explicitly set the horizontal alignment when you create Uicontrol Text objects.
	In MATLAB 4, Uicontrols of style `'edit'` executed their callback routine whenever you moved the pointer out of the edit box. In MATLAB 5, edit controls execute their callbacks after you perform a specific action.	The callback is called when: Return key is pressed (single-line edits only) Focus is moved out of the edit by: clicking elsewhere in the Figure (on another Uicontrol or on another graphical object) clicking in another Figure clicking on the menubar (X Windows only)

Graphics Property Changes
Property Object Type Change Action
AspectRatio
Axes
Obsolete
Replace with
DataAspectRatio and
PlotBoxAspectRatio.

BackgroundColor
Uimenu
Obsolete
Do not use.

CDataScaling (MATLAB 5 Beta property)
Image, Patch, Surface
Renamed
CDataMapping

CurrentMenu
Figure
Becoming obsolete. No warning message produced.
Replace with the function gcbo.

EraseMode
Image, Line, Patch,
Surface, Text
Now use xor against the Axes color rather than the Figure color.
Modify code as appropriate.

ExpFontAngle
Axes, Text
Obsolete
Do not use.

ExpFontName
Axes, Text
Obsolete
Do not use.

ExpFontSize
Axes, Text
Obsolete
Do not use.

ExpFontStrikeThrough
Axes, Text
Obsolete
Do not use.

ExpFontUnderline
Axes, Text
Obsolete
Do not use.

ExpFontUnits
Axes, Text
Obsolete
Do not use.

ExpFontWeight
Axes, Text
Obsolete
Do not use.

FontStrikeThrough
Axes, Text
Obsolete
Do not use.

FontUnderline
Axes, Text
Obsolete
Do not use.

HiddenHandle
(MATLAB 5 Beta property)
All graphics objects
Renamed
HandleVisibility

LineStyle
Line, Patch, Surface
Setting the LineStyle property to a marker value (such as '+') now produces a warning.
Setting the marker style of a line now affects the
MarkerStyle property instead of the
LineStyle property. Although you will be able to set a line marker using the LineStyle property (with a warning), you will not be able to get marker style information from
LineStyle.
Set the MarkerStyle property instead. Note that plot will continue to take line-color marker line styles.
If your code relies on markers in the
LineStyle, you'll have to change it to use the
MarkerStyle instead.

Mode
(MATLAB 5 Beta property)
Light
Renamed
Style

NextPlot
Axes, Figure
Use of value 'new' is obsolete. Produces warning message.
Use HandleVisibility to protect UIs from command line users.

PaletteMode
Image, Patch, Surface
Renamed
CDataMapping

ProjectionType
(MATLAB 5 Beta property)
Axes
Renamed
Projection

RenderLimits
Axes
Obsolete
Do not use. Limits are now always accurate.

Units
Axes, Figure, Text, Uicontrol
Units/Position is always order dependent for all objects. In MATLAB 4, it was inconsistent.
The Units property should precede any properties that depend upon it. A command such as axes('position',[100200 300 100],'units', 'pixels') is not the same asaxes('units','pixels, 'position',[100 200 300 100]). In the first case the numbers are interpreted in normalized coordinates.

WindowID
Figure
Possibly becoming obsolete.
May be removed in a future release.

XLoc2D (MATLAB 5 Beta property)
Axes
Renamed
XAxisLocation

XTickLabels
Axes
Renamed
XTickLabel

YLoc2D (MATLAB 5 Beta property)
Axes
Renamed
YAxisLocation

YTickLabels
Axes
Renamed
YTickLabel

ZTickLabels
Axes
Renamed
ZTickLabel

Graphics Property Changes
`Property`	`Object Type`	`Change`	`Action`
`AspectRatio`	`Axes`	Obsolete	Replace with `DataAspectRatio` and `PlotBoxAspectRatio`.
`BackgroundColor`	`Uimenu`	Obsolete	Do not use.
`CDataScaling (MATLAB 5 Beta property)`	`Image, Patch, Surface`	Renamed	`CDataMapping`
`CurrentMenu`	`Figure`	Becoming obsolete. No warning message produced.	Replace with the function `gcbo`.
`EraseMode`	Image, Line, Patch, Surface, Text	Now use `xor` against the Axes color rather than the Figure color.	Modify code as appropriate.
`ExpFontAngle`	`Axes, Text`	Obsolete	Do not use.
`ExpFontName`	`Axes, Text`	Obsolete	Do not use.
`ExpFontSize`	`Axes, Text`	Obsolete	Do not use.
`ExpFontStrikeThrough`	`Axes, Text`	Obsolete	Do not use.
`ExpFontUnderline`	`Axes, Text`	Obsolete	Do not use.
`ExpFontUnits`	`Axes, Text`	Obsolete	Do not use.
`ExpFontWeight`	`Axes, Text`	Obsolete	Do not use.
`FontStrikeThrough`	`Axes, Text`	Obsolete	Do not use.
`FontUnderline`	`Axes, Text`	Obsolete	Do not use.
`HiddenHandle` `(MATLAB 5 Beta property)`	`All graphics objects`	Renamed	`HandleVisibility`
`LineStyle`	Line, Patch, Surface	Setting the `LineStyle` property to a marker value (such as `'+'`) now produces a warning. Setting the marker style of a line now affects the `MarkerStyle` property instead of the `LineStyle` property. Although you will be able to set a line marker using the `LineStyle` property (with a warning), you will not be able to get marker style information from `LineStyle`.	Set the `MarkerStyle` property instead. Note that `plot` will continue to take line-color marker line styles. If your code relies on markers in the `LineStyle`, you'll have to change it to use the `MarkerStyle` instead.
Mode (MATLAB 5 Beta property)	Light	Renamed	Style
NextPlot	Axes, Figure	Use of value 'new' is obsolete. Produces warning message.	Use HandleVisibility to protect UIs from command line users.
PaletteMode	`Image, Patch, Surface`	Renamed	`CDataMapping`
`ProjectionType` `(MATLAB 5 Beta property)`	`Axes`	Renamed	Projection
`RenderLimits`	`Axes`	Obsolete	Do not use. Limits are now always accurate.
`Units`	Axes, Figure, Text, Uicontrol	Units/Position is always order dependent for all objects. In MATLAB 4, it was inconsistent.	The Units property should precede any properties that depend upon it. A command such as `axes('position',[100200 300 100],'units', 'pixels')` is not the same as`axes('units','pixels, 'position',[100 200 300 100])`. In the first case the numbers are interpreted in normalized coordinates.
WindowID	Figure	Possibly becoming obsolete.	May be removed in a future release.
`XLoc2D (MATLAB 5 Beta property)`	`Axes`	Renamed	`XAxisLocation`
`XTickLabels`	`Axes`	Renamed	XTickLabel
`YLoc2D (MATLAB 5 Beta property)`	`Axes`	Renamed	`YAxisLocation`
`YTickLabels`	`Axes`	Renamed	YTickLabel
`ZTickLabels`	Axes	Renamed	`ZTickLabel`

Converting MATLAB 4 External Interface Programs to the MATLAB 5 Application Program Interface (API)

MATLAB 4 External Interface programs, including MEX-files, MAT-file programs, and Engine programs may run without any modification on
MATLAB 5, or they may require modification and/or recompilation. The following pages and flowcharts describe how to determine which of these possibilites applies in your situation and how to choose the appropriate conversion technique.

General Considerations

Non-ANSI C Compilers

MATLAB 4 let you compile External Interface programs with non-ANSI C compilers. MATLAB 5 API header files include strict prototyping of API functions and require an ANSI C compiler.

MATLAB Character Strings

MATLAB 4 and MATLAB 5 represent string data in different ways. MATLAB 4 supported only one data type. All data was represented as double-precision, floating-point numbers, even individual characters in a string array. A numerical array and a character array differed only by how MATLAB displayed these values. MATLAB 5 represents each "character" in a string array as an mxChar, a 16-bit unsigned integer data type. If the mxArray's class is mxCHAR_CLASS, the API treats each number in the mxArray as an element from the current character set. Character sets are platform specific.

External Interface programs that call the API routines mxGetString() and mxCreateString() to manipulate strings continue to work. All MEX-files that directly manipulate strings must be rewritten. MAT-file and Engine applications which directly manipulate strings need not be rewritten. However, to recompile these applications under MATLAB 5, any code that directly manipulates strings must be rewritten. We highly recommend that you use the API string access and creation routines to do this. To help in this endeavor, we have added a new C routine, mxCreateCharMatrixFromStrings(), in addition to mxGetString() and mxCreateString(), to make it easy to create two-dimensional string matrices.

MEX-File Argument Complexification

In MATLAB 4, if one argument to a MEX-function was complex, all arguments were passed as 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, and initialized with zero values.

MATLAB 5 does not allocate this memory for you. If your MEX-file assumes argument complexification, you will have to rewrite your MEX-file. Each argument to a MEX-function needs to be tested with mxIsComplex() to guarantee that an argument indeed has a complex component.

Type Imputation by Process of Elimination

In MATLAB 4 the only way to determine if a matrix was a full, non-string matrix was by a process of elimination. For example, if your code checked a variable and found that it was a full matrix (nonsparse), and was not a string, you could also assume that the variable was double-precision, floating-point and two-dimensional. In MATLAB 5, with the addition of several new data types and support for multidimensional data, this assumption is no longer valid. mxIs* routines and mxGetNumberOfDimensions() have been added to the C interface so that now you can explicitly check arguments for specific data types and shapes. mxIsDouble(), which always returned 1 in MATLAB 4, now correctly returns 1 only if the mxArray is of type double precision floating point.
mxIsDouble() is available in C as well as Fortran. mxGetN() returns the total number of elements in dimensions 2-n, and therefore works correctly with multidimensional as well as two dimensional arguments.

Version 3.5 MEX-Files

MEX-files generated under MATLAB 4 using the -v3.5 switch to the cmex or fmex script are no longer supported and must be rewritten. Refer to both the MATLAB 4 External Interface Guide for information on upgrading to MATLAB 4 syntax and the section in this document on recoding for MATLAB 5 compliance.

SIMULINK

By design, SIMULINK S-functions written in C must be recompiled under the latest version of SIMULINK. The code is source compatible, but the binary must be recompiled. If you attempt to run a SIMULINK 1.3 C S -function under SIMULINK 2.0, you get an appropriate warning message. SIMULINK S-functions written in Fortran do not have this restriction.

Fortran MEX-File Considerations

The MATLAB Fortran API has not changed from MATLAB 4 to MATLAB 5. However, Fortran mex users on Windows, 68K Macintosh and the SUN4 must recompile their applications, using the mex script for programs that call mxCreateString() or mxGetString(). Only these platforms, which statically link in the Fortran interface, are affected. No recompilation is required on other platforms.

Rebuilding MEX-Files Loaded in Memory

In MATLAB 4, on Windows and UNIX, you could execute cmex or fmex from within MATLAB by using the ! command or execute in another window. These methods are no longer supported with MATLAB 5. However, the M-file, mex.m, that builds MEX files is available on all platforms and can safely rebuild loaded MEX files by unloading them before proceeding with the build. The interface provided by the M-file is identical to the external mex script.

Default MEX-File Optimization

In MATLAB 4 MEX-files by default were built with no optimization flags passed to the compiler. In MATLAB 5 the default is to optimize MEX-files. See the MATLAB 5 Application Program Interface Guide for more information.

Debugging MEX-Files

The -debug switch to cmex/fmex is no longer supported. Instead, on all platforms, MATLAB 5 supports MEX-file debugging from within a MATLAB session. (See the debugging sections of the Application Program Interface Guide for more details). In addition, the mex script has been enhanced with the -argcheck switch that provides a way for C mex users to generate code to check input and output arguments at runtime and issue appropriate error messages if invalid data is detected.

MAT-File External Applications

MAT-file external applications built under MATLAB 4 will continue to work under MATLAB 5. Note that the MAT-file format has changed between MATLAB 4 and MATLAB 5. Although MATLAB will be able to read MATLAB 4 MAT-files generated by a stand-alone program, stand-alone programs will not be able to read MAT-files in a MATLAB 5 format. You can generate MATLAB 4 MAT-files from MATLAB 5 by specifically passing the -v4 switch to the save command.

Windows Considerations

MEX-files are generated under MATLAB 5 as 32-bit DLLs. The cmex and fmex batch files have been superseded by mex (a PERL script) and a set of compilerspecific option files. These compilers are fully supported for creating MEX or stand-alone applications through MathWorks-supplied option files:

Watcom C
Microsoft Visual C++
Borland C

Microsoft Fortran, currently the only supported Fortran compiler, is supported for MEX applications only. You will not be able simply to recompile your MATLAB 4 Fortran MEX-file source with this new compiler. See "Creating Fortran MEX-files" in the Application Program Interface Guide for further information.

NDP Fortran, previously supported under MATLAB 4, is not supported in this release.

16-bit DLL MEX-files are no longer supported and cannot be generated. Existing MATLAB 4 REX MEX-files are usable but cannot be created under MATLAB 5.

See "Fortran MEX-file Considerations" above for Windows-specific restrictions on creating and accessing MATLAB character strings.

MATLAB 4 C language Engine binaries will not run with MATLAB 5. Programs must be recompiled. MATLAB 5 data types are currently not supported on the PC from an Engine program. There is currently no support for Fortran Engine or MAT-file programs.

See the MATLAB 5 Application Program Interface Guide for instructions on compiling stand-alone programs in MATLAB 5.

UNIX Considerations

The cmex and fmex Bourne shell scripts for building MEX-files have been superseded by mex, also a Bourne shell script, that sources an options file,
mexopts.sh for all platform compiler-specific information. The options file contains all the pertinent compiler and linker switches for building ANSI C and Fortran MEX-file applications. The .mexrc.sh file is no longer supported and must be converted to the new format. The mexdebug MATLAB command that allows UNIX users to debug their MEX-files while MATLAB is running has been changed to dbmex. The behavior of dbmex under MATLAB 5 is identical to mexdebug under MATLAB 4.

See "Fortran Considerations" above for SUN4-specific restrictions on creating and accessing MATLAB character strings.

You can use your existing UNIX Engine and MAT-file binary files unmodified; no recompilation is necessary. Note that MATLAB 4 Engine programs have no access to new MATLAB 5 data types. If you try to invoke
engGetMatrix(ep,my_variable), and my_variable is a cell array, structure array, object, etc., the operation automatically fails.

Macintosh Considerations

The Absoft MacFortran and Symantec Think C compilers are no longer supported.

MEX-files built under MATLAB 4 with MPW C on the 68K Macintosh that call the following I/O routines must be recompiled: putc(), getc(), ferror(), feof(), clearerr().These exist as macros in MPW's stdio.h. In MATLAB 5, these functions have been reimplemented as function callbacks to MATLAB.

See "Fortran MEX-file Considerations" above for 68K Macintosh-specific restrictions on creating and accessing MATLAB character strings.

VMS Considerations

MEX-files compiled for MATLAB 4 on the VMS platform are not binary compatible. You must regenerate these files from source code before using them with MATLAB 5.

Conversion

Rebuilding MEX-Files

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 define a macro V4_COMPAT that supports MATLAB 4 syntax and function calls. Therefore, any ANSI 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.c

yields 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.

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. See "Recoding for MATLAB 5 Compliance" below.

Rebuilding Stand-Alone MAT-File and Engine Programs

If your source code is ANSI compliant, you can recompile your source without modification by using the compiler flag -DV4_COMPAT. This allows you to avoid recoding, such as rewriting obsolete function calls as their MATLAB 5 equivalents. However, the resulting program will have the same restrictions as existing binary files.

See the MATLAB 5 Application Program Interface Guide for instructions on compiling stand-alone programs in MATLAB 5.

MEX-file Conversion Flowcharts

The flowcharts below help you determine what steps you should take to run your MATLAB 4 MEX-files under MATLAB 5

Recoding for MATLAB 5 Compliance

Recoding your MATLAB 4 C code for MATLAB 5 compliance involves:

Rewriting any non-ANSI C code as ANSI C code. (For details, see an ANSI C book.)
Changing all 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);

Rewriting all function prototypes.
The function prototype of almost every MATLAB 4 function is different in MATLAB 5. The two primary prototype changes are
- All Matrix arguments are now mxArray arguments.
- Pointers to read only data are now declared as const *.
For MEX-files, rewriting mexFunction to take a constant mxArray * as a fourth argument.
Changing 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);
to create an m-by-n sparse matrix with nzmax nonzero real elements. In MATLAB 5, the correct syntax for this same function is:
mxCreateSparse(m,n,nzmax,mxREAL);

Translating obsolete function calls into their MATLAB 5 replacements.
A number of functions have become obsolete. However, MATLAB 5 offers replacements for nearly all obsolete functions.
Handling MATLAB 5 new data types.
You should explicitly check the data type of your input arguments to ensure that you have what you want.

Table 2-5 lists MATLAB 4 External Interface functions along with a description of how to recode those functions to work with MATLAB 5.

Recoding MATLAB 4 Functions for MATLAB 5 Compliance
`MATLAB 4 Function`	`MATLAB 5 Replacement`
`engGetMatrix`	`engGetArray`
`engGetFull`	`engGetArray` followed by calls to the appropriate `mx*` routines
`engPutMatrix`	`engPutArray`
`engPutFull`	`mxCreateDoubleMatrix` followed by `engPutArray`
`engSetEvalCallback`	Windows platform only. Obsolete in MATLAB 5.
`engSetEvalTimeout`	Windows platform only. Obsolete in MATLAB 5.
`engWinInit`	Windows platform only. Obsolete in MATLAB 5.
`matGetMatrix`	`matGetArray`
`matGetNextMatrix`	`matGetNextArray`
`matGetFull`	`matGetArray` followed by calls to the appropriate `mx*` routines
`matPutMatrix`	`matPutArray`
`matPutFull`	`mxCreateDoubleMatrix` followed by `matPutArray`
`mexAtExit`	No change
`mexCallMATLAB`	Second and fourth arguments are `mxArray *`
`mexErrMsgTxt`	No change
`mexEvalString`	No change
`mexFunction`	Second and fourth arguments are `mxArray *` . Fourth argument is a `const`.
`mexGetEps`	Obsolete; call `mxGetEps` instead
`mexGetFull`	Obsolete; call this sequence instead: `mexGetArray(array_ptr, "caller"); name = mxGetName(array_ptr); m = mxGetM(array_ptr); n = mxGetM(array_ptr); pr = mxGetPr(array_ptr); pi = mxGetPi(array_ptr);`
`mexGetGlobal`	Obsolete; call `mexGetArrayPtr` instead, setting the second argument to `"global".` Note: it is better programming practice to call`mexGetArray(,"global");`
`mexGetInf`	Obsolete; call `mxGetInf` instead
`mexGetMatrix`	Call `mexGetArray(name,"caller");`
`mexGetMatrixPtr`	Call `mexGetArrayPtr(name,"caller");`
`mexGetNaN`	Obsolete; call `mxGetNaN` instead.
`mexIsFinite`	Obsolete; call `mxIsFinite` instead.
`mexIsInf`	Obsolete; call `mxIsInf` instead.
`mexIsNaN`	Obsolete; call `mxIsNaN` instead.
`mexPrintf`	No change
`mexPutFull`	Obsolete; call this sequence instead: `mxArray parray;` `int retval;` `parray = mxCreateDouble(0,0,0);` `if(parray == (mxArray)0) return(1);` `mxSetM(parray,m);` `mxSetN(parray,n);` `mxSetPr(parray,pr);` `mxSetPi(parray,pi);` `mxSetName(parray,name);` `retval = mxPutArray(parray,"caller");` `mxFree(parray);` `return(retval);`
`mexPutMatrix`	Obsolete; call `mexPutArray` instead.
`mexSetTrapFlag`	No change
`mxCalloc`	No change
`mxCreateFull`	Obsolete; call `mxCreateDoubleMatrix` instead.
`mxCreateSparse`	Returns `mxArray *.`
`mxCreateString`	Returns `mxArray *.`
`mxFree`	No change
`mxFreeMatrix`	Obsolete; call `mxDestroyArray` instead.
`mxGetIr`	First argument is `mxArray *.`
`mxGetJc`	First argument is `mxArray *.`
`mxGetM`	First argument is `mxArray` *.
`mxGetN`	First argument is `mxArray *.`
`mxGetName`	First argument is `mxArray *.`
`mxGetNzmax`	First argument is `mxArray *.`
`mxGetPi`	First argument is `mxArray *.`
`mxGetPr`	First argument is `mxArray *.`
`mxGetScalar`	First argument is `mxArray *.`
`mxGetString`	First argument is `mxArray *.`
`mxIsComplex`	First argument is `mxArray *.`
`mxIsDouble`	First argument is `mxArray *.` Note that MATLAB 4 stores all data as `double`s; MATLAB 5 stores data in a variety of integer and real formats.
`mxIsFull`	Obsolete; call `!mxIsSparse` instead.
`mxIsNumeric`	First argument is `mxArray *.`
`mxIsSparse`	First argument is `mxArray *.`
`mxIsString`	Obsolete; call `mxIsChar` instead.
`mxSetIr`	First argument is `mxArray *.`
`mxSetJc`	First argument is `mxArray *.`
`mxSetM`	First argument is `mxArray *.`
`mxSetN`	First argument is `mxArray *.`
`mxSetName`	First argument is `mxArray *.`
`mxSetNzmax`	First argument is `mxArray *.`
`mxSetPi`	First argument is `mxArray *.`
`mxSetPr`	First argument is `mxArray *.`
`mxSetString`	Obsolete; MATLAB 5 provides no equivalent call since the `mxArray` data type does not contain a string flag. Use `mxCreateCharMatrixFromStrings` to create multidimensional string `mxArray`s.

[ Previous | Help Desk | Next ]