Invoke

f90VB Modules

f90VBDefs, f90VBVariants, f90VBAutomation

Summary

Function Invoke can be used to execute methods, as well as to set or retrieve the values of the properties of an object.

Syntax

Arguments

VarObj [Input]

A variant containing a reference to the IDispatch interface of a running object.

MemberRef [Input]

Can be either a character string with the name or an integer value with the Dispatch ID (DispID) of the member function or property to be invoked.

Flags [Input]

Flags describing the context of the Invoke call. See Comments for more information.

DispatchParams [Input]

A DISPPARAMS structure containing the arguments to the invoked member function.

EInfo [Output, Optional]

A variable of type EXCEPINFO, which will contain extended error information if an error occurs during the process of executing the method.

IdxArgErr [Output, Optional]

If an error occurs due to an error in one of the arguments in OptParmtr01..OptParmtr50, this value contains the index of the offending parameter. See comments for additional information.

iRet [Output/Optional]

Upon return, iRet contains S_OK or an error code.

Comments

The Invoke function is almost a direct wrapper around IDispatch’s Invoke method, which is the standard Automation method used to change or retrieve values of properties, and to execute the methods exposed by Automation objects. This is considered an advanced function in f90VB. We recommend you review the documentation for the Invoke method of the IDispatch interface (in the COM SDK) before you use it

In most cases f90VB’s PropertyPut, PropertySet, PropertyGet and ExecMethod are the more convenient options to manipulate object’s properties and methods, but these functions have some limitations:

PropertyPut, PropertySet, PropertyGet and ExecMethod have a limit in the number of arguments that can be passed to access objects properties and methods (each of these procedures can handle up to 50 arguments). The limit in the number of arguments is so high that it usually does not represent a problem. In the unusual cases in which you need to call a method that needs more than 50 arguments, the only option is to use function Invoke.

PropertyPut, PropertySet, PropertyGet and ExecMethod cannot handle named arguments. All arguments to these procedures are positional. Invoke can handle named arguments through the standard convention for passing arguments in the DISPPARAMS structure.

PropertyPut, PropertySet, PropertyGet and ExecMethod create a DISPPARAMS structure with the arguments you pass, so they can be related to the IDispatch’s Invoke member function. When you call f90VB’s Invoke function, you are already passing the constructued DISPPARAMS structure. So you can eliminate a little bit of processing overhead by using f90VB’s Invoke function rather than PropertyPut, PropertySet, PropertyGet and ExecMethod.

Argument MethodRef

This is the argument used to identify the method to execute. You can either pass the name of the method as a character string, or the method’s DispID, which is a number used by OLE to internally identify properties and methods exposed by an object.

The performance of function Invoke is strongly affected by whether you use a character string with the method name or the DispID of the method. In the first case, function Invoke must internally call IDispatch::GetIDsOfName, to search for the DispID corresponding to the requested method. On the other hand, when Invoke is called with a DispID this step is omitted, and so the function performs much faster. This difference in performance can become particularly obvious when Invoke is called many times for the same method. You can easily get the DispIDs of all methods and properties of an object in a single operation by calling f90VB subroutine EnumerateMembers.

When dealing with hierarchies of objects, argument MethodRef can contain a path through the hierarchy, as long as the path does not need to use arguments (see examples of these cases in PropertyGet and PropertyPut).

Argument Flags

The Flags argument is used to describe the context of the member function invoked. The following values are allowed:

Argument DispatchParams

DispatchParams is used to pass or receive arguments to or from the invoked member function. DispatchParams is a structure of type DISPPARAMS:

    type DISPPARAMS

        sequence

        integer(POINTER_KIND)::rgvarg 

        integer(POINTER_KIND)::rgdispidNamedArgs 

        integer(LONG_KIND)::cArgs 

        integer(LONG_KIND)::cNamedArgs 

    end type

Field cArgs contains the total number of arguments the client application is passing to the invoked method. If the application is passing named arguments to the invoked method, cNamedArgs contains the number of these arguments. Field rgvarg is a pointer to an array of variant values, each containing one of the arguments passed to the invoked method or property. The arguments are stored in inverse order, so the last argument appears as the first entry of the array. rgdispidNamedArgs is a pointer to an array containing the IDs of named arguments included in rgvarg. Array rgvarg must contain an entry for each argument in the invoked member function. This also includes any optional arguments in the invoked method or property. If a controller does not want to use an optional argument in the invoked member function, it must pass a variant of type VT_ERROR with content DISP_E_PARAMNOTFOUND for this argument. Argument DispatchParams is used to handle all the arguments of invoked methods, or the new value of a property put or set invocation. Methods that change the content of an argument must receive a variant with the VT_BYREF flag set.

Argument EInfo

EInfo is a structured type used to describe IDispatch exceptions and errors. The EXCEPINFO type has the following definition:

type EXCEPINFO

     sequence

     integer(WORD_KIND)::wCode           

     integer(WORD_KIND)::wReserved 

     integer(BSTRHNDL_KIND)::bstrSource 

     integer(BSTRHNDL_KIND)::bstrDescription 

     integer(BSTRHNDL_KIND)::bstrHelpFile 

     integer(DWORD_KIND)::dwHelpContext 

     integer(POINTER_KIND)::pvReserved 

     integer(POINTER_KIND)::pfnDeferredFillIn 

     integer(LONG_KIND)::scode

end type EXCEPINFO

When this argument is passed and the invoked member produces an error, EInfo is filled with more descriptive error information. See Table 6.2 of the f90VB User Manual for more information about the content of the structure.

Argument IdxArgErr

If an error condition results as a consequence of an erroneous or incompatible value passed in DispatchParams, Invoke returns the index of the offending argument in IdxArgErr. Note that the index identifies the argument in the same order that arguments are passed in DispatchParams (i.e. in inverted order).

Examples

!This example is the same as Example 6.1, but using

!Invoke rather than PropertyPut and ExecMethod

!Copyright (C) 1999-2000, Canaima Software, Inc.

use f90VBDefs

use f90VBVariants

use f90VBAutomation

!Variants containing main objects

type(VARIANT)::IE

!Variants used to stored temporal objects and collections

type(VARIANT)::VarTmp,URL

!Dispatch parameters structure

type(VARIANT)::Args(5)

type(DISPPARAMS)::DP

integer(LONG_KIND)::NamedArgs(5)

integer(HRESULT_KIND)::iRet

integer::i

real::k

print *,'NOTE: This program works only if you already have an '

print *,'      open dial-up connection or a permanent internet'

print *,'      connection'

!Initialize Ole

iRet = OleInitialize()

!Get an instance of Internet Explorer

IE = CreateOleObject('InternetExplorer.Application', iRet)

!Set the DISPPARAMS structure for property Visible

!PropertyPut always have at least one named 

!argument with DispID=DISPID_PROPERTYPUT

Args(1)=VariantCreate(VT_BOOL,.true.)

NamedArgs(1)=DISPID_PROPERTYPUT

DP%rgvarg = loc(Args)

DP%cArgs=1

DP%rgdispidNamedArgs=loc(NamedArgs)

DP%cNamedArgs=1

!Set property using Invoke. This is equivalent to the 

!following PropertyPut call:

!call PropertyPut(IE,'Visible',Args(1),iRet=iRet)

VarTmp= Invoke(IE,'Visible',DISPATCH_PROPERTYPUT, DP,iRet=iRet)

!Set the DISPPARAMS structure for method Navigate

!removing named argument used in previous Invoke

DP%cNamedArgs=0

Args(1)=VariantCreate(VT_BSTR,'www.canaimasoft.com/f90VB/index.htm')

!call method Navigate using Invoke. This is equivalent to the

!following ExecMethod call:

!VarTmp = ExecMethod(IE,'Navigate',Args(1),iRet=iRet)

VarTmp = Invoke(IE,'Navigate',DISPATCH_METHOD, DP,iRet=iRet)

!Release the instance to IE, leaving the browser on

call Release(IE)

!Clean up variants

call VariantClear(URL)

call VariantClear(VarTmp)

!Uninitialize Ole

call OLEUninitialize()

stop

end

Related Topics

NullGUID