Deploying Visual DataFlex 9 Applications

A Data Access Worldwide White Paper
by Dennis Piccioni

April 16, 2003
Last Edited: December 23, 2003

As of Visual DataFlex 8, deployment of Visual DataFlex (VDF) applications has been simplified tremendously. This paper will show you how to install your finished Visual DataFlex 9 applications on your end users' PCs. Many aspects of the deployment process have changed from VDF revisions prior to 8.

Contents

• The Short Version
• Client License Installation
• Deploying Your Application
  • Application Files
  • Registry Settings
  • ActiveX controls
  • Workspaces.ini
  • Current Workspace Registry Value
  • Crystal Reports Runtime
• Other Deployment Issues
  • Using Multiple Workspaces with the Same Application
  • Change in DLL File Finding
  • Client License Pre-Registration
  • Novell Netware TTS Support
  • Non-DataFlex Databases
  • Installing on Networks
    • Using Universal Naming Convention (UNC)
    • Registry (.reg) File Formats
  • Licensing Issues
• Additional Reading
• Contacting Data Access Worldwide

The Short Version

Deploying a Visual DataFlex 9 application really involves only 2 steps:

1. Install the Visual DataFlex Client Installation (available from the download section of our Web site: http://www.dataaccess.com).
2. Install all files in the non-source code subdirectories of your workspace (bitmaps, data, help, programs).

You may want to review the rest of this paper for details, or print out a copy to take with you to your deployment site in case you run into any unanticipated issues.

Client License Installation

The Visual DataFlex Client Installation (VDFCI) is an executable file, provided by Data Access Worldwide, that installs the Visual DataFlex runtime, Database Builder, Database Explorer, the Crystal Reports for DataFlex* Runtime and other utilities provided by Data Access Worldwide as part of Visual DataFlex.

* Due to numerous developer requests, as of Visual DataFlex 8.2, the Crystal Reports runtime is no longer installed as part of the Client License Installation. Thus, if your application includes Crystal Reports reports, you must install the runtime files yourself. Please see the Crystal Reports Runtime section for detailed instructions on how to do this.

The VDFCI always installs all files and makes all necessary Windows Registry settings to allow Visual DataFlex applications to run on the destination computer. You can control what optional components are installed and certain Client Installation display options by using the Client Installation configuration file. The Client Installation configuration file is a text file and completely self-documented.

You can download the most current Visual DataFlex Client Installation and Visual DataFlex Client Installation Configuration File for the version of Visual DataFlex (8 and up) you are using from the download section on our Web site: http://www.dataaccess.com.

You may choose to develop an installation program using any available software installation tool, such as Wise Installer or InstallShield. For licensing reasons, you must install the Visual DataFlex runtime using the VDFCI. You can implement this by calling the VDFCI executable from your installation program to install the VDF runtime. 

Deploying Your Application

Once the Visual DataFlex runtime is installed via the Visual DataFlex Client Installation, you need to install the files needed by your application.

• Application Files

• Configuring Deployed Workspaces

The best way to simplify application installation is to mirror the workspace setup of your development environment on the deployment PC or environment. If you need to change the workspace setup, you will have to modify the workspace (.ws) file installed with your application.

Please read the Workspace Changes section in the What's New Help File that is installed with your Visual DataFlex development system to understand how the workspace (.ws) files work.

• Files to Install

Generally, all files in the bitmaps, data, help and programs directories of a workspace are deployed.

Specific files to install

\workspace\bitmaps\*.bmp	- bitmap files
\workspace\bitmaps\*.ico	- icon files
\workspace\data\filelist.cfg	- main database list file
\workspace\data\*.dat	- DataFlex tables
\workspace\data\*.hdr	- DataFlex table header files
\workspace\data\*.k*	- DataFlex index files
\workspace\data\*.tag	- DataFlex table field name files
\workspace\data\*.vld	- DataFlex compressed tables
\workspace\help\*.*	- help files
\workspace\programs\*.exe	- compiled program files
\workspace\programs\*.ws	- workspace file
\workspace\programs\*.ocp *	- ActiveX control preferences files

* You only need to deploy .ocp files if you are using FlexCOM 1. If you are using FlexCOM2 (any ActiveX controls imported and managed by the Visual DataFlex Studio starting with Visual DataFlex 8.3), you no longer need to distribute these files. You should see these files in Programs folder if they are used by your application. 

If you are using non-DataFlex databases in your application, please consult the documentation for those database and drivers for those databases for which additional files may need to be distributed.

Changes from VDF 7

Your compiled application now has a .exe extension (in VDF7, the extension was .vd7).

You must install the workspace (.ws) file for your workspace in the same folder where your compiled application resides, unless you specify in your application the path to this file.

If you are taking advantage of the ability to embed bitmaps and icons into a compiled application as resources, you will not have to deploy those bitmap and icon files separately.

• Registry Settings

  No Windows Registry settings need to be set for your application during installation. All runtime-specific and utility-specific Registry settings will be installed by the VDFCI.

  An exception to this would be specific non-standard Registry settings required for parts of your application (e.g. you are using the Windows Registry to store application-specific values that need to be known the first time the application runs).

• ActiveX Controls

The necessary files for the FlexCOM component of Visual DataFlex, which allows ActiveX controls to integrate with VDF, are automatically installed by the VDFCI.

You must install and (possibly) register any files for the ActiveX controls your VDF application uses. Consult the documentation provided with the specified OLE server(s) on how to install on a client site.

If you made any changes to the ActiveX control properties in the VDF IDE, you will need to deploy the associated .ocp file that is located in the Programs directory of your workspace.

• Workspaces.ini

The bin directory of your Visual DataFlex development system contains a file named workspaces.ini. This file contains the list of registered workspaces and is only used by any program that uses the package SelectWorkspace.dg, which includes VDF utilities, such as DataBase Builder and Database Explorer, to allow selection of different workspaces. If you are not deploying any of our utilities and your applications do not use this file, you do not need to deploy workspaces.ini.

You can start Database Builder and Database Explorer in a specific workspace by passing a workspace file as a command line argument.

For example, this will start Database Builder in the Order Sample workspace:

"C:\Program Files\Visual DataFlex 9.0\bin\DBBLDR" -w"C:\Program Files\Visual DataFlex 9.0\Examples\Sample Applications\Order\Programs\DAW.Sample Applications.Order.ws"

For example, this will start Database Explorer in the Order Sample workspace:

"C:\Program Files\Visual DataFlex 9.0\bin\DBEXPLOR" "C:\Program Files\Visual DataFlex 9.0\Examples\Sample Applications\Order\Programs\DAW.Sample Applications.Order.ws"

• Current Workspace Registry Value

If you deploy Database Builder, Database Explorer or the Error Maintenance Utility, you should be aware that these utilities will open the workspace named in the Current Workspace Registry value by default. So, be sure to set this Registry value to the name of the workspace you wish to have the utilities open by default.

The full path to the Current Workspace Registry value for VDF 9.0 is:
HKey_Current_User/Software/Data Access Worldwide/Visual DataFlex/9/Workspaces/Current Workspace

NOTE: You will not be able to create a new workspace on a PC with only a VDF client license installed.

• Crystal Reports Runtime

Due to numerous developer requests, as of Visual DataFlex 8.2, the Crystal Reports runtime is no longer installed as part of the Client License Installation. Thus, if your application includes Crystal Reports reports, you must install the runtime files yourself.

NOTE: This section pertains only to DataFlex Connectivity Kit for Seagate Crystal Reports 8.

NOTE: This section will show files needed for the DataFlex Connectivity Kit for Crystal Reports 8, version 2.0. You will need to know which version of the Connectivity Kit you are using to determine which files you need to deploy.

Visual DataFlex 9 does not install Crystal Reports or the Crystal Reports Connectivity Kit. You must install Crystal Reports separately and install the Crystal Reports runtime files if you want to deploy Crystal Reports reports with your VDF application.

This section tells you which Crystal Reports 8 files you need to install with your VDF application to run Crystal Reports .rpt files. If you are deploying runtime files using other versions of Crystal Reports, please consult the Crystal Reports documentation of that revision for more details on which files to deploy with your reports.

The files listed here are those you need to install with each Crystal Reports 8 report. Other files may be needed for specific reports, such as files for certain export formats. To see which files are necessary for any specific report, open the report in Crystal Reports and check the list of DLLs displayed when clicking on the More Info button from the Help | About Seagate Crystal Reports menu option and consult the Crystal Reports documentation for more information.

NOTE: The More Info button may list winmm.dll, msshrui.dll and other dynamic link libraries. Do NOT distribute these files with your report. These files are part of the Windows operating system and are operating system and build specific.

Crystal Reports 8 installs numerous files into your Windows System directory. When deploying your application, these files should be installed into the \visual dataflex 9.0\bin directory instead, so that they do not interfere with existing Crystal Reports installations, which may be different Crystal Reports revisions other than 8.

Files

• WindowsSystemDir refers to the full path to the Windows System directory, the directory in which Windows system files are installed on the current PC. The default value for this on Windows 95, 98, ME and XP is c:\Windows\System. The default for this on Windows NT 4 and 2000 is c:\WinNT\System32.
• RtDeployPath refers to the full path to the directory in which the VDFCI is installed on the deployment PC.

Crystal Reports 8 32-bit runtime files

Development Location	Destination Location
WindowsSystemDir\Crpaig80.dll	RtDeployPath\bin\Crpaig80.dll
WindowsSystemDir\Crpe32.dll	RtDeployPath\bin\Crpe32.dll
WindowsSystemDir\implode.dll	RtDeployPath\bin\implode.dll
WindowsSystemDir\mfc42.dll	RtDeployPath\bin\mfc42.dll
WindowsSystemDir\msvcirt.dll	RtDeployPath\bin\msvcirt.dll
** WindowsSystemDir\msvcp60.dll	RtDeployPath\bin\msvcp60.dll

** msvcp60.dll should only be installed if it does not already exist on the deployment PC.

DataFlex Connectivity Kit for Crystal Reports 8 version 2.0 files

Development Location	Destination Location
WindowsSystemDir\Apidll.dll	RtDeployPath\bin\Apidll.dll
WindowsSystemDir\Crystal\P2bdfapi.dll	RtDeployPath\bin\P2bdfapi.dll
WindowsSystemDir\df_collate.cfg	RtDeployPath\bin\df_collate.cfg

NOTE: The reason the files in the chart have been moved from the development computer \WindowsSystemDir to the deployment computer \bin directory is to avoid possible conflicts with software already loaded on the deployment computers. This chart assumes you are using Crystal .RPT files with your VDF application.

If you are using Crystal .EXE files (with all the required distribution files), you need to copy the .EXE (and distribution files) to the bin directory so the Connectivity Kit files listed in the chart can be found by the .EXE program. If your .EXE files cannot be located in the \bin directory then the Connectivity files listed in the chart need to be copied to the deployment \WindowsSystemDir or to the same directory as the .EXE (and distribution files). If the Connectivity Kit files are copied to the deployment computer's \WindowsSystemDir directory be sure to check that no conflicts with other software exist.

Other Deployment Issues

• Using Multiple Workspaces with the Same Application

You may have a need to create multiple workspaces to be accessed from the same application, for example, to provide different sets of some tables to different departments at a client site. The ability to do this is now easier and more controlled by the application developer than with prior VDF versions.

There is a complete code example of allowing an application to accept command line parameters to decide which workspace to open in the Workspace Changes > cWorkspace class section of the What's New Help File.

• Change in DLL File Finding

Due to the fact that as of VDF 8, VDF applications compile to .exe files, the finding of .dll files may have changed from revisions of Visual DataFlex prior to 7. This may especially affect you if you use products such as Crystal Reports and/or one or more of our Connectivity Kits.

The first location Windows executable (.exe) applications search for .dll files they need to load is the same directory as the .exe file. Next, they search the Windows system folders and then along the PATH. In VDF revision 7 and below, the main Windows executable file for VDF applications was dfrun.exe, which was located in the same folder (bin) where all related .dll files were installed, so the .dll files installed there would be found first and any older versions of the same files located in the Windows system folders were ignored. Now, older versions of .dll files used by VDF that are found in the Windows system folders may be loaded first, resulting in error messages from applications expecting newer versions of these .dll files.

To solve this problem, you may have to install .dll files that cause such problems to the same folder where your compiled application (.exe) is located, so that they are found first by your application.

• Client License Pre-Registration

You may pre-register a Client License for your client using the Registration tool for Visual DataFlex (Start > Programs > Visual DataFlex 9.0 > Register), and install the registration files as part of your application installation. The registration files are termlist.cfg and {Serial Number}.dfr (e.g. 123456.dfr), and should be placed in the bin folder of the deployment PC.

• Novell Netware TTS Support

A separate install for TTS support files has been produced for Visual DataFlex. The Visual DataFlex 9 TTS File Install Kit is available on the DAW Web Site.

• Non-DataFlex Databases

Data Access Corporation has several non-DataFlex database drivers (Connectivity Kits) available:

• DataFlex Connectivity Kit for Pervasive.SQL
• DataFlex Connectivity Kit for IBM DB2 Universal Database
• DataFlex Connectivity Kit for ODBC
• DataFlex Connectivity Kit for Microsoft SQL Server

Visit the Client/Server Solutions page of our Web site to find out more information about our Connectivity Kits.

The Visual DataFlex runtime loads the driver(s) for any database you wish to use without having to recompile the application, so you can seamlessly switch to or access any non-DataFlex database you wish to.

Please consult the documentation for the individual Connectivity Kits for installation information.

• Installing on Networks

  There are 2 ways of installing Visual DataFlex on a network:

• Install all components on the server
• Install most components on each workstation and only shared components on the server

• Install all components on the server
  1. From a workstation (say workstation X), map a drive to where you want the client to be installed (for example: drive P)
  2. From workstation X, run the VDFCI and install it on the P drive. Register the client license.
     This step ensures that:
     • You have all the necessary registry settings on the workstation
     • The files are installed on the server
  3. From workstation X, export the HKey_Local_Machine\Software\Data Access Worldwide Registry
     branch to a .reg file.
  4. From all other workstations, you will need to:
     • Map a drive to P exactly as you mapped it on the first workstation (X)
     • Import the Registry entries from workstation X (saved in step 3) to these other workstations

• Install most components on each workstation and only shared components on the server
  1. Install VDFCI locally on one workstation (for example, in drive c). Register the client license.
  2. Map a drive to the server (e.g. Map P to the server's C drive) and then create a directory to hold your application data files (e.g. P:\MyAppData)
  3. Copy the termlist.cfg, XXX.dfr (<LicenseNumber>.dfr) and application, data to a directory (e.g. P:\MyAppData) on the server
  4. Adjust the application's DataPath to point to the server (e.g. in the .WS file, DataPath = P:\MyAppData)
  5. Install the VDFCI on all other workstations without registering it and copy the edited .WS file (containing the new DataPath) to them.

Here are some other things you should be aware of:

• Make sure that you register any ActiveX controls your application uses on each workstation.
• Ensure that the required minimum revisions of the below DLLs are installed on each workstation (the VDFCI does this for you):

• psapi.dll = 4.0.1371.1
• msvcrt.dll = 6.0.8797.0
• mfc42.dll = 6.0.8665.0

• Using Universal Naming Convention (UNC)

You may want to consider using the Universal Naming Convention (UNC) for your network installations. This will prevent problems with mapped drive mismatches.

For example:

• user 1 may have F: mapped to \\Server1\Drive1\Visual DataFlex 9.0
• user 2 may have G: mapped to \\Server1\Drive1\Visual DataFlex 9.0

In this scenario, without using UNC, you would have to:

• Customize each user's Registry entries or
• Synchronize all user's drive mappings

Universal naming convention does not use mapped drives, but instead addresses networked directories and files using this method:

\\ServerName\ShareName\Path\FileName

where:

ServerName is the name of the server (PC) where the files are located
ShareName is the shared directory name where the files are located
Path is the additional path to the files (if applicable) below the shared directory
FileName is the name of the file (if applicable) to access

• Registry (.reg) File Formats

Windows 2000 and XP use a newer format for Registry files than do older version of Windows (95, 98, ME and NT). When exporting Registry information from the Windows Registry Editor on a 2000 or XP machine, the default format is "Registration Files", which uses the 2000/XP format, but you can also select "Win9x/NT4 Registration Files" as the format, which will export the information using the old file format. For network installations, the best tip is to export all necessary Registry settings in both formats, so that they can be imported onto any type of Windows PC.