External Interfaces/API

The DDE Name Hierarchy

When you access MATLAB as a server, you must specify its service name, topic, and item. The figure below illustrates the MATLAB DDE name hierarchy. Topics and items are described in more detail below.

The two MATLAB topics are System and Engine.

MATLAB System Topic

The System topic allows users to browse the list of topics provided by the server, the list of System topic items provided by the server, and the formats supported by the server.

The MATLAB System topic supports these items:

• SysItems

• Provides a tab-delimited list of items supported under the System topic (this list).

• Format

• Provides a tab-delimited list of string names of all the formats supported by the server. MATLAB supports Text, Metafilepict, and XLTable. These formats are described in Clipboard Formats.

• Topics

• Provides a tab-delimited list of the names of the topics supported by MATLAB.

MATLAB Engine Topic

The Engine topic allows users to use MATLAB as a server by passing it a command to execute, requesting data, or sending data.

The MATLAB Engine topic supports these items:

• EngEvalString

• Specifies an item name, if required, when you send a command to MATLAB for evaluation.

• EngStringResult

• Provides the string result of a DDE execute command when you request data from MATLAB.

• EngFigureResult

• Provides the graphical result of a DDE execute command when you request data from MATLAB.

• <matrix name>

• When requesting data from MATLAB, this is the name of the matrix for which data is being requested. When sending data to MATLAB, this is the name of the matrix to be created or updated.

The MATLAB Engine topic supports three operations that may be used by applications with a DDE client interface. These operations include sending commands to MATLAB for evaluation, requesting data from MATLAB, and sending data to MATLAB.

Sending Commands to MATLAB for Evaluation

Clients send commands to MATLAB using the DDE execute operation. The Engine topic supports DDE execute in two forms because some clients require that you specify the item name and the command to execute, while others require only the command. Where an item name is required, use EngEvalString. In both forms, the format of the command must be Text. Most clients default to Text for DDE execute. If the format cannot be specified, it is probably Text. The table summarizes the DDE execute parameters.

Item	Format	Command
EngEvalString	Text	String
null	Text	String

Requesting Data from MATLAB

Clients request data from MATLAB using the DDE request operation. The Engine topic supports DDE requests for three functions:

Text that is the result of the previous DDE execute command.   You request the string result of a DDE execute command using the EngStringResult item with Text format.

Graphical results of the previous DDE execute command.   You request the graphical result of a DDE execute command using the EngFigureResult item. The EngFigureResult item can be used with Text or Metafilepict formats:

• Specifying the Text format results in a string having a value of "yes" or "no." If the result is "yes," the metafile for the current figure is placed on the clipboard. This functionality is provided for DDE clients that can retrieve only text from DDE requests, such as Word for Windows. If the result is "no," no metafile is placed on the clipboard.
• Specifying the Metafilepict format when there is a graphical result causes a metafile to be returned directly from the DDE request.

The data for a specified matrix.   You request the data for a matrix by specifying the name of the matrix as the item. You can specify either the Text or XLTable format.

The table summarizes the DDE request parameters.

Item	Format	Result
EngStringResult	Text	String
EngFigureResult	Text	Yes/No
EngFigureResult	Metafilepict	Metafile of the current figure
<matrix name>	Text	Character buffer, tab-delimited columns, CR/LF-delimited rows
<matrix name>	XLTable	Binary data in a format compatible with Microsoft Excel

Sending Data to MATLAB

Clients send data to MATLAB using the DDE poke operation. The Engine topic supports DDE poke for updating or creating new matrices in the MATLAB workspace. The item specified is the name of the matrix to be updated or created. If a matrix with the specified name already exists in the workspace it will be updated; otherwise it will be created. The matrix data can be in Text or XLTable format.

The table summarizes the DDE poke parameters.

Item	Format	Poke Data
<matrix name>	Text	Character buffer, tab-delimited columns, CR/LF-delimited rows
<matrix name>	XLTable	Binary data in a format compatible with Microsoft Excel

Accessing MATLAB as a Server

Example: Using Visual Basic and the MATLAB DDE Server