External Interfaces/API

Invoking Methods

Use these MATLAB functions to find out what methods a COM object has and to invoke any COM or MATLAB method on that object.

Function	Description
invoke	Invoke a method or display a list of methods and types
methods	List all method names for the control or server
methodsview	GUI interface to list information on all methods and types

The invoke function either invokes a method or returns information on the methods implemented for a COM object or available through an interface. Create a Microsoft Calendar control and use invoke without arguments to return a list of all methods for the control:

• cal = actxcontrol('mscal.calendar', [0 0 500 500])
  cal =
     COM.mscal.calendar
  
  invoke(cal)
     NextDay = HRESULT NextDay(handle)
     NextMonth = HRESULT NextMonth(handle)
     NextWeek = HRESULT NextWeek(handle)
     NextYear = HRESULT NextYear(handle)
     PreviousDay = HRESULT PreviousDay(handle)
     PreviousMonth = HRESULT PreviousMonth(handle)
     PreviousWeek = HRESULT PreviousWeek(handle)
     PreviousYear = HRESULT PreviousYear(handle)
     Refresh = HRESULT Refresh(handle)
     Today = HRESULT Today(handle)
     AboutBox = HRESULT AboutBox(handle)
  

You can invoke any of these methods on the object using the arguments shown in the returned method list. The following example reads today's date and then advances it by 50 years using the NextYear method in a loop.

To get today's date, type

• sprintf('%d/%d/%d', cal.Month, cal.Day, cal.Year)
  ans =
     11/5/2001
  

Now, use NextYear to advance the date, and then verify the results:

• for k=1:50
     NextYear(cal);
  end
  
  sprintf('%d/%d/%d', cal.Month, cal.Day, cal.Year)
  ans =
     11/5/2051
  

Graphical Methods Display

MATLAB also has a graphical user interface to view the methods of an object along with related fields of information. Type

• methodsview(h)
  

to bring up a window such as the one shown here.

Methods that return void show no Return Type in the display.

Returning Multiple Output Arguments

If you know that a server function supports multiple outputs, you can return any or all of those outputs to a MATLAB client. Specify the output arguments within brackets on the left-hand side of the equation. This gives the MATLAB client code access to any values returned by the server function.

The syntax shown here shows a server function being called by the MATLAB client. The function's return value is shown as retval. The function's output arguments (out1, out2, ...) follow this.

• [retval out1 out2 ...] = functionname(handle, in1, in2, ...);
  

MATLAB makes use of the pass by reference capabilities in COM to implement this feature. Note that pass by reference is a COM feature. It is not available in MATLAB at this time.

Argument Callouts in Error Messages

When a MATLAB client sends a command with an invalid argument to a COM server application, the server sends back an error message similar to that shown here, identifying the invalid argument. Be careful when interpreting the argument callout in this type of message.

• PutFullMatrix(handle, 'a', 'base', 7, [5 8]);
  ??? Error: Type mismatch, argument 3.
  

In the PutFullMatrix command shown above, it is the fourth argument, 7, that is invalid. (It is scalar and not the expected array data type.) However, the error message identifies the failing argument as argument 3.

This is because the COM server receives only the last four of the arguments shown in the MATLAB code. (The handle argument merely identifies the server. It does not get passed to the server). So the server sees 'a' as the first argument, and the invalid argument, 7, as the third.

As another example, submitting the same command with the invoke function makes the invalid argument fifth in the MATLAB client code. Yet the server still identifies it as argument 3 because neither of the first two arguments are seen by the server.

• invoke(handle, 'PutFullMatrix', 'a', 'base', 7, [5 8]);
  ??? Error: Type mismatch, argument 3.
  

Object Properties

COM Control Events