Upgrading to Release 11 (Release 11 New Features)

Release 11 New Features

Upgrading from MATLAB 5.1 to MATLAB 5.3

This section describes compatibility issues involved in upgrading from MATLAB 5.1 to MATLAB 5.2.

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

Use of P-Code Between MATLAB Versions

You cannot use Version 5.2 P-code in a pre-5.2 P-code application. You can use pre-5.2 P-code in a Version 5.2 P-code application.

If you want to distribute an application to users who might be running a different version of MATLAB than the one in which you are writing the application, you should use M-files instead of P-code.

Colon Expressions with Floating-Point Numbers

Values produced in colon (:) expressions may vary between MATLAB 5.2 and pre-5.0 versions of MATLAB, if you are doing an exact comparison of floating-point numbers.

For floating-point numbers, you should use tolerance-based comparisons (eps), not exact comparisons. (Use exact comparisons only for integers.)

Warning When Using == with an Empty Matrix

The expression A == [] produces 0 or 1 (as it did in MATLAB 4), and MATLAB issues the following warning message when this expression is used:

Warning: X == [] is technically incorrect. Use isempty(X) instead.

This warning is issued in anticipation of future versions of MATLAB, which will return an empty matrix, [], for this expression.

Invoking the Path Editor from the Command Line

To invoke the MATLAB path editor from the command line, issue the pathtool command. In previous releases on various platforms the pathedit and editpath commands also invoked the path editor, but the command that works on all platforms for Version 5.2 is pathtool.

Frame Uicontrols and Stacking Order

Frames are opaque, not transparent, so the order you define Uicontrols is important in determining whether Uicontrols within a frame are covered by the frame or are visible. Stacking order determines the order objects are drawn: objects defined first are drawn first; objects defined later are drawn over existing objects. If you use frames to enclose objects, you must define the frames before you define the objects.

Before MATLAB 5.2, frames were always drawn below other Uicontrols on Microsoft Windows applications regardless of the order they were created.

If you use MATLAB on UNIX computers, this change does not affect you. If, however, you use MATLAB on Microsoft Windows, stacking order affects any applications that define frames after they define objects contained within the frames. To ensure that frames are drawn below other objects, either:

Revise the M-files by altering the order in which these objects are defined. Create frames before creating the objects contained in the frames.

Modify the stacking order to ensure that objects within the frames are visible. For example, these statements define a push button, a check box, and a frame, then alter the stacking order for the Figure (position vectors are defined by pbpos, cbpos, and fpos to simplify the code):

hpush  = uicontrol('Style','pushbutton','Position',pbpos);
hcheck = uicontrol('Style','checkbox','Position',cbpos);
hframe = uicontrol('Style','frame','Position',fpos);
% change stacking order to put frame on bottom
% gcf is the current figure
stackvec(1)=hpush; stackvec(2)=hcheck; stackvec(3)=hframe;
set(gcf,'Children',stackvec)

Issue a system_dependent command to force frames to be drawn below other objects. The form of this command is:

Note that the ForceFramesOnBottom string is case sensitive. Issue the command before running the application. When you issue the command, MATLAB issues a warning indicating that frames will be inserted below other objects. To suppress the warning message for just this command, include these statements in your M-file or your startup.m file:

warning off
system_dependent('ForceFramesOnBottom','on')
warning on

You should use these commands only until you have had a chance to correct the M-files. The first two solutions are preferable to this solution; this solution is provided to ease the transition for users who were not aware that the Microsoft Windows behavior was inconsistent with stacking order rules that applied to all other Handle Graphics objects.

You can turn off this behavior using this statement:

system_dependent('ForceFramesOnBottom','off')

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-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. In previous releases MATLAB did not treat these as keywords.

Matrix Assignment

In pre-5.2, for

A(:) = b

where b is a scalar or vector, the resulting type was the type of b. Starting with 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 performs a depth-first search when a method is called (this is how the method search was documented as working in pre-5.2 versions). MATLAB 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:

In MATLAB 5.2 and later, Class X's foo would be invoked.
In MATLAB 5.0 or 5.1, Class Z's foo would be invoked.

Changes to legend

The second output argument for legend is no longer m-by-2. Instead, it is a column containing line, patch, and text object handles, in no particular order.

PC-Specific Changes

Change to clc Command

In MATLAB 5.2, the clc command produces the same result as using the Edit menu item Clear Sessions. Thus, after you issue clc, you can no longer scroll back to see the previous contents of the Command Window (as you could in earlier versions of MATLAB).

However, you can use the up arrow to see the history of the commands, one at a time.

Change to cd Command

In MATLAB 5.2, if you cd from one drive to another for your working directory, the cd command does not retain any subdirectory part of the path if you cd back to the initial drive.

For example, if you first issue a cd command such as

cd C:\MyApps

and then issue

cd D:\MyMatlabDir
cd C:
pwd

you will see

C:\

In earlier versions of MATLAB, if you issued the same commands as shown above, you saw

C:\MyApps

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.


Warning:  You are attempting to call mxFree on a <class-id> array. 
The destructor for mxArrays is mxDestroyArray; please call this 
instead. MATLAB will attempt to fix the problem and continue, but 
this will result in memory faults in future releases.

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.

    mxArray *temp = mxCreateDoubleMatrix(1,1,mxREAL);
...
    mxFree(temp);  /* INCORRECT */

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:

mxDestroyArray(temp);  /* CORRECT */

Incorrectly Constructing a Cell or Structure mxArray

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

Warning.

Warning: You are attempting to use an array from another scope 
(most likely an input argument) as a member of a cell array or 
structure. You need to make a copy of the array first. MATLAB will 
attempt to fix the problem and continue, but this will result in 
memory faults in future releases.

Example That Causes Warning.

myfunction('hello')
/* myfunction is the name of your MEX-file and your code */
/* contains the following:    */

    mxArray *temp = mxCreateCellMatrix(1,1);
...
    mxSetCell(temp, 0, prhs[0]);  /* INCORRECT */

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:

mxSetCell(temp, 0, mxDuplicateArray(prhs[0]));  /* CORRECT */

Creating a Temporary mxArray with Improper Data

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

Warning.

Warning: You have attempted to point the data of an array to a 
block of memory not allocated through the MATLAB API. MATLAB will 
attempt to fix the problem and continue, but this will result in 
memory faults in future releases.

Example That Causes Warning.

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

   mxArray *temp = mxCreateDoubleMatrix(0,0,mxREAL);
   double data[5] = {1,2,3,4,5};
...
   mxSetM(temp,1); mxSetN(temp,5); mxSetPr(temp, data); 
   /* INCORRECT */

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:

    mxArray *temp = mxCreateDoubleMatrix(1,5,mxREAL);
    double data[5] = {1,2,3,4,5};
...
    memcpy(mxGetPr(temp), data, 5*sizeof(double));  /* CORRECT */

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

pr = mxCalloc(5*5, sizeof(double));
... <load data into pr>
plhs[0] = mxCreateDoubleMatrix(5,5,mxREAL);
mxSetPr(plhs[0], pr);  /* INCORRECT */

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

plhs[0] = mxCreateDoubleMatrix(5,5,mxREAL);
pr = mxGetPr(plhs[0]);
... <load data into pr>

or alternatively:

pr = mxCalloc(5*5, sizeof(double));
... <load data into pr>
plhs[0] = mxCreateDoubleMatrix(5,5,mxREAL);
mxFree(mxGetPr(plhs[0]));
mxSetPr(plhs[0], pr);

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 destroyed. This approach is consistent with other MATLAB API applications (i.e., MAT-file applications, Engine applications, and MATLAB Compiler-generated applications).

[ Previous | Next ]