External Interfaces/API

MATLAB COM Automation Methods

This section lists the methods that are supported by the MATLAB Automation Server. The data types for the arguments and return values 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.

BSTR Execute([in] BSTR Command);

This command accepts a single string (Command), which contains any command that can be typed at the MATLAB command window prompt. MATLAB will execute the command and return the results as a string. Any figure windows generated by the command are displayed on the screen as if the command were executed directly from the command window or an M-file. A Visual Basic example is

• Dim MatLab As Object
  Dim Result As String
  Set MatLab = CreateObject("Matlab.Application")
  Result = MatLab.Execute("surf(peaks)")
  
  void GetFullMatrix(
      [in] BSTR Name,
      [in] BSTR Workspace,
      [in, out] SAFEARRAY(double)* pr, 
      [in, out] SAFEARRAY(double)* pi);
  

Note    The first statement above should be declared in the general declarations section in order to keep the scope throughout the application.

This method retrieves a full, one- or two-dimensional real or imaginary mxArray from the named workspace. The real and (optional) imaginary parts are retrieved into separate arrays of doubles.

Name.   Identifies the name of the mxArray to be retrieved.

Workspace.   Identifies the workspace that contains the mxArray. Use the workspace name "base" to retrieve an mxArray from the default MATLAB workspace. Use the workspace name "global" to put the mxArray into the global MATLAB workspace. The "caller" workspace does not have any context in the API when used outside of MEX-files.

pr.   Array of reals that is dimensioned to be the same size as the mxArray being retrieved. On return, this array will contain the real values of the mxArray.

pi.   Array of reals that is dimensioned to be the same size as the mxArray being retrieved. On return, this array will contain the imaginary values of the mxArray. If the requested mxArray is not complex, an empty array must be passed. In Visual Basic, an empty array is declared as
Dim Mempty() as Double. A Visual Basic example of this method is

• Dim MatLab As Object
  Dim Result As String
  Dim MReal(1, 3) As Double
  Dim MImag() As Double
  Dim RealValue As Double
  Dim i, j As Integer
  rem We assume that the connection to MATLAB exists.
  Result = MatLab.Execute("a = [1 2 3 4; 5 6 7 8;]")
  Call MatLab.GetFullMatrix("a", "base", MReal, MImag)
  For i = 0 To 1
      For j = 0 To 3
      RealValue = MReal(i, j) 
      Next j
  Next i
  
  void PutFullMatrix(
      [in] BSTR Name, 
      [in] BSTR Workspace, 
      [in] SAFEARRAY(double) pr, 
      [in] SAFEARRAY(double) pi);
  

Note    The first statement above should be declared in the general declarations section in order to keep the scope throughout the application.

This method puts a full, one- or two-dimensional real or imaginary mxArray into the named workspace. The real and (optional) imaginary parts are passed in through separate arrays of doubles.

Name.   Identifies the name of the mxArray to be placed.

Workspace.   Identifies the workspace into which the mxArray should be placed. Use the workspace name "base" to put the mxArray into the default MATLAB workspace. Use the workspace name "global" to put the mxArray into the global MATLAB workspace. The "caller" workspace does not have any context in the API when used outside of MEX-files.

pr.   Array of reals that contains the real values for the mxArray.

pi.   Array of reals that contains the imaginary values for the mxArray. If the mxArray that is being sent is not complex, an empty array must be passed for this parameter. In Visual Basic, an empty array is declared as Dim Mempty() as Double. A Visual Basic example of this method is

• Dim MatLab As Object
  Dim MReal(1, 3) As Double
  Dim MImag() As Double
  Dim i, j As Integer
  For i = 0 To 1
      For j = 0 To 3
      MReal(i, j)  = I * j;
      Next j
  Next I
  rem We assume that the connection to MATLAB exists.
  Call MatLab.PutFullMatrix("a", "base", MReal, MImag)
  

Note    The first statement above should be declared in the general declarations section in order to keep the scope throughout the application.

MATLAB Automation Server Support

MATLAB Automation Properties