Active GUI element

Static GUI element

Code

WPS object

File/Path

Command line

Entry-field content

[Key combination]

more

In my last article I mentioned how you can use a so-called unattended, or CID, mode to install a Feature Installer-based product entirely from the command line. In this installment, I describe this process in more detail, and also touch on a few troubleshooting techniques related to installing Feature Installer-based products.

CID

CID is short for “Configuration, Installation, and Distribution,” which is IBM's terminology for automated software installation. A product which is CID-enabled can be installed without the need for user interaction, typically by placing configuration options into an ASCII file known as a response file, and typing a single command to run the installation.

All OS/2 components, and a large number of OS/2 software products, are CID-enabled. CID support is built in to the Feature Installer engine itself, meaning that any Feature Installer-based product is automatically CID-enabled.

Most Feature Installer-based products have CID installation instructions somewhere in their install documentation. These instructions describe how to create the response file, and how to launch the installation in CID mode.

Unfortunately, there are a couple of products (notably VisualAge C++ 4.0) which don't include any such instructions. Fortunately, it isn't too difficult figure out what you need.

Determining response file values

If you're lucky, the product's own install documentation tells you how to create a CID response file. Even if it doesn't, it's generally not that difficult.

You may remember that, in my last article, I described how you can use a partial response file to set installation variables for any product. Guess what? This partial response file is the same thing as the CID response file that you use for CLIFI—with one important difference.

The difference is that before, you didn't need to specify the components you were installing within this file because you could do that through the Install Object GUI. When doing an unattended install, though, you don't have access to a GUI, meaning that you need to specify all installation options in the response file. So, as well as the installation variables, we need to add the correct response file keywords for selecting the specific components we want.

In both cases, if there's no documentation then you have to do a bit of work to figure out what options you need to set. This isn't any different from how we did it in the last article; the easiest way is to just create an Install Object, populate it using the product definition response file, and take a look at the Variables page of its properties notebook.

For my real-world example this time, I'm going to be installing IBM VisualAge C++ 4.0; which, as I mentioned, doesn't include any documentation for unattended installation. (Well, actually, it does include some brief documentation on the subject; specifically, it says that it's not supported. Fortunately, I happen to know better. Any Feature Installer-enabled product can be installed in unattended mode; you just have to know the technique.)

So what I'll do is temporarily create an Install Object for VisualAge C++ 4.0, just so I can check the various variables. (In theory, I could read this information directly out of the product definition response file; but this is kind of a pain to do for variables, which can be scattered throughout this huge file. I think reading Install Objects is easier.)

The product definition file for VisualAge C++ 4.0 is located on the installation CD as \VACPP\VACPP.RSP. After I create and populate an Install Object with this file, I end up with an object called VACPP_FI. Taking a look at the Variables page, there are a total of 26 variables defined. Once again, I can disregard most of them, since they're either derived from other variables, irrelevant to my purposes, or both.

After a brief inspection of these variables, I conclude that the only ones I need to change are:

I don't plan on installing the Toolkit since I happen to have a later version on my system already, so I can ignore the variables specific to that component.

It's also worth mentioning that I don't need to change the Media Path variable that I mentioned in my last article, since CID installations don't make use of it.

Every Feature Installer product, and every selectable component of that product, is known as a feature. Now, each of these features has a feature ID, which is the internal symbolic name used by Feature Installer to identify it.

When I'm creating the CID response file, I need to prefix each variable name with the feature ID of the top-level feature, followed by a period. (I mentioned this last time.) I can determine the feature ID by opening the Install Object's properties notebook, and looking at the very first page (called Information).

The feature ID is listed as Installation Feature ID which is the first field shown. In the case of VisualAge C++ 4.0, it's VAC. Therefore, in my response file each variable name is prefixed with VAC..

So now I know what variables I need to specify, and how to specify them. The next problem is to tell Feature Installer which specific components I want to install.

For this, we need to know the feature IDs for each selectable component. Close the properties notebook, and double-click on the Install Object to open its normal view. This provides a hierarchical list of the various components (or child features) that make up the product.

To find out what the feature ID for each child feature is, right-click on its name in the tree, and choose Properties. The Install Object properties notebook for that child feature comes up.

Once again, the very first item on the first page, Installation Feature ID, shows the symbolic name of this child feature.

You'll notice the tree expansion buttons (“+” signs) next to most of the items in the Install Object. That indicates that they have child features of their own. I can determine what these are by expanding the tree nodes.

And I can determine the feature IDs of these third-level child features using the same method. In this case, they all seem to be described as “On CD/Lan”. I'm not entirely sure what these options do; however, they seem to be selected by default, so I'll leave them that way.

If I go through all of the child features in this way, I can eventually determine that the various VisualAge C++ components are:

At this point I have the information I need. I can now close and delete the Install Object since I won't be using it for installation. All I needed it for was to check the variable and feature ID names.

Now I'm ready to create my response file.

Creating the response file

To create the response file, I simply place each variable and each feature selection keyword in a text file, one per line. This text file should have the extension .RSP; I'll call mine VACPPCID.RSP.

Each variable must be specified in the format feature ID.variable=value, where feature ID is the top-level feature ID (in my case, VAC), variable is the name of the variable to be modified, and value is the new value for the variable.

Each selection keyword must be specified in the format child feature ID.Selection=value, where child feature ID is the feature ID of the product component (child feature), and value is either 0 (not selected) or 1 (selected). Do not prefix the selection keywords with the top-level feature ID; for these, only the child feature ID is required.

Here's my response file:

###  Drive and path variables
VAC.VACInstDrv=D:
VAC.VACSampDrv=D:
VAC.VACInstDir=Programs\IBMCPP40
VAC.VACSampDir=Programs\IBMCPP40

###  Selected components
VAC_BASE.Selection=1
VAC_IDE.Selection=1
VAC_IDETEC.Selection=0
    VAC_IDETEC_CDLAN.Selection=0
VAC_TKT.Selection=0
    VAC_TKT_CDLAN.Selection=0
VAC_TKTDOC.Selection=0
    VAC_TKTDOC_CDLAN.Selection=0
VAC_RES.Selection=1
VAC_VB.Selection=1
VAC_DAX.Selection=0
    VAC_DAX_CDLAN.Selection=0
VAC_SAMP.Selection=1
VAC_HTML.Selection=1
VAC_IOCL.Selection=1
VAC_IOCS.Selection=0
    VAC_IOCS_CDLAN.Selection=0
VAC_UNINST.Selection=1
VAC_CDLAN.Selection=0

You can put comments in by prefixing them with # (number sign).

As I mentioned, I've decided not to install the Toolkit that comes bundled with VisualAge. I'm also not installing the IBM Open Class Source, or the Data Access Builder (since I'm not doing DB/2 development). And I'm not actually sure what the IDE Tech Preview or the CD/LAN Install Option are, but since they're not selected by default in the product definition response file (they weren't checkmarked when I created the Install Object), I'll assume I don't need them either.

As you can see, for each child feature that I've deselected, I've been careful to specifically deselect its own child features in turn. These are the indented lines (the indentation isn't necessary, but I find it helps to visually distinguish the subordinate features). The reason I have to do this is that they default to selected in the product definition response file, and this ties in to an important characteristic of Feature Installer: deselecting a feature does not automatically deselect its children. So I have to do this explicitly. (I don't have to specify the children of the features which I'm selecting to install for the same reason: they're selected by default already.)

Starting the install

Starting an unattended Feature Installer installation involves using CLIFI.EXE, the command line interface to Feature Installer. This program is installed as part of Feature Installer, so it should be on your system PATH already.

CLIFI.EXE has quite a number of command-line options; for doing unattended installs, you only need a few of them.

The relevant command-line syntax looks like this:

    CLIFI /A:C /B:<boot drive>
               /S:<installation source>
               /R:<product definition response file>
               /R2:<CID response file>
               /L1:<name of error log file>
               /L2:<name of history log file>

I'll briefly describe the various parameters.

/A:C (specified exactly as typed)

This means “action - CID install&rdquo unattended mode.

/B:

Indicates the system boot drive; this is used to look for CONFIG.SYS and various other things (depending on the product).

/S:

Indicates the directory where the product's install files are located. This should be the same directory as where the product definition file (the next item) is located.

/R:

Specifies the file which contains the product definition used by Feature Installer. This is the product definition response file that I described in my last article; it contains all of the data about the product being installed, in ASCII text format. This file is always included with the product install's files, and is usually located either in the top-level product directory, or in an immediate subdirectory. It has a .RSP extension, and is probably quite large.

/R2:

Specifies the actual CID response file which contains the the various installation options. Feature Installer refers to this file as the partial response file; this is the response file that you created.

/L1: and /L2:

Specify the names of the log files to which Feature Installer saves the installation error log and history. These parameters are optional; if you don't specify them, the error log is written to the root directory of your boot drive as ERROR.LOG, and no history log is created.

So, to launch the installation of VisualAge C++ 4.0, I run:

clifi /a:c /b:c: /s:s:\vacpp /r:s:\vacpp\vacpp.rsp /r2:c:\vacppcid.rsp /l1:c:\var\log\vacpp.l1 /l2:c:\var\log\vacpp.l2

The product should start installing without any further prompting.

The sharp-eyed among you will probably notice that an Install Object actually gets created on the desktop when CLIFI starts running, and its title changes to reflect that of the product being installed. This is exactly the same process that we performed manually last time: CLIFI creates an Install Object, populates it with the product definition, sets its variables and selections according to the partial response file, and starts the install. The key difference is that CLIFI does all this automatically, without us having to do anything.

Once CLIFI has everything initialized and under way, you should see a progress display like this:

Assuming the installation completes successfully, CLIFI returns silently. (Any Install Objects it creates on the desktop are deleted automatically.) You should reboot before using the installed product.

In my case, I can see that VisualAge C++ 4.0 has been installed successfully to D:\Programs\IBMCPP40, my system files have been updated as they should, and the product folder was created on my desktop:

Troubleshooting

If you run into problems with Feature Installer, there are a few things you can do to resolve them.

Hangs during installations

First of all, Feature Installer's error recovery is neither robust nor speedy. If it encounters an error during installation, it can sometimes take a long time for it to figure out what's wrong, and abort. When this happens, it may appear to “hang” with a stalled progress indicator and no visible disk activity. I've known it to sit like this for a couple of hours (yes, hours), even on fast modern systems, before finally waking up and returning an error message.

Therefore, if Feature Installer appears stalled like this, you should wait for a few hours at least before assuming that it's actually hung.

True hangs in Feature Installer are usually more obvious. Unfortunately, one of Feature Installer's main weaknesses is the way it runs within the Workplace Shell process: if it actually hangs or crashes, it tends to take your desktop with it. In such cases, you may kill and restart the Workplace Shell, or you may need to reboot.

Occasionally, I've observed a situation which falls in between these two phenomena. Feature Installer may encounter an error and appear to abort successfully; however, in some cases, it doesn't properly clean up after itself, and any further attempts to use it fail until you reboot (or at least restart the WPS). In my experience, fortunately, situations like this seem to be pretty rare.

Log files

When installing any product, Feature Installer writes an error log file and, optionally, a history log file. You can specify these using CLIFI's /L1 and /L2 parameters, described above.

In practise, there is very little difference between the error and history log files. They both contain a detailed history of the installation, and if an error occurs, you can occasionally find indications within one of these files as to what went wrong. However, it's quite possible that they won't help you very much, and you'll have to look elsewhere for meaningful information.

Besides these two files, the Feature Installer always writes information to another log file called WPINSTAL.LOG, which is located in the \OS2\INSTALL directory. This file contains a history of all Feature Installer installations, dating all the way back to when the operating system (or at least Feature Installer) was first installed. This file can get very large, but it often contains information about problems which the other two log files do not. Check the end of the file for information about the most recent install.

Debugging response files

When you install a product using a response file, any minor error in the response file can result in the product not installing exactly in the way you want. Common problems include ending up with the wrong components installed, or files being installed to the wrong location.

These problems generally arise because you either failed to specify all of the necessary keywords in the response file, or because you specified some of them incorrectly.

Keep the following in mind when creating your CID response file:

• Always remember to prefix variable names with the feature ID of the top-level feature. However, you must not do this with component selection keywords, since those must be prefixed with the component's own (child) feature ID instead.
• When you deselect any component for installation, you must remember to explicitly deselect all of its children as well.

You can test your response file for possible errors by creating an Install Object on your desktop, reading the product definition into it (as described in my last article), and then reading your response file into it in the same way. Then double-check the Variables page of the object's properties notebook to make sure all the variables were set correctly, and also confirm that the correct components within the Install Object were selected or deselected as they should have been.

Cleaning up Installed Features

As discussed in my last article, any Feature Installer-based product which has been installed has an Install Object created for itself under the Installed Features folder (located under \OS2\INSTALL on your boot drive). These Install Objects are known as inventory objects, and they contain all the information about the installed product. You can use these objects to view the installation history, and uninstall all or part of the products they represent.

Data about these objects is kept in the file \OS2\INSTALL\FI.INI. It's possible for a failed installation to result in invalid or incomplete inventory objects, and under such circumstances FI.INI can end up “out of sync” with the contents of Installed Features. This problem can manifest itself with mysterious errors and crashes in Feature Installer when trying to install or uninstall products.

There are a pair of free utilities (by Henk Kelder, author of CHECKINI) called MAKEFI and READFI, which are designed to fix problems relating to FI.INI and the Installed Features folder. These are available on Hobbes, and simple instructions are included. The general approach is to delete any invalid inventory objects from the Installed Features folder (possibly running CHECKINI or a similiar utility afterwards), then run READFI.EXE to identify any corruption in FI.INI, and MAKEFI.EXE to recreate FI.INI if necessary.

Warp Server SMP and the Netscape plugin

For those of you using Warp Server SMP (version 4), you may have noticed a little problem with Feature Installer and the most recently available versions of Netscape Communicator. The Feature Installer plugin does not work, and there appears to be no way to make it work.

This seems to be something peculiar to Warp Server SMP. Fortunately, after reading these articles, you should be better-equipped to install FI-based products without needing the Netscape plugin.

If you absolutely need to use the web browser method, I've found that the plugin does work with Netscape Navigator 2.02, so you can install and use that version (assuming you can get hold of a copy). It may also work with older builds of Netscape Communicator 4.x (not the latest versions), but I have no way of confirming this.

Problem product: Java 1.1.8

Java 1.1.8 is one of the most unpleasant Feature Installer products that I've ever installed. I have to admit that I've never yet managed to successfully install it using the Install Object method.

The first problem is that this product relies on a particularly large number of obscure variables, and figuring out the dependencies is quite difficult.

The second problem is that several of these variables, most especially the Media Path variable, are only defined relative to the current working directory (which is assumed to be the directory containing the install executable that calls Netscape). Unfortunately, when you try to install using an Install Object, the current working directory doesn't resolve properly, meaning that Feature Installer can't locate the product files no matter where you tell it to look.

There's a good chance that this can be solved by overriding enough of the variables to point to the correct place. However, I haven't spent enough time trying to map all of the variable dependencies to get this to work.

For this reason, if you have to install Java 1.1.8 without Netscape, I recommend you use the CLIFI method (which is at least described in the accompanying documentation), rather than an Install Object.