OBJECT statement

Purpose

Communicate with a COM object through the dispatch interface.

Syntax

OBJECT GET interface.member[.member…] [([[paramname =] vrntparam1 _

    [, ...]])] TO vrntresult

OBJECT LET interface.member[.member…] [([[paramname =] vrntparam1 _

    [, ...]])] = vrntvalue

OBJECT SET interface.member[.member…] [([[paramname =] vrntparam1 _

    [, ...]])] = vrntvalue

OBJECT CALL interface.member[.member…] [([[paramname =] vrntparam1 _

    [, ...]])] [TO vrntresult]

Remarks

There are four general forms of the OBJECT statement which are used to communicate through an exposed COM interface to a COM object.

OBJECT GET

Retrieve or read the value of an Interface member Property. This is similar to retrieving the value of a variable.

OBJECT LET

Assign or write a value to an Interface member Property. This is similar to assigning a value to a variable.

OBJECT SET

Assign or write a value to an Interface member Property that contains a reference to an object.  For example, a reference to another Interface.

OBJECT CALL

Call or execute a member Method of an Interface.  This is equivalent to calling a Sub or Function.

All parameters, return values, and assignment values must be in the form of Variant variables.  Dispatch object Method calls are bound at run-time, and require no declaration of Properties and Methods.  However, for this reason, the validity of these references is also not checked at compile-time.

The OBJECT statement can use both positional and named parameters, but you should keep in mind that while most COM Dispatch Servers support named parameters, it is not universal.

A positional parameter is simply a Variant variable containing an appropriate value.  A named parameter consists of a parameter identifier, an equal (=) sign, and a Variant variable containing an appropriate value.  Positional parameters must precede any and all named parameters, but named parameters may be specified in any sequence.

Restrictions

All parameters, return values, and assignment values must be in the form of variant variables.  If an error occurs during an OBJECT statement, the ERR system variable is set.  An extended COM error code can be retrieved from the OBJRESULT variable, and this can be useful for both debugging and handling run-time errors.

Using the wrong member mode (GET/LET/SET/CALL) can result in unexpected and fatal run-time errors in some situations.  For example, a member method (OBJECT CALL) is expected to return an Interface reference via a variant return variable, but a programming error specifies an OBJECT GET statement instead.  When used correctly, the variant variable would contain the Interface reference as the return result, but because of the programming and subsequent run-time error that occurs, the variant's content is considered undefined.  At this point, attempting to assign the undefined variant to an object variable will likely trigger a General Protection Fault (GPF).

So, test the result code in OBJRESULT and ERR after an OBJECT statement, in order to detect such run-time failures.

See also

DIM, CLSID$, GUID$, GUIDTXT$, INTERFACE/END INTERFACE, ISNOTHING, ISOBJECT,  OBJACTIVE, OBJPTR, OBJRESULT, PROGID$, SET

Example

' (Assumes Interface definitions have been declared

'  for the IVSSDatabase and IVSSItem Interfaces)

DIM Ini       AS VARIANT

DIM User      AS VARIANT

DIM Password  AS VARIANT

DIM tVnt1     AS VARIANT

DIM tVnt2     AS VARIANT

DIM tVnt3     AS VARIANT

 

' Use early-binding to IVSSDatabase and IVSSItem

DIM oVss1     AS IVSSDatabase ' Interface name

DIM oVss2     AS IVSSItem     ' Interface name

 

' Create a new instance of the COM Object

LET oVss1 = NEW IVSSDatabase IN $COMServer

IF ISOBJECT(oVss1) = 0 THEN EXIT FUNCTION

 

' Log in to the Database

Ini       = ""

User      = "MyUserName"

Password  = "MyPassword

OBJECT CALL oVss1.Open(Ini, User, Password)

IF OBJRESULT <> 0 THEN GOTO ErrorHandler

 

' Get an Interface reference for the root item

tVnt1 = "$/"

OBJECT GET oVss1.VSSItem(spec=tVnt1) TO tVnt2

IF OBJRESULT <> 0 THEN GOTO ErrorHandler

 

' Assign the Interface to an object variable

LET oVss2 = tVnt2

IF ISOBJECT(oVss2) = 0 THEN GOTO ErrorHandler

 

' Get the .Count Property value from the Interface's .Items() member Property

tVnt3     = 0

OBJECT GET oVss2.Items(tVnt3).Count TO tVnt3

IF OBJRESULT <> 0 THEN GOTO ErrorHandler

 

' Convert the result to a non-Variant variable

Count& = VARIANT#(tVnt3)