Call-out Installations

Using a call-out installation allows you to encapsulate a complete installation of Pervasive.SQL 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.SQL 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.SQL. 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.SQL installation detects if Pervasive.SQL 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.SQL 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.SQL 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 website.

---

Note
There are no DOS client file installation programs. Instead, follow the instructions for installing a DOS client in Getting Started with Pervasive.SQL (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.SQL 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.SQL components under your own install. This form of installation is known as a silent install.

The command to call-out silently to a Pervasive.SQL 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.SQL 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.SQL 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.SQL installation has finished writing to ptksetup.ini. Note that the Pervasive.SQL installation writes these values to ptksetup.ini. If you set the values before the Pervasive.SQL 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.SQL 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.SQL 9 may require a system reboot after setup.exe updates system components, but before any Pervasive.SQL components are installed. This reboot must occur at this time because some of the Pervasive.SQL utilities and engine components require recent system components to be loaded before the Pervasive.SQL files can self-register.

All Windows Platforms

Pervasive.SQL requires the following system files and minimum version numbers to be installed on the computer before the Pervasive.SQL 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.SQL installation. Otherwise, if the system files require updating, the Pervasive.SQL installation will cause a reboot. This could leave your installation unfinished.

---

Windows 98 and DCOM

Pervasive.SQL 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.SQL installation places a value under the registry RunOnce key when a pre-installation reboot is triggered:

This value allows the Pervasive.SQL 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.SQL installation.

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