MATLAB 6.5 Release Notes (MATLAB Release Notes)

MATLAB Release Notes

External Interfaces/API Upgrade Issues

The issues involved in upgrading from MATLAB 6.1 to MATLAB 6.5, in terms of external interfaces and API features, are discussed below. These include

Changes to logical and sparse Data Types

In MATLAB 6.5, the sparse data type has been changed to be an attribute of its underlying data type. Also, the logical data attribute has been changed to be a first class data type. See Programming and Data Types Upgrade Issues for more information on this change.

The following sections describe how this change may affect your C programs.

No Change to mxIsLogical. The mxIsLogical function is unchanged in MATLAB 6.5. It returns true for logical arrays, as it did for arrays with a logical attribute in previous releases.

Testing for Numeric. In previous releases, mxIsNumeric returned true for numeric arrays with the logical attribute. This function now returns false for logical arrays, since logical is a nonnumeric data type.

Using mxGetClassID on logicals. mxGetClassID returns a new mxLOGICAL_CLASS value for logical arrays.

Using mxGetClassID on Sparse Arrays. mxGetClassID no longer returns the enumerated value mxSPARSE_CLASS. Instead, it returns the enumerated value corresponding to the underlying data type. Use mxIsSparse to determine if an mxArray is sparse.

Testing for Sparse. In previous releases, you could use the following statement to determine if a matrix is sparse. This does not work in MATLAB 6.5.

```
mxGetClassID(x) == mxSPARSE_CLASS
```

You should use mxIsSparse(x) to determine if a matrix is sparse. The mxIsSparse function operates the same as in previous releases and also executes faster than the operation shown above.

Testing for Sparse with mxIsDouble. Because sparse has been changed from a MATLAB data type to a data attribute, mxIsDouble(x) no longer implies ~mxIsSparse(x), as it did in previous releases. Test the sparseness of an array using mxIsSparse instead.

No Change to mxIsSparse. The mxIsSparse function is unchanged in MATLAB 6.5. It returns true for arrays with a sparse attribute, as it did for sparse arrays in previous releases.

Obsolete logical Functions. The following two functions are now obsolete. Support for these functions will be removed in a future release.

Function
Description

mxSetLogical
Convert mxArray to logical type

mxClearLogical
Convert mxArray to numeric type

Function	Description
`mxSetLogical`	Convert `mxArray` to `logical` type
`mxClearLogical`	Convert `mxArray` to numeric type

Functions Replaced in MATLAB 6.5

MATLAB handles mxArrays more efficiently in version 6.5 by not storing a variable name in the mxArray. When an mxArray name is required, these new C and Fortran functions enable you to pass it in the argument list.

The functions shown in the left column of the table replace those in the right column. The functions shown in the right column are now obsolete and may be unavailable in a future version of MATLAB.

New Function
Replaces

mexGetVariable
mexGetArray

mexGetVariablePtr
mexGetArrayPtr

mexPutVariable
mexPutArray

engGetVariable
engGetArray

engPutVariable
engPutArray

matDeleteVariable
matDeleteArray

matGetVariable
matGetArray

matGetVariableInfo
matGetArrayHeader

matGetNextVariable
matGetNextArray

matGetNextVariableInfo
matGetNextArrayHeader

matPutVariable
matPutArray

matPutVariableAsGlobal
matPutArrayAsGlobal

New Function	Replaces
`mexGetVariable`	`mexGetArray`
`mexGetVariablePtr`	`mexGetArrayPtr`
`mexPutVariable`	`mexPutArray`
`engGetVariable`	`engGetArray`
`engPutVariable`	`engPutArray`
`matDeleteVariable`	`matDeleteArray`
`matGetVariable`	`matGetArray`
`matGetVariableInfo`	`matGetArrayHeader`
`matGetNextVariable`	`matGetNextArray`
`matGetNextVariableInfo`	`matGetNextArrayHeader`
`matPutVariable`	`matPutArray`
`matPutVariableAsGlobal`	`matPutArrayAsGlobal`

For example, you should replace the second and third line shown here

parr = mxCreateDoubleMatrix(0, 0, 0);
mxSetName(parr, name);
retval = matPutArray(ph, parr);

with the second line shown below. The name of the mxArray is passed with matPutVariable rather than stored in the mxArray by mxSetName:

parr = mxCreateDoubleMatrix(0, 0, 0);
retval = matPutVariable(ph, name, parr);

mxCreateScalarDouble Replaced. New function mxCreateDoubleScalar replaces mxCreateScalarDouble. The latter function is still supported at this time, but support may be removed in a future release.

New Function
Replaces

mxCreateDoubleScalar
mxCreateScalarDouble

New Function	Replaces
`mxCreateDoubleScalar`	`mxCreateScalarDouble`

Compiling C++ Files

You no longer need to use the preconfigured options file, cxxopts.sh, to compile C++ MEX-files. MATLAB recognizes the following file extensions as C++ extensions, and automatically uses the C++ compiler.

```
.cxx
.cpp
.cc
```

The cxxopts.sh file is no longer available in MATLAB.

Also, on UNIX, you must now use the -cxx switch to the MEX script if you are linking C++ objects.

LCC Support for LAPACK

On Windows platforms, you can now compile and link C MEX-files that call LAPACK and BLAS functions using the MATLAB C compiler, Lcc. Use the following command to compile the file myCmexFile.c and link it with the LAPACK library file, libmwlapack.lib.

mex myCmexFile.c <matlab>/extern/lib/win32/lcc/libmwlapack.lib

The term <matlab> stands for the MATLAB root directory.

Client Support for COM

Client support for the MATLAB COM interface has changed significantly in MATLAB 6.5. There are many new features as well as important changes in previously supported features. This section describes how these changes may affect your existing programs.

See New COM Client Support Features in these Release Notes and MATLAB COM Client Support in the MATLAB documentation for more information.

Creating an Object or Interface. When you create a COM control or server with actxcontrol or actxserver, MATLAB returns a COM object which now is displayed as COM.<string> rather than as activex object:

h = actxserver('Excel.Application')
h =
   COM.excel.application

This also applies to interfaces to a COM object. MATLAB represents the interface as Interface.<string> rather than as activex object:

w = get(h, 'Workbooks')
w =
   Interface.excel.application.Workbooks

New Error on Non-Existent ProgID. Both actxcontrol and actxserver return a different error message when an invalid ProgID is entered:

h = actxcontrol('xxxxx')
??? Error using ==> actxcontrol
Control creation failed. Invalid ProgID 'xxxxx'

Data Returned by get. Information returned by the get function now shows the type for each interface:

h = actxserver ('Excel.Application');
get(h)
ans = 
      Application: [1x1 Interface.excel.application.Application]
           Parent: [1x1 Interface.excel.application.Parent]
          Windows: [1x1 Interface.excel.application.Windows]
        Workbooks: [1x1 Interface.excel.application.Workbooks]
            .
            .

Property names returned by get are no longer arranged alphabetically. They are displayed in the order that MATLAB gets them from the Type Library.

Set Invoked with No Arguments. When you invoke the set function without any arguments other than the object or interface handle, MATLAB no longer returns an error. Instead it returns a structure array, listing all properties for the object. The structure array also contains enumerated values for those properties that allow you to express values as enumerated strings.

Old error message:

set(h)
??? Index exceeds matrix dimensions.

Values returned in MATLAB 6.5:

set(h)
ans = 
         Application: {}
             Creator: {'xlCreatorCode'}
              Parent: {}
              Cursor: {4x1 cell}
                .
                .

Change in Method Data Returned by invoke. The invoke function now returns more useful data on the methods of an object or interface. Note the differences shown in the example below:

h = actxserver('excel.application');

% Invoke, prior to MATLAB 6.5
invoke(h)
   DeleteCustomList = Void DeleteCustomList (Int)
   MailLogon = Void MailLogon (Variant[opt], Variant[opt],
      Variant[opt])
   NextLetter: 'Variant(Pointer) NextLetter ()'
         :
         :

% Invoke, in MATLAB 6.5
invoke(h)
   DeleteCustomList: 'void DeleteCustomList(handle, int32)'
   MailLogon: 'void MailLogon(handle, [Optional]Variant)'
   NextLetter: 'handle NextLetter(handle)'
         :
         :

Also note that the required handle argument is now explicitly shown.

Methods Function for COM. The methods function now returns the names for all methods of the specified class:

h = actxcontrol('MWSAMP.MWSampCtrl.1');
methods(h)

Methods for class COM.mwsamp.mwsampctrl.1:

AboutBox         GetR8Array         SetR8         move
Beep             GetR8Vector        SetR8Array    propedit
FireClickEvent   GetVariantArray    SetR8Vector   release
GetBSTR          GetVariantVector   addproperty   save
                             :
                             :

You can also use the methodsview function on COM objects now to get a graphical display of object properties.

Properties with Arguments. Any property that takes arguments is treated as a method in MATLAB 6.5. For example, the Range and Item properties in an Excel application server are now methods.

So, this statement, where Item is a property of Sheets

```
sheet2 = get(Sheets, 'Item', 2);
```

can now be replaced by the following, where Item is now a method of Sheets.

```
sheet2 = invoke(Sheets, 'Item', 2);
```

If you request a list of properties and methods for Sheets (using get and invoke, respectively), MATLAB now lists Item as a method.

For backward compatibility, functions in MATLAB 6.5 support properties that take arguments both as methods and as properties.

Arguments to Event Handlers. When a control triggers an event, MATLAB passes arguments from the control to any registered event handlers. MATLAB now passes two additional arguments:

A string argument, holding the name of the event.
A structure argument, holding the event name, control name, event identifier, event argument names, and event argument values.

See Writing Event Handlers in the MATLAB documentation for more information on changes affecting event handlers.

Specifying Events Using Identifiers. When registering events with their handler functions using either the actxcontrol or registerevent function, you can specify events either by event ID number or by event name.

Using event ID numbers:

h = actxcontrol('MWSAMP.MwsampCtrl.2', [0 0 200 200], f, ...
    {-600, 'myclick'; -601 'my2click'; -605 'mymoused'});

Using event names:

h = actxcontrol('MWSAMP.MwsampCtrl.2', [0 0 200 200], f, ...
    {'Click', 'myclick'; 'DblClick' 'my2click'; ...
     'MouseDown' 'mymoused'});

Use the new events function to display the names of all events recognized by the COM object in use. For example, to list all events for the mwsamp control, use

f = figure ('pos', [100 200 200 200]);
h = actxcontrol ('mwsamp.mwsampctrl.2', [0 0 200 200], f);

events(h)
   Click = void Click()
   DblClick = void DblClick()
   MouseDown = void MouseDown(int16 Button, int16 Shift,
      Variant x, Variant y)

Boolean Return Values. Invoking get on a property that returns a Boolean value now returns 1 to indicate true. Previously, it returned -1 for true:

h = actxserver('Excel.Application');
set(h, 'DisplayStatusBar', 1);
get(h, 'DisplayStatusBar')
ans =
   1

Also, invoking a method that returns a Boolean value now returns 1 to indicate true. This also previously returned -1 for true:

h = actxserver('Excel.Application');
invoke(h, 'Wait', 5)
ans =
   1

Argument Callouts in Error Messages. When a MATLAB client sends a command with an invalid argument to a COM server application, the server sends back an error message similar to that shown here, identifying the invalid argument. Be careful when interpreting the argument callout in this type of message.

PutFullMatrix(handle, 'a', 'base', 7, [5 8]);
??? Error: Type mismatch, argument 3.

In the PutFullMatrix command shown above, it is the fourth argument, 7, that is invalid. (It is scalar and not the expected array data type.) However, the error message identifies the failing argument as argument 3.

This is because the COM server receives only the last four of the arguments shown in the MATLAB code. (The handle argument merely identifies the server. It does not get passed to the server). So the server sees 'a' as the first argument, and the invalid argument, 7, as the third.

As another example, submitting the same command with the invoke function makes the invalid argument fifth in the MATLAB client code. Yet the server still identifies it as argument 3 because neither of the first two arguments are seen by the server.

invoke(handle, 'PutFullMatrix', 'a', 'base', 7, [5 8]);
??? Error: Type mismatch, argument 3.

Releasing and Deleting Controls or Servers. This release addresses a potential memory leak in MATLAB. The leak was caused by the following:

MATLAB did not completely clean up COM objects or interfaces without the explicit use of release or delete. For example, the following clear command did not release all memory used by the object. An explicit release(h) was required before the clear:

    h = actxcontrol ('MWSAMP.MwsampCtrl.1');
    clear all

When a variable representing a COM object or interface was successfully assigned a new value, MATLAB did not release all of the memory originally allocated to the object or interface.
When such a variable went out of scope, MATLAB did not release all of the memory originally allocated.

Explicit release or deletion of a COM object or interface is no longer necessary. MATLAB successfully clears the object or interface from memory when clear is invoked, or when the variable that represents the object or interface is either assigned a new value or goes out of scope.

Graphics Upgrade Issues Creating Graphical User Interfaces (GUIDE) Upgrade Issues