The following topics cover concepts and procedures for customizing Zen installations on Windows systems. Customizing the installation allows you to bundle all or part of a Zen product with your application.

This topic covers the technology and customization settings used for Zen product installations. On Windows systems, Zen installation uses Microsoft Installer (MSI). The PTKSetup.ini file contains default settings that you can change for custom installations.

For most installation scenarios, the installer executable file should be used for installations. The installer is an InstallShield package that performs a variety of checks before installation. It also detects whether you have 32- or 64-bit Windows, launches the appropriate installation, and automatically provides all 32- and 64-bit client components appropriate to your system.

The following table describes Zen installers on Windows operating systems.

PTKSetup.ini contains all settings needed for a typical installation. This file is used by every Zen product. On the installation media, it is located in the same folder as the .msi file that uses it.

PTKSetup.ini is divided into two parts:

Each setting has a current value that is the default for a typical installation. Comments in the file explain the settings and give all accepted values.

The following table lists settings in the PTKSetup.ini Properties section. The settings are grouped into categories. The value for each setting is contained in a key.

The Registry Migration section of the PTKSetup.ini file can be used when upgrading from PSQL v9 or earlier. The settings in this section enable migration of selected registry values from the earlier to the later version.

All of the configuration settings are explained in detail in Advanced Operations Guide.

The Registry Migration section lists each setting for the previous Zen version first, followed by an equal (=) sign. The setting for Zen is listed to the right of the equal sign.

The format used for registry migration settings is <Setting for Prior Version>=<Setting for New Version>.

Comment out any settings that should not be migrated during installation from any version of Zen before v10. If the key to be migrated already exists, the earlier registry setting replaces it.

To view your current settings, use the bcfg utility described in Advanced Operations Guide. This utility allows you to capture your current configuration settings in a report that may be useful for considering needed changes.

After installing Zen, you can use the configuration functions available in the Distributed Tuning Interface (DTI) to configure and tune your database engines. The functions available in DTI allow you to perform a variety of tasks to check current settings and make changes to them programmatically.

For information on using the DTI functions to configure a database engine after installation, see the list of configuration function groups described in Distributed Tuning Interface Guide.

The Zen DTO object is a COM Interface to perform Zen configuration functions similar to the DTI interface.

In an enterprise environment where reimaging or some other technique may be the preferred method for workstation recovery, and System Restore is never used, the additional time and disk space required to create restore points may be recovered and performance improved by disabling System Restore for installer activity. To disable System Restore, see the Microsoft help system for detailed information.

This setting affects only installer-initiated restore activity and is available in Group Policy to aid its deployment to workstations.

You can change what is installed for Zen by using one of the following methods:

Once you have modified PTKSetup.ini by uncommenting any properties and setting them to new values, you can simply run the installer from the command line to use those properties in the .ini file.

The available PTKSetup.ini properties are covered in PTKSetup.ini Settings.

Before PSQL v11, you could specify a Zen authorization key as an attribute in the PTKSetup.ini file. The same key could be used for multiple installations. Since PSQL v11, each installation requires a unique key. You can still specify a key in PTKSetup.ini, but it must be unique to the machine where the installation runs.

Various means are used for distribution of keys, such as a key printed on the product packaging or included inside the box or in email to the end user. Whatever method you use to distribute keys, one way to ensure uniqueness of the key in PTKSetup.ini is for your application installation to prompt the end user for the key. Your application installation could then write that key to a local copy of PTKSetup.ini and continue with the installation process that uses PTKSetup.ini. The Zen installation process will automatically authorize a valid key if one is specified in PTKSetup.ini. Note that part of key validity is that it must be unique for the machine on which the installation is being performed.

The MSI Public Property PVSW_CFG_FILE can be set to use an alternate configuration file by passing a fully qualified file path name on the command line when you run the installer executable. The property and its value are passed to the underlying msiexec Windows process.

Before passing the property, determine whether its value contains spaces. If not, your command should resemble the following:

Install_<product>.exe /v"PVSW_CFG_FILE=c:\temp\ConfigFile.ini"

If the property value contains spaces, you must enclose it in double quotation marks preceded by a backslash (\"), as in this example:

Install_<product>.exe /v"PVSW_CFG_FILE=\"c:\temp\My Folder\ConfigFile.ini\""

Combinations of the examples above can be used to pass multiple property settings:

Install_<product>.exe /v"PROPERTY1=0 PROPERTY2=\"c:\My Path\File.txt\""

See also Prerequisites for Installing a Zen MSI.

The Zen installation includes cabinet (CAB) files that can be removed from your installation package to decrease the overall size of the installation package and avoid using unnecessary files. Removing these files automatically removes the corresponding feature from the list of available features in the graphical user interface during a custom installation.

This section covers the following topics:

CAB files are located in the same directory as the MSI. CAB files beginning with an underscore (_) are required for that installation type.

The core set of CAB files does not change. However, Zen updates contain additional CAB files from the original set released for the major version of the product to cover newly added components or features. Be sure and obtain the latest files for the installation type and optional features you need.

CAB files that are required are designated by a name that begins with an underscore. The following table lists the cabinet files required for each installation package type.

In addition to the files listed under Required CAB Files, your custom installation must have the following items in a folder called Data, located in the same folder where the installer executable runs:

The following table lists optional features by the installation package type that applies them. If you want to install them, you must leave them in their location under the Data folder described in the previous topic. For more information on these features, see Zen Optional Features in Getting Started with Zen.

Certain optional features require that other components accompany them in order to function. The following table lists the optional features that require other components.

The following provides an example of customizing your installation using CAB files. This example installs the Workgroup engine with documentation as the only optional feature.

This example is for a system running on a Windows operating system.

The files listed in these two steps are the only CAB files that you need in order to install the Workgroup Engine and documentation. All other CAB files may be removed from the installation package. All non-CAB files described under Required Files Other than CAB must also remain in the installation package.

To embed Zen in your application, we recommend using Windows Installer. Originally called the Microsoft Installer, its acronym is MSI and its file extension is .msi.

This section covers the following topics:

Zen MSI installation requires the following:

In addition to the syntax and options displayed by running msiexec /? at a command prompt, MSI technology is fully documented by Microsoft on its website.

The following table lists Zen products and their MSI files.

The Microsoft transform (MST) provides a method of customizing your embedded installation. An .mst file is a set of changes to use during installation. Using a transform file to customize your installation allows for flexibility in selecting features and simplifies product updates.

To generate a MSI transform, you must work with the installer database that stores application information needed during installation. You can use several tools to generate a transform file, including InstallShield, Microsoft Orca, or the MSI utilities in the Windows Platform SDK.

A common use case for a transform file is to embed a Zen installation without creating shortcuts in the Start menu or on the Desktop. The following steps provide an example of this customization.

Here is an example installation based on these steps:

msiexec.exe /i {path}\ActianZenv14<product-type><platform>.msi /qn REBOOT=ReallySuppress /l*v "%temp%\Zen_<version>_Install.log" TRANSFORMS=MyTransform.mst PSQL_PREREQS_INSTALLED=Y

You can combine MSI options and parameters and PTKSetup.ini file settings in a Zen installation. To do this, be sure to disable the property in the .ini file by commenting it out. Then, run the installation from the command line using the options you disabled in the file.

The following examples combine methods used in the previous examples.

Use the MSI file only if the MSI prerequisites are met. See Prerequisites for Installing a Zen MSI.

The MSI Public Property PVSW_CFG_FILE can be set to use an alternate configuration file by passing a fully qualified file path name on the command line.

Before passing the property, determine whether its value contains spaces. If not, your command should resemble the following:

msiexec.exe /i "{path}\MSIPackage.msi" PSQL_PREREQS_INSTALLED=Y PVSW_CFG_FILE=c:\temp\ConfigFile.ini

If the property value contains spaces, you must enclose it in double quotation marks as in this example:

msiexec.exe /i "{path}\MSIPackage.msi" PSQL_PREREQS_INSTALLED=Y PVSW_CFG_FILE="c:\My Folder\ConfigFile.ini"

A silent installation runs without interaction from a user and by displaying little to no user interface during installer execution. It can be accomplished in two ways:

Because silent installations cannot launch other installations automatically, you may need to execute other installations to make sure that the product is completely up to date. See Special Considerations for Silent (or Basic UI) Installation.

The following is an example of installing Zen Client silently with a log file in the user's temp folder:

Install_Zen_Client.exe /s /v"/qn /l*v \"%temp%\Zen_<version>_SilentInstall.log\""

The next example creates a log file in the user’s temp folder and sets license key and service installation options:

Install_Zen_Workgroup_Engine.exe /s /v"/qn REBOOT=ReallySuppress PVSW_PSQL_LICENSE_KEY={key_value} PVSW_RUN_WGE_AS_SVC=Y TRANSFORMS=MyTransform.mst /l*v \"%temp%\Zen_<version>_Install.log\""

The embedding of an .msi file for one product in the installation of another product is often done by silent installation. The following example creates a log file in the user’s temp folder and specifies the license key and service installation options. See also Prerequisites for Installing a Zen MSI.

msiexec.exe /i {path}\ActianZenv14WGE32_x86.msi /qn REBOOT=ReallySuppress PVSW_PSQL_LICENSE_KEY={key_value} PSQL_PREREQS_INSTALLED=Y PVSW_RUN_WGE_AS_SVC=N TRANSFORMS=MyTransform.mst /l*v "%temp%\Zen_v14_Install.log"

This example uses a Microsoft transform file (.mst) to customize the installation. For more information, see Customizing Zen Embedding with a Microsoft Transform.

If you want to script a silent installation of Zen, you cannot use the installer executables listed under Customized Installation Overview because they do not remain running for the duration of the installation. Instead, use one of the two following options. Both examples are for Zen Enterprise Server and both use Microsoft PowerShell, which we recommend over Windows batch scripts to better handle scripting complexity.

Product updates for Zen are compressed, self-extracting .zip archives. Files in these archives are used to update, or patch, an existing Zen installation.

This section covers the following topics:

When you run the .exe file for a product update, it asks you to choose a location for the extracted update files (default is %temp% folder) and whether to launch the update executable (default is yes).

When one of the update executables is launched, it verifies the bitness of the installed Zen and launches the appropriate Microsoft patch package (.msp).

Update_Zen_Client.exe /s /v"/qn /l*v \"%temp%\Zen_Client_silent_update.log\""

On Windows systems, in most cases a Zen product update can be “rolled back” by uninstalling it. This removal restores Zen binaries to their versions before the product update. See the note in this section about unremovable patches.

To remove a product update for Zen from the command line, you need the following:

Either of the following commands can remove a product update:

Windows does not list Zen updates under Programs and Features to ensure that you are prompted to elevate to Administrator when uninstalling or modifying the Zen installation.

Two types of installations cannot launch other installations automatically:

In both these cases, unlike an installation executed from the installer executable UI, the installation does not ensure that all needed patches are applied. When you install silently or in Basic UI mode, you may need to apply these patches independently to make sure the product is complete.

The next two topics give examples of such independent updates:

An upgrade moves the product version from a previous release to the current release, such as 11.31 to 12.00. You may need to apply a patch before you upgrade the release. Patches are provided as .msp files. See the release notes for the current release, which lists any required patches. Be sure to install these first before upgrading.

For example, an optional patch is available for upgrading from a major release to a service pack. Install this patch if you want to keep personalized settings applied in the original release. The patch may be available only from the Actian website, so you must download the .msp file to apply it.

Use the following command to silently install the optional patch:

Product_type_platform.msp /qn /l*v "%temp%\product_beforeupdate.log"

where:

Product is the product, and type and platform are the product type and the platform on which the product runs. For example, ActianZenv14Patch_EnterpriseServer32_x86.msp is for the v14 Enterprise Server on a 32-bit platform.

The current release may require a patch after the silent installation. If a patch is required, you can find its .msp file in the installation media in the ~\Redist\Data folder.

Install any .msp file in that folder to complete installation of the current release. For example, the following command silently installs a patch for the Zen v14 Enterprise Server on a 64-bit platform:

path_to_installation_media\Redist\Data\ActianZenv14Patch_EnterpriseServer64_x64.msp /qn /l*v "%temp%\Zenv14_InstalledPatch.log"