MATLAB 5.2 Product Family New Features     Search    Help Desk 

Chapter 4
Upgrading to MATLAB 5.2

Migrating to MATLAB 5.2 

Roadmap for Different Migration Routes 

Toolboxes and Blocksets 

Upgrading from MATLAB 5.1 to MATLAB 5.2 

Change to clear Behavior 

try, catch, and persistent Are Now Keywords 

Matrix Assignment 

Change to Method Search Order 

API Memory Management Compatibility Issue 

Upgrading from MATLAB 5.0 to MATLAB 5.2 

Upgrading from MATLAB 4 to MATLAB 5.2 

Converting M-Files to MATLAB 5.0 

Converting MATLAB 4 External Interface Programs to
the MATLAB 5.0 Application Program Interface 

Upgrading Toolboxes and Blocksets 

Fuzzy Logic Toolbox: Updating FIS Models 

DSP Blockset: Upgrading from Version 1.0a 

Migrating to MATLAB 5.2

It is useful to introduce two terms in discussing this migration. The first step in converting your code to MATLAB 5.2 is to make it MATLAB 5.2 compatible. This involves a rather short list of possible changes that let your M-files run under MATLAB 5.2. The second step is to make it MATLAB 5.2 compliant. This involves 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.2 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 must change to make your M-files MATLAB 5.2 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.2 compliant. To help you gradually make your code compliant, MATLAB 5.2 displays warning messages when you use functions that are obsolete, even though they still work correctly.

Roadmap for Different Migration Routes

The sections of this chapter that you need to read depend on the version of MATLAB from which you are upgrading.

If You Are Upgrading to MATLAB 5.2 from...
Read These Sections ...
MATLAB 5.1
 "Upgrading from MATLAB 5.1 to MATLAB 5.2"
MATLAB 5.0
 "Upgrading from MATLAB 5.0 to MATLAB 5.2"
"Upgrading from MATLAB 5.1 to MATLAB 5.2"
MATLAB 4
 All

Toolboxes and Blocksets

The last section discusses upgrade issues for toolboxes and blocksets. Only the Signal Processing Toolbox and the DSP Blockset have any upgrade issues.

Upgrading from MATLAB 5.1 to MATLAB 5.2

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

Change to clear Behavior

The clear function does not remove an M-file from the MATLAB workspace if that M-file is locked with the mlock function, introduced in MATLAB 5.2.

Although pre-Version 5.2 code does not use mlock, if that code is modified to use mlock, clear will not behave as it did in previous versions of MATLAB (i.e., it will not be guaranteed to clear all M-files in the workspace). To unlock an M-file, use munlock.

try, catch, and persistent Are Now Keywords

You can no longer use try, catch, and persistent as variable names in MATLAB 5.2. In previous releases MATLAB did not treat these as keywords.

Matrix Assignment

In pre-Version 5.2, for

where b is a scalar or vector, the resulting type was the type of b. In MATLAB 5.2, the resulting type is the type of A. So, if A is a uint8 array to begin with, and b is a double, the result is that A is still a uint8.

This change to preserve A's type was made to ensure consistent indexing behavior.

Change to Method Search Order

When an object inherits from two different classes, MATLAB 5.2 performs a depth-first search when a method is called (this is how the method search was documented as working in previous versions). MATLAB 5.2 exhausts the search in one parent, then goes up the class hierarchy for each class from which the object inherits (from left to right, as appears in the class definition). In previous releases, MATLAB actually performed a modified breadth-first search.

In this hierarchy:

If function foo is called:

API Memory Management Compatibility Issue

To address performance issues, the internal MATLAB memory management model has been changed somewhat. These changes support future enhancements to the MEX-file API.

With this release, MATLAB now implicitly calls mxDestroyArray, the mxArray destructor, at the end of a MEX-file's execution on any mxArrays that are not returned in the left-hand side list (plhs[]). You are now warned if MATLAB detects any misconstructed or improperly destroyed mxArrays.

We highly recommend that you fix code in your MEX-files that produces any of the warnings discussed in the following sections. For additional information, see the "Memory Management" section in Chapter 3 of the Application Program Interface Guide.

The rest of this discussion describes situations in which you would receive such warning messages. The discussion of each situation includes an example and a solution.

Improperly Destroying an mxArray

You cannot use mxFree to destroy an mxArray.

Warning

Note: In MATLAB 5.2, these warnings are enabled by default for compatibility reasons. They can be disabled with the command

feature('MEXFileCompat',0)

Disabling the code that detects and fixes these error conditions may slightly improve performance, but will cause serious problems if your MEX-file actually causes any of these errors.

Example That Causes Warning

mxFree does not destroy the array object. This operation frees the structure header associated with the array, but MATLAB will still operate as if the array object needs to be destroyed. Thus MATLAB will try to destroy the array object, and in the process, attempt to free its structure header again.

Solution

Call mxDestroyArray instead:

Incorrectly Constructing a Cell or Structure mxArray

You cannot call mxSetCell or mxSetField variants with prhs[] as the member array.

Warning

Example That Causes Warning

When the MEX-file returns, MATLAB will destroy the entire cell array. Since this includes the members of the cell, this will implicitly destroy the MEX-file's input arguments. This can cause several strange results, generally having to do with the corruption of the caller's workspace, if the right-hand side argument used is a temporary array (i.e., a literal or the result of an expression).

Solution

Make a copy of the right-hand side argument with mxDuplicateArray and use that copy as the argument to mxSetCell (or mxSetField variants); for example:

Creating a Temporary mxArray with Improper Data

You cannot call mxDestroyArray on an mxArray whose data was not allocated by an API routine.

Warning

Example That Causes Warning

If you call mxSetPr, mxSetPi, mxSetData, or mxSetImagData with memory as the intended data block (second argument) that was not allocated by mxCalloc, mxMalloc, or mxRealloc, as shown below:

then when the MEX-file returns, MATLAB will attempt to free the pointer to real data and the pointer to imaginary data (if any). Thus MATLAB will attempt to free memory, in this example, from the program stack. This will cause the above warning when MATLAB attempts to reconcile its consistency checking information.

Solution

Rather than use mxSetPr to set the data pointer, instead create the mxArray with the right size and use memcpy to copy the stack data into the buffer returned by mxGetPr:

Potential Memory Leaks

Prior to Version 5.2, if you created an mxArray using one of the API creation routines and then you overwrote the pointer to the data using mxSetPr, MATLAB would still free the original memory. This is no longer the case.

For example:

will now leak 5*5*8 bytes of memory, where 8 bytes is the size of a double.

You can avoid that memory leak by changing the code:

or alternatively:

Note that the first solution is more efficient.

Similar memory leaks can also occur when using mxSetPi, mxSetData, mxSetImagData, mxSetIr, or mxSetJc. You can address this issue as shown above to avoid such memory leaks.

Recommendation: MEX-Files Should Destroy Their Own Temporary Arrays

In general, we recommend that MEX-files destroy their own temporary arrays and clean up their own temporary memory. All inconsistent mxArrays except those returned in the left-hand side list and the return from the mxGetArrayPtr may be safely destructed. This approach is consistent with other MATLAB API applications (i.e., MAT-file applications, Engine applications, and MATLAB Compiler generated applications).

Upgrading from MATLAB 5.0 to MATLAB 5.2

This table describes some changes you can make to your code to eliminate error messages and warnings due to incompatible and noncompliant statements in MATLAB 5.0 code that you are upgrading to MATLAB 5.2.

Note: If you are upgrading from MATLAB 5.0 to MATLAB 5.2, in addition to this section, you should read the previous section, called "Upgrading from MATLAB 5.1 to MATLAB 5.2."

Table 4-1: MATLAB 5.1 Language Changes  
Function
 Change
 Action
find
 find was modified for sparse row vectors. find(sparse_row) was a column in MATLAB 4 and MATLAB 5.0. In 5.1 it produces a row when the input is a row. All other cases still return columns.
 Update code.
lasterr
 In MATLAB 5.1, lasterr doesn't contain the ??? that prints out when you get an error. Some types of errors in MATLAB 5.0 erroneously contained ???.
 None required.
plot
 In MATLAB 5.0, plot incorrectly accepted arrays with more than two dimensions, but treated them as 2-D arrays. In 5.1, this causes an error.
 Do not use arrays of more than two dimensions as arguments for plot.
Set functions:
intersect,
setdiff, setxor, union, unique
 These functions now error out if the inputs aren't vectors, and you aren't using the rows flag.
 Update code if required.
size
 An empty string created within a MEX-file is now of size 0,0, consistent with the rest of MATLAB. (This change occurred with MATLAB 5.1.)
 Update code accordingly.

Upgrading from MATLAB 4 to MATLAB 5.2

MATLAB 5.0 was a major upgrade to MATLAB 4. 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.0, there were a number of changes that you need to know about in order to migrate your code from MATLAB 4 to MATLAB 5.0.

Note: In addition to this section, you should read the rest of this chapter as well if you are upgrading from MATLAB 4.0 to MATLAB 5.2.

Converting M-Files to MATLAB 5.0

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

Table 4-2: MATLAB 5.0 Language Changes  
Function
 Change
 Action
auread, auwrite
 New syntax.
 Change call to use new syntax.
bessel
functions
 The bessel functions no longer produce a table for vector arguments of the same orientation.
 For example, 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.
echo
 echo does not display multiline matrices.
 Update code.
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 an externally defined eps won't work.
Change code accordingly.
for
 for loop variable different after loop for empty loops. In
MATLAB 4:
i = 10;
for i = 1:0, %goes nowhere
end
i
produces i = 10.
In MATLAB 5.0 it produces
i = [].
 Protect the for loop with an isempty call:
i = 10;
if ~isempty(n)
 for i=1:n
 end
end
i
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).
MATLAB 4 produced a link in the workspace to an uninitialized global. It shows up in whos but exist returns 0. Do not use exist to test for the first time the global has been accessed. Use isempty.
gradient
 gradient no longer produces complex output.
 Use two outputs in the 2-D 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 3-D interpolation.
 Update code accordingly.
Automeshing
interpolation
commands
 Interpolation automeshing has changed. griddata, interp2, interp3, interpn, and bessel* now automesh if (xi,yi) or (nu,z) are vectors of different orientations. Previously they automeshed if the vectors were different size.
 When xi and yi are vectors of the same orientation but different lengths, change calls such as interp2(...,xi,yi) to interp2(...,xi,yi').
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.
max ignores NaNs.
 Use length(v) in place of max(size(v)).
min
 min ignores NaNs.
Change code if necessary.
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.

No longer accepts column vector.

 The size vector must be a row vector with integer elements.

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.
polyfit
 Second output now a structure.
 Change code to access structure component.
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.
sound
 Doesn't autoscale.
 Use soundsc.
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.
wavread, wavwrite
 New syntax.
 Change call to use new syntax.
zeros
 No longer accepts column vector.
 Size vector must be a row vector with integer elements.
Note: The following language changes do not directly apply to specific functions.

 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).
 Change code accordingly.

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.
 Change code accordingly.

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 ([]).

Indices must be integers. Strings are no longer valid indices.
 Use a(round(ind)) to get MATLAB 4 behavior.

_,^,{, and } are now interpreted, not displayed.
Use \_,\^, \{, and\}.

Concatenating a string and a double truncates the double.
 Use double to convert the string before concatenating.

Input arguments are no longer evaluated left to right.
 Evaluate input arguments before passing them to a function.

String handling difference.
In MATLAB 4
a = 32*ones(1,10);
a(1:5) = 'hello' produces 'hello'.
In MATLAB 5.1, it produces:
104 101 108 11 32 32 32 32 32.
 Initialize a to be a character array or convert it after assignment.

Using inline matrix constants and continued matrix constants inside function calls:
fun(arg1,[1 2 3
3 4 5,
5 6 6])
is a syntax error.
 Put continuation dots and semicolon after each matrix line.

Table 4-3: MATLAB 5.0 Obsolete Language Functions  
Obsolete Function
 Action
casesen
 Remove the call.
csvread, csvwrite
 Use dlmread(filename,',') and dlmwrite(filename,',').
ellipk
 Replace with ellipke.
extent
 Replace with Extent property.
figflag
 Use findobj.
finite
 Rename to isfinite. finite will continue to work in MATLAB 5.2 but will probably be removed in a later release.
fwhich
 Use which.
hthelp
 hthelp works in MATLAB 5.2, 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.2.
loadhtml
 Use helpwin or doc.
matq2ws
 Replace with assignin and evalin.
matqdlg
 Replace with assignin and evalin.
matqparse
 Replace with assignin and evalin.
matqueue
 Replace with assignin and evalin.
menulabel
 Bug in Handle Graphics is now fixed.
mexdebug
 Rename to dbmex.
ode23p
 Use ode23 with no left-hand arguments or set an output function with odeset.
polyline, polymark
 Use the line object or plot.
printmenu
 No replacement in MATLAB 5.2.
saxis
 Use soundsc.
ws2matq
 Replaced by assignin and evalin.

Table 4-4: MATLAB 5.0 Graphics Function Changes  
Function
Change
 Action
figure
 In MATLAB 4 if a figure extended past the top of the window, it was adjusted to be visible. MATLAB 5.0 performs no adjustment.
 Avoid hardcoded Figure positions. Unless you know the screen size, it is better to position the Figure by first querying the Root ScreenSize property.
get
 get(h,'currentfigure') and get(h,'currentaxes') no longer create a Figure or 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.0 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.0 defaults to a white background on all platforms. (MATLAB 4 defaulted to white background 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'.
rotate
 rotate alpha is reversed from MATLAB 4.
 If your call looked like
rotate(h,[theta phi],alpha), change to
rotate(h,[theta phi],-alpha[0 0 0]).
text
 text(S) when S is a multirow character array formerly produced one handle per row. Now it produces one multiline text handle.
 Rewrite code so that it doesn't assume a specific number of handles.
uicontrol
 The default Uicontrol text horizontal alignment is centered in MATLAB 5.0. (MATLAB 4 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.0, 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 menu bar (X Window systems only)
Note: The following change does not directly apply to a specific function.

 MATLAB 5.0 sets font size selection to match platform conventions. A MATLAB 4 font selection may be a different size in MATLAB 5.0.
 Resize font appropriately.

Table 4-5: MATLAB 5.0 Graphics Property Changes  
Property
 Object Type
 Change
 Action
AspectRatio
 Axes
 Obsolete
 Replace with
DataAspectRatio and
PlotBoxAspectRatio.
BackgroundColor
 Uimenu
 Obsolete
 Do not use.
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.
For non-normal
erasemode, MATLAB recomputes Axes limits only when you fully update the display (e.g., with a drawnow command).
 Modify code as appropriate.

Set the Axes limits (and other properties you depend upon) before using non-normal modes to create animation.
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.
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
Marker 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 Marker 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
Marker instead.
NextPlot
Axes, Figure
 Use of value 'new' is obsolete. Produces warning message.
 Use HandleVisibility to protect user interfaces from command line users.
PaletteModel
Image, Patch, Surface
 Property renamed and value of bypass removed
 Use CDataMapping
RenderLimits
 Axes
 Obsolete
 Do not use. Limits are now always accurate.
SelectionType
 Figure
 Right mouse button went from Extended in MATLAB 4 to Alternate in MATLAB 5.0.
 None required.
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',[100200300 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.
XLim, XTick
 Axes
 Values must be monotonically increasing.
 Sort the ticks:
set(gca,'xtick',
sort ([3 2 1])
XTickLabels
 Axes
 Renamed
 Use XTickLabel
YLim, YTick
 Axes
 Values must be monotonically increasing.
 Sort the ticks:
set(gca,'ytick',
sort ([3 2 1])
YTickLabels
 Axes
 Renamed
 Use YTickLabel
ZLim, ZTick
 Axes
 Values must monotonically increase.
 Sort the ticks:
set(gca,'ztick',
sort ([3 2 1])
ZTickLabels
 Axes
 Renamed
 ZTickLabel

Converting MATLAB 4 External Interface Programs to the MATLAB 5.0 Application Program Interface

MATLAB 4 External Interface programs, including MEX-files, MAT-file programs, and Engine programs may run without any modification on the MATLAB 5.0 Application Program Interface (API), or they may require modification and/or recompilation. The following pages and flowcharts describe how to determine which of these possibilities 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.0 API header files include strict prototyping of API functions and require an ANSI C compiler.

MATLAB Character Strings

MATLAB 4 and MATLAB 5.0 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.0 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 that directly manipulate strings need not be rewritten. However, to recompile these applications under MATLAB 5.0, 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, you can use the 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.0. 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.0 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, nonstring 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.0, 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 the MATLAB 4 syntax and the section later in this document on recoding for MATLAB 5.0 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.1, 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.0. 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.0. However, the M-file that builds MEX-files, mex.m, 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

MATLAB 4 MEX-files, by default, were built with no optimization flags passed to the compiler. In MATLAB 5.0 the default is to optimize MEX-files. See the MATLAB 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.0 supports MEX-file debugging from within a MATLAB session. (See the debugging sections of the MATLAB Application Program Interface Guide for more details). In addition, the mex script has been enhanced with the -argcheck switch. That switch 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.0. Note that the MAT-file format has changed between MATLAB 4 and MATLAB 5.0. 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.0 format. You can generate MATLAB 4 MAT-files from MATLAB 5.0 by specifically passing the -v4 switch to the save command.

Microsoft Windows Considerations

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

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 MATLAB 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.0.

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.0. Programs must be recompiled. MATLAB 5.0 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 Application Program Interface Guide for instructions on compiling stand-alone programs in MATLAB 5.0.

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.0 is identical to mexdebug under MATLAB 4.

See "Fortran MEX-file 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.0 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, as of MATLAB 5.0.

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.0, 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.0.

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

yields a MEX-file that MATLAB 5.0 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.0 compliance is a better strategy. See "Recoding C Code for MATLAB 5.0 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.0 equivalents. However, the resulting program will have the same restrictions as existing binary files.

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

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




.



Recoding C Code for MATLAB 5.0 Compliance

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

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

Table 4-6: Recoding MATLAB 4 Functions for MATLAB 5.0 Compliance 
MATLAB 4 Function
 MATLAB 5.0 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 5.0.
engSetEvalTimeout
 (Windows platform only.) Obsolete in 5.0.
engWinInit
 (Windows platform only.) Obsolete in 5.0.
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 doubles; MATLAB 5.0 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.0 provides no equivalent call since the mxArray data type does not contain a string flag. Use mxCreateCharMatrixFromStrings to create multidimensional string mxArrays.

Upgrading Toolboxes and Blocksets

The versions of the toolboxes and blocksets shipped with MATLAB 5.2 are compatible with the previous versions of the respective toolboxes/blocksets. However, there are a minor upgrade issues for the

The Fuzzy Logic Toolbox 2.0 includes an upgrade function to update FIS models from previous versions of the toolbox.

The DSP Blockset 2.2 is completely compatible with Version 1.0a, but there are some limitations on mixing buffer blocks from the two versions, and you will need to recompile any custom blocks that use C-MEX S-functions so that they work with Simulink 2.2.

Fuzzy Logic Toolbox: Updating FIS Models

In the Fuzzy Logic Toolbox 2.0, the Fuzzy Inference System (FIS) is represented as a MATLAB structure. A structure (instead of a flat matrix) is now the basic element in constructing a fuzzy logic system. This fundamental change in the way of representing fuzzy logic system makes many details of working with the constructed system easier.

A Fuzzy Inference System that you created with a pre-2.0 version of the Fuzzy Logic Toolbox is still usable in 2.0, if you run the convertfis function on it. The convertfis function automatically converts pre-2.0 Fuzzy Inference Systems to work with Version 2.0.

DSP Blockset: Upgrading from Version 1.0a

The DSP Blockset 2.2 is completely compatible with Version 1.0a of the blockset, and Version 2.2 blocks can be used directly in models containing Version 1.0a blocks. However, because of changes to the buffering operation in 2.2, you should avoid using 2.2 buffer blocks in the same model with 1.0a buffer blocks. If you wish to continue using the 1.0a Buffer, Complex Buffer, Unbuffer, and Complex Unbuffer blocks in a model, do not use the 2.2 version of these blocks, or the 2.2 Partial Unbuffer and Complex Partial Unbuffer blocks. If you want to use the 2.2 versions in your model, we recommend that you replace any 1.0a buffering blocks with the 2.2 versions as well.

Also note that if you have custom blocks that use C-MEX S-functions, you will need to recompile the C-MEX S-functions to work with Simulink 2.2. All of the Version 2.2 DSP Blockset C-MEX S-Functions are completely compatible with Simulink 2.2. Additionally, DSP Blockset 2.2 includes updated C-MEX S-functions for the Version 1.0a blocks that use them, so that these 1.0a blocks will continue to work with Simulink 2.2. However, the updated 1.0a C-MEX S-functions will generate warnings indicating that these functions are obsolete, and we recommend that you replace these old blocks with the 2.2 versions when convenient.


[ Previous | Help Desk | Next ]