External Interfaces

Automation Server Functions

MATLAB provides a number of functions to enable an Automation controller written in either MATLAB or Visual Basic to manipulate data in the MATLAB server. These are shown in the tables below and are described in individual function reference pages.

• Executing Commands in the MATLAB Server
• Exchanging Data with the Server
• Controlling the Server Window
• Terminating the Server Process
• Client-Specific Information

For a description of how to use these functions in controller programs, see COM Server Reference in the External Interfaces reference documentation.

Executing Commands in the MATLAB Server

The client program can execute commands in the MATLAB server using these functions.

Function	Description
Execute	Execute MATLAB command in server
Feval	Evaluate MATLAB command in server

Use Execute when you want the MATLAB server to execute a command that can be expressed in a single string:

• h = actxserver('matlab.application');
  
  h.PutWorkspaceData('A', 'base', rand(6))
  h.Execute('A(4:6,:) = [];'); % remove rows 4-6
  B = h.GetWorkspaceData('A', 'base')
  B =
      0.6208    0.2344    0.6273    0.3716    0.7764    0.7036
      0.7313    0.5488    0.6991    0.4253    0.4893    0.4850
      0.1939    0.9316    0.3972    0.5947    0.1859    0.1146
  

Referencing Server-Side Variables

The expression 'A=' causes MATLAB to interpret A as a server-side variable name.

Use Feval when you want the server to execute commands that you cannot express in a single string. The following example uses variables defined in the client to modify server: rows, cols, and pages.

This is a continuation of the example shown above:

• rows = 3;   cols = 3;   pages = 2;
  h.Feval('reshape', 0, 'A=', rows, cols, pages);
  

Note that the reshape operation in the statement above does not make an assignment to the server variable A; it is equalvalent to the following MATLAB statement:

• reshape(A,3,3,2)
  

which returns a result, but does not assign the new arrary. If you get the variable A from the server, it is unchanged:

• B = h.GetWorkspaceData('A', 'base')
  B =
      0.6208    0.2344    0.6273    0.3716    0.7764    0.7036
      0.7313    0.5488    0.6991    0.4253    0.4893    0.4850
      0.1939    0.9316    0.3972    0.5947    0.1859    0.1146
  

Use the Feval method returned value to get the result of this type of operation. For example, the following statement reshaps the server-side array A and returns the result of this MATLAB operation in the client-side variable a.

• a = h.Feval('reshape', 1, 'A=', rows, cols, pages);
  

Exchanging Data with the Server

MATLAB provides several functions to read and write data to any workspace of a MATLAB server. In each of these commands, you pass the name of the variable to read or write, and the name of the workspace holding that data.

Function	Description
GetCharArray	Get character array from server
GetFullMatrix	Get matrix from server
GetWorkspaceData	Get any type of data from server
PutCharArray	Store character array in server
PutFullMatrix	Store matrix in server
PutWorkspaceData	Store any type of data in server

The Get/PutCharArray functions read and write string values to the MATLAB server.

The Get/PutFullMatrix functions pass data as a SAFEARRAY data type. You can use these functions with any client that supports the SAFEARRAY type. This includes MATLAB and Visual Basic clients.

The Get/PutWorkspaceData functions pass data as a variant data type. Use these functions with any client that supports the variant type. These functions are especially useful for VBScript clients as VBScript does not support the SAFEARRAY data type.

Write a string to variable str in the base workspace of the MATLAB server and then read it back to the client:

• h = actxserver('matlab.application');
  h.PutCharArray('str', 'base', ...
     'He jests at scars that never felt a wound.');
  
  S = h.GetCharArray('str', 'base')
  S =
    He jests at scars that never felt a wound.
  

Controlling the Server Window

These functions enable you to make the server window visible or to minimize it.

Function	Description
MaximizeCommandWindow	Display server window on Windows desktop
MinimizeCommandWindow	Minimize size of server window

Create a COM server running MATLAB and minimize it:

• h = actxserver('matlab.application');
  h.MinimizeCommandWindow;
  

Terminating the Server Process

When you are finished with the MATLAB server, quit the MATLAB session and terminate the server process using the Quit function.

Function	Description
Quit	Terminate MATLAB server

To terminate the server process, enter

• h.Quit;
  

Client-Specific Information

This section provides information that is specific to either a MATLAB or Visual Basic client.

For MATLAB Clients.   To see a summary of all functions available to controller applications along with the required syntax, start a MATLAB Automation server, and then use the invoke function with only the handle argument:

• handle = actxserver('matlab.application');
  handle.invoke
  

For Visual Basic Clients.   Data types for the arguments and return values of the server functions are expressed as Automation data types, which are language-independent types defined by the Automation protocol. For example, BSTR is a wide-character string type defined as an Automation type, and is the same data format used by Visual Basic to store strings. Any COM-compliant controller should support these data types, although the details of how you declare and manipulate these are controller specific.

Connecting to an Existing Server

Examples of a MATLAB Automation Server

© 1994-2005 The MathWorks, Inc.