Invoking Methods :: COM and DDE Support (Windows Only) (External Interfaces)

External Interfaces

Invoking Methods

This section covers the following topics on how to invoke and pass arguments to class methods:

Functions for Working with Methods

Use the following MATLAB functions to find out what methods a COM object has and to invoke any of these methods on the object.

Function
Description

invoke
Invoke a method or display a list of methods and types

ismethod
Determine if an item is a method of a COM object

methods
List all method names for the control or server

methodsview
GUI interface to list information on all methods and types

Function	Description
`invoke`	Invoke a method or display a list of methods and types
`ismethod`	Determine if an item is a method of a COM object
`methods`	List all method names for the control or server
`methodsview`	GUI interface to list information on all methods and types

When using these functions, enter event names and event handler names as strings or in a cell array of strings. These names are case insensitive, but cannot be abbreviated.

Listing the Methods of a Class or Object

You can see what methods are supported by a control or server object either in a graphical display using the methodsview function, or in a returned cell array using the methods function.

Using methodsview. The methodsview function opens a new window with an easy to read display of all methods supported by the specified control or server object along with several related fields of information. Type the following to bring up a window such as the one shown below:

cal = actxcontrol('mscal.calendar', [0 0 400 400]);
cal.methodsview

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

Using methods. The methods function returns in a cell array the names of all methods supported by the specified control or server object. This includes MATLAB COM functions that you can use on the object.

When you include the -full switch in the command, MATLAB also specifies the input and output arguments for each method:

cal.methods('-full')

Methods for class COM.mscal.calendar:

release(handle, MATLAB array)
delete(handle, MATLAB array)
MATLAB array events(handle, MATLAB array)
         .
         .
HRESULT Refresh(handle)
HRESULT Today(handle)
HRESULT AboutBox(handle)

The invoke function, when called with only a handle argument, returns a similar output.

Invoking Methods on an Object

To execute, or invoke, any method on an object, use either the MATLAB invoke function, or the somewhat simpler method name syntax.

Using invoke. The invoke function executes the specified method on an object. You can use either of the following syntaxes with invoke:

v = invoke(handle, 'methodname', 'arg1', 'arg2', ...);
v = handle.invoke('methodname', 'arg1', 'arg2', ...);

See the output of methodsview for a method to see what data types to use for input and output arguments.

The following example reads today's date and then advances it by 5 years by invoking the NextYear method in a loop.

To get today's date, type

cal = actxcontrol('mscal.calendar', [0 0 400 400]);
cal.Value
ans =
   11/5/2001

Call the NextYear method to advance the date, and then verify the results:

for k = 1:5
   cal.NextYear;
end

cal.Value
ans =
   11/5/2006

Using the Method Name. Instead of using invoke, you can just use the name of the method to call it. The syntax for calling by method name is

v = handle.methodname('arg1', 'arg2', ...);

Continuing the example shown in the last section, return to the original data by going back 5 years.

for k = 1:5
   cal.PreviousYear;
end

cal.Value
ans =
   11/5/2001

Specifying Enumerated Parameters

Enumeration is a way of representing a somewhat cryptic symbolic value by using a more descriptive name that makes it clear what the value stands for. For example, a program that takes atomic numbers of elements as input will be easier to work with if the program accepts element names as input rather than requiring you to recall and pass atomic numbers for each element. You could pass the word 'arsenic' as an enumeration for the value 33.

MATLAB supports enumeration for parameters passed to methods under the condition that the type library in use reports the parameter as ENUM, and only as ENUM.

Note MATLAB does not support enumeration for any parameter that the type library reports as both ENUM and Optional.

The last line of this example passes an enumerated value ('xlLocationAsObject') to the Location method of a Microsoft Excel Chart object. You have the choice of passing the enumeration or its numeric equivalent:

e = actxserver('Excel.Application');

% Insert a new workbook.
Workbook = e.Workbooks.Add;
e.Visible = 1;
Sheets = e.ActiveWorkBook.Sheets;

% Get a handle to the active sheet.
Activesheet = e.Activesheet;

%Add a Chart
Charts = Workbook.Charts;
Chart = Charts.Add;

% Set chart type to be a line plot.
Chart.ChartType = 'xlXYScatterLines'
C1 = Chart.Location('xlLocationAsObject', 'Sheet1');

When you are dealing with only three numeric values, it is not that difficult to remember the meaning of each. But with programs that require a large number of such values, enumeration becomes more important.

Optional Input Arguments

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 calling a method with second argument (arg2) not specified is as follows:

```
handle.methodname(arg1, [], arg3);
```

The example below invokes the Add method of an Excel object. This method adds new sheets to an Excel workbook. The Add method takes up to four optional input arguments:

Before -- The sheet before which to add the new sheet
After -- The sheet after which to add the new sheet
Count -- The total number of sheets to add
Type -- The type of sheet to add

The following code creates a workbook with the default number of worksheets, and then inserts an additional sheet after Sheet 1. To do this, you invoke Add specifying only the second argument, After. You can omit the first argument, Before, by using [] in its place. This is done on the last line:

% Open an Excel Server.
e = actxserver('excel.application');

% Insert a new workbook.
e.Workbooks.Add;
e.Visible = 1;

% Get the Active Workbook with three sheets.
eSheets = e.ActiveWorkbook.Sheets;

% Add a new sheet after eSheet1.
eSheet1 = eSheets.Item(1);
eNewSheet = eSheets.Add([], eSheet1);

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 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 ...] = handle.functionname(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 is seen by the server:

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

Identifying Objects and Interfaces Object Properties