Manipulating the object through its properties and methods

Once you have secured a dispatch interface to the object, you can start sending requests to the object. In Example 6.1 we only perform two operations; first we set the visible property of Internet Explorer to true, to make the browser appear on the screen. By default most automation servers are started in invisible mode (i.e. they are loaded, but you don’t see them on the desktop). To set properties you use subroutine PropertyPut:

call PropertyPut(IE,'Visible',VariantCreate(VT_BOOL,.true.),iRet=iRet)

Note that the first argument is the variant variable containing the reference to the object (IE), and the second argument is a character string with the name of the property you are changing. The third argument is the new value for the property. The new value for the property is always passed as a variant variable, which in this case is created on-the-fly by using the f90VB VariantCreate function. In Visual Basic, the call to PropertyPut shown above is equivalent to the following statement:

IE.Visible = True

Some objects expose indexed properties. For these cases, in addition to the new value for the property you must also pass an index. To do this with subroutine PropertyPut, you pass the index (or indexes) as variant variables following the argument with the new property value.

If the value of the property is changed successfully, PropertyPut returns S_OK in argument iRet. If an error occurs, for example, if the object does not have a property with the indicated name, argument iRet will contain a negative value indicating the reason for the error. If you need more descriptive information for errors, you can call subroutine PropertyPut with an Exception Information structure. For example:

…

type(EXCEPINFO)::ExInfo

…

call PropertyPut(IE,'Visible',VariantCreate(VT_BOOL,.true.), &

                 iRet=iRet, Einfo=ExInfo)

Example 6.1 also executes Internet Explorer’s Navigate method. This method requests that Internet Explorer load a web page. In Visual Basic, you would call this method as follows:

IE.Navigate “http:://www.canaimasoft.com/f90vb”

In f90VB, object methods are executed by calling function ExecMethod:

URL=VariantCreate(VT_BSTR,'www.canaimasoft.com/f90VB')

VarTmp = ExecMethod(IE,'Navigate',URL,iRet=iRet)

Note that ExecMethod is a function and not a subroutine. Many methods exposed by objects return values so they must be called as functions rather than subroutines. In those cases in which an invoked method returns a value, this value is returned as the result of the ExecMethod function. The value is always returned as a variant variable. If the invoked method does not have a return value, ExecMethod returns an empty variant (i.e. a variant of type VT_EMPTY).

Note that, as is the case for PropertyPut, the first argument to ExecMethod is the variant containing the reference to the object; and the second argument is the name of the method. The third argument and subsequent parameters in function ExecMethod are the arguments necessary to execute the invoked method in the object. In this case, method Navigate only needs one argument, the URL you are directing the browser to load. Also, as is the case for PropertyPut, all arguments passed to the invoked object’s method are passed as variant variables. So we create a variant variable (URL) containing a BString with the address of the page to load, and pass this variable to ExecMethod [39].

If the object’s method invoked through ExecMethod does not exist, the passed arguments are invalid, or the method produces an exception, function ExecMethod returns an error condition on iRet.