Migrating Applications to Visual DataFlex 12.0

A Data Access Worldwide White Paper
by Marcia Booth

February 8, 2007
Last edited: February 8, 2007

Visual DataFlex 12.0 brings a lot of useful features to your development environment; features that will make you much more productive in developing your applications and will make you addicted to using the new Studio.

All that is good, but before you migrate your applications, it would be a good idea to familiarize yourself with the changes Visual DataFlex 12.0 brings to your development environment, especially in regards to:

• New Concepts

• Work Habits

• Workspace Management

• New Options

After reviewing those items, you will have a better understanding of the new development environment that Visual DataFlex 12.0 introduces. You should be, then, ready to take the next step and migrate your applications.

New Concepts

1.      Projects

Projects used to be referred to as applications.

A project is the code that you compile and run.  A project consists of a file (usually a .src file) that uses other components (component files, class files, Data Dictionary files, etc.) to create an executable program. A project can be large (e.g. MyBigApplication.src) containing all of the components and classes within your workspace, or it can be small (e.g. MyTest.src) consisting of a few components that you wish to test.

You can create as few or as many projects within a workspace as you wish. For a project to be part of a workspace, you must add the project file to a list that the Studio maintains. Projects can be easily added or removed from this list.

The Studio expects you to always select a current project and then work within that project. When you tell the Studio to compile, debug or run, it will always operate on the current project. When the Studio provides you with code-sense, that information will come from the current project’s perspective.

2.      Autonomous Files

Any source file can be considered to be autonomous or non-autonomous.

An autonomous file is a file where all of its class dependencies (required super-classes and mixins) are satisfied by the file or by one of the files it uses. From a development point of view, an autonomous file is the most flexible type of file. You can drop this file into any project or use it within any other file and you are sure that all the files required to allow this file to compile have been brought along. From the Studio's point of view, an autonomous file allows it to most fully understand and, therefore, most fully model the classes and objects within the file. All of the objects, classes, super-classes, mixins and their interfaces are all known to the Studio.

A non-autonomous file is a file where not all of the class dependencies are satisfied by the file or the files it uses. A non-autonomous file cannot be compiled stand-alone. However, when used within a project, a non-autonomous file can be properly compiled. This occurs because the files and classes that the non-autonomous files are dependent upon are provided by the other files used within the project. The Studio cannot fully model a non-autonomous file when it is considered as a standalone file. Classes and interfaces may exist in other files and the Studio has no way of knowing where those classes are.

In order to help the Studio understand and model a non-autonomous file, we need to tell the Studio that those non-autonomous files are part of a larger project. This is done by context: if your non-autonomous file is a member of the current project (i.e., it will get used and compiled when the current project is compiled), the Studio will use all of the files available in the current project to help satisfy any missing dependencies.

3.      Libraries

A Library is a group of classes (files) that are defined in a way that they can be used by multiple workspaces. A workspace may include any number of libraries. By “include” we really mean, “point to”. When a library is added to a workspace, the library paths are added to the workspace’s makepath.

It should be your goal to organize your workspaces and libraries in a way that offers maximum ease of use, flexibility and portability. This is best accomplished by:

1. Using relative paths

2. Arranging your workspaces and libraries so that they have a common root. This makes it easier to support relative paths, to check in and check out entire source areas, and to copy development areas to other computers.

3. Using sub-directories under AppSrc path to organize your files

4. Avoiding the use multiple AppSrc paths – use Libraries (2) and sub-directories (3) instead.

5. Not changing the system make path. If you want to add system-wide directories, use libraries

Libraries are themselves just a workspace. Libraries are created and maintained within that library’s workspace.  Although libraries are complete workspaces, only their classes are used within other workspaces.   

A library has its own AppSrc\config folder containing all of the required configuration information such as a class list, templates and object preference files. All those files will be available to the workspace using the library.

A library may contain other libraries. When a library defines classes, it will define those classes based on the super-classes that are already defined. Those super-classes can be classes defined in the library, classes defined in a library being used by the library, or classes defined in the System Class Library.

The System Class Library consists of the packages and classes installed as part of a Standard Visual DataFlex installation. The files in the System Class Library are read-only and should never be changed by the developer.

All workspaces and all libraries always have access to the System Class Library. They do not need to be explicitly added as a library.

Work Habits

1.   Project-Oriented Environment

Visual DataFlex Studio expects you to always work within a project. So any Visual DataFlex component you create must be added to a project before it can be compiled, run, tested and deployed.

When you are building an application, your actual project or projects may be quite large. If you need to test new or changed components, it could be a big overhead to compile and run your actual projects to refine those components. There will be times when you will have to do this, but for basic component testing, you can use a smaller project; a test project.

A test project is just a project that gets used for test purposes. If your project is small enough, your test project may be your actual project.

If your project is a web project, you are only allowed to create a single web project per workspace and that project must be named “WebApp.src”. Therefore, with a web project, your main project and your test project are one and the same.

If you use test projects, you may have a single test project or you may have many test projects, each one customized to handle a specific need.  Your test projects may be used to test a single component (e.g. a view) or they may be used to test multiple components (e.g. views and reports).

The components within a test project may end up being entirely maintained by Workspace Explorer or you may wish to directly modify the contents of your test project. You may end up creating a test project from a template and using it without any modifications, or you may need to perform significant alterations.

A typical testing process may proceed as follows:

1. Create your Test Windows Project. You may only do this once you created your workspace.

2. Create a new View with either a wizard or a template selecting your Test Project as the target project. Upon completion, your component will be added to that project.

3. Make any custom changes you need to your component.

4. Set breakpoints as needed.

5. Compile and run the Test Project.

6. Debug your project as needed.

7. Fix any errors and go back to c.  It is expected that steps c – f will be repeated many times. When you finally have things “right” go to h.

8. You might want to add this component to your main project.  If this is the case:

• Change projects and select your main project

• Add the component to the project, compile, run and test it – if you did your testing properly this will all work

You may now wish to create and test another component. Repeat Steps b – g  as needed. If you follow these exact steps, your test project would now contain two components: the older tested one and the one you just created. You might find that having both components is useful for testing in which case you would leave things as is.

If you wish to remove the older component, click on Workspace Explorer and remove it.

Again it is worth noting that this describes the simplest method for testing projects and components. It is expected that developers will want to use this as a starting point.  Some of the more advanced development strategies might include:

• Load a test project and customize it any way you like.

• You may wish to include your own class libraries and precompiled sections directly in your test project. In this scenario, your test project structure will probably look very similar to your actual project.

• You can add additional debugging features to the project.

• You can create your own test component templates so that any test component that gets created is customized to your needs.

• If you add this component to a library all workspaces using this library will have access to the component.

• You can test as many components as you wish within a single test project

• You can create multiple test projects, each customized to handle a special need.

• You can use a test project to test components that are not automatically added to the projects menu. For example, you could test a modal dialog by adding the dialog and creating a procedure that calls it. Place a breakpoint in the procedure and you are all set.

 2.   Multi-Developer Environment

A multi-developer environment is an environment where several developers work on any single workspace, meaning that these developers open files in the same workspace concurrently. That is a common but very risky and error-prone practice.

There are many problems with sharing workspaces over a network:

• Developers risk overwriting each others changes and worse, there is no way to know if or when this has happened. The result can be a situation where source code is lost without anyone realizing it or being able to properly recover or reconstruct the lost code.

• ClassList.xml and DDClassList.xml are shared and could be compromised.

• Multiple developers cannot compile at the same time.

For integrity reasons, the Studio will not normally allow you to share workspaces over a network. If you are currently doing this, we strongly encourage you to reevaluate this strategy. 

Our recommendations for multiple developers working on joint Visual DataFlex projects are as follows:

• For maximum speed and efficiency, work on a local workstation hard drive.

• Work on a local copy of the workspace's source code.

• Use source code management (SCM) software.

• Back up the SCM data store frequently.

These recommendations are consistent with the expected development strategies utilized by most modern development systems and it is no different when working in the Visual DataFlex environment.

The Visual DataFlex Environment

When installing the Visual DataFlex Studio, numerous components are installed, created and registered on the operating system, including folders, files, ActiveX controls and dynamic link libraries (DLLs). If installing on a Windows operating system with Internet Information Server (IIS) running, the Web Application Server service is also installed and registered, and multiple virtual directories created and configured.

Due to the nature of the various components installed and their requirements, it is not possible for all of these pieces to be installed over a network. The Studio should be installed locally (on a local hard drive) and is only tested and supported in that manner.

During the typical development cycle, Visual DataFlex Studio performs the following actions:

• When opening a workspace, the Studio parses all of the source code in the workspace and creates a metadata file from this information.

• When configured to do so, the Studio reopens all windows that were previously opened in their previous location and state, opens all files that were previously opened in their previous state and re-enables all breakpoints and bookmarks.

• During compilation, the Studio reads many files from the current workspace, any included libraries, and the standard Visual DataFlex libraries. It also needs to write the compiled program to disk, as well as other files that may be created during the build process.

• Developers often load the program being developed many times for testing and debugging purposes.

All of the above processes are affected by hardware performance, such as hard disc access, processor speed and RAM. Consider whether the location of the workspaces you work on will affect your development productivity. Generally speaking, installing Visual DataFlex Studio and project workspaces on a local hard drive is optimal for maximum speed and efficiency.

Conclusion

Sharing workspaces over a network is a risky and error-prone practice that it is in no way recommended. No development tool supports or should support this way of working.

If you are currently doing this, we strongly encourage you to reevaluate this strategy following the recommendations we listed above.

While you restructure your development environment to comply with our recommendations, you may use an interim workaround: share the workspace folders but have a local IDESrc.

The one directory in a workspace that cannot be shared is the IdeSrc directory. If an environment is configured where each developer has their own IdeSrc directory for a workspace, the workspace can be shared. This could be accomplished through the use of a common local directory name (e.g. C:\LocalIdeSrc on each developer machine) or though the use of multiple .sws and .ws files, or through alternative drive mappings.

Although this allows multiple users to access the same shared workspace, it solves none of the problems previously listed. This strategy is not recommended and should be used only temporarily.

Workspace Management

1.      Workspace Structure

• Workspaces are organized in the same basic directory structure with only one subfolder added to AppSrc: config. This new folder must now exist under each workspace’s primary AppSrc directory (e.g. Projects\Order Entry\AppSrc\config). This directory stores all the configuration information for a workspace.

• The IDESrc folder is now used slightly different: this folder should no longer be used by the developer. It is now used to store information maintained for and used by the Studio. The information that used to be stored in IDESrc is now either not needed or is stored in the config directory (e.g. AppSrc\config) of the workspace.

• The Studio now allows you to reference relative paths in a “Use” statement. This allows you to organize your files (components, classes, etc.) using the standard file system. Relative paths are always relative to the main workspace and library paths (e.g. AppSrc).

• Projects and components can reside in subfolders of the workspace. In fact, any source path may contain subdirectory paths. This provides an effective and recommended mechanism for organizing your files. All subdirectories defined within a source path are considered to be part of the workspace.

  Files in these workspace subdirectories must be referenced relative to their location of a main source path. Most often that main source path will be your AppSrc directory.

2.      Workspace Files

• A new Studio Workspace file (workspacename.sws) is used to identify a workspace. This file resides in the root directory of a workspace (e.g. Projects\Order Entry\Order Entry.sws). This is a development only file and is not required for deployment.

• The Workspace file (workspacename.ws) is now created as Config.ws for all new workspaces. The .ws file still resides in Programs. It is required for both development and deployment and contains all the paths used by the workspace.

• Workspaces.ini is no longer used. Workspaces do not have to be registered and or maintained in a list of registered workspaces (workspaces.ini). Workspaces are now opened by selecting the Studio Workspace (.sws) file, which can be done outside the Studio (double-clicking on that file) or within the Studio (File | Open Workspace menu option).

• The tables ABData and ddData are no longer used by the Studio. The contents of ABData, which contained information about registered components, are no longer needed (components are no longer registered). ddData, which contains a list of all Data Dictionaries, has been replaced with a more source control friendly XML file.

• Components no longer have to be registered. You select components as you would any other file, with a file selector. The Studio will determine what type of component a file contains and will handle the appropriate modeling.

• DFO files, which are still optional, are now stored in the AppSrc\config directory.

• DFC files no longer exist. All of the information stored in the DFC files is now obtained directly from the source code either in actual commands or in meta-tags.

3.      Workspace Classes

• Workspace class information (packages, classes, DFOs, templates, class list, icons) now resides under the AppSrc and AppSrc\config folders of your workspace.

• A workspace class list is now stored as an XML file (classlist.xml) in the AppSrc\config directory. This list is used to determine which classes will appear in the class palette.

• A class does not have to be added to the class list for it to be modeled. For example, you could create a dbForm class and not add it to your class list and it would still get modeled properly in the Visual Designer. You only need to add a class to the class list if you wish to be able to drag and drop it onto a Designer view.

4.      Global Classes

• All system class information (packages, classes, DFOs, templates, class list, icons) now resides under the PKG and PKG\config folders of your Visual DataFlex. All of these files are read-only. You should never add, change or move any of these files.

• The Usr\Global directory structure is no longer used to contain global class information. All of system information is now in the PKG folder. All developer created “global” information should be moved to libraries.

• The use and the concept of class layers, both Global and Workspace, have been deprecated. The idea that a developer would want a single global class layer for all classes and a complete workspace layer for all classes was both restrictive and overly complicated. This has been replaced with the use of libraries.

• A global class layer can be replaced with a global library. Create a workspace for the global layer and define all of your global classes. Add this “layer of classes” to your workspace as a library.

• We no longer recommend that you create complete class layers. Just create sub-classes for classes you actually need.

• The cApplication class has changed. A standard cApplication object will open a workspace file named Config.ws. As long as you have a workspace file named Config.ws in the same directory as your compiled program (.exe file), the application will load and run. If you wish to customize your workspace file by naming it something other than Config.ws, you can do so by either changing the value of psAutoOpenWorkspace or augmenting the OnCreate event.

5.      Global Paths

• We advise that you only use a single AppSrc path.  Multiple source paths can be better handled though the use of libraries and sub-directories. Note that library paths do not need to be added as secondary AppSrc paths. The Studio will make the source from the libraries available for you.

• We advise against changing the System Makepath. This technique has been used in the past to add a global class layer or to add packages from other providers (e.g. VDFQuery). Both of these requirements can be better accomplished using libraries.

• Utilities and classes from other providers, such as VDFQuery, should be added to a workspace as a library. You do not need to change the System Makepath or the AppSrc path of the workspace to do this.

New Options

Visual DataFlex Studio 12.0 introduces different concepts and has a totally new design. However, some features found in the previous revisions of the product are still present; they were just redesigned or relocated.

Here is a list of the most common features and how to get to them – this will help you getting started:

1.   Importing an ActiveX control

This is now found in File | New menu options, under Class tab: Import COM ActiveX

2.   Adding Web Service Client Classes

This is now found in File | New menu options, under Class tab: Client Web Service Class.

3.   Creating Subclass Layers

Now you can subclass any classes at any time. Just select File | New menu options, under Class tab: New Class or Multiple Classes.

You should consider using libraries to help you organizing your layers.

4.   Adding and Removing Classes from the Class Palette

No DFC files are used in the new Studio. In order to add or remove a class from the class palette you will need to right-click on the class palette and select Add class to palette or Remove class from palette.

When working with libraries, you should use Add/Remove libraries.

5.   Defining the Tab Order of your Objects

You can now right-click on the object name from the Code Explorer tree and select Move Object Up and Move Object Down.

6.   Working with Non-Visual Objects

Non-visual objects from your workspace’s class list can be dropped onto a Designer view. However, those objects will only be visible in your source code, not in the Visual Designer – the Visual Designer only displays what you will see when running your application.

In order to select those objects and view/edit the properties in the properties window, you will need to click on them from the Code Explorer tree.

7.   Using Compile-time Conditionals

The Studio Parser can be configured with respect to how it should treat #IFDEF source code blocks.

By default the Studio parses all code on both sides of the #IFDEF, and it can be configured to parse only the true block or the false block. In most cases the default configuration will be adequate. It means that the Studio will parse and collect information about both sides of the specified #IFDEF block, which gives the Studio more information about your workspace.

However, in some cases, parsing both sides of the #IFDEF block, can cause conflicting information which may lead to metadata errors. For example, both sides might define a class with the same name, which would confuse the Studio.

In that case you can configure the workspace to treat the specified symbol as evaluating to true/false, which will instruct the Studio to parse only one side of the #IFDEF block. In most cases, #IFDEF blocks cause no metadata conflicts, and the Studio can safely parse both sides, simply collecting as much information as possible.

To configure how the workspace should treat specific #IFDEF symbols, open the Configure Workspace Properties dialog, accessed from the Tools menu, and select the Conditionals tab. You can specify each #IFDEF symbol, e.g. USE$VPE, and whether the Studio should parse the true/false block.

The Studio also has a built-in #IFDEF rule, IS$WINDOWS, which evaluates to true and causes the Studio to parse the true block and ignore the false block.

Migrating your Applications

So, it is time to move on to 12.0, but how can you smoothly get your applications migrated to Visual DataFlex 12.0?

It’s fast & easy! You just need to use the Workspace Migration Wizard included in the product and all will be done for you.

The wizard will help you bring your applications from a previous revision of Visual DataFlex into Visual DataFlex 12.0. All settings from your current environment and specifically for your workspace should be converted to conform with the requirements of the new Visual DataFlex revision. This will allow the features you built in previous revisions to be used in the latest revision.

The workspace migration process involves examining the source code used in the workspace as well as the environment settings (like system make path, registry subclasses, subclass layers, registered components, class palette classes, etc.) and translating all that into something the new revision can understand.

The necessary changes to the source code and the workspace configuration can be automatically preformed through the wizard. The wizard can operate in two different modes: Full or Limited.

In full migration mode, the wizard has access to the host environment (i.e. the original Visual DataFlex Studio is installed on this machine and the selected workspace is registered in it) and it will be able to detect environment settings like global subclass layer, subclasses preferences, class palette classes, etc. If you run in full migration mode, all your settings and files used by the workspace will be migrated.

In limited migration mode, the wizard does not have access to the host environment and it will not be able to detect environment settings like global subclass layer, subclasses preferences, class palette classes, etc. If you run the wizard in limited migration mode, just the workspace and the source code specified in the paths in its WS file will be examined and migrated.

Before you start the Workspace Migration Wizard for migrating your workspace, take a moment to analyze its structure and content:

• Identify potential Libraries

• Migrate Libraries first – or get packages available for 12.0 from your Vendors (e.g. VDFQuery and Starzen products) – so you can point to those libraries when migrating your workspace using the Library Candidates page.

Depending on the current Visual DataFlex revision of your application, you will need to have different starting points:

Visual DataFlex 7 (or earlier) and WebApp 3 Applications

1. If you do not have Visual DataFlex 11.1 Studio installed, download and install it. You can run VDF 11.1 for 30 days in evaluation mode, even if you do not plan to use it for development.

2. Launch the "Migrate VDF 7 Workspaces" wizard from Start |  Programs | Visual DataFlex 11.1 | Utilities | Migrate VDF 7 Workspaces.

3. Follow the instructions in the wizard to migrate the workspace to Visual DataFlex 11.1.

Once successfully migrated to VDF 11.1, follow the instructions to migrate the workspace to Visual DataFlex 12 listed under Visual DataFlex 8 (or higher) Applications.

 Visual DataFlex 8 (or higher) Applications

1. Open the Visual DataFlex 12.0 Studio.

2. Select "Open Workspace" from the File menu.

3. Select "Workspaces to migrate (*.ws, *.sws)" from the "Files of type" combo box.

4. Navigate to the .ws file of the workspace you would like to migrate.

5. Follow the instructions in the wizard to migrate the workspace to Visual DataFlex 12.0.

Important!

The Workspace Migration Wizard does not create any virtual directories when migrating a workspace. So, after migrating any web application, you will need to use the Web Application Administrator to configure those applications for Visual DataFlex 12.0.

 

Additional Reading

• Visual DataFlex 12.0 Help
• HOWTO: Migrating from Visual DataFlex 7 and WebApp Server 3 to Visual DataFlex 12

http://www.dataaccess.com/kbasepublic/KBPrint.asp?ArticleID=2272

• Getting the most from Visual DataFlex Studio

http://www.dataaccess.com/whitepapers/Getting_the_most_from_Visual_DataFlex_Studio.htm

• Newsgroup do Project Horizon

news://news.dataaccess.com/project-horizon