Chapter 25 -- Building an Application for Distribution | Microsoft Visual FoxPro 6. 0 Programmer's Guide 1998

Building an application for distribution is similar to developing a standard Visual FoxPro application. You work in the Visual FoxPro development environment as usual, but then you create an executable file or Automation server (a COM component) and test it in the run-time environment. You then distribute your application and any related files to your distribution sites.

This chapter describes changes you need to make to prepare an application for distribution, as well as some suggested changes that help make a distributed application look unique.

This chapter addresses:

The Distribution Process
Preparing an Application for Distribution
Customizing an Application for Distribution
Preparing to Make Distribution Disks

The Distribution Process

The following list identifies the steps you need to follow to distribute a Visual FoxPro application:

Create and debug the application using the Visual FoxPro development environment.
Prepare and customize your application for the run-time environment. For details, see Customizing an Application for Distribution and Preparing an Application for Distribution.
Important Certain development environment features aren t available in the run-time environment and must be removed from your application. These features are listed in Removing Restricted Visual FoxPro Features and Files later in this chapter.
Create documentation and online Help. For more information about creating Help for your application, see Part 7, Creating Help Files.
Build an application or executable file. For more information about building an application, see Chapter 13, Compiling an Application.
Create a distribution directory containing all the files a user needs to run your application.
Create distribution disks and an installation routine using the Setup Wizard. For more information, see Chapter 26, Creating Distribution Disks.
Package and distribute your application disks and any printed documentation.

Preparing an Application for Distribution

The following sections describe the steps you might need to take to prepare your application for the run-time environment. These steps include:

Choosing the type of build.
Considering environment issues.
Ensuring correct run-time behavior.
Including resources in your application.
Removing restricted features and files.
Customizing your application.

Choosing the Type of Build

Before you can distribute your application, you must build either an application file, with an .app extension, or an executable file, with an .exe extension. The following table lists the differences between the builds.

Build Type	Characteristics
Application (.app) file	10K to 15K smaller than an .exe file. User must own a copy of Visual FoxPro.
Executable (.exe) file	Application includes the Visual FoxPro loader so users don t need to own Visual FoxPro. You must provide the two support files Vfp6r.dll and Vfp6renu.dll (EN denotes the English version). These files must be placed in the same directory as the executable file or along the MS-DOS path. See BUILD EXE for more information about creating and distributing executables.
OLE DLL	Used to create a file that can be called by other applications. For details about using this build option, see Chapter 16, Adding OLE.

When you choose the type of build, consider the size of your final application file and whether your users own Visual FoxPro.

Considering Hardware, Memory, and Network Issues

You should consider and test the minimum environment your application can operate in, including the amount of disk space and memory. The results of your testing and the resolution of other issues covered in this chapter can help determine the type of build you choose, the files you include with your application, and the way you structure your distribution directory.

The applications you create have the same hardware, memory, and network requirements as Visual FoxPro. For more information on those requirements, see System Requirements in Chapter 1, Installing Visual FoxPro, in the Installation Guide. For additional information on creating applications for multiuser environments, see Chapter 17, Programming for Shared Access.

An executable application file always checks for the presence of the Visual FoxPro run-time library, Vfp6r.dll. To run an application .exe file using the development version of Visual FoxPro, you must force the application to use the Visual FoxPro .exe file instead.

To run an executable application in Visual FoxPro

Start Visual FoxPro, and then from the Project menu, choose Do. In the Do dialog box, select your application s .exe file name.
-or-
In the Command window, enter DO followed by the name of your application s .exe file name.
-or-
In the command line that starts Visual FoxPro, specify the E switch. For example, if your application is called MYAPP, you can run it with the following command line:
```
MYAPP.EXE -E 
```
This command line switch forces the application to use the executable file Vfp6.exe. For this switch to work, Vfp6.exe must be in the search path.

Ensuring Correct Run-Time Behavior

An application consisting only of modeless forms will not function properly in a run-time environment unless you provide a READ EVENTS command. You can ensure that the application runs properly by adding a calling program or setting the WindowType property.

To run a form in a run-time environment

Run the form from a program containing a READ EVENTS command.
-or-
Set the form s WindowType property to Modal.

Some Visual FoxPro applications rely heavily on Visual FoxPro system menus. At run time, some menus and commands are unavailable, and without a provision for a READ EVENTS command, a menu-driven application ends as quickly as it starts. Use the following section to review any menus you include in your application.

For more information on structuring an application with the READ EVENTS command, see Controlling the Event Loop and Examples of How to Structure an Application in Chapter 13, Compiling an Application.

Menu Options

If you use the Visual FoxPro system menu, your application file includes only the following default menus and menu commands.

Menu	Menu items
File	Close, Save, Save As, Exit
Edit	Undo, Redo, Cut, Copy, Paste, Paste Special, Select All, Find, Replace
Window	Arrange All, Hide, Hide All, Show All, Clear, Cycle, all open windows
Help	Contents, Search for Help on, Technical Support, About Visual FoxPro

You can disable or remove any of the default menus and menu commands, or add your own menus and menu commands to run-time applications.

Troubleshooting If your menu system works in the development environment but closes prematurely in your application, make sure you have a READ EVENTS command active while your menu system is running. Also be sure to include a CLEAR EVENTS command when you exit the menu system.

For more information about customizing menus, see Chapter 11, Designing Menus and Toolbars.

Including Resources in Your Applications

Visual FoxPro provides several resource files that extend the basic functionality of your applications, including FOXUSER resource files, API libraries, and ActiveX controls. If you use these files, you must include them in your project or distribution tree.

Including FOXUSER Resource Files

Visual FoxPro resource files store useful information for your application, including window positions, Browse window configurations, and label definitions. If your application relies on specific settings for any of these resource items, you must also distribute the FOXUSER database and memo files or the resource files you create specifically for your application. These resource files consist of a Visual FoxPro table with an associated memo file, usually named Foxuser.dbf and Foxuser.fpt.

Note The FOXUSER resource file isn't the same as the locale-specific resource file that contains dialog boxes and error messages. The FOXUSER resource file stores application information such as macros you've defined; the locale-specific resource file stores system text strings. For more information, see Including a Locale-Specific Resource File later in this chapter.

Including External Library Files

If your application includes external library files such as ActiveX controls (.ocx files) or Visual FoxPro API libraries (.fll files), use the Setup Wizard to ensure they're placed in the appropriate directory. You can distribute the Visual FoxPro file Foxtools.fll with your applications. For more information on creating external libraries to access the Visual FoxPro API, see Part 9, Accessing APIs.

Including COM Components

If you include ActiveX controls or have created a Automation server (a COM component) as part of your application, include any .ocx files in your project and ensure the necessary support files are installed on the user s machine in the Windows system directory. Note that you can only distribute ActiveX controls for which you are licensed. For Automation servers, you must also include registration files, such as type libraries (.tlb files) and registry files (.vbr files), with your application.

If you use the Setup Wizard to create the distribution disks, you can include these files automatically. In Step 6, make sure the ActiveX column contains check marks for the ActiveX controls you re shipping. When you do this, the Setup program created by the Setup Wizard will ensure that COM components are registered properly on the user s computer when the application is installed. For more information on the Setup Wizard, see Chapter 26, Creating Distribution Disks

All users can run forms containing ActiveX controls; however, your application cannot accomplish certain tasks if it is running under the run-time version of Visual FoxPro. Remember the following guidelines:

Your application must be running under a full version of Visual FoxPro to change forms, classes, or subclasses that include ActiveX controls.
Your application must be running under a full version of Visual FoxPro to add ActiveX controls to forms at run time. For example, the full version of Visual FoxPro is required to add the Outline control to a form by running the following code:
```
PUBLIC frmOleNewForm frmOleNewForm = CREATEOBJECT("form") frmOleNewForm.Show frmOleNewForm.ScaleMode = 3 frmOleNewForm.Addobject("NewOutline","OLEControl",; "MSOutl.Outline") 
```
Note When a form is closed, controls added at run time aren't saved.
Your application can be running under either the run-time or full version of Visual FoxPro to add subclassed ActiveX controls to a form at run time. For example, you can define the RedOutline subclass from the Outline class, and distribute the subclass in Olelib.vcx; all users can then add the RedOutline control to a form by running the following code:
```
PUBLIC frmOleNewForm frmOleNewForm = CREATEOBJECT("form") frmOleNewForm.Show frmOleNewForm.ScaleMode = 3 SET CLASSLIB TO CURR() + OLELIB.VCX frmOleNewForm.Addobject("NewOutline","RedOutline") 
```

Including a Configuration File

The configuration file, Config.fpw, can establish many default Visual FoxPro settings. For instance, you can change the Visual FoxPro title, the background color, and the way a user navigates with the keyboard.

If you want the configuration file to be read-only, place it in your project and mark it as included. If you want the configuration to be modifiable, place the file in your project and mark it as excluded. Then distribute the configuration file with your application or executable file, as a separate file. By default, Visual FoxPro looks for a configuration file named Config.fpw. However, you can specify a different configuration file name using the -C command-line switch when starting Visual FoxPro.

For more information about options that you can set in the configuration file, see Using a Configuration File in Chapter 3, Configuring Visual FoxPro, in the Installation Guide.

Including a Locale-Specific Resource File

If you're distributing your application along with the run-time version of Visual FoxPro, you might need to include a locale-specific resource file. This file contains the dialog boxes and other user-interface elements that Visual FoxPro uses to interact with the user. There's a different run-time resource file for each language in which Visual FoxPro is available.

For more information about using locale-specific run-time files, see Distributing Locale-Specific Run-Time Files in Chapter 18, Developing International Applications.

Note The locale-specific resource file isn't the same as the FOXUSER resource file, which stores application information such as macros you've defined. The locale-specific resource file stores system text strings. For more information, see Including FOXUSER Resource Files earlier in this chapter.

Including All Your Files

You can freely reproduce and distribute some Visual FoxPro files, graphics, and programs with the applications you create. For detailed information, see Removing Restricted Visual FoxPro Features and Files later in this chapter.

Before you build your application, make sure that your project includes the necessary files for your application as well as any additional resource files, such as graphics files or templates.

The following table list files you can add to your project.

If you are	Add these files to your projects
Applying a custom configuration to your application	Config.fpw
Applying custom settings to your application	Foxuser.dbf and Foxuser.fpt
Distributing a .dbf-style Help file	Your .dbf-style Help file

To add files to your application

Include the files in your project.
If you don't want to change them in the distributed application, place the files in your project and mark them as included. The files are then read-only and cannot be modified.
-or-
Add the files to your application directory. For details, see Chapter 26, Creating Distribution Disks.
If you want to modify them, place the files in your project and mark them as excluded. Then distribute them with your application as separate files.

For more information about creating a project, and including or excluding files in a project, see Chapter 13, Compiling an Application.

Removing Restricted Visual FoxPro Features and Files

The development environment of Visual FoxPro contains many features and files that are licensed for your use only. If your application contains any of these features or files, remove them.

Restricted Visual FoxPro Features

You cannot include the following Visual FoxPro menus and their menu commands in a distributed executable file.

Restricted menus
Database	Project
Form	Query
Menu	Table
Program

If your application includes the following commands, it will return the error Feature not available. Although you cannot include commands that create or modify menus, forms, or queries, you can run compiled menu, form, or query programs in your application.

Unavailable commands
BUILD APP	MODIFY FORM
BUILD EXE	MODIFY MENU
BUILD PROJECT	MODIFY PROCEDURE
COMPILE	MODIFY PROJECT
CREATE FORM	MODIFY QUERY
CREATE MENU	MODIFY SCREEN
CREATE QUERY	MODIFY STRUCTURE
CREATE SCREEN	MODIFY VIEW
CREATE VIEW	SUSPEND
MODIFY CONNECTION	SET STEP
MODIFY DATABASE

If used in a distributed application, the following commands are ignored.

Ignored commands
SET DEBUG	SET DOHISTORY
SET DEVELOPMENT	SET ECHO

Restricted Visual FoxPro Files

Visual FoxPro installs files on your computer that are restricted and may not be reproduced or distributed, including:

Wizard files
TrueType fonts
SpellCheck utility files
Help files

Although you cannot distribute Visual FoxPro sample applications with your applications, you can refer to portions of sample application code as examples for building your own application. You can also include the wizard class library, Wizstyle.vcx, and the sample class libraries in your application.

License.txt

Visual FoxPro contains many files that are licensed for your use for design, development, and testing purposes only. See License.txt, located in your Visual FoxPro directory, for a list of restricted files.

If your application contains any of these files, remove them. Under the terms of the Microsoft License Agreement you received with this product, you aren't permitted to ship these files in your application or on your disks.

Distributable Files

You may distribute any Visual FoxPro file that isn't restricted. Pursuant to the Microsoft License Agreement you received with this product, files must be distributed in conjunction with a corresponding application. The following guidelines apply to distributable files.

Setup Wizard

The Setup Wizard checks for restricted files and will exclude them from distributable disk sets. Do not assign these file names to any files you will distribute. The Setup Wizard will exclude any file that has a name identical to one on this list.

Any files in the Visual FoxPro Distrib.src and SETUP directories that are required to support a corresponding application may be distributed. When you use the Setup Wizard to create distribution disks, it automatically places the required files from these directories on the distributable disks in a compressed format. Upon installation, these file are decompressed and are installed by name in the appropriate directories on the user s machine. It isn't necessary to copy these files to your distribution tree.

Samples

Files in the Visual Studio \Samples\Vfp98 folders and in the Vfp98\Api\Samples folders are provided for you to learn from and build on. Although you may not distribute unmodified Visual FoxPro sample applications, you may refer to portions of sample application code as examples for building your own application.

If you use any files in these directories (including all .bmp, .ico, and .cur files), they must be included in your project and in the application build. They must not appear by name on the distributable disks and may not be distributed independently of your applications.

Class Libraries

You can use any .vcx file, including those in the Vfp98\Ffc and Vfp98\Gallery directories, without modification in your applications. The libraries must be included in your project and in your application build.

ODBC Files

Please refer to the Microsoft License Agreement you received with this product for specific restrictions with respect to your redistribution of ODBC files.

ActiveX Controls

Visual FoxPro includes a set of ActiveX controls (.ocx files) you can add to and distribute with your applications.

Customizing an Application for Distribution

The Visual FoxPro default run-time environment looks like the development environment: it displays Visual FoxPro icons and menus. To give your application a unique appearance, you might want to customize some of its features by:

Protecting and documenting your source code.
Calling error-handling and shutdown routines.
Changing the default Visual FoxPro menu and menu commands.
Including a configuration file to specify custom title, icon, keyboard, and Help settings.
Modifying the main Visual FoxPro window.
Adding Help to your application.

Protecting and Documenting Your Source Code

To prevent users from viewing or changing the source code of your application, encrypt your source code and remove debugging information.

Tip Always back up your source code before encrypting it.

To protect your source code

Open your application project.
From the Project menu, choose Project Info.
In the Project Information dialog box, select Encrypted and clear Debug info.
In the Project Manager, choose Build.
In the Build Options dialog box, select Recompile all files and choose OK.
In the setup section of your application, include the SET DEBUG OFF command.

Before you begin the distribution process, if you haven t already done so, you can comment and format your code so it has a consistent appearance and is easier to maintain. You can use the Beautify option from the Tools menu or the Documenting Wizard to customize your application documentation in several ways, including:

Capitalizing keywords and variables.
Indenting source code.
Adding headers to files, procedures, and methods.

To use the Documenting Wizard

From the Tools menu, choose Wizards.
From the submenu, choose Documenting.

You can also use the Documenting Wizard to create cross-references of symbols you ve used in your application and to produce an analytical summary of your project.

Calling Error-Handling and Shutdown Routines

At times, errors occur when users run your application. You can call your own error-handling routine by including ON ERROR. Typically, ON ERROR uses a DO command to run a routine which handles the error, as in:

ON ERROR DO My_Error

If your application contains no error-handling routines when an error occurs, the application pauses and Visual FoxPro displays an error message with the following options:

Cancel If a user chooses Cancel, Visual FoxPro immediately stops running the application and returns control to the system.
Ignore If a user chooses Ignore, Visual FoxPro ignores the line that caused the error and continues to the next line in the program.

For more information about error handling, see Handling Run-Time Errors in Chapter 14, Testing and Debugging Applications.

For a complete list and explanation of Visual FoxPro error messages, see Error Messages.

Tip Be sure to provide documentation to your users that describes the errors that they might see, and suggests ways in which they can correct errors.

Create your own shutdown routine by including the command ON SHUTDOWN in your code. Typically, ON SHUTDOWN uses a DO command to call a routine if you try to exit the application, as in the following example:

ON SHUTDOWN DO My_Shutdown

This routine typically includes a dialog box that asks if the user is sure they want to quit the current application. If the user wants to quit the application, the routine can close open files and clean up the environment, and then issue the QUIT command. If the user doesn't want to exit the current application, the routine can return control to the application.

Adding Help to Your Application

You can integrate context-sensitive Help into your applications, so that users can press F1 or choose Help from a menu to get assistance with your application. The Help that you provide with your application has the same features as the Help in Visual FoxPro. For more information, see Part 7, Creating Help Files.

If you create graphical Help for your application, include the .chm or .hlp file in your application distribution directory so that the Setup Wizard includes it on your distribution disks.

Note You cannot distribute Winhelp.exe or the Help files shipped with Visual FoxPro. For more information, see Removing Restricted Visual FoxPro Features and Files later in this chapter.

Modifying the Appearance of Your Application

You can modify the appearance of your application without changing your application code by:

Changing the default menu system.
Changing the default title.
Changing the default application icon.
Specifying platform-specific keyboard navigation.

Changing the Default Visual FoxPro Menus

You can add your own menus and menu options to distributed applications by using the Menu Designer. If you don't create your own menu, the run-time environment displays a default Visual FoxPro menu.

For details on the default menus, see Ensuring Correct Run-Time Behavior earlier in this chapter. For more information about the Menu Designer, see Chapter 11, Designing Menus and Toolbars.

Changing the Default Title

Your application runs in the main Visual FoxPro window. By default, the text Microsoft Visual FoxPro appears in the title bar.

To customize the title of the main Visual FoxPro window

Add the following statement to your configuration file.
```
TITLE = cMyTitle 
```
Replace cMyTitle with the title of the main window of your application.

To include a Visual FoxPro function as part of the title, use the Caption property of the main window as in the following example.

COMMAND=_SCREEN.Caption=; "Visual FoxPro " + SUBSTR(VERSION(),25,3)

Changing the Default Application Icon

After your application is compiled, the default Visual FoxPro icon appears in the Windows Explorer or Start Menu as the application icon. You can use the generic icon that is supplied by Visual FoxPro or design your own.

If you want to display your own icon, create an icon (.ico) file with two images: one small (16 by 16) and one standard (32 by 32). Create both images as 16-color icons.

You can change the default Visual FoxPro icon in the Project Info dialog box of the Project menu. If you use the Setup Wizard to create distribution disks for your application, you can also specify an application icon there.

To change the default application icon using the Project Manager

In the Project Manager, select the main file for your project.
From the Project menu, choose Project Info and then select the Project tab.
Choose Attach icon.
Choose Icon and then select an icon (.ico) file to assign to your project.

Backing Up Your Source Code

In all application development, it s a good practice to make complete backup copies of your original program files before you build an application. Store the backup copies separately from your compiled applications.

Important Be sure to maintain separate copies of your original source programs for future use. You cannot re-create your source programs from their compiled code.

Building Your Application

When your application project contains all the necessary files, you're ready to build a distributable file. You can build your project as a standard application that only runs when Visual FoxPro is present, or as an executable application that runs without Visual FoxPro.

Note You can also build your application as an Automation server. For details, see Creating Automation Servers in Chapter 16, Adding OLE .

Building a Standard Visual FoxPro Application

You can build a standard Visual FoxPro application with the Project Manager or with the BUILD APP command. However, more build options are available when you create an application through the Project Manager.

To build a standard application

In the Project Manager, choose Build, then in the Build Options dialog box, choose Build Application.
-or-
Use the BUILD APP command.

Building an Executable File

You can build a Visual FoxPro executable file with the Project Manager or with the BUILD EXE command.

To build an executable file

In the Project Manager, choose Build, then in the Build Options dialog box, choose Build Executable.
-or-
Use the BUILD EXE command.
If you include the STANDALONE or EXTENDED clauses of the BUILD EXE command, Visual FoxPro generates a Feature not available error message.

You can also build an Automation server, which creates a DLL that can be called from other Windows programs.

To compile an Automation server

In the Project Manager, choose Build, then in the Build Options dialog box, choose Build OLE DLL.
-or-
Use the BUILD DLL command.

Preparing to Make Distribution Disks

Now that you ve considered all the requirements and options that Visual FoxPro provides, and built an application from your files, follow these steps:

Create a distribution directory.
Copy your application files from the project to the appropriate locations in your distribution directory.
Create distribution disks.

Creating a Distribution Directory

The distribution directory contains copies of all the project files that comprise your application. The structure of this distribution tree represents the way the Setup routine created by the Setup Wizard will install files on a user s machine.

Mapping the project files to the distribution tree

To create the distribution directory

Create a directory named as you want it to appear on a user s machine.
Divide the distribution directory into any subdirectories folders that are appropriate for your application.
Copy files from the application project into the directory folder.

You can use this directory to test your application in the run-time environment. If necessary, temporarily reset defaults on your development machine to reflect the minimum settings on a target user machine. When everything works correctly, use the Setup Wizard to create disk images that will reproduce the correct environment when you distribute copies of your application.

Creating the Distribution Disks

To create distribution disks, use the Setup Wizard. The Setup Wizard compresses the files in the distribution tree and copies these compressed files to the disk image directory, placing them in a separate subdirectory for each disk. After you use the Setup Wizard to create images of your application disks, copy the contents of each disk image directory to a separate disk.

When you distribute the package, the user can install all the files for your application by running Setup.exe from Disk 1.

For details on using the Setup Wizard, see Chapter 26, Creating Distribution Disks.