Converting Your Existing Applications to Visual FoxPro 3.0

Thinking of converting your existing FoxPro 2.6 applications to Visual FoxPro 3.0? Check here for information on how to start using the new Visual FoxPro 3.0 features while still leveraging your existing development investment.

Introduction
Converting Projects
Visual Form Conversion
Deciding Between Visual or Functional Conversion
What Can Cause Conversion Problems
Conclusion


Introduction

Visual FoxPro 3.0 has opened up a wealth of new developer tools that can only be considered as revolutionary for the FoxPro programmer. From object orientation to visual form and class tools, the whole application scheme has been revamped. Even though the Visual FoxPro environment provides a whole new way of doing things, your existing FoxPro 2.6 application can be almost seamlessly integrated into this brave new developer environment. The expansiveness of the new Visual FoxPro features can be daunting, but this is mitigated by the conversion utilities built into the product. This paper will look at how you go about converting your existing 2.6 application in Visual FoxPro. With this conversion you can start using these wonderful new features while still leveraging your existing development investment.

Successful conversion of an application requires planning how the components of the application will be converted. The decision process is two-fold. First, it must be decided if you want to take the default, Functional conversion, that completely converts the 2.6 screen to a backwardly compatible Visual FoxPro form set, or Visual conversion, which entails running the 2.6 coded .SPR file and manually implementing the converted form set. Secondly, decisions have be made on how you wish to incorporate the new extensions found in Visual FoxPro. The second question directly affects the first, of Visually or Functionally converting your screens. However, no matter what conversion route you choose, the conversion will run your existing application AS IS, in the new Visual FoxPro environment.

The areas affected by conversion include projects, forms, reports, labels and code. The most intensive area is what used to be known as screens in FoxPro 2.6 and are now known as forms in Visual FoxPro. However, we will take a top down approach by looking at converting a project first and then working our way through the other components.

---

Converting Projects

Conversion of a project from 2.6 to Visual FoxPro starts by opening the 2.6 project in Visual FoxPro. Visual FoxPro will recognize the file is a 2.6 .PJX file and process it through the CONVERT.APP application. This CONVERT.APP application is installed by default in the Visual FoxPro home directory. Upon starting the conversion utility, a dialog box, as depicted below, is presented to the developer.



This conversion dialog box is very much like the dialog box that is presented to you when you open a non-converted 2.6 .SCX screen file.

The first option of the dialog box relates to if and where backup copies of pre-converted 2.6 screen sets are copied to. Before converting the 2.6 screen to a Visual FoxPro form, CONVERT.APP will create a directory OLD, off of the designated one.

The second option allows the specification of a log file. This is a text file with the suffix .LOG and contains a recap of the conversion process. The information includes: if conversion took place, elapsed time of the conversion, whether the conversion was successful or not, and error messages related to unsuccessful conversion. If problems occur during conversion, this log will be the source of detail for those errors.

Selecting Functional or Visual conversion is the area of most concern for the developer in converting their applications. Both conversion methods allow you to simply convert your application, build it and the run the resulting .APP or .EXE file, the differences between the methods come into play when you start implementing and extending the converted form.

The Functional conversion creates the most hands-off type of conversion, but can cause more work when extending your existing application with the new features built into Visual FoxPro. With Visual conversion, the forms in the application are better prepared to take advantage of new Visual FoxPro features, but require manual placement of the code behind the forms. The project implements these two methods in two very distinct ways. We'll first look at the differences in the conversion methods as they relate to the project and then follow up with a detailed look at how forms are converted differently under the two methods.

When Functional conversion takes place, the forms are converted and the converted forms are called within the application. Under Visual FoxPro the code to call a form is DO FORM ; in FoxPro 2.6 the syntax is DO .SPR. The converter does not modify the original calls to the forms, but creates a corresponding SPR file that executes a DO FORM . Here's what the CUSTOMER.SPR program looks like after Functional conversion takes place, as executed with a DO CUSTOMER.SPR:

*- CUSTOMER.SPR

*- [CONVERTER] Declare variables for record pointers

PUBLIC _iconvCustomerGoToPlaceHolder

DO FORM "CUSTOMER.SCX" NAME _R2716LSBP LINKED 

*- [CONVERTER] Begin CLEANUP and other procedures from 2.x Form

PROC CLEANUPSAMP

WAIT WIND 'nada'

*- [CONVERTER] End CLEANUP and other procedures from 2.x Form

Note that a public variable is initialized. This variable is filled with the current record number during the Unload event of the form, to be used to reset the record pointer when re-entering the form. Additionally, any procedures or functions that existed in the 2.6 cleanup code are placed into this .SPR file. Unlike a standard Visual FoxPro form, this form emulates a 2.6 READ and creates a wait state while the form is running. The program does not finish executing until after the form is released, thereby giving the form access to procedures and functions contained within the calling .SPR program.

A Visual conversion differs in that although the screen is converted, the SPR is not overwritten with the code demonstrated above. The SPR remains the same as it was in 2.6 and is simply recompiled. The converter doesn't make assumptions about where to place code snippets in the new Visual FoxPro form set, but rather writes them out to a program file. The new Visual FoxPro form will not run if it is dependent on these disembodied snippets. To make the form functional, there needs to be some interaction by the developer, first in calling the form with a DO FORM and then placing the code snippets in their correct events of the form.

Converting from the project level is the most desirable way to convert an application. Not only does it convert all components of an application, it is the only method that will convert multiple screen sets into a Visual FoxPro form set.

Form Conversion

Form conversion can be invoked by opening a 2.6 screen or electing to convert a project that contains screens. Either method presents the developer with the election of executing the default Functional or optional Visual conversion. The resulting forms from each conversion method differ in several ways. The resulting forms from a Functional conversion result in a complete working form that respects all facets of the previous 2.6 environment. The Visually converted forms require the developer to manually place code snippets where appropriate.

Functional Form Conversion

Functional conversion creates a form set and places all the controls from the 2.6 screen onto a Visual FoxPro form within a page frame container. Each page frame relates to an individual READ in the predecessor 2.6 screen, so if the screen was created in 2.6 with multiple READs, they would each correspond to a page frame in the converted Visual FoxPro form. Even though multiple READs in a single screen were not common in version 2.6, the Functional conversion takes their possible implementation into consideration and can be considered one of the major drawbacks of this method.

The most important setting in the Functionally converted form is the form set's WindowType property. If the value of this property is 2 or 3 then the form set takes on the READ qualities of a 2.6 screen set. Execution stops when a DO FORM or SHOW command calls the form. The WindowType value of 2 is a normal form set which can be deactivated; a value of 3 makes the form modal so that it must be released before execution can start again. These WindowType properties relating to 2.6 screen compatibility are only available with Functionally converted 2.6 screens. When screens are converted Visually or are created in Visual FoxPro, this WindowType property only relates to standard Visual FoxPro modeless and modal behavior and does not allow the backwardly compatible settings of 2 and 3. The only time you will see form set WindowType properties with READ capabilities is in a Functionally converted form set.

Code is moved from the 2.6 events to Visual FoxPro events in a specific pattern. The following is a table of the conversion of 2.6 events to Visual FoxPro events.



FoxPro 2.6 Screen Event	Converted Visual FoxPro 3.0 Event
Setup - #Section 1	FormSet.Load
Setup - #Section 2	Form.Load
Activate	Form.Activate & FomSet.Activate
Deactivate	FormSet.Deactivate
Show	FormSet.ReadShow
When	FormSet.ReadWhen
Valid	FormSet.ReadValid
Cleanup	FormSet.Unload & SPR for procs/functions

The READ keywords CYCLE, LOCK, MOUSE, SAVE, and TIMEOUT are moved to form set properties with the names ReadCycle, ReadLock, ReadMouse, ReadSave, and ReadTimeout.

A behavior unique to this backwards-compatible screen relates to variable scoping. Variables that are defined in the Load event are scoped to the life of the form. This is for compatibility reasons only and does not conform with standard Visual FoxPro variable scoping

It should be noted that environmental settings are automatically defined in the form set Load event and the current record pointers are saved in public variables during the form set Unload event. The data environment of the form is updated with all appropriate 2.6 view environment objects such as the table aliases, index orders, and relationships. The 2.6 generator directives for automatically opening and closing the tables are moved to the properties AutoOpenTables and AutoCloseTables in the DataEnvironment object.

Extending a Functionally-Converted Form

The following steps are a program for extending functionally converted forms into a Visual FoxPro format. By definition, the functional conversion creates a backwards-compatible form set. By applying these steps to the situations that apply to the particular form, you can change the backwards-compatible form set into a standard Visual FoxPro form set. This conversion process is an excellent learning tool for the 2.6 programmer moving to Visual FoxPro.

1.Move parameter code from the Load event to the Init event.
2.Change form-level variables to user-defined form properties.
3.Create form methods for form-specific procedures and functions (those moved to the SPR).
4.Change CLEAR READ to RELEASE THISFORMSET or RELEASE THISFORM.
5.Change SHOW GET to <object>.Refresh.
6.Change SHOW GETS to THISFORM.Refresh or THISFORMSET.Refresh.
7.Change SHOW GET for List and Combo boxes to <object>.Requery.
8.Move READ SHOW and READ WHEN to the form set Load event.
9.Move READ ACTIVATE and READ DEACTIVATE to the form set Activate and Deactivate events.
10.Move READ VALID to the QueryUnload event.
11.Convert foundation READs to READ EVENTS and CLEAR EVENTS.
12.Change the WindowType property to 0 or 1.



---