Call-out Installations

Using a call-out installation allows you to encapsulate a complete installation of Pervasive PSQL in your product installation, without having to significantly modify your installation code. Using this type of installation, all you need to do is execute a command in your installation to invoke the Pervasive PSQL installation. This type of installation also offers the ability to customize the components that are installed, and run the installation silently.

A call-out installation is easy to use and works from a variety of installation tools. Using this method, you include the Pervasive PSQL. installation programs that you want to install on your distribution media and call the setup.exe program from your application's installation program.

Check If Product Already Installed

The Pervasive PSQL installation detects if Pervasive PSQL is already installed on the target machine. If so, the installed version is archived. If you choose, you can verify the installed version of Pervasive PSQL before you run a call-out installation. This is not required, but could save time during your installation if a call-out command is not required.

First, check if the following registry key(s) exists.

HKEY_LOCAL_MACHINE\SOFTWARE\Pervasive 
Software\product\InstallInfo 

Where product is one of the following

:

If a particular key does not exist, then that Pervasive PSQL product is not installed.

If the key(s) exists, you may further refine your check by determining the following values under InstallInfo:

---

Note
For NetWare installs, check the same values from the file bti.cfg. Use INI file routines to read the sections and keys in bti.cfg.

---

Available Call-out Installations

There are several different install options you can call from your own installation program.

The call-out installations are the same as the ones shipped with the product. Therefore, they are not included in the Toolkit package. Use the installation programs included on your CD or download them from the Pervasive Web site.

---

Note
There are no DOS client file installation programs. Instead, follow the instructions for installing a DOS client in Getting Started With Pervasive PSQL (Server edition). As discussed in that manual, the DOS client files should be manually copied to the DOS client.

---

Running a Call-out Installation

To prepare your product installation to call the Pervasive PSQL installation, create a directory on your CD image. You may name the directory whatever you choose. The example code below uses the directory name psql. Copy the contents of the appropriate Pervasive install program directory (see Table 1-1) to the directory on your CD image.

By default, the Pervasive installations present the user with dialogs to ask for installation options. If you want to provide an installation where you alone define the user interface, the Pervasive installations can be called out with parameters to cause it to perform its installation functions with no user input. In effect, this hides the installation of Pervasive PSQL components under your own install. This form of installation is known as a silent install.

The command to call-out silently to a Pervasive PSQL installation located in a "psql" subdirectory is:

psql\setup.exe /S /v" /l*v "c:\install.log" /qn 
 


 Note


Installation failures encountered during a silent install are written to the install.log file. No failure messages are displayed to the user. The log file is located in the location you specified in the call-out command. In the preceding example, this location is the root of drive C. 

A silent install of the Workgroup Engine fails if the Workgroup Engine is running. Ensure that you stop the Workgroup Engine before attempting to install it. You do this by changing a key value in the "modules" section in ptksetup.ini.

In the INI file, change
[modules]
w3dbsmgr.exe=2
to
[modules]
w3dbsmgr.exe=1

A "1" instructs the process detection component of installation to continue checking processes and then shut down the module. A "2" stops the installation process if the module is running (for example, if w3dbsmgr.exe is running). By default, w3dbsmgr.exe is set to "2."

Customizing a Call-out Installation

To change the default behavior of a call-out installation, the Installation Toolkit provides the ptksetup.ini configuration file. This file is located in the same directory as the other installation files, including setup.exe. It is in the form of a Windows initialization file. It contains settings that can be modified with a text editor. You can modify these settings to specify that certain actions are or are not performed when the installation program is executed.

For more detailed information on the ptksetup.ini file, please see Performing Simple Installation Customizations .

The ptksetup.ini file provides a variety of other settings for customization including:

For a list of ptksetup.ini settings and valid values please see Performing Simple Installation Customizations .

Call-out to Pervasive System Analyzer

The Pervasive System Analyzer (PSA) contains its own installation program. By default, the Pervasive PSQL engine installation automatically issues a call-out command to install PSA based on a setting in ptksetup.ini.

You may customize the PSA install in a similar manner to the Pervasive PSQL install. Refer to the PSA section in ptksetup.ini for the INI keys that apply to PSA.

The command to call-out to a PSA installation located in a "psa" subdirectory is:

psa\setup.exe 

The command to call-out to a PSA installation and have it run silently is:

psa\setup.exe -s 

The command to call out to a PSA installation with an alternate ptksetup.ini file is:

psa\setup.exe -i"c:\temp" -s 

Redirecting PSA Transactional Tests

By default, the PSA transactional tests are directed to the machine where you installed the Server or Workgroup engine or client components. You may redirect the transactional tests to a different machine if you choose.

Create a script that sets the values for SourceDir or TargetDir in ptksetup.ini. You must set these values after the Pervasive PSQL installation has finished writing to ptksetup.ini. Note that the Pervasive PSQL installation writes these values to ptksetup.ini. If you set the values before the Pervasive PSQL installation finishes, they will be overwritten.

Suppose you are installing the Server engine or Workgroup engine on drive C:, but you want to direct the transactional tests to X:\MyDatabase\PVSW\Samples. Set TargetDir to X:\MyDatabase\PVSW. The Pervasive PSQL installation automatically adds "\Samples" to TargetDir. If you add "\Samples" to the INI setting, the installation program tries to run the transactional tests on X:\MyDatabase\PVSW\Samples\Samples and an error occurs.

Similarly, suppose you are installing the client components to drive C: and you want to invoke the transactional test to X:\MyDatabase\PVSW\Samples. Set SourceDir to X:\MyDatabase\PVSW. As with the engine example, do not specify "\Samples." The installation automatically adds "\Samples" to the INI listing for SourceDir.

Requirements for Rebooting

In some cases, installing Pervasive PSQL v9 Service Pack 2 may require a system reboot after setup.exe updates system components, but before any Pervasive PSQL components are installed. This reboot must occur at this time because some of the Pervasive PSQL utilities and engine components require recent system components to be loaded before the Pervasive PSQL files can self-register.

All Windows Platforms

Pervasive PSQL requires the following system files and minimum version numbers to be installed on the computer before the Pervasive PSQL install can continue (these all reside in the Windows system folder):

---

Note
Update the system files before issuing a call-out command to the Pervasive PSQL installation. Otherwise, if the system files require updating, the Pervasive PSQL installation will cause a reboot. This could leave your installation unfinished.

---

Windows 98 and DCOM

Pervasive PSQL requires DCOM to exist on the target installation computer. If the above registry key does not exist, then the install cannot continue, but a system reboot is not triggered. This situation occurs because Microsoft does not allow redistribution of the DCOM updater for Windows 98.

---

Note
Commonly, a Windows 98 system will have some version of DCOM installed.

---

Registry RunOnce Key

The Pervasive PSQL installation places a value under the registry RunOnce key when a pre-installation reboot is triggered:

This value allows the Pervasive PSQL install to continue automatically after the reboot. Note that this could prevent your installation from continuing. For this reason, you should update the system files before issuing a call-out command to the Pervasive PSQL installation.

Otherwise, your installation will not get a chance to write to the RunOnce key because the Pervasive PSQL installation has already written to it and caused a reboot.