'Where is the Setup Wizard?' and Other Annoying InstallShield Questions 

This article may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist. To maintain the flow of the article, we've left these URLs in the text, but disabled the links.

'Where is the Setup Wizard?' and Other Annoying InstallShield Questions

Whil Hentzen

You can divide people into two groups, so the saying goes. One group is made up of people who divide people into two groups, and the other group is made up of people who don't. Similarly, developers can be divided into two camps—those who wonder what happened to the Visual FoxPro Setup Wizard, and those who don't. In this article, Whil Hentzen describes how to deploy Visual FoxPro 7.0 applications—as well as how to solve some of the problems that can crop up during the process.

Maybe you're lucky. Maybe you've got a brand-new copy of Visual FoxPro 7.0 on a CD, and when your trembling, sweaty hands loaded it into your computer's CD-ROM drive, you elected to read the README file before anything and, after doing so, saw the hyperlink for installing InstallShield and remembered to click on it after installing Visual FoxPro itself. If so, you can skip to the next section of this article.

But maybe you're not so lucky. Maybe you downloaded VFP 7 (in all of its 360MB glory) from the MSDN Web site. Or maybe you used the VFP 7 CD from your MSDN Galactica Edition package. Or maybe autorun on your CD-ROM drive doesn't work. Or maybe you bought an extremely inexpensive copy of VFP 7 from www.theresoneborneveryminute.com, neglecting to read the fine print that stated "all programs provided on floppy diskettes," only to find out later that VFP 7 requires 319 floppies. (It does. I tried it. I swear I am not making this up.)

So let's start at the very beginning.

Why InstallShield?

Many 7.0 developers build their first 7.0 app without worrying about deploying until the very end. And it's then that they pull down the Wizards menu, only to find that "Setup Wizard" has disappeared. So then they might try to copy the VFP 7.0 runtime files (after digging through Help to determine what those files are) manually with their own custom application's EXE, and meet with disastrous results. And then... What's next?

The VFP team elected to include a "Lite" version of InstallShield with VFP 7 instead of spending the resources required to roll their own setup program. For those of you who liked the 6.0 Setup Wizard, you may be wondering why.

First of all, the Setup Wizard really wasn't all that friendly. You had to create separate directories for your distributable files and the resulting setup files—if you didn't, you could end up including all of your source code with your distribution files. And more than a couple developers did...

Second, the Setup Wizard was rather limited if you wanted to do anything other than a very vanilla installation—you couldn't create shortcuts, allow the user to install just a subset of your application's features (like you can today with Office, for example), install certain files in other directories (like datasets), and so on. And you couldn't create Windows 2000 logo-compliant applications with it either.

InstallShieldExpress for Visual FoxPro 7.0 (that's the full name—for the purpose of this article, we'll just call it "Bob." No, wait. That was taken. How about we call it ISE/VFP?) is a limited version of the Professional version of InstallShield that gives you access to most of the features of its big brother.

Where is it?

If you've got a virgin VFP 7.0 CD, you're probably in luck. Load it into your CD-ROM drive, and you'll get the VFP Setup screen, as shown in Figure 1.

There's a host of reasons why you might not get this screen, however. If you don't, find the VFPSTART.HTA file in the root of your VFP 7.0 CD, MSDN CD with VFP 7 on it, or from the results of unzipping that huge file from the MSDN Web site. I've been able to unzip the MSDN download successfully only intermittently. The rest of the time, I get helpful errors like "Setup was unable to find the baseline data" and "Setup was unable to copy the file F:\VFP7\msvcr70.dll to your temporary directory. Please make sure that this file exists and rerun setup." Okay, we all know those messages are nonsense, but I'll rant about that another time—or on another page. See my editorial in this issue for more on error messages.

Once you've gotten to this screen, you can install VFP, and then come back to it and install ISE/VFP as well. It's important to note that ISE/VFP is completely independent from Visual FoxPro—so you won't see a menu item added to the VFP system menu, for example.

Don't simply try to run the SETUP.EXE program from the VFP 7 root—that will get you to the screen in Figure 2, where you can install VFP by itself.

More help

Some developers will expect that they'll be able to find information about deploying applications in the VFP Help file, but they'll be disappointed. The decision to include InstallShield was made very late in the VFP 7 development process, well after the docs were frozen. So there's nary a mention of deployment in any fashion in the Help file.

To make up for this, Mike Stewart of the Fox Team has written a detailed paper on using InstallShield—you can find this paper by clicking the Technical Articles link on the main VFP startup screen, or, if you prefer to do things by hand, by browsing in the Technical Articles folder of your VFP CD. Still, there are some practical gotchas that only become apparent after you've had to build and deploy some setups for real customers. So the rest of this article will supplement Mike's walkthrough with real-world examples. Once you've been through this article, refer to Mike's work for additional information on advanced scenarios.

The plan of attack

The rest of this article will take you through the process of installing InstallShield, preparing your application for distribution, and then creating your distribution files with ISE/VFP.

1. Installing InstallShield First, you'll need to install InstallShield. You can either launch the setup program from the main VFP Setup screen (back in Figure 1), or you can run the SETUP.EXE program in the INSTALLSHIELD subdirectory on the VFP 7 or MSDN CDs. You'll get the screen shown in Figure 3.

I won't belabor the installation of ISE/VFP—you've been through the drill of installing new software enough times you could probably write this part yourself. Suffice it to say there aren't any real surprises. You'll go through the License Agreement, Customer Information (including a nice option to install the software for the current user or all users), the Destination Folder, and then a series of thermo bars that tell you what's going on (copying files, writing Registry values, and so on). The default installation folder won't be in the VFP program path, but rather a separate InstallShield folder beneath \Program Files.

Finally, the installation process wraps up by opening the InstallShield Web site. The page was supposed to open a page that encouraged you to upgrade to the full version of InstallShield, but when I installed ISE/VFP, the link failed (which is pretty ironic) and the main support page was displayed instead, as shown in Figure 4.

2. Preparing your application for deployment After you've gotten your application finished, you'll finally build an EXE (or a DLL) that you'll want to be installed and running on another machine. Whether that other machine is a stand-alone PC or workstation that's being used by one person at a time, a file server serving up a traditional LAN or client/server application, or a Web server doesn't matter at this point. (There are additional details you'll want to read up on in Mike's walkthrough.) For sake of simplicity, I'll refer to your application's EXE.

You've probably also got some ancillary files that will reside with your EXE, such as APP files for specific modules, CHM files for your application's Help, and perhaps some other files that are used by your app but excluded from the EXE.

And, since Visual FoxPro is a database application, you could well have some database files! Hopefully, you don't keep those in the same directory as your EXE, and, for purposes of this article, I'll assume you don't.

Unlike VFP 6, you don't have to do anything special with these files, like moving them into a special deployment directory or anything—you just have to know what and where they are.

InstallShield will need a place to put all the files it creates, and, if you let it, it'll try to locate that directory in a brain-dead choice deep in the bowels of your C drive. Instead, I suggest you create a "deployment" directory as part of your application's directory structure. Do it now, before starting up InstallShield. If you find yourself annoyed at having to navigate out of drive C and onto your development drive, you can change the default project location through the Tools | Options dialog in ISE/VFP. I changed mine to the root of drive E, since that's where all my development projects are stored.

3. Creating an InstallShield project Now that your application files are ready to go, it's time to start up ISE/VFP and build your setup files. When you build an installation with ISE, you'll create an ISE "project," and the parameters of that project are stored in a file named YOURPROJECT.ISM in the directory I mentioned in the previous paragraph, as shown in Figure 5. Once you start building your InstallShield project, a series of subdirectories under that directory will automatically be created, also shown in Figure 5.

In order to load ISE, select Start | Programs | InstallShield | Express Visual FoxPro Limited Edition. You'll be greeted with the Welcome screen shown in Figure 6.

Click on "Create a new project." You'll be prompted for the name and location of your project—as you can see in Figure 7, the default name is "Your Project Name-1," and the default location is way down in Documents and Settings. At this point, either type in the name of your deployment directory that you created at the end of step 2, or use the Browse button to navigate to that directory. Then click the Create button in the upper right corner of the dialog.

4. Setting parameters and customizing your installation You'll then be greeted with the screen shown in Figure 8. The left pane walks you through each of the steps, and the right pane gives you additional information and allows you to enter information as appropriate for each step of the process. At first glance, the list of steps in the left pane is pretty intimidating—but at the same time, you can now see how powerful and customizable ISE/VFP is compared to the alternatives we've had in the past.

Your own needs will vary, and there isn't time to go into a detailed explanation of every setting in every step, but I'll walk you through the steps you're most likely to use.

The first thing you'll have to do is define some general parameters for your project. Click on the General Information node under Organize Your Setup. Once you click on a node, you'll see a red checkmark next to the node's name and icon, telling you that you've been to that step at least once. You can go back and forth between nodes as much as you want, although changes in some nodes do affect choices and data available in other nodes.

There's a lot of information in the General Information node, as you can see in Figure 9. There's too much here for you to possibly get right the first time, so you should plan on creating a sample project just to get an idea of how the process works and what all of the settings mean.

The settings that you'll definitely want to change in the General Information area are Product Name, INSTALLDIR, and DATABASEDIR (not shown in Figure 9). The Product Name is what shows up in many of the splash screens, and in the Add/Remove Programs applet in the Control Panel. This value defaults to "Default," which looks kind of funny in the Add/Remove list. You can see I changed the Product Name to "WR Gizmo Plus."

The INSTALLDIR and DATABASEDIR entries define where you want your application files and your data files to be installed. The choices available for these entries are pretty interesting. In Figure 9, you'll see that the INSTALLDIR is:

The value inside the square brackets is a semaphore for "Program Files"—that means that when it comes time to install the package on the target machine, the installation routine will look in the Windows Registry to find out where "Program Files" is located and will create a "Hentzenwerke\WRGizmoPlus" directory there automatically. It doesn't matter what "Program Files" is actually called on the machine—in Germany, for example, the directory is called "Programme." InstallShield will find the correct directory.

In order for your application to be Windows 2000 logo-compliant, you need to follow this standard—you can't just go off and install your application any old place you feel like. That's why they're standards!

Suffice it to say there are a variety of choices available to you for INSTALLDIR and DATABASEDIR. (Why are there choices if "Program Files" is required to be logo-compliant? Well, how many of your custom applications have to be logo-compliant?)

Anyway, there are other General Settings to choose from as well—experiment with the ones that are important to you, and watch where that information shows up when you do your test installation.

The next step is to deal with "Features." This is pretty cool.

You know how when you install Microsoft Office you get this complex-looking tree full of nodes and drop-down arrows and such? Using this mechanism, you can choose which parts of the program you want to install now, which you want to be installed upon first use, and which you want to always run from the CD.

With ISE/VFP's Features feature <s>, you can provide the same choice to your customers. You can identify parts of your application as specific "features," and then signify which features have to be installed, and which can be installed optionally.

The big question on your mind is probably, "Hey, I've got a 6.4MB EXE—how can InstallShield know which parts of that EXE relate to which features, and, more importantly, how can it 'get into' my EXE and allow only certain parts of the application to be installed?"

The short answer is... it can't. You have to segment your application into discrete modules, such as a series of .APP files. Then you relate the various .APP files to features that you identify. Yes, unfortunately, you have to do a bit of pre-planning—okay, a lot of pre-planning. But if you have the need, ISE allows you to do this automatically, instead of your having to write some complex Visual FoxPro code to accomplish the same thing.

The next step is to Specify Application Data—which is actually both your application (the EXE and related files) and your data. See Figure 10 for the nodes under the Specify Application Data step.

It's here that you identify each file in your application, tell ISE where you want it placed, and, if you're using the Features capability, which feature each file belongs to.

Using the Files node is a bit tricky at first. The right pane divides into four windows, as shown in Figure 11.

The top two windows are tied to the source computer—where the files are coming from. The left window is the directory structure, and the right window is a list of files in the directory selected in the left window—typical Explorer fashion.

The bottom two windows have the same relationship, except that they represent the destination computer—you know, where you're going to be doing the installation.

Note that in Figure 11, there are two directories, one named DATABASEDIR and one named INSTALLDIR. These are the semaphores for the actual entries you created in the General Information node earlier. However, these directories don't show up automatically in the pane. You need to right-click on the Destination Computer node and select the Show Predefined Folder menu item. A second context menu will display with a series of available choices, such as DATABASEDIR, INSTALLDIR, and a whole panoply of others.

The next step is to add files to those directories. Figure 12 shows the results after I dragged WR04A.EXE and WR04A.INI from the Source computer explorer pair to the ISNTALLDIR node in the Destination computer's folders.

If you've taken advantage of the Features capability of InstallShield, you'll then identify which files belong to which features via the Files and Features node.

The next required step is to identify the files that you need to include with your application that aren't strictly part of your application. InstallShield calls these "Objects/Merge Modules"—things like your runtimes, ActiveX controls, OLE DB and ODBC drivers, and SOAP SDK files.

In Figure 13, you'll see I've selected all of the Visual C++ 7.0 Runtime Libraries and the Visual FoxPro 7 Runtime Libraries. You actually only need the first of the Visual C++ files, but it doesn't hurt if you select all of them.

The various VFP 7 Runtime Resource Libraries (listed under the Runtime Libraries item) are packages for specific languages—if you highlight one and then read the description, you'll see that the filenames look like VFP7RKOR.MSM, VFP7RDEU.MS, and so on. Mike's paper describes which languages these represent. For English-only applications, none of these additional items need be selected.

In the Customize.../Dialogs node, you'll need to check the customer information check box if you want your apps to have the option to install "for anyone who uses this computer." You have to install the app as an Admin, and if you don't check the check box, nobody else can use the app.

As you work through the steps, you'll occasionally run into a node where the descriptions display a padlock next to the caption "This view is available only in the full edition," as shown in Figure 14. This should be self-explanatory—since ISE/VFP is a limited edition, you don't get all the features. If you have InstallShield already (or if you go and buy it), you don't need ISE/VFP anymore.

Space constraints keep me from describing each and every node—you could literally write 50 pages on the details. So let's move on to the grand finale—actually building your installation files!

Figure 15 shows the Build Your Release node. You can choose which type of Media Type you want to build for. The choices include a variety of DVD formats, CD_ROM, Single Image, and a Custom choice. The CD_ROM and various DVD choices automatically break up your installation files into "Disk 1," "Disk 2," and so on. (Remember when software used to fit on a single CD_ROM? I just love saying that!)

The Single Image choice is what the VFP 6.0 Setup Wizard called a "Web Install"—it builds a single large SETUP.EXE file with everything jammed into it. This is suitable for network and Web installs, where you don't have to distribute the files on physical media. The Custom choice allows you to create your own set of parameters for creating files that are distributed on media, such as floppies or ZIP disks.

What to do once you've gotten to Figure 15 isn't immediately apparent—the UI doesn't work quite the same way as previous steps.

First, select the Media Type you want, such as Single Image. A variety of parameters are displayed in the far right window, and you can change some of them—which depends on which Media Type you've selected. Then right-click to bring up the context menu, as shown in Figure 16.

Select the Build menu option (or press the ever-intuitive F7 key), and InstallShield will begin to generate your files. A window named Output will open up on the bottom of the InstallShield dialog, showing you the progress of the process, as shown in Figure 17.

When the build process is done, the window remains at the bottom. You can use the very small close box in the upper-left corner of the Output window to close it. You can also use the two vertical lines below the close box to undock the window from the rest of the InstallShield frame, or you can use the View | Output menu option to hide/display the window.

When the build process is completely done, you'll get a slew of subdirectories under your main InstallShield directory. Depending on which Media Type you selected, the directories may change a bit.

For example, if you've selected Single Image, you'll see the directory structure displayed in Figure 18, with just a single large SETUP.EXE file as the result.

On the other hand, if you've selected CD_ROM, you'll see the directory structure and files displayed in Figure 19.

You don't actually have to find the files resulting from the build process—the last step allows you to have InstallShield deploy the installation file(s) to the target machine instead of having to manually find and copy them. I've just found it handy to understand what's going on under the hood.

Depending on your personality, you may want to click on the Test Your Release node. You have options to either do a complete test—including actually installing all the files on the machine you're testing on—or simply test the user interface, so you can see the screens, dialogs, and prompts.

The last step is to then deploy your files to the target machine. Click on the Distribute Your Release node under step 6, select the Media Type you've built for, and then enter the location you want to send your files to, as shown in Figure 20. You can use the Browse button or simply enter the location manually.

Finally, click on the Distribute to Location button, and wait.

Two things happen here that you should be aware of. First of all, there's no visual clue that the distribution process is done, other than the possible disappearance of the hourglass cursor. I thought this was a rather odd omission in a product that has a lot of other very nice fit-and-finish items.

The other thing is that if you're copying the setup files for a CD or DVD, the destination will receive all of the files and directories as if you were copying right to the media. And if that's the way you can do it, great. But some of us may not have writeable media hooked up to our development machine, so we'd need to archive off the distribution files to another machine first. Thus, be aware that you don't want to point to, say, the root of the C drive, with the intent of creating your media later—because you'll end up with the following files in the root:

• SETUP.EXE
• SETUP.INI
• YOURAPP.MSI
• INSTMSIA.EXE
• INSTMSIW.EXE

as well as directories for various pieces, such as [DATABASEDIR], [PROGRAMFILES], and [WINDOWS], and you'll have to clean it all up later.

5. Installing your application on the target You've done this 100 times—each time you install an application using Windows Installer technology, you go through pretty much the same steps. Find the SETUP.EXE program on your target machine—it should be where you put it in the Distribute Your Release step just a few moments ago. You start out with a Welcome screen, like the one shown in Figure 21 for WR Gizmo Plus, and continue on as you'd expect.

Because this is standard Windows Installer technology, you can uninstall your application through the Add/Remove Programs applet in the Control Panel.

6. Opening an existing project Open up InstallShield, click on the "Open a project" link, select the project from the Project List box, and click on the Open button as shown in Figure 22.

7. When stuff goes wrong Okay, this is Windows, and this is new stuff. Things are going to break. I recently received an error message "Internal Error 2355" when testing a Single Image install the other day. This is pretty typical of emergent technology (not that you should get used to it, or willingly accept it, but that's a different story). What do you do when something goes wrong?

The first place to look, of course, is the InstallShield Help file, and it only took a couple of minutes to find a comprehensive list of errors, their causes, and possible resolutions. As you probably guessed, of course, "2355" wasn't in the list. So then I went up to the various electronic forums, like the Universal Thread, the Wiki, and so on, to find out whether anyone else had run into this.

After ending up with a zero there, I went to the InstallShield forum at http://community.installshield.com. You can browse the message boards and archives anonymously, but you have to register (it's free) to post and receive mail. I found the answer to this error message in about four minutes on their message boards.

Another valuable online Web site is www.installsite.org, a robust community run by German Stefan Krueger. There's a ton of useful information, discussion boards, a file downloads section, and more.

It turns out that this particular error isn't an InstallShield problem, but something to do with the Windows Installer (for which InstallShield is just a wrapper) engine. Fortunately, you can get at the details through the MSI Help Library, which you can also launch from the InstallShield Help menu. Searching on "Error Messages" gives you a set of choices, the first of which is a complete list of runtime errors. It turns out that 2355 translates to "Corrupt Cabinet"—somewhat arcane by itself, but basically it means that the SETUP.EXE file is bad. I rebuilt the project and used "CD_ROM" as the Media Type, and everything ran and installed fine.

Conclusion

If you run around the online forums for a while, you'll see some people complaining about the limitations of ISE/VFP. I prefer to see the glass as half-full—ISE/VFP provides a host of features and capabilities that we didn't have with previous versions of Fox, and I'm glad to see it included. Admittedly, there are a few rough edges, but hopefully those will go away in future versions of Fox. But ISE/VFP is a great addition to an already great product.

To find out more about FoxTalk and Pinnacle Publishing, visit their website at http://www.pinpub.com/html/main.isx?sub=57

Note: This is not a Microsoft Corporation website. Microsoft is not responsible for its content.

This article is reproduced from the January 2002 issue of FoxTalk. Copyright 2002, by Pinnacle Publishing, Inc., unless otherwise noted. All rights are reserved. FoxTalk is an independently produced publication of Pinnacle Publishing, Inc. No part of this article may be used or reproduced in any fashion (except in brief quotations used in critical articles and reviews) without prior consent of Pinnacle Publishing, Inc. To contact Pinnacle Publishing, Inc., please call 1-800-493-4867 x4209.

© Microsoft Corporation. All rights reserved.