| External Interfaces/API, MATLAB® Version 7 (R14) Release Notes | |
New features and changes introduced in this version are organized by these topics:
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.
Compatibility Considerations. MAT-files saved in MATLAB® version 7.0 without using the new -v6 flag will not be readable in previous versions of MATLAB.
The save function now saves data to a MAT-file in a compressed format by default.
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.
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.
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.
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
ICustomObject2Once 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.
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.
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. |
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 Microsoft® 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])")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.
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 GUI in the External Interfaces documentation.
There are five new COM client functions.
Function | Description |
|---|---|
List all currently installed ActiveX controls | |
Display graphical interface for creating an ActiveX control | |
List custom interfaces to a COM server | |
Determine if input is a COM or ActiveX object | |
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 |
|---|---|
Evaluate MATLAB function call in the server | |
Get data from server workspace | |
Store data in server workspace |
See the function reference pages in the External Interfaces Reference documentation for more information.
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 Methods on an Object in the External Interfaces documentation.
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.
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 |
|---|---|
Return a list of events attached to listeners | |
List all events, both registered and unregistered, a control or server can generate | |
Determine if an item is an event of a COM object | |
Register an event handler with a control or server event | |
Unregister all events for a control or server | |
Unregister an event handler with a control or server event |
Refer to Responding to Events — an Overview and in the External Interfaces documentation.
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.
In this release, you can now implement ActiveX event handlers as function handles.
When calling a method that takes optional input arguments, you can skip any optional argument by specifying an empty array ([]) in its place. The syntax for invoke with the second argument (arg2) not specified is as follows:
invoke(handle, 'methodname', arg1, [], arg3);
See the section, Optional Input Arguments in the External Interfaces documentation for more information.
MATLAB has changed the way it displays a COM interface in this release. For example, the string used to represent an interface in MATLAB 6.5 was
[1x1 Interface.excel.application.Workbooks]
MATLAB 7.0 represents this same interface with the following string:
[1x1 Interface.Microsoft_Excel_9.0_Object_Library.Workbooks]
Compatibility Considerations. You may need to change any code that depends on the previous behavior.
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 in MATLAB® Workspace in the External Interfaces documentation.
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 Microsoft® Windows® systems, and LD_LIBRARY_PATH on UNIX®[1] 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.
New functions mxIsInt64 and mxIsUint64 return true if an mxArray represents its data as signed or unsigned 64-bit integers respectively.
If MEX-files don't load on a Windows system, the error message is not informative. The dependency walker is a very useful tool distributed with MSVC. It is also freely available from http://www.dependencywalker.com.
In Release 14, MATLAB uses C++ exception handling. MEX-files built prior to R14 did not support C++ exceptions.
For example, write a C MEX-file that just calls mexErrMsgTxt. If you build this with a release prior to Release 14 and run it, the program aborts MATLAB. If you build this with Release 14 and run it, MATLAB will handle the exception correctly.
Compatibility Considerations. On GLNX86 and Macintosh® systems, all MEX-files that can throw errors need to be recompiled for R14.
Shared libraries previously residing in directory $MATLAB/extern/lib/$ARCH are now in $MATLAB/bin/$ARCH.
Compatibility Considerations. You may need to change any code that depends on the previous behavior.
[1] UNIX is a registered trademark of The Open Group in the United States and other countries.
| Creating Graphical User Interfaces (GUIs), MATLAB Version 7 (R14) | Compatibility Summary for MATLAB® Software | |
| © 1984-2008- The MathWorks, Inc. - Site Help - Patents - Trademarks - Privacy Policy - Preventing Piracy - RSS |