External Interfaces/API Features :: (MATLAB Release Notes)

MATLAB Release Notes

External Interfaces/API Features

MATLAB 7.0 adds the following external interfaces/API features and enhancements:

Importing and Exporting

General Features

MATLAB Interface to Java

Also see the section, External Interface/API Upgrade Issues for information that may affect you when upgrading to this new release of MATLAB.

Saving Character Data with Unicode Encoding

The save function now saves character data to a MAT-file using Unicode character encoding by default. You can use your system's default character encoding scheme instead by specifying the -v6 option with save. See MATLAB Stores Character Data As Unicode for a full description of this change.

Caution MAT-files saved in MATLAB version 7.0 without using the new -v6 flag will not be readable in previous versions of MATLAB. See Making Release 14 MAT-files Readable in Earlier Versions.

Saving Data in Compressed Format

The save function now saves data to a MAT-file in a compressed format by default. See Compressed Data Support in MAT-Files for more information.

Large File I/O for MEX-Files

MATLAB supports the use of 64-bit file I/O operations in your MEX-file programs. This enables you to read and write data to files that are up to and greater than 2 GB (2^31-1 bytes). Note that some operating systems or compilers may not support files larger than 2 GB.

See Large File I/O in the External Interfaces documentation for more information.

New mx Functions

New functions mxIsInt64 and mxIsUint64 return true if an mxArray represents its data as signed or unsigned 64-bit integers respectively.

Automatic Registration of Automation Server on Installation

When installing previous versions of MATLAB, system administrators also had to run MATLAB at least once on each machine to register the Automation server. In MATLAB 7.0, the MATLAB installation software does the Automation server installation for you.

Support for Multiple COM Type Libraries

MATLAB now fully supports importing additional type libraries from within an IDL file. Any COM object that depends on an imported type library is now handled correctly.

COM Interface Supports Custom Interfaces

MATLAB now supports custom interfaces to a server component in configurations where MATLAB is the client controlling an ActiveX control, or an in-process or out-of-process server. For those COM components that implement one or more custom interfaces, you can list the interfaces in MATLAB using the new interfaces function:

h = actxserver('ComponentA.CustomObject')
h =
   COM.componenta.customobject

customlist = interfaces(h)
customlist =
   ICustomObject1
   ICustomObject2

Once you select the custom interface that you want, use the invoke function to get a handle to it:

c1 = invoke(h, 'ICustomObject1')
c1 =
   Interface.componenta_Type_Library.ICustomObject1_Interface

You can now use this handle with most of the COM client functions to access the properties and methods of the object through this custom interface. For example, to list the methods available through the ICustomObject1 interface, use

invoke(c1)
   Add = double Add(handle, double, double)
   CustomMethod1 = HRESULT CustomMethod1(handle, int32)
   CustomMethod2 = HRESULT CustomMethod2(handle, int32)
   TripleAdd = [double, double] TripleAdd(handle, double, double)
   method3 = [string, int32, string, string] method3(
       handle, int16, int32, double, string)
   outin = [double, double, double, double] outin(
       handle, double, double)
   strings = string strings(handle, string)

You can read more about this feature in the section, Getting Interfaces to the Object in the External Interfaces documentation.

COM Data Type Support for Scripting Languages

In previous versions of MATLAB, a COM client program written in VBScript could not retrieve numeric data from or write data to the workspace of a MATLAB client. This was because VBScript does not support the SAFEARRAY data type used by MATLAB to pass numeric data to and from the server workspace using the GetFullMatrix and PutFullMatrix functions.

Release 14 adds two new functions, GetWorkspaceData and PutWorkspaceData, that pass data using the variant data type, a type that is supported by VBScript. You can use these new functions to pass either numeric or string data to any workspace in the COM server running MATLAB.

Refer to Exchanging Data with the Server in the External Interfaces documentation.

Additional ProgIDs for Latest MATLAB Version

There are three additional COM programmatic identifiers (ProgIDs) in MATLAB 7.0:

MATLAB.Autoserver
MATLAB.Autoserver.Single
MATLAB.Autoserver.7

Using any of these identifiers with the actxserver function guarantees that the MATLAB server you create always runs the latest version of MATLAB (version 7.0).

Note These new ProgIDs do not replace the MATLAB.Application identifier used in previous versions of MATLAB. You can continue using this ProgID, but there is no guarantee that actxserver will create a server running MATLAB 7.0.

Connecting to an Existing MATLAB Server

Instead of having to create new instances of a MATLAB server, clients can connect to an existing MATLAB automation server using the GetObject command. This sample Visual Basic program connects to a running MATLAB automation server, returning a handle h to that server. It then executes a simple plot command in the server:

Dim h As Object

' Call GetObject (omit first argument).
Set h = GetObject(, "matlab.application") 

' Handle h should be valid now. Test it by calling Execute
h.Execute ("plot([0 18], [7 23])")

Graphical Interface to Listing Available ActiveX Controls

The actxcontrollist function enables you to see what COM controls are currently installed on your system. Type

```
list = actxcontrollist;
```

and MATLAB returns a list of each control, including its name, programmatic identifier (or ProgID), and filename, in the output cell array.

Refer to Finding Out What Controls Are Installed in the External Interfaces documentation.

Graphical Interface to Creating ActiveX Controls

The simplest way to create a control object is to use the actxcontrolselect function. This function displays a graphical interface that lists all controls installed on the system and creates the one that you select from the list.

The actxcontrolselect interface has a selection panel at the left of the window and a preview panel at the right. Click on one of the control names in the selection panel to see a preview of the control displayed. (If MATLAB cannot create the control, an error message is displayed in the preview panel.) Select an item from the list and click the Create button.

Refer to Creating Control Objects Using a Graphical Interface in the External Interfaces documentation.

New Functions for the MATLAB COM Interface

There are five new COM client functions.

Function
Description

actxcontrollist
List all currently installed ActiveX controls

actxcontrolselect
Display graphical interface for creating an ActiveX control

interfaces
List custom interfaces to a COM server

iscom
Determine if input is a COM or ActiveX object

isinterface
Determine if input is a COM interface

Function	Description
actxcontrollist	List all currently installed ActiveX controls
actxcontrolselect	Display graphical interface for creating an ActiveX control
`interfaces`	List custom interfaces to a COM server
`iscom`	Determine if input is a COM or ActiveX object
`isinterface`	Determine if input is a COM interface

There are three new COM server functions. When invoked by a MATLAB or Visual Basic client, these functions execute in the server associated with the specified handle parameter.

Function
Description

Feval
Evaluate MATLAB function call in the server

GetWorkspaceData
Get data from server workspace

PutWorkspaceData
Store data in server workspace

Function	Description
`Feval`	Evaluate MATLAB function call in the server
`GetWorkspaceData`	Get data from server workspace
`PutWorkspaceData`	Store data in server workspace

See the function reference pages in the "External Interfaces Reference" documentation for more information.

COM Interface Supports Dot Syntax in Commands

You can now use a simpler form of syntax when invoking either MATLAB COM functions or methods belonging to COM objects. In this dot syntax (as it is referred to in the MATLAB documentation), you specify the object name, a dot (.), and then the name of the function or method you are calling. Enclose any input arguments in parentheses after the function name. Specify output arguments to the left of the equals sign:

outputvalue = object.function(arg1, arg2, ...)

For example, Release 13 syntax for invoking the addproperty function on a COM object with handle h was

```
invoke(h, 'addproperty', 'Position');
```

You can now perform the same operation using

```
h.addproperty('Position');
```

The get and set operations are even simpler:


 ** R13 SYNTAX **                    ** R14 SYNTAX **
x = get(h, 'Radius');                 x = h.Radius;
set(h, 'Radius', 50);                 h.Radius = 50;

Refer to Invoking Commands on a COM Object in the External Interfaces documentation.

Enumeration in COM Method Arguments

In addition to supporting enumeration for the properties of a COM object, MATLAB now supports enumeration for parameters passed to methods of a COM object. The only restriction is that the type library in use must report the parameter as ENUM, and only as ENUM.

Refer to Specifying Enumerated Parameters in the External Interfaces documentation.

Event Handling for COM Servers

In addition to handling events from ActiveX controls, MATLAB now handles events fired by Automation servers as well. Use the same event handling functions that you have been using for events from controls.

Function
Description

eventlisteners
Return a list of events attached to listeners

events
List all events, both registered and unregistered, a control or server can generate

isevent
Determine if an item is an event of a COM object

registerevent
Register an event handler with a control or server event

unregisterallevents
Unregister all events for a control or server

unregisterevent
Unregister an event handler with a control or server event

Function	Description
`eventlisteners`	Return a list of events attached to listeners
`events`	List all events, both registered and unregistered, a control or server can generate
`isevent`	Determine if an item is an event of a COM object
`registerevent`	Register an event handler with a control or server event
`unregisterallevents`	Unregister all events for a control or server
`unregisterevent`	Unregister an event handler with a control or server event

Refer to How to Prepare for and Handle Events from a COM Server" and "Example -- Responding to Events from an Automation Server in the External Interfaces documentation.

Callbacks to COM Event Handlers Written as Subfunctions

Instead of having to maintain a separate M-file for every event handler routine you write, you can consolidate some or all of these routines into a single M-file using M-file subfunctions.

Refer to Writing Event Handlers Using M-File Subfunctions in the External Interfaces documentation.

Event Handlers Can Be Function Handles

In this release, you can now implement ActiveX event handlers as function handles.

Java Interface Adds Dynamic Java Class Path

MATLAB loads Java class definitions from files that are on the Java class path. The Java class path now consists of two segments: the static path, and a new segment called the dynamic path.

The static path is loaded from the file classpath.txt at the start of each MATLAB session and cannot be changed without restarting MATLAB. This was the only path available in previous versions of MATLAB. Thus, there was no way to change the Java path without restarting MATLAB.

The dynamic Java class path can be loaded at any time during a MATLAB session using the javaclasspath function. You can define the dynamic path (using javaclasspath), modify the path (using javaaddpath and javarmpath), and refresh the Java class definitions for all classes on the dynamic path (using clear java) without restarting MATLAB. See the function reference pages for more information on how to use these functions.

The javaclasspath function, when used with no arguments, displays both the static and dynamic segments of the Java class path:

javaclasspath

       STATIC JAVA PATH

   D:\Sys0\Java\util.jar
   D:\Sys0\Java\widgets.jar
   D:\Sys0\Java\beans.jar
             .
             .

       DYNAMIC JAVA PATH

   User4:\Work\Java\ClassFiles
   User4:\Work\Java\mywidgets.jar
             .
             .

You can read more about this feature in the sections, The Java Class Path and Making Java Classes Available to MATLAB in the External Interfaces documentation.

Locating Java Native Method DLLs with File librarypath.txt

Previous versions of MATLAB required that you set a system environment variable to enable Java to locate the shared libraries supporting any native methods you need to use. This environment variable was PATH on Windows systems, and LD_LIBRARY_PATH on UNIX systems. This is no longer necessary.

Now you can enter the names of those directories that contain native method libraries in a new file called librarypath.txt using one line per directory. The librarypath.txt file resides adjacent to the similar file classpath.txt in the $matlab/toolbox/local directory.

Graphics and 3-D Visualization Features Creating Graphical User Interfaces (GUIDE) Features