How do you call a DISPATCH METHOD?

To call a Method through the DISPATCH interface, you will use the OBJECT statement. This differentiates it from direct access, so PowerBASIC can handle your request in the appropriate manner.

There are five general forms of the OBJECT statement:

OBJECT GET	Retrieve the value of a PROPERTY. This is similar to retrieving the value of a variable.
OBJECT LET	Write a value to a PROPERTY. This is similar to assigning a value to a variable.
OBJECT SET	Write an object reference to a PROPERTY. This is similar to assigning to an object variable.
OBJECT CALL	Call a DISPATCH METHOD. This is equivalent to calling a standard Sub or Function.
OBJECT RAISEEVENT	Call an EVENT METHOD. (Event Methods are fully covered in a later section).

OBJECT GET DispVar.Prop1 TO ResultVar
OBJECT LET DispVar.Prop1 = NewValue
OBJECT SET DispVar.Prop1 = NewReference
OBJECT CALL DispVar.Meth1(param1, TEXT=MyStr$$)
OBJECT RAISEEVENT EventMeth1

All parameters, return values, and assignment values must be in the form of COM-compatible variables. Literals and expressions are not allowed. COM-compatible variables include BYTE, WORD, DWORD, INTEGER, LONG, QUAD, SINGLE, DOUBLE, CURRENCY, OBJECT, STRING, WSTRING, and VARIANT. You should use caution passing string data since COM Objects assume that Unicode format is used. When string data is contained in a VARIANT variable, conversion to/from Unicode is automatic, and no intervention is needed from the programmer. However, if you pass data in a dynamic string variable, you must use the ACODE$() and UCODE$() functions to convert the data to an appropriate format.

The OBJECT statement can use both positional and named parameters, but you should keep in mind that not all COM Dispatch Servers support named parameters. Positional parameters are universally supported.

A positional parameter is a variable containing an appropriate value. It is identified by its position in the parameter list, just as in a traditional SUB or FUNCTION. A named parameter consists of a parameter identifier (a name), an equal (=) sign, and a variable containing an appropriate value. Positional parameters must precede any and all named parameters, but named parameters may be specified in any sequence.

Each time you call a Method or Property using the OBJECT statement, a status code is returned in a hidden parameter to indicate the success or failure of the operation. You can retrieve information about this status code with the OBJRESULT function, and also by using the IDISPINFO Dispatch Information Object. If the failure was severe, then a PowerBASIC error 99 (Object Error) is also generated and the ERR system variable is set. You can find more information about these items by referring to OBJRESULT, IDISPINFO, and ERR.