Software Installer: Your Tool for Installation

by Anita Hampton and Lalethia Vereen

Software Installer is a development tool that you can use to create a front end for your OS/2 applications. When you use Software Installer to develop your product, your users can install, update, restore, and delete it. Software products that use Software Installer can be installed in an interactive graphical mode or in an unattended batch mode. (You can find Software Installer in the Development Tools category of your accompanying Developer Connection for OS/2 CD-ROMs.)

Software Installer provides the following features:

• Exits that allow modification of CONFIG.SYS files
• Exits that allow creation and deletion of Workplace Shell objects
• The ability to run application-specific exits
• The ability to replace product files that are in use (accomplished via the locked files device driver)
• Check for required hard disk space
• Tailorable initial installation screen
• Shared component support
• Multiple language versions

And much more!

Software Installer lets you create diskette, CD-ROM, host, or unattended LAN installations. The unattended LAN installation uses IBM's Configuration, Installation, and Distribution (CID) architecture.

Creating Your Installation Program

You must enable your product for Software Installer. The two primary files needed for Software Installer customization are the catalog file and the package file. These files consist of multiple entries represented by entry types and keywords. Before beginning your enablement for Software Installer, you should decide how your product will be packaged and how the user's environment will be changed. Consider the following:

• How will you distribute your product? (diskette, CD-ROM, LAN, host?)
• Will your packaging contain one product or multiple products?
• Does your product have components that can be installed separately?
• How many directories are required for your product?
• Does your product require changes to the user's CONFIG.SYS or .INI files?
• What objects are required on the desktop for your product?
• What will the user see while Software Installer is starting the installation of your product?

Enabling Your Product for Software Installer

To enable your new product to use Software Installer, follow these steps:

1. Select the Add New Product object from the Software Installer main folder. A folder will be created for your product.
2. Select your product folder from the Software Installer main folder.
3. Select the Add New Language object from your product folder and follow the instructions on the screen.
4. Select the Install Utility folder from your product folder.

The Install Utility folder contains the steps you must follow to enable your product to use Software Installer. In this article, we will take you through a sample enablement using Software Installer. We'll use the Install Utility folder to:

• Create catalog, package, and description files.
• Build the hook .DLL (this is optional).
• Create the response file.
• Customize the initial installation screen (IIRC.RC file).
• Create an INSTALL.IN_ file.
• Package the product.

In our example we will present shared components, exits, and a sample hook.

Creating a Catalog File

The catalog file contains product information that Software Installer needs to install and maintain your product.

The catalog file is a text file that contains entry types. These entry types, or entries, have keywords that have values. These values tell Software Installer all about the product and how to install it. You can think of the catalog file as a description of the product, whereas the package file describes the files that compose the product.

To start with a template of the catalog file, select Add New Catalog File from step 1 in the Install Utility folder. Figure 1 shows the catalog file for our product (which we've named My Product).

CATALOG
NAME = 'My Product Catalog',
DESCRIPTION = 'My Product is a great product.
This text is from the DESCRIPTION keyword of the
CATALOG entry in GETSTART.ICF. The text describes
the product catalog. The catalog description is limited
to 512 bytes. The catalog file also contains a PACKAGE
entry for each of the products in the catalog.'

PACKAGE
NAME = 'My Product',
NUMBER = '1000-003',
FEATURE = '0000',
VRM = '010300',
PACKAGEFILE = 'DRIVE: GETSTART.PKG',
PKGDESCRFILE = 'DRIVE: GETSTART.DSC',
SIZE = '32000',
UPDATECONFIGSYS = 'NO'

Figure 1. Catalog file for My Product

As you can see, the catalog file has only one CATALOG entry but can have as many PACKAGE entries as there are products (up to a maximum of 78). The PACKAGE entry includes the following keywords:

• The NAME is the name of the product.
• The NUMBER value can be a product number or order number. We used 1000-003 for our example.
• The FEATURE keyword designates a set of features our sample product contains. We used 0000.
• VRM is the version number. Our product is version 01, release 03, and modification 00. You can use zeroes for the parts of the VRM that do not apply to your product. If your product doesn't have any of these specifications, use 000000 for the VRM.
• PACKAGEFILE is the name of the package file we plan to use. For our sample, the name is GETSTART.PKG. We used the DRIVE:<file_name.ext> format because our product installs from a diskette drive.
• PKGDESCRFILE is the name of the description file that we plan to use. For our sample, the name is GETSTART.DSC.
• The SIZE value indicates how many bytes the product requires. We have used 32000 bytes as the combined size of all of our components and file system requirements. (The value is displayed as the Bytes required field on the Disk space window. To open this window, select Product Status from the Details pull-down menu on the Installation and Maintenance window.)
• The UPDATECONFIGSYS keyword is either Yes or No. Because our sample product does not update the CONFIG.SYS file during installation, the value is No.

Creating a Package File

The package file describes the files that make up your product. The entry types and keyword values in the package file define all of the information needed by Software Installer to install, update, restore, or delete a product on the workstation.

To create a package file, select step 1 on the Install Utility screen, and then select Add New Package File. In our example, we will be installing a shared component. Software Installer lets you share components between products within the same group. Your user only needs to install the shared component once.

Products that share a component must be installed to the same high-level directory. The directory that contains the shared component must be the FILE directory or a subdirectory under it, and it must be the same directory for all products that install it. Use the disableentry and getproductdir APIs to force installation to the same FILE directory by priming the target directory entry field and preventing the user from changing it.

Next, you must create a package file for the shared component (see Figure 2) and include it in the main package file.

Except for the COMPONENT entry type and its keywords, the information for a shared component must be in its own package file, which is included (using the INCLUDE entry) in the main package file of each of the products that share it. The shared component's package file cannot include any other package files. This ensures that each product has the same information about the shared component. By separating the shared component entries, Software Installer can transfer an updated package file when necessary to ensure that the shared component's PACKAGE file entries always match the component. If products in the suite are packaged separately, each product must ship its own copy of the shared component's package file as shipped by the various products of the suite.

We recommend that all FILE entries in the shared component's package file have WHEN='ALWAYS' or a combination of INSTALL, UPDATE, or DELETE . The package file must be the same (except for the VOLUME values) among all products in the suite, so avoid run-time evaluation of the WHEN key values, which could cause them to be evaluated differently for each product.

The shared component's package file can contain the following entry types:

• ADDCONFIG
• EXIT
• FILE
• PACKFILE
• UPDATECONFIG

The shared component's package file usually contains FILE and EXIT entries, but does not contain entry types such as DISK, SERVICELEVEL, and PATH. Those entry types belong in the main package file.

Figure 2 shows a package file for our shared component:

FILE
WHEN = 'ALWAYS',
UNPACK = 'NO',
SOURCE = 'DRIVE:COMMON1.EXE',
VOLUME = 'ONE',
PWS = 'COMMON1.EXE',
SIZE = '1000'

FILE
WHEN = 'ALWAYS',
UNPACK = 'NO',
SOURCE = 'DRIVE:COMMON2.FIL',
VOLUME = 'ONE',
PWS = 'COMMON2.FIL',
SIZE = '1000'

FILE
EXITWHEN = 'INSTALL !! UPDATE !! RESTORE',
EXITIGNOREERR = 'NO',
EXIT = 'CREATEWPSOBJECT WPProgram 'Shared Component'
<GETSTFLD> R
'EXENAME=%EPFIFILEDIR%\\COMMON1.EXE;OBJECTID=<COMM1EXE>''

FILE
EXITWHEN = 'DELETE',
EXITIGNOREERR = 'YES',
EXIT = 'DELETEWPSOBJECT <COMM1EXE>'

Figure 2. Shared component package file

Next, add a COMPONENT entry for the shared component in the main package file of each product that ships it. Shared components require the following special COMPONENT entry type keywords: NUMBER, FEATURE, VRM, PKGFILE, and SHARED.

A component is indicated as shared by setting the SHARED keyword to Yes and setting the PKGFILE keyword to the name of the shared component's package file. The value of the PKGFILE keyword must be the same in the main package file for each product that ships it. The NAME, NUMBER, DELETE, and FEATURE keywords must also match in the main package files.

Except for the component entry type and its keywords, all other entry types and keywords for the shared component must be located in a separate included package file. Each shared COMPONENT entry type must have one and only one INCLUDE entry. It cannot include more than one shared component package file. The INCLUDE entry must sequentially follow the shared COMPONENT entry in the main package file.

Figure 3 shows the package file for our sample product:

PATH
FILE = 'C:/GETSTART/EXE',
FILELABLE = 'Executable directory: ',
AUX1 = 'C:/GETSTART/DOC',
AUX1LABEL = 'Documentation directory: '

* Product Folder

COMPONENT
NAME = 'My Product',
ID = 'PRODFLD',
DISPLAY = 'NO',
SIZE = '0'

* Register My Product folder to the desktop

FILE
EXITWHEN = 'INSTALL !! UPDATE !! RESTORE',
EXITIGNOREERR = 'NO',
EXIT = 'CREATEWPSOBJECT WPFolder 'My Product'
<WP_DESKTOP> R 'OBJECTID=<PRODFLD>''

* Define the Executable Component

COMPONENT
NAME = 'Executable',
DESCRIPTION = 'My Product object',
REQUIRES = 'PRODFLD',
SIZE = 28000,
DISPLAY = 'YES'

* Transfer GETSTART.EXE and run an application specific exit

FILE
PWS = 'GETSTART.EXE',
PWSPATH = 'FILE',
SOURCE = 'DRIVE: GETSTART.EX_',
UNPACK = 'YES',
EXITWHEN = 'INSTALL !! UPDATE !! RESTORE',
EXITIGNOREERR = 'NO',
EXIT = 'EXEC fg pm %EPFICURPWS%
'Exit 1 opened when GETSTART.EXE is installed.''

* Register the Executable component in My Product folder

FILE
EXITWHEN = 'INSTALL !! UPDATE !! RESTORE',
EXITIGNOREERR = 'NO',
EXIT = 'CREATEWPSOBJECT WPProgram 'My Product
Program Object' <GETSTFLD> R 'EXENAME=%EPFIFILEDIR%\\GET-
START.EXE;OBJECTID=<GETSTEXE>; PARAMETERS='Thanks.'''
.
.
.

* Delete the Getting Started Executable on a delete action

FILE
EXITWHEN = 'DELETE',
EXITIGNOREERR = 'YES',
EXIT = 'DELETEWPSOBJECT <GETSTEXE>'
.
.
.

* The Getting Started Shared Component

COMPONENT
NAME = 'Shared Component',
NUMBER = '1234-567',
FEATURE = '0000',
ID = 'SHARE',
PKGFILE = 'COMMON.PKG',
VRM = '010100',
SHARED = 'YES',
DISPLAY = 'YES',
REQUIRES = 'PRODFLD',
SIZE = '500000'

* Include the shared component package file

INCLUDE
NAME = 'DRIVE:COMMON.PKG'
.
.
.

* Delete the product folder last on a delete action

FILE
EXITWHEN = 'DELETE',
EXITIGNOREERR = 'YES',
EXIT = 'DELETEWPSOBJECT <GETSTFLD>'

Figure 3. My Product package file (partial listing)

Building EPFIHOOK.DLL

If you need special installation directory processing, you can customize the EPFIHOOK.C program by changing the code and rebuilding EPFIHOOK.DLL. In the following example, we'll customize the EPFIHOOK function to use the disableentry and getproductdir APIs.

{ // begin EPFIHOOK1()
.
.
.
ULONG ulProdFound;
PRODUCTDIR *pProductDir; /* pointer to the PRODUCTDIR structure */

ulProdFound = 0;

/*******************************************************/
/* Allocate memory for the product directory structure */
/* pointer. This pointer is defined in varsfp.h. */
/*******************************************************/
pProductDir = (PRODUCTDIR *) malloc(sizeof(PRODUCTDIR));
.
.
.
/****************************************************************/
/* Check if the product is installed using the getproductdir */
/* API. */
/****************************************************************/
ulProdFound = getproductdir('My Product',
'1000-003',
'0000',
pProductDir);
/**********************************************************/
/* The product is installed so prime the directory fields */
/* and disable user entry. */
/**********************************************************/
if (ulProdFound)
{
strcpy(szFilePath, pProductDir->szFilePath);
disableentry('YES');
}
else
{
disableentry('NO');
} /* endif */
.
.
.
free(pProductDir);
} // end EPFIHOOK1()

Figure 4. Sample code to be added to the EPFIHOOK1 function

Creating the Response File

You can use response files to pass information to the Software Installer executables. The response files must be on the workstation before the Software Installer executable (EPFIDLDS.EXE) is started.

Software Installer supports installations that have one specific response file and, optionally, have general response files that are included by the specific response file. The response file must contain all the keywords or installation variables your product's installation processing needs. Your documentation for unattended installation should explain how to set the values of the response file keywords. You can use an existing response file or use a template (step 3 on the Install Utility screen) to create a new one.

The following is an example of a response file that can be used to customize an installation:

FILE = D:\PRODUCT\EXELIB
WORK = D:\PRODUCT\WORK
COMP = COMPONENT1_NAME
COMP = COMPONENT2_NAME
COMP = COMPONENT3_NAME
CFGUPDATE = AUTO
OVERWRITE = YES
SAVEBACKUP = NO
DELETEBACKUP = NO

Note: Do not use quotes around the component name, even when the name is more than one word with blanks between words.

Modifying, Compiling, and Testing the IIRC.RC Resource File

Use the IIRC.RC resource file to customize the appearance of your product installation, including:

• Bitmaps for the installation window and where and how they appear
• Color, title, size, text, and buttons on the initial installation window
• Information and dialog boxes

First, create any bitmaps that you want on your initial window. Your company or product logos are ideal candidates. Then do the following:

1. Select the IIRC.RC file from the contents of the step 4 folder. Follow the directions in the file to modify it. The IIRC.RC file must contain one bitmap statement for each bitmap you plan to display. For example:

   BITMAP INST_BITMAP1 SIMPLE.BMP

2. Create any information files you reference in the IIRC.RC resource file.
3. Select Compile IIRC.RC from the contents of the step 4 folder to compile the resource file and bind it to EPFIDLDS.EXE, the initial installation program executable file. When you do this, you must have the OS/2 resource compiler, RC.EXE, installed and the following files must be in the current working directory:
   • The modified IIRC.RC
   • EPFIIIRS.RES
   • IIRCH.H
   • EPFIDLDS.EXE
   • Any bitmap files you reference in IIRC.RC
4. Test the IIRC.RC file by selecting Test IIRC.RC Changes. The initial installation window with your bitmaps and installation instructions appears.

Check the location and contents of the bitmaps and information windows you defined when you modified the IIRC.RC file. When you see the information window with the Continue and Cancel push buttons, you have tested your product's IIRC.RC file. Select the Exit push button in the initial installation window.

Creating an INSTALL.IN_ File

Finally, let's create a compressed installation file containing the compressed Software Installer files and other files specific to the application:

1. Select step 5 on the Install Utility screen.
2. If desired, type the names of the files you want packed as part of INSTALL.IN_. The number of file names is limited only by the 255-character limit of the command line. Separate the names by a single space. (Note: HPFS file names with imbedded spaces are not allowed.)
3. Select Open. Software Installer packs the installation files needed for the distribution diskette into INSTALL.IN_ and places INSTALL.IN_ in your working directory.

Packaging Your Product

To package your product, follow these steps:

1. Format one diskette for each DISK entry in the package file.
2. Copy the following files from your working directory onto the first distribution diskette in the following order:
   • INSTALL.EXE
   • INSTALL.IN_
   • The catalog, package, and description files
3. Select Package Product onto a Diskette, step 6 on the Install Utility screen.
4. Type the parameters, for example:

   /ud drive myprod.pkg a: d:\mywork

   and select Open.
5. When you are prompted for a new path and name for the output package file, enter an output package file name. Follow the instructions on the screen.
6. Copy the output package file to the first distribution diskette using a .PKG extension.

Testing CID Enablement

IBM has developed a configuration, installation, and distribution method, called CID, to standardize how products are installed and distributed. If your product must be CID-certified, this last step helps you meet those requirements. To test your product for CID enablement, do the following:

1. To prepare your product documentation, select CIDTEMPL.TXT and modify the file for your product. Add this information to your product documentation. It must include the following:
   • How to transfer diskette images to hard disk
   • How to create a response file
   • How to install your product using command line parameters
   • What return codes your product uses
2. Select Test CID Enablement Using Command Line Parameters. Specify your parameters and select Open.
3. Install your product using the LAN CID Utility (LCU).
4. Install your product using NetView Distribution Manager/2.

Testing Your Installation

Of course, you'll want to test the installation diskette. To do so, insert the diskette into your diskette drive (in this example, drive A) and type a :\install at an OS/2 command prompt. Follow the instructions on the Install window and the Install - directories window. When you have selected the Install push button, you'll see the Install - progress window.

Conclusion

Software Installer provides a great installation and maintenance tool for your application. With its support of diskette, CD-ROM, and host and unattended LAN installations, it is definitely your tool for installation.

Software Installer Additional Information

For more information about Software Installer, call the following:

• Technical Sales Support Fax: 919-254-4820
• IBM SWS Development Lab:

US: 1-800-426-2279

Outside US: 1-919-254-4760

• Obtain Technical Support through:

IBM Talklink: INSTALL2 FORUM. For Talklink registration and access questions, call 1-800-547-1283.

CompuServe: GO OS2DF2, Section 8. For CompuServe registration and access questions, call:

US: 1-800-848-8990 (representative #239)

UK: 0800-289-378

Germany: 0130-86-4643

Registering Your Software

To register as a user of Software Installer, complete the registration form, REGISTER.FRM, and return it to us.

Please write in English, imbed the form in a note, and send it to installr @vnet.ibm.com.

You can also print this form and fax it to the Software Installer Development Team at 919-254-4914.

Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation