DataBlade Developers Kit User's Guide Using BladePack

To package your DataBlade module, you add content to a BladePack project, assign components, customize the installation procedure, and build the package.

For information on packaging DataBlade modules for UNIX, see Packaging for UNIX Installations. For information on packaging DataBlade modules for InstallShield 5.1, see Packaging for InstallShield 5.1 Installations.

1. Open a project file:
• For DataBlade modules created using BladeSmith, open the project.prd file by choosing Project Open or launch BladePack from the BladeSmith Tools menu while the project is open.
• For other products, create a new BladePack project by choosing Project New.
2. Define the content of your product, including files, directories, and registry changes.
3. Define and assign installation components.
4. Define optional customizations.
5. Build the installation package.
6. Transfer files from the build area to installation media.

You can add these objects to your product in BladePack:

• Files and directories to install

For a DataBlade module, you need the project.bld or project.jar file and the SQL script files. If you have an ActiveX client project, you also need the project.dll file. These files are automatically added to the Files to Install folder when you open a project.prd file.

In addition, consider adding documentation, help, applications, and other files to support your DataBlade module.

If you have an ActiveX client implementation, consider including CLSID (class identifier) and IID (interface identifier) information by including C++ client support library files (see Support Library Files) in the installation package.

• Files and directories to delete

If you are packaging an upgrade, you might need to specify files or directories to delete in the old installation.

• Registry changes

You might have to specify registry changes for your DataBlade module.

1. Choose Edit Insert object, where object is File to Install, File to Delete, Directory to Install, Directory to Delete, or Change to Registry.

The object appears on the Files/Directories page.

2. Specify the properties of the object on the Details and other pages in the item view.

The following sections describe the properties of the objects on the Files/Directories page.

The following table lists properties you define when you add files and directories to install or delete.

If you have files that are operating-system-specific, put them in a directory structure that is the same except for one directory, which is named for the operating system. When you add the file to your BladePack project, replace the directory named for the operating system with %OS%.

For example, if you compile your C or C++ DataBlade module on Sun Solaris and Windows NT, you have two project.bld files, one in each of these directories:

• project/src/c/Solaris-sparc
• project\src\c\WinNT-i386

Add the project\src\c\WinNT-i386\project.bld file to the Files to Install folder and then replace WinNT-i386 with %OS%. When you build the BladePack project for Sun Solaris and Windows NT, BladePack adds the appropriate project.bld file to each project.

For a Java DataBlade module, you have only one version of the project.jar file, which is in the project/src/java directory.

You have the following options in the list for the Directory on target machine field:

• __home. The directory the installer chooses during the installation process. By default this directory is $INFORMIXDIR.
• __system. The Windows NT system directory.
• __windows. The Windows NT directory.

The target directory for the DataBlade module files (project.bld and the SQL scripts) should be the extend\project directory under the $INFORMIXDIR directory.

For files in the Files to Install folder, choose one of these file sharing options from the Copy Options page:

• File is system shared DLL. Indicates that the file can be used by more than one program on the target computer. The file is marked to prevent it from being removed in an uninstallation process.
• File may be in use on target system. Indicates that the file can be in use when the program is installed. If the file exists on the target computer and is in use during the installation process, the installation continues, but the computer must be rebooted before the program is run. In this case, the installation program displays the Setup Complete, Reboot Required screen.
• None. Default. Indicates that your files are not shared and cannot be in use during the installation process. In this case, the installation program displays the Setup Complete screen without a prompt to reboot the computer.

You can add entries to the Windows NT registry for the initialization and configuration of your DataBlade module and its associated programs.

Refer to your Microsoft Developer Studio documentation for information about the registry.

1. Choose Edit Insert Change to Registry.
2. Complete the Registry Changes Details page in the item view.

The following table lists the properties you define when adding registry changes.

BladePack allows you to organize your product installation package into three layers: component, subcomponent, and shared component. To see the component hierarchy for your product, click the Components tab in the project view.

Organizing an installation package into a component structure allows you to define Typical, Compact, and Custom installations. You specify whether each component or subcomponent is included in the Typical and Compact installations, and whether it is initially selected when users choose the Custom installation.

Use a shared component for those portions of your product that are shared by more than one component. A shared component is always installed with the subcomponent with which it is associated.

During a Custom installation, users can choose to install any components or subcomponents. When you mark a component Custom, the component is initially selected. The user can choose to include or exclude any components, except shared components, from the installation.

In most cases, the component level is sufficient to create Typical, Compact, and Custom installation options. For example, suppose you have created the following components (and no subcomponents) in your installation package and marked them as shown:

• DataBlade module. Typical, Compact, Custom.
• Help. Typical.
• Examples. Typical.
• Debugging Support. Custom.

In this scheme, users install the DataBlade module, help files, and examples if they choose the Typical installation. If they choose the Compact installation, they install the DataBlade module only. If they choose the Custom installation, the DataBlade module and debugging support are preselected. They can choose to add help and examples.

1. Choose Edit Insert Component.
2. Complete the properties on the Component Details page in the item view.

1. Select the component to which you want the subcomponent to be subordinate.
2. Choose Edit Insert Subcomponent.
3. Complete the properties on the Component Details page in the item view.

1. Select the subcomponent to which you want the shared component to be subordinate.
2. Choose Edit Insert Shared Component.
3. With the shared component still selected, choose Edit Copy.
4. Select another component to which you want to add the shared component.
5. Choose Edit Paste.

The following table lists the properties of components and subcomponents you define when you create them.

Shared components have one property: an identifier that is assigned by BladePack. You can edit the identifier; it can be an alphanumeric string up to 128 characters. Make sure it is unique among shared components. If you change an identifier, be sure to update it for every instance of that shared component.

You must assign every item on the Files/Directories and Customization pages to a component, subcomponent, or shared component. If you try to build the project with unassigned items, the build fails and you receive an error message telling you which item is not assigned to a component.

Initially, all files and directories that appear on the Files/Directories page are listed under the Unassigned Files and Directories folder on the Components page. Custom extensions are not shown on the Components page.

To assign an item to a component, use one of these methods:

• On the Components page, drag an item out of the Unassigned Files and Directories folder into the folder of the correct component. This process is not valid for custom extensions.
• On the Details page for the item in the item view, select a component from the Install when customer selects this component list. You must have already defined the component.

Custom extensions for the installation program are optional. For InstallShield 3.1 installation packages, you can add these custom extensions:

• Routines to call from the installation program
• InstallShield dialog boxes
• Programs to call from the installation program
• README files for the installation program

In addition to adding the custom routines, dialog boxes, and programs in their respective folders, you must also add the file containing the custom extension to the Support Files folder. However, if you have more than one routine, dialog box, or program in a file, you need only add that file to the Support Files folder once.

1. Choose Edit Insert Item, where Item is Custom DLL Routine, Custom DLL Dialog, or Custom Program.
2. Complete the Details page in the item view.
3. Choose Edit Insert Support File.
4. Type the path and filename of the file containing the custom routine, dialog box, or program or click Browse to select the file from the Open dialog box.

1. Choose Edit Insert Readme File.
2. Type the path and filename or click Browse to select the file from the Open dialog box.

The following table lists the properties of custom routines, dialog boxes, and programs you specify when you add them to your installation project.

When the content and organization of your installation package are complete, build and test it.

To build, choose Build Build Installation. The Build Installation wizard is launched and prompts you for the following information:

• Installation type: interactive or file tree

See Installation Type for more information.

• Platform for which to build the installation package

Choose one from the list. Build a separate package for every platform.

• Installation screen text

See Installation Screen Display Text for more information.

• The target directory in which to build the installation

This can be any directory. By default it is the project\install directory.

• List of BladePack project.prd files to include in the installation package

You can bundle more than one project in a single installation.

Warning: If the combined length of the path and filename of any file is longer than 255 characters, the build fails. This is due to a Windows limitation. To solve this problem, you can select a shorter staging directory.

BladePack creates a directory structure in the target directory and copies files into the tree. When you build an interactive installation package for Windows, BladePack calls InstallShield to process the files and create CD-ROM and diskette images.

When you build a file tree installation, BladePack creates the file tree specified in the project in the target directory. A file tree build is useful for debugging the BladePack project.

After you successfully build an interactive installation, the target directory contains the subdirectories described in the following table.

BladePack provides default text strings for the InstallShield installation wizard screens for Windows. You can override some of these text strings. For example, in the Select Installation Type wizard, you can change the text that appears next to the words Typical, Compact, and Custom to provide your own definitions for these three types of installations. When you save a BladePack project, BladePack saves any new string definitions in the appropriate string files.

To ensure that customers can install DataBlade modules and other Informix products using common instructions, the product you distribute must conform to the Informix DataBlade module installation standard. BladePack creates an interactive installation that ensures a consistent user interface.

To install a product from diskettes on a Windows platform, the installer executes the Setup.exe program on the first diskette. To create diskettes, copy the contents of the disk1 ... diskn directories to formatted 1.4 MB diskettes.

To create all other types of media, use the cdrom directory in the build area.

To distribute multiple products with their own installations on a CD-ROM or tape, rename the cdrom directory to the name of the DataBlade module before you copy the directory and its contents to the media or into the archive file.

For example, to install the Circle DataBlade module from CD-ROM, the installer mounts the CD-ROM, changes to the circle subdirectory, and executes Setup.

Important: Put the Setup.exe program in a short path. If the combined length of the path and filename of any file is longer than 255 characters, the program will not execute. This is due to a Windows limitation.