MATLAB Release Notes

External Interfaces/API Features

MATLAB 6.5 adds the following external interface and API features and enhancements:

• New MX and MEX Functions
• New COM Client Support Features

New MX and MEX Functions

There are a number of new logical mx functions provided as part of changing logical from an attribute to a MATLAB class, several additional mx functions, and two new mex error handling functions.

New Logical Functions.   This release introduces seven new C mx functions to use with logicals.

Function	Description
mxCreateLogicalArray	Create N-dimensional, logical mxArray initialized to false
mxCreateLogicalMatrix	Create two-dimensional, logical mxArray initialized to false
mxCreateLogicalScalar	Create scalar, logical mxArray initialized to false
mxCreateSparseLogicalMatrix	Create unpopulated, two-dimensional, sparse, logical mxArray
mxGetLogicals	Get pointer to logical array data
mxIsLogicalScalar	True if scalar mxArray of class mxLOGICAL
mxIsLogicalScalarTrue	True if scalar mxArray of class mxLOGICAL is true

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

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

New mx Functions in C API.   MATLAB 6.5 also introduces these new C mx functions.

Function	Description
mxGetChars	Get pointer to character array data
mxCreateDoubleScalar	Create scalar, double-precision array initialized to the specified value

Note    mxCreateDoubleScalar replaces mxCreateScalarDouble, although the latter function is still supported at this time.

New mex Functions for Error Handling.   There are two new C and Fortran MEX functions that enable you to specify a message identifier and message string when reporting an error or warning. These functions also accept formatting conversion characters, such as those used with the MATLAB sprintf function, in the error or warning message string.

Function	Description
mexErrMsgIdAndTxt	Issue error message with identifier and return to MATLAB prompt
mexWarnMsgIdAndTxt	Issue warning message with identifier

New COM Client Support Features

In an effort to provide a consistent interface to object-oriented technologies, MATLAB 6.5 introduces several changes that affect the way you interact with Component Object Model (COM) controls and servers through MATLAB.

Key benefits of this change are

• Robust memory management -- Objects and interfaces are destroyed automatically when the variable that represents the object or interface is either reassigned or goes out of scope.
• Flexibility in event handling -- Register and unregister a control's events with callback or event handler routines at any time after the control has been created.
• Custom properties -- You can attach your own properties to a control and store any kind of data in the control.
• A graphical user interface for viewing and modifying COM properties.
• Multiple arguments with the set function.
• More useful information on methods returned by invoke.
• More detail in error messages.

See Client Support for COM in the MATLAB documentation for more information on these features. You may also want to read through the External Interfaces/API Upgrade Issues to find out how these changes may affect your existing programs.

COM Demo.   MATLAB includes three demos showing how to use the COM client interface. To run any of the demos, click on the Demos tab in the MATLAB Help Browser. Then click to expand the folder called Automation Client Interface (COM).

New MATLAB Functions for COM.   There are a number of new functions available for the COM interface.

Function	Description
addproperty	Add custom property to COM object
deleteproperty	Remove custom property from COM object
eventlisteners	Return a list of events attached to listeners
events	Return a list of events that the control can trigger
isevent	Determine if an item is an event of a COM control
ismethod	Determine if an item is a method of a COM object
isprop	Determine if an item is a property of a COM object
registerevent	Register an event handler with a control's event
unregisterallevents	Unregister all events for a control
unregisterevent	Unregister an event handler with a control's event

MATLAB Functions New to COM.   You can now use these MATLAB functions in the COM environment.

Function	Description
fieldnames	Return property names of a COM object
inspect	Display graphical interface to list and modify property values
methods	List all methods for the control or server
methodsview	Display graphical interface to list method information

Specifying Property Names.   You may abbreviate the names of properties, as long as you include enough letters in the name to make it unambiguous. Also, property names are not case-sensitive. For example, to get the value of the OrganizationName property from a COM server running an Excel application, you can use

• get(h, 'org')
  ans =
     The MathWorks, Inc.
  

Get and Set on Multiple Objects.   You can use the get and set functions on more than one object at a time by putting the object handles into a vector and then operating on the vector. See Get and Set on Multiple Objects in the MATLAB documentation.

Enumerated Values for COM Properties.   When setting the value for a COM property in MATLAB, you can now use an enumerated string in place of a numeric value. An enumerated string, such as xlUnicodeText, is much easier to remember than its equivalent numeric value, and thus makes it unnecessary to spend time looking up valid settings for a property.

To list all possible enumerated values for a property of object h, use

• set(handle, 'propertyname')
  

To set a property to the value represented by an enumerated string, use this syntax. The enumstring argument can be abbreviated, as long as you use enough letters to make it unambiguous:

• set(handle, 'propertyname', 'enumstring')
  

To get the current enumerated value of a property, use

• get(handle, 'propertyname')
  

See Using Enumerated Values for Properties in the MATLAB documentation for more information.

Custom Properties.   You can attach your own properties to a control using the addproperty function. The syntax shown here creates a custom property for control, h:

• addproperty(handle, 'propertyname')
  

This example creates the mwsamp control, adds a new property called Position to it, and assigns the value [200 120] to that property:

• h = actxcontrol('mwsamp.mwsampctrl.2', [200 120 200 200]);
  addproperty(h, 'Position');
  set(h, 'Position', [200 120]);
  

To remove custom properties from a control, use deleteproperty with the following syntax:

• deleteproperty(h, 'propertyname')
  

See Custom Properties in the MATLAB documentation for more information.

New Event Handling Functions.   With earlier versions of MATLAB, you could register events for a control only at the time the control was created. In MATLAB 6.5, you can register and unregister events at any time using the registerevent, unregisterevent, and unregisterallevents functions.

You can also list all events that a control can respond to, or just those events that are currently registered, using the events and eventlisteners functions, respectively. The events function supersedes the COM send function.

See COM Control Events in the MATLAB documentation for more information on event handling.

GUI Interface to Get and Set Properties.   Use the new inspect function to see a list of all properties belonging to a COM object or interface. Create an Excel server object and invoke inspect to bring up the Property Inspector window shown below:

• h = actxserver('excel.application');
  inspect(h)
  

To change the value of one of the properties, click on the property name at the left and then type in the new value in the field at the right.

See Using the Property Inspector in the MATLAB documentation.

set Accepts Multiple Arguments.   You can now set more than one property value with one set command. The syntax is

• set(h, property1, newvalue1, property2, newvalue2, ...);
  

Each property argument must be followed by a newvalue argument. The example shown here changes the Label and Radius for an mwsamp control:

• h = actxcontrol('mwsamp.mwsampctrl.2', [0 0 200 200]);
  get(h)
  ans = 
       Label: 'Label'
      Radius: 20
  
  set(h, 'label', 'Hello', 'radius', 35);
  get(h)
  ans = 
       Label: 'Hello'
      Radius: 35
  

Returning More Than One Output Argument.   A MATLAB client can now return more than one output argument from COM server applications. If you know that a server function supports multiple outputs, you can return any or all of those outputs to the MATLAB client.

With previous versions of MATLAB, you could only get back a single return value (shown here as ret) from a function call to the server, even for those functions that could return more than one output value:

• ret = functionname(in1, in2, ...);
  

In MATLAB 6.5, you can specify additional output arguments (shown here as out1 out2 ...) in a function call, enabling the client access to all values returned by the function:

• [ret out1 out2 ...] = functionname(in1, in2, ...);
  

If there are multiple output arguments, the return value is always the first argument on the left hand side (lhs).

MATLAB makes use of the pass by reference capabilities in COM to implement this feature. Note that pass by reference is a COM feature. It is not available in MATLAB at this time.

Argument Types Listed By Invoke.   The invoke function now lists data types for input and output arguments. The function m1 defined in an Interface Definition Language (IDL) file is shown here:

• m1([in,out] BSTR* strInOut, [out] short* shortOut, [in] long 
  longIn, [out,retval] double* doubleRet);
  

MATLAB 6.1 invoke lists the function as

• m1 = double m1(Variant(Pointer), Variant(Pointer), Int)
  

while MATLAB 6.5 invoke lists it as

• m1 = [double, string, int16] m1(handle, string, int32)
  

More Detail in Error Messages.   MATLAB now returns more detailed information when a COM error is generated. This includes the source and description of the error, along with the location of help resources provided to assist in resolving the error:

• h = actxserver('excel.application');
  Repeat(h)
  ??? Invoke Error, Dispatch Exception: 
  Source: Microsoft Excel
  Description: Repeat method of Application class failed
  Help File: D:\Applications\MSOffice\Office\1033\xlmain9.chm
  Help Context ID: 0.
  

Graphics Features

Creating Graphical User Interfaces (GUIDE) Features