VFPCOM Utility for Visual FoxPro

The Visual FoxPro team is proud to present the VFPCOM utility as a free web download to extend Visual FoxPro interoperability with other COM and ADO components. The utility provides additional functionality when you use ADO and access COM events with your Visual FoxPro (version 5.0 and above) applications. The VFPCOM.DLL utility is a COM server, similar to those you can create in Visual FoxPro, that exposes methods to extend functionality of your application. For example, it provides the ability to change Visual FoxPro cursors to ADO recordsets. VFPCOM also lets you bind Visual FoxPro code to events exposed by COM objects (e.g., the WillMove event from an ADO recordset).

Notes for this Release

Installation and Setup

The setup prompts you for the location of your Visual FoxPro 7.0 directory. If you do not have Visual FoxPro 7.0 installed, you should change the install location to your Visual FoxPro 6.0 directory. Note: if you have a previous version of the VFPCOM utility, you can safely delete the files from the older version after you have installed the newer one.

The VFPCOM utility and sample files are installed by default in a subdirectory \VFPCOM of your Visual FoxPro root directory, however, you can install them in a different location. The installer automatically registers the VFPCOM.DLL file. If you move the file, or if CREATEOBJECT('vfpcom.comutil') fails, you should use REGSVR32.EVE to re-register VFPCOM.DLL. From the Start Menu's Run... option, type in REGSVR32.EXE <path>vfpcom.dll.

Functions

This VFPCOM server exposes the following 5 methods:

CursorToRS( )

       

Converts an existing Visual FoxPro data cursor (specified in workarea) to an ADO recordset.

Syntax

CursorToRS(oRecordSet [, cTableAlias | nWorkArea] [, lNoData ])

Arguments

oRecordSet - the object reference to the ADO recordset. This is required.

cTableAlias - the alias of the table or cursor from which data is migrated to the ADO recordset.

nWorkArea -  the work area number of the table or cursor from which data is migrated to the ADO recordset.

lNoData - if you want to create a recordset with only structure and no data, set this value to .T.

Remarks

·    CURSORTORS() returns 0 if successful.

·    General fields are not supported by this method.

·    If you specify no TableAlias or WorkArea, the method will default to the current workarea.

·    The method will overwrite any existing recordset contents. If you want to append data, append to cursor first.

·    If no cursor exists in the specified workarea, nothing happens (i.e., no change is made to the existing ADO recordset structure or contents).

Example

#DEFINE C_VFPCOMCLASS  'vfpcom.comutil'
oVFPCOM = CreateObject(C_VFPCOMCLASS)
SELECT * FROM cTableName INTO CURSOR foo
oRecordSet=CreateObject('ADODB.RECORDSET')
nError = oVFPCOM.CURSORTORS(oRecordSet)

 RSToCursor( ) 

    

Imports an existing ADO recordset to a Visual FoxPro cursor.

Syntax

RSToCursor(oRecordSet [, cAlias ])

Arguments

oRecordSet - the object reference to the ADO recordset. This is required.

cAlias - name to use when creating new Visual FoxPro cursor.

Remarks

·    If successful, a new Visual FoxPro cursor is created in the current workarea.

·    If an existing cursor is already opened in current workarea, it is automatically closed.

·    A unique cursor name is generated if the cAlias parameter is not passed.

·    The cursor generated is read/write.

·    User can create a table using the COPY TO command afterwards.

Example

#DEFINE C_VFPCOMCLASS  'vfpcom.comutil'
oVFPCOM = CreateObject(C_VFPCOMCLASS)
oRecordSet = CreateObject('ADODB.RECORDSET')
oRecordSet.CursorType = 3 && adOpenStatic Also adOpenForwardOnly
oRecordSet.LockType = 1   && adLockReadOnly
oRecordSet.Open('SELECT * FROM AUTHORS', + ;
   'Provider=sqloledb;Server=MYSQL1;' + ;
   'Initial Catalog= pubs;UId=sa;PWD=; ')
nError = oVFPCOM.RSToCursor(oRecordSet, 'mycursor')
BROWSE

ExportEvents( )

        

Exports the event interface of a COM server to that of a Visual FoxPro class in a text file.

Syntax

ExportEvents(oCOMObject, cFileName )

Arguments

oCOMObject - the object reference to the COM object whose events you want to export.

cFileName - the text file name to which you want to export the class definition and events.

Remarks

·    If the file already exists, it is overwritten.

Example

#DEFINE C_VFPCOMCLASS  'vfpcom.comutil'
oVFPCOM = CreateObject(C_VFPCOMCLASS)
oOutlook = CreateObject("Outlook.Application")
oVFPCOM.ExportEvents(oOutlook,"C:\OutlookHandler.prg")
RELEASE ALL
MODIFY COMMAND C:\OutlookHandler.prg

Sample Output

DEFINE CLASS ApplicationEvents AS custom

      PROCEDURE ItemSend(Item,Cancel)
      * Add user code here
      ENDPROC

      PROCEDURE NewMail()
      * Add user code here
      ENDPROC

      PROCEDURE Reminder(Item)
      * Add user code here
      ENDPROC

      PROCEDURE OptionsPagesAdd(Pages)
      * Add user code here
      ENDPROC

      PROCEDURE Startup()
      * Add user code here
      ENDPROC

      PROCEDURE Quit()
      * Add user code here
      ENDPROC

ENDDEFINE

BindEvents( )

       

Binds COM server events to equivalent named methods on a Visual FoxPro object. This allows users to write user-executable Visual FoxPro code for events on objects such as ADO Recordsets and Connections.

Syntax

BindEvents(oCOMObject, oVFPObject )

Arguments

oCOMObject - the object reference to the COM object whose events you want to bind.

oVFPObject - the object reference to the Visual FoxPro event sink object which contains user-defined method code that maps to the corresponding COM object events.

Remarks

·    A valid COM object must be passed. We will not support Visual FoxPro native objects.

·    Multiple COM objects can be bound to the same Visual FoxPro events sink object. In addition, the same COM object can be bound to multiple Visual FoxPro objects.

·    The instance of VFPCOM.COMUTIL being used for a BindEvents call needs to be scoped with a lifetime at least as long as all the VFP object(s) using the BindEvents event binding. This means that VFP objects used in BindEvents must either be unbound using UnbindEvents or released from memory BEFORE the instance of VFPCOM.ComUtil is released. If the object instance to VFPCOM. COMUTIL is released before associated VFP object(s) bound to COM events (via BindEvents), VFP can cause an exception failure. You can ensure that the VFPCOM utility object is properly scoped for use with BindEvents by instantiating it with a PUBLIC variable or to a form property, e.g., oForm.oVFPCOM = CREATEOBJECT('VFPCOM.COMUTIL').

·     Event handling will automatically be unbound when either the Visual FoxPro or COM object reference is released. Users can explicitly call the UnBindEvents() function to unbind objects without the necessity of releasing object references.

Example

#DEFINE C_VFPCOMCLASS  'vfpcom.comutil'
oVFPCOM = CreateObject(C_VFPCOMCLASS)
oRecordSet = CreateObject('ADODB.RECORDSET')
oRecordSet.CursorType = 3 && adOpenStatic
oRecordSet.LockType = 1 && adLockReadOnly
oRecordSet.Open('SELECT * FROM AUTHORS', + ;
   'Provider=sqloledb;Server=MYSQL1;' + ;
   'Initial Catalog= pubs;UId=sa;PWD=; ')
oEvents = CreateObject('adoevents')
nError = oVFPCOM.BindEvents(oRecordSet, oEvents)
oRecordSet.MoveNext

DEFINE CLASS adoevents AS Session

      PROCEDURE WillMove(adReason, adStatus, pRecordset)
            WAIT WINDOW 'Moving one record...' NOWAIT
      ENDPROC

ENDDEFINE

UnBindEvents( )

    

Unbinds event objects setup using the BindEvents( ) function.

Syntax

UnBindEvents(oCOMObject, oVFPObject )

Arguments

oCOMObject - the object reference to the COM object whose events you want to unbind.

oVFPObject = the object reference to the Visual FoxPro event sink object which contains user-defined method code which maps to corresponding COM object events.

Remarks

·    Same rules apply as BindEvents function.

·    An error is returned if invalid object references are passed.

Samples

VFPCOM0 - this is a simple program you can run to see how each of the 5 methods in the VFPCOM.DLL server utility works.Examine the code in this program for ideas about using this utility in your applications. To execute this sample, run the VFPCOM0.PRG program.

VFPCOM1 -this sample shows you how to use BindEvents, UnBindEvents, and ExportEvents to execute Visual FoxPro code for events that occur in a web page using IE5 (Internet Explorer 5.0 or higher). The VFPCOM1.SCX form contains several VFP controls and the IE5 Web Browser control (you must have IE5 or higher installed to run this sample).

When you run VFPCOM1.PRG, it launches the VFPCOM1.SCX form which opens VFPCOM1.HTM in the form's web browser control. Then, when the document is loaded (see oleWebBrowser.DocumentComplete event code), VFP class code in VFPCOM1.PRG binds to various HTML elements in the web page using BindEvents. When you click on the HTML button, you'll see a WAIT WINDOW. You should also see all events for that HTML element stream out to the VFP desktop. If you type text in either the VFP textbox or the HTML textbox, you'll see that it automatically updates the other textbox. Click the HTML anchor hyperlink, and you will notice that no code fires in the web page. Rather, event code fires from the VFP object that executes MODIFY COMMAND VFPCOM1.PRG displaying the source code for this example.

This sample also shows advanced examples of how to properly scope VFPCOM.COMUTIL when using BindEvents, and where to place the BindEvents and UnBindEvents calls. If the UnBindEvents methods are not called as in this example, you will leave references of the VFP event binding objects in VFP memory.

ADOTEST - this is a great example of how you can use ADO recordsets in your application. The form uses several classes from the VFPADO.VCX class library. These classes (adoConnection and adoRecordset) are Visual FoxPro classes with an event interface that corresponds to that of the ADO connection and recordset objects created and used by the form. The classes are used to bind to events triggered by the ADO connection and recordset objects. For example, when you click on a navigation button, the adoRecordset MoveComplete method is automatically called since that object is bound to the ADO recordset object via BindEvents(). The MoveComplete method controls the enabling/disabling of navigation buttons, depending on location of the record pointer in the recordset. This sample uses a connection string to the Northwind sample database which ships with SQL Server. To execute this sample, run the ADOTEST.SCX form.

When you run this sample, change the Connection String to point to a data source that you have available  (i.e., Data Source=JVP).

Distribution

You are allowed to distribute VFPCOM.DLL with your Visual FoxPro run-time applications.

Product Support

The VFPCOM Utility is provided as is and supported minimally by the Visual FoxPro Product Support group. Support for this utility is limited to setup and usage issues. Use Support Online to search the Microsoft Knowledge Base and other technical resources for fast, accurate answers. For additional technical resources and information on developing with Microsoft products and technologies, visit MSDN Online.

File List

vfpcom.dll - VFPCOM utility
vfpcom0.prg - program for VFPCOM0 sample
vfpcom1.prg - program for VFPCOM1 sample
vfpcom1.htm - web page for VFPCOM1 sample
vfpcom1.scx - form for VFPCOM1 sample
vfpcom1.sct - form for VFPCOM1 sample
vfpado.vcx - class library for ADOTEST sample
vfpado.vct - class library for ADOTEST sample
adotest.scx - form for ADOTEST sample
adotest.sct - form for ADOTEST sample
adovfp.h - include file for ADOTEST sample
vfpcom.htm - readme file


© 2001 Microsoft Corporation. All rights reserved. Terms of Use.