Rapid-Q Documentation by William Yu (c)1999, appended by John Kelly Chapter 15

15. COM Programming

Component Object Model (COM) and Distributed COM (or DCOM), is a specification that defines object creation and communication between objects. Rapid-Q only supports client-side COM programming (ie. you will not be able to create COM servers in Rapid-Q). Also, not all COM interfaces are supported. Most likely this component uses the IDispatch interface that is common to Visual Basic. Expect several bugs in the QOLEOBJECT and QOLECONTAINER components, and some EVENTS are not detected. 

If you need some background on COM programming look at "COM tutorial" and the IUnknown interface in this CHM help file. Programming alternatives are BCX, RealBasic, FSBL, etc. Possibly FreeBasic will become COM compliant in the future. Another option is to download B2C which converts VB code into visual C++ code. Then you compile that with the free visual C++ toolkit. There are some limitations to the B2C. see http://support.microsoft.com/kb/216388 
the free VC++ toolkit is at: http://msdn.microsoft.com/visualc/vctoolkit2003/default.aspx

15.1 Supported COM extensions
COM has many extended services which have grown over time. Unfortunately Rapid-Q is limited to only a few:
  • COM clients (or Automation controllers) is implemented in QOLEOBJECT
  • Active Documents is implemented in QOLECONTAINER
Automation controllers can be used to drive automation servers such as MS WORD over a local machine or remotely. So what are the benefits of automating a server? Well, since the server can be invoked by another machine, this can free up resources and CPU cycles needed on your client system. Since you could automate an application from across a network (or the internet), you don't need the application to reside on your machine to do some useful work on it. Imagine automating machinery from your home. Active documents is similar to automation, however, the "document" (more like ActiveX control) is embedded into your application. Once embedded, you can use automation to control the behaviour of the document. Rapid-Q does not support Type Libraries, so vtable binding is not possible. Speaking of binding, a COM server is usually registered on your computer the first time it is run or installed. For .DLLs or .OCXs, this may not always be the case, so to register a COM server manually, you can use Window's regsvr32 program.
    regsvr32 myprog.dll
You can type that in your MS-DOS command line prompt, or via Start|Run. There are also programming examples to register a COM object, see the Windows API help file for more information.

As mentioned in the previous section, QOLEOBJECT implements an automation controller. This component works similarly to VB (no, VB does not have a QOLEOBJECT component), except for a few things which are either implemented in another way or is not yet supported. Let's look at some examples comparing the 2 methods:

    ' Both examples invoke MS WORD
    ' in VB

    Set Obj = CreateObject("Word.Basic")
    ' or just DIM Obj AS Word.Basic

    ' in Rapid-Q

Note that type checking is off for OBJECT and QOLEOBJECT, so when you invoke Obj.AppShow this calls the method AppShow in MS WORD. You may notice that Rapid-Q also supports the Invoke method. This is to eliminate ambiguity but also to provide a work around. So what if MS WORD has a method called CreateObject? In Rapid-Q this causes a problem since CreateObject is a valid method of QOLEOBJECT, so that method will be called, not the one in MS WORD. The work around is to use the Invoke method.
    ' in Rapid-Q

    Obj.Invoke("CreateObject") ' Call CreateObject method in MS WORD
Obviously you shouldn't run the above example, MS WORD doesn't have a CreateObject method, but you get the idea. Setting and getting properties can be done similarly:
    ' in Rapid-Q

    Obj.AutoStart = 1
    Obj.Invoke("AutoStart") = 1 ' this also works
So what's not supported in Rapid-Q? Several data types and arrays are not supported yet, as well as events. Also there isn't a "set" method available. ie:
    ' in VB
    DIM ADOCommand AS ADODB.Command
    DIM ADOConnection AS ADODB.Connection

    set ADOCommand.ActiveConnection = ADOConnection
The line in red is not yet available in Rapid-Q. See the Appendix section on QOLEOBJECT, you will find a method called InvokeCopy which does the samething, but unfortunately isn't fully functional as of this writing.

QOLECONTAINER is basically a container for embedding ActiveX components or Active documents. This component is very similar to QOLEOBJECT, it is again type check free, so you can automate the control like you would automating servers. You may find yourself using the Invoke method more often than not, since QOLECONTAINER does have a lot of properties and methods already defined. Another way to avoid this problem is the assign the Container method of QOLEOBJECT. This creates a reference to the object, and so you can use QOLEOBJECT to automate the control. For those that aren't familiar, ActiveX controls are reusable visual controls which are heavily used in VB. Again, the limitations are obvious, Rapid-Q doesn't support ActiveX events, type libraries, and a few others mentioned before.
    '-- A short example

    Obj.Parent = Form
Since an ActiveX control is a visible component, you'll note that the QOLECONTAINER requires a parent property. You'll also have to be wary of the fact that the ActiveX component could update/refresh the component even before the form is shown, so you'll receive a Can't focus a disabled or invisible window when that happens. QOLECONTAINER has an AutoShow property which can be set to False meaning that the ActiveX control should not be displayed when created. You can use the method Show of QOLECONTAINER to display the control at anytime after creating the object. There is also another way to avoid the error message from popping up, see the Appendix section on QOLECONTAINER for a complete example.

Prev Chapter Contents Next Chapter