Programming Upgrade Issues :: (MATLAB Release Notes)

MATLAB Release Notes

Programming Upgrade Issues

The issues involved in upgrading from MATLAB 6.5 to MATLAB 7.0, in terms of programming features, are discussed below.

Changes You Should Note

Other Programming Issues

Crashes in dbstop Have Been Resolved

In previous versions, a MATLAB session would terminate prematurely when attempting to execute certain P-code files if you had set a debugger breakpoint in the function represented by that file. For example, an attempt to run Guide would terminate your MATLAB session if you had used the dbstop function to set a breakpoint in the corresponding M-file:

```
dbstop in guide
guide
```

This bug has been fixed in this release enabling you to debug these files successfully.

Making Release 14 MAT-files Readable in Earlier Versions

Caution Release 14 MATLAB writes character and figure data to MAT-files using Unicode encoding by default. Unicode encoded MAT-files are not readable by earlier versions of MATLAB. Thus, if you save data to a MAT-file using MATLAB Release 14, and you intend to load this MAT-file into an earlier release of MATLAB, you must override the Unicode default during the save, as explained in this section.

In Release 14, MATLAB uses Unicode character data encoding in mxArrays and mxArray storage in MAT-files. This is now the default encoding used by MATLAB when writing to MAT-files with the save and hgsave functions or with the MAT-file external interface functions.

You can override the default encoding by using the -v6 switch with save and hgsave:

```
save filename -v6
hgsave filename -v6
```

or, when saving with MAT functions, by setting the mode to "wL" on the matOpen operation:

```
matOpen(filename, "wL");
```

MAT-Files Generated By Release 14 Beta2 Must Be Reformatted

Any MAT-files that you created with Release 14 Beta 2 were written using an internal format that is no longer supported by MATLAB. As a result, if you need to import data from these files using any release besides Release 14 Beta 2, you must first regenerate the files as described in this section. You cannot read these files using other releases of MATLAB 7.0, and attempting to read them with MATLAB 6.5 or 6.5.1 will corrupt memory.

There are two ways in which you can regenerate your MAT-file:

If you want to use the MAT-file with earlier versions of MATLAB, regenerate the file using the local character set for your system. To do this, run MATLAB R14 prerelease or MATLAB R14 Beta 2, load the MAT-file, and rewrite the file using the command

```
save filename -v6
```

If you want to use the MAT-file with R14 LCS or later, regenerate the file using Unicode encoding. To do this, run MATLAB R14 prerelease, load the MAT-file, and rewrite it using the following command that uses the -unicode default.

```
save filename
```

Caution The final R14 release of MATLAB does not allow you to import a MAT-file written with Release 14 Beta 2. You will get an error if you attempt to do this. To use a Beta 2 MAT-file with Release 14, you must first reformat the file with MATLAB R14 prerelease as described above.

If you no longer have access to Release 14 Beta2 or the R14 prerelease, then you must regenerate the data and save it again.

Reserved Bytes in MAT-File Header

In previous releases of MATLAB, the last 4 bytes of the 128-byte MAT-file header were reserved for use by the MathWorks. In Release 14, the last 12 bytes of this header are reserved. See the PDF file "MAT-File Format" for more information.

New Features for Nondouble Data Types

The section New Nondouble Mathematics Features describes new features affecting the nondouble (single and integer) data types. These changes affect single and integer arithmetic operations, and also conversion of single and double data types to integers.

Case-Sensitivity in Function and Directory Names

Prior to this release, filenames for MATLAB functions and Simulink models (M, P, MEX, DLL, and MDL files), and also directory names were interpreted somewhat differently by MATLAB with regards to case sensitivity, depending upon which platform you were running on. Specifically, earlier versions of MATLAB handled these names with case sensitivity on UNIX, but without case sensitivity on Windows.

This release addresses the issue of case sensitivity in an effort to make MATLAB consistent across all supported platforms. By removing these differences, we hope to make it easier for MATLAB users to write platform independent code.

This change is described under the following topics:

Case Sensitivity in MATLAB 6 and Earlier

There are several rules regarding case sensitivity that were already consistent across all platforms in MATLAB 6, and remain in effect on all platforms in MATLAB 7. MATLAB interprets each of the following with case sensitivity on both Windows and UNIX:

Function names that correspond to MATLAB built-ins
M-file subfunction names
The names of functions imported from another language environment, such as Java or COM

UNIX. On all UNIX platforms, including the new implementation on MacIntosh, all function, model, and directory names were case sensitive and required an exact match. This rule remains true for UNIX systems in MATLAB 7.

Windows. On Windows platforms, MATLAB 6 obeys the following rules. These rules are changing in MATLAB 7:

Function and model names were not case sensitive.
Directory names, including MATLAB class directory names (e.g., @MyClass) and private directory names (e.g., prIVAte) were not case sensitive.

Case Sensitivity in MATLAB 7

MATLAB 7 removes the platform specific behaviors by adopting its UNIX case sensitivity rules on Windows systems. MATLAB running on Windows now gives preference to an exact (case sensitive) name match, but falls back to an inexact (case insensitive) match when no exact match can be found.

New Warnings Related to Case Sensitivity. Whenever MATLAB 7 detects a potential naming conflict related to case sensitivity, it issues a warning. If you get one of these warnings when running a MATLAB program, you may want to modify the related code to eliminate the warning, or you may wish to simply disable the warning.

Comparing Case Sensitivity in MATLAB 6 and MATLAB 7

There are four main conditions under which MATLAB 7 interprets directory or function names differently in regards to case sensitivity:

Two Files of the Same Name. Consider the situation in which there are two or more directories on the MATLAB path that contain a function or model file of the same name. The names of these M-files differ only in letter case:

H:\released\myTestFun.m
K:\under_test\mytestfun.m

Of these two directories, H:\released is closer to the beginning of the MATLAB path and thus has priority over the other:

```
path = H:\released; K:\under_test; ...
```

On Windows Platforms --

In MATLAB 6, executing the function mytestfun invokes H:\released\myTestFun.m.
In MATLAB 7, executing the function mytestfun invokes K:\under_test\mytestfun.m and also displays the following warning:

Function call mytestfun invokes K:\under_test\mytestfun.m 
however, function H:\released\myTestFun.m, that differs only in 
case, precedes it on the path.

On UNIX Platforms --

MATLAB 7 does the same as on Windows, except that the warning message is disabled by default.

Two Method Files of the Same Name. In this case, there are two M-files of the same name that implement methods of a MATLAB base class and one of its subclasses:

@baseclass/my_method.m
@subclass/My_Method.m

On Windows Platforms --

In MATLAB 6, the command my_method(subclass) invokes @subclass/My_Method.
In MATLAB 7, the same command invokes @baseclass/my_method because it is an exact match.

On UNIX Platforms --

MATLAB 7 does the same as on Windows.

One File with an Inexact Match. Another situation that MATLAB now handles differently involves just one function or model file that matches the function being called:

```
H:\released\myTestFun.m
```

However, the name of this M-file does not match the called function (mytestfun) in letter case.

On Windows Platforms --

In MATLAB 6, calling the function mytestfun invokes H:\released\myTestFun.m.
In MATLAB 7, calling the function mytestfun invokes the same M-file but also displays the following warning:

Function call mytestfun invokes inexact match 
H:\released\myTestFun.m.

On UNIX Platforms --

In MATLAB 6, calling the function mytestfun results in an error.
In MATLAB 7, calling mytestfun invokes H:\released/myTestFun.m and generates the following warning:

Function call mytestfun invokes inexact match 
H:/released/myTestFun.m.

Private Directory Names. Private functions must reside in a directory named private that is one level down from the directory of any calling function. As of this release, the directory name private is case sensitive on Windows as it has always been on UNIX.

On Windows Platforms --

In MATLAB 6, calling function myprivfun in an environment where only a subdirectory named \PriVAte contains the M-file myprivfun.m invokes \PriVAte\myprivfun without displaying a warning.
MATLAB 7 does the same as MATLAB 6, except that it also displays the following warning:

Wrong case spelling of 'private' as a directory name in 
\released\PriVate\myprivfun.m.

On UNIX Platforms --

In MATLAB 6, calling function myprivfun in an environment where only a subdirectory named \PriVAte contains the M-file myprivfun.m results in an error.
In MATLAB 7, calling myprivfun in this same environment invokes /PrivATe/myprivfun and also displays the following warning:

Wrong case spelling of 'private' as a directory name in 
/released/PriVate/myprivfun.m.

Turning Off Warnings Caused by Case Mismatch

You can disable most warnings caused by case mismatch with the following command:

warning off MATLAB:dispatcher:InexactMatch

To disable this warning for all of your MATLAB sessions, add this command to your startup.m or matlabrc.m file.

If you continue to get case sensitivity warnings after entering this command, you can disable a wider range of warnings with the following command:

warning off ...
  MATLAB:dispatcher:CaseInsensitiveFunctionPrecedesExactMatch

Note This latter warning alerts you when, for case sensitivity reasons, MATLAB may have selected a different M-file from the one you had intended to run. It is recommended that you leave this warning enabled.

Differences Between Built-Ins and M-Functions Removed

MATLAB implements many of its core functions as built-ins. In previous releases of MATLAB, there have been several significant differences between the way MATLAB handles built-in and M-file functions. As of this release, MATLAB handles both types of functions the same. This change affects the following:

Function Dispatching

MATLAB now dispatches both built-in and M-file functions according to the same precedence rules, (see Function Precedence Order in the Programming and Data Types section of the MATLAB documentation). In previous releases, subfunctions, private functions, and class constructor functions took precedence over M-functions of the same name, but not over built-ins. In this release, built-in functions follow the same rules given to M-functions, and thus are lower in precedence than the three function types named above.

This change addresses a potential problem in that changes to the internal implementation of MATLAB functions could potentially affect the operation of your own M-code. For example, if a new version of MATLAB were to change an internal function from being M-based to being built-in, the function in the new version would now be subject to different precedence rules. If one of your M-code modules had a subfunction with the same name as this function (now obeying the built-in rules), then this subfunction would never be called.

This release resolves this potential conflict by using the same precedence rules for both M-functions and built-ins.

Return Value from the functions Function

The MATLAB functions function returns information about a function handle such as the function name, type, and filename. In previous releases, functions returned the filename for a built-in function as the string

```
'MATLAB built-in function'
```

In this release, MATLAB associates each built-in function with a placeholder file that has a .bi extension (for example, reshape.bi for the built-in reshape function).

Output from the which Function

The which function now displays the pathname for built-in functions, as well as for overloaded functions when only the overloaded functions are available.

Function Handles and Backward Compatibility

In Releases 12 and 13, you could form an array of function handles using the array constructor operator [], and refer to handles within this array using the array indexing operator (). To call the function referred to by a function handle value, you needed to use the feval function.

In Release 14, you invoke a function handle in the same way that you would call a function by name. For example, if the handle to a function was stored in variable h, you would call the function as if the handle h were a function name:

```
h(arg1, arg2, ...)
```

Using feval for this purpose is no longer necessary and is, in fact, slower.

This change is not backward compatible. This release, however, has a transition strategy that will leave almost all Release 12 & Release 13 programs working:

Constructing a non-scalar array of functions handles is only a warning, not an error.
Parenthesis notation on a non-scalar function handle means subscripting, just as in Release 13, while the same notation on scalar function handles means function call, as described above.

Incompatibility can arise only if you construct a scalar array of function handles and actually index it, necessarily with an index of 1.

Changes to Error Message Format

The last two lines of MATLAB error messages have changed for Release 14. Two advantages of this change are that error messages are now displayed in a consistent format, and part of the text of the message can be used directly with certain MATLAB commands, like dbstop.

An example of the new format is

??? Error using ==> strcmp
Too many input arguments.

Error in ==> errmsgtest at 11
strcmp('aa','bb','cc');

See Changes to Error Message Format under "Programming Features" for more information on features of the new error message format.

Regular Expression Functions No Longer Support Character Matrices

You can now pass a vector of strings in a cell array to any of the MATLAB regular expression functions (regexp, regexpi, and regexprep). Because this is the preferred method of passing a string vector, MATLAB no longer supports using character matrices for this purpose.

bin2dec Ignores Space Characters

The bin2dec function now ignores any space (' ') characters in the input string. Thus, the binary string '010 111' now yields the same result as the string '010111'.

In Release 13, bin2dec interpreted space characters as zeros:

```
bin2dec('010 111')
ans =
    39
```

In this release, bin2dec ignores all space characters:

```
bin2dec('010 111')
ans =
    23
```

isglobal Function To Be Discontinued

Support for the isglobal function will be removed in a future release of MATLAB. In Release 14, invoking isglobal generates the following warning:

Warning: isglobal is obsolete and will be discontinued.  
Type "help isglobal" for more details.

getfield and setfield Not To Be Deprecated

There are no plans to remove the getfield and setfield functions from the MATLAB language, as stated in the release notes for MATLAB Release 13.

Warning on Concatenating Different Integer Classes

If you concatenate integer arrays of different integer classes, MATLAB displays the warning

Concatenation with dominant (left-most) integer class may 
overflow other operands on conversion to return class.

The class of the resulting array is the same as the dominant (or left-most) value in the concatenation:

a = int8([52 37 89; 23 16 47]);
b = int16([74 61 32; 98 73 25]);

% Combine int8 and int16 (int8 is dominant)
c = [a b];
class(c)
ans =
   int8

% Combine int16 and int8 (int16 is dominant)
c = [b a];
class(c)
ans =
   int16

Mathematic Operations on Logical Values

Most mathematic operations are not supported on logical values.

Reading Date Values with xlsread

When reading date fields from a Microsoft Excel file using earlier versions of MATLAB, it was necessary to convert the Excel date values into MATLAB date values. This was necessary because Excel and MATLAB calculated date values based on a different reference date. This is explained in the section, "Handling Excel Date Values" on the function reference for xlsread.

With MATLAB 7.0, you no longer have to do this conversion because xlsread now imports dates as strings rather than as numerical values. If your existing code converts Excel date values to MATLAB values, you will need to remove this step so that you end up with the correct results.

64-Bit File Handling on MacIntosh

The release notes for MATLAB Release 13 should have included MacIntosh in the list of those platforms that support 64-bit file handling. This support is available on the following platforms:

Windows
Solaris
Linux 2.4.x
HP-UX 11.0, 9000/785
Macintosh

Importing Dates from Excel Worksheets

Prior to this release, xlsread imported date information from an Excel file and returned the results as a double. In Release 14, xlsread returns this information as a cell array containing data of class char. The reason for this is that MATLAB now imports Excel files using an Excel COM server. Excel returns dates is as strings, and there is really no indication that what is returned is a date.

Change in Output from xlsfinfo

xlsfinfo now returns the names or all worksheets in an Excel file instead of just the ones with numbers in them (as in Release 13).

Change to How evalin Evaluates Dispatch Context

In Release 13 and earlier, the evalin function evaluated its input in the specified workspace, but not the workspace's corresponding dispatching context. Hence, running the following example used to succeed, calling the subfunction MySubfun but using the value of x from the base workspace:

function demo
evalin('base', 'MySubfun(x)')

function MySubfun(in)
disp(in)

When you call evalin in Release 14, MATLAB tries to find a function named MyLocalFunction that is accessible in the base workspace, i.e. at the command prompt. Since MySubfun is a subfunction and therefore not in scope at the command prompt, MATLAB errors, reporting that MySubfun is undefined.

There are two ways to change your existing code to work with this new behavior. First, if your code only needs to get the value of the subfunction's inputs from the base workspace (as demo.m does above), and does not care what context MySubfun is run in, then you can change your code to use evalin only to get the values of the inputs from the base workspace, like this:

function demo_workaround1
MySubfun(evalin('base', 'x'))

function MySubfun(in)
disp(in)

If, however, it is important that the subfunction itself be run in the context of the base workspace, you can place a function handle to the subfunction in the base workspace and then evaluate that:

function demo_workaround2
assignin('base', 'MySubfunHandle', @MySubfun);
evalin('base', 'MySubfunHandle(x)')

function MySubfun(in)
disp(in)

You can also substitute 'caller' for 'base' in the workaround code if your original code uses evalin('caller', ...).

Warning on Naming Conflict

The following warning was added to identify the case when you first use a name as a function and later use it as a variable:

Warning: File: D:\Work\MATLAB XL\theworks\my_yprime.m Line: 17 
Column: 1 Variable 'getdata' has been previously used as a 
function name. 
(Type "warning off MATLAB:mir_warning_variable_used_as_function: 
to suppress this warning.)

For example, this code generates such a warning:

X = i;  %  Calls the function i() to get sqrt(-1)
for i = 1:10  % uses i as a variable.  This produces the warning. 
... end

Enabling and Disabling Warning Messages

The following message, which MATLAB appended to all warning messages in the previous release, is no longer displayed.

(Type "warning off <msgid:msgstr>" to suppress this warning.)

Use the off and on options of the warning function to control the display of all or selected warnings. This example disables a selected warning, and then enables all warnings:

% All warnings are enabled by default.
A = 5/0;
Warning: Divide by zero.

% Disable the most recent warning
[msgstr msgid] = lastwarn;
warning('off', msgid);

% Try it again. This time there is no warning.
A = 5/0;

% Enable all warnings
warning('on', 'all')

% Verify that the warning is reenabled.
A = 5/0;
Warning: Divide by zero.

Catching Ctrl-C in try-catch Statements

In previous releases of MATLAB, typing Ctrl-C while executing the try part of a try-catch statement resulted in the program branching to the catch part of that statement. In this release, typing Ctrl-C is purposely not caught by try-catch statements.

The reason for this change is that, under certain circumstances, this behavior in try-catch statements was found to adversely affect internal MATLAB code. In these cases, this resulted in MATLAB code catching the Ctrl-C rather than responding appropriately to it by terminating the current operation.

Mathematics Upgrade Issues Graphics Upgrade Issues