Transcript
Pervasive.SQL V8
Installation Toolkit Handbook How to Integrate Pervasive Program Installations into Your Own
Pervasive Software Inc. 12365 Riata Trace Parkway Building B Austin, TX 78727 USA
Telephone: 512 231 6000 or 800 287 4383 Fax: 512 231 6010 Email:
[email protected] Web: http://www.pervasive.com
disclaimer
PERVASIVE SOFTWARE INC. LICENSES THE SOFTWARE AND DOCUMENTATION PRODUCT TO YOU OR YOUR COMPANY SOLELY ON AN “AS IS” BASIS AND SOLELY IN ACCORDANCE WITH THE TERMS AND CONDITIONS OF THE ACCOMPANYING LICENSE AGREEMENT. PERVASIVE SOFTWARE INC. MAKES NO OTHER WARRANTIES WHATSOEVER, EITHER EXPRESS OR IMPLIED, REGARDING THE SOFTWARE OR THE CONTENT OF THE DOCUMENTATION; PERVASIVE SOFTWARE INC. HEREBY EXPRESSLY STATES AND YOU OR YOUR COMPANY ACKNOWLEDGES THAT PERVASIVE SOFTWARE INC. DOES NOT MAKE ANY WARRANTIES, INCLUDING, FOR EXAMPLE, WITH RESPECT TO MERCHANTABILITY, TITLE, OR FITNESS FOR ANY PARTICULAR PURPOSE OR ARISING FROM COURSE OF DEALING OR USAGE OF TRADE, AMONG OTHERS.
trademarks
Btrieve, Client/Server in a Box, Pervasive, Pervasive Software, and the Pervasive Software logo are registered trademarks of Pervasive Software Inc. Built on Pervasive Software, DataExchange, MicroKernel Database Engine, MicroKernel Database Architecture, Pervasive.SQL, Solution Network, Ultralight, and ZDBA are trademarks of Pervasive Software Inc. Microsoft, MS-DOS, Windows, Windows 95, Windows 98, Windows NT, Windows Millennium, Windows 2000, Windows XP, Win32, Win32s, and Visual Basic are registered trademarks of Microsoft Corporation. NetWare and Novell are registered trademarks of Novell, Inc. NetWare Loadable Module, NLM, Novell DOS, Transaction Tracking System, and TTS are trademarks of Novell, Inc. All other company and product names are the trademarks or registered trademarks of their respective companies. Copyright 2003 Pervasive Software Inc. All rights reserved. Reproduction, photocopying, or transmittal of this publication, or portions of this publication, is prohibited without the express prior written consent of the publisher. This product includes software developed by Powerdog Industries. Copyright 1994 Powerdog Industries. All rights reserved. This product includes software developed by KeyWorks Software. Copyright 2002 KeyWorks Software. All rights reserved. This product includes software developed by DUNDAS SOFTWARE. Copyright 1997-2000 DUNDAS SOFTWARE LTD., all rights reserved. This product includes software developed by the Apache Software Foundation (http://www.apache.org/). The ODBC Driver Manager for NetWare (ODBC.NLM) included in this product is based on the GNU iODBC software Copyright 1995 by Ke Jin
and was modified by Simba Technologies Inc. in June 1999. This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. A copy of the GNU Lesser General Public License is included in your installation of Pervasive.SQL at \program files\common files\Pervasive Software Shared\doc\lesser.htm. If you cannot find this license, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 021111307 USA. You may contact Pervasive Software Inc. using the contact information on the back cover of this manual.
Installation Toolkit Handbook February 2003 100-004145-001
Contents About This Manual . . . . . . . . . . . . . . . . . . . . . . . . . . .
vii
Who Should Read This Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Manual Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1
What’s New in the Installation Toolkit. . . . . . . . . . . . . . . . .
viii ix x
1-1
An Overview of New Features in the Pervasive.SQL Installation Toolkit Licensing. . . . . . . . . . . . . . . . . . . . . . . . . . . Example InstallShield Project for Workgroup Engine . . PSA Installation . . . . . . . . . . . . . . . . . . . . . . . Environment Variables Required To Build Your Media . Uninstall Functionality . . . . . . . . . . . . . . . . . . . Easy Updates . . . . . . . . . . . . . . . . . . . . . . . .
2
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
Embedding Pervasive.SQL in Your Product Installation . . . . . .
1-2 1-3 1-4 1-5 1-6 1-7
2-1
How to Customize and Embed the Pervasive Installation Programs Pre-Installation Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Path Length . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Installing the Pervasive Installation Toolkit. . . . . . . . . . . . . . . . . . . . . Working with Pervasive.SQL Smart Components . . . . . . . . . . . . . . . . . Example Installation Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configure InstallShield for Update Directory . . . . . . . . . . . . . . . . Configure InstallShield for PSA Directory . . . . . . . . . . . . . . . . . . Suppress Registration Form . . . . . . . . . . . . . . . . . . . . . . . . . . Suppress Execution of PSA . . . . . . . . . . . . . . . . . . . . . . . . . . Call-out Installations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Check If Product Already Installed . . . . . . . . . . . . . . . . . . . . . . Available Call-out Installations . . . . . . . . . . . . . . . . . . . . . . . . Running a Call-out Installation . . . . . . . . . . . . . . . . . . . . . . . . Customizing a Call-out Installation . . . . . . . . . . . . . . . . . . . . . Call-out to Pervasive System Analyzer . . . . . . . . . . . . . . . . . . . . Requirements for Rebooting . . . . . . . . . . . . . . . . . . . . . . . . . Using the Pervasive Installation Toolkit API . . . . . . . . . . . . . . . . . . . . Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . Applying a License Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . Merging the Pervasive.SQL Installation Toolkit with an Existing Project . Calling the Pervasive.SQL Install API . . . . . . . . . . . . . . . . . . . . Creating a Database After Installation . . . . . . . . . . . . . . . . . . . . Running PSA During Setup . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . .
2-2 2-3 2-4 2-6 2-7 2-7 2-8 2-8 2-8 2-10 2-10 2-11 2-12 2-13 2-14 2-16 2-20 2-20 2-21 2-22 2-23 2-31 2-32
iii
Contents
Function Reference . . . . . . . . . . . . . . . . Easy Updates . . . . . . . . . . . . . . . . . . . . How Easy Updates Works . . . . . . . . . How to Use Easy Updates . . . . . . . . . Uninstalling the Pervasive.SQL Products . . . . Ptksetup.ini File . . . . . . . . . . . . . . . Sections . . . . . . . . . . . . . . . . . . . Keys. . . . . . . . . . . . . . . . . . . . . . Manual File Installations . . . . . . . . . . . . . Performing Simple Installation Customizations. Pkg Layout . . . . . . . . . . . . . . . . . . . . . Frequently Asked Questions. . . . . . . . . . . .
iv
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
2-33 2-69 2-69 2-70 2-73 2-73 2-73 2-80 2-88 2-90 2-91 2-92
Figures
Figures 2-1
Merge Utility User Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-22
v
Tables 2-1 2-2 2-3 2-4 2-5 2-6 2-7 2-8 2-9 2-10 2-11 2-12 2-13
vi
Call-Out Installations . . . . . . . . . . . . . . . . . . . . . . . . Required System Components . . . . . . . . . . . . . . . . . . . Affect of Using Suppress Reboot Parameter . . . . . . . . . . . Environment Variables Required Merged InstallShield Project . UPD Subfolders Recognized by the Installation Program . . . . Path Expansion Values . . . . . . . . . . . . . . . . . . . . . . . Keys Used To Test Whether Operations Should be Performed . Additional Keys Supported in Ptksetup.ini . . . . . . . . . . . . DOS Batch File Examples. . . . . . . . . . . . . . . . . . . . . . Registry examples . . . . . . . . . . . . . . . . . . . . . . . . . . Windows NT/2000 Installation Locations. . . . . . . . . . . . . Windows 9x/ME/XP Installation Locations. . . . . . . . . . . . NetWare Installation Locations . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . . .
. 2-11 . 2-16 . 2-17 . 2-21 . 2-70 . 2-81 . 2-83 . 2-84 . 2-88 . 2-89 . 2-94 . 2-95 . 2-95
About This Manual This manual contains information for developers about how to integrate a Pervasive product installation with another application installation. Pervasive Software would appreciate your comments and suggestions about this manual. As a user of our documentation, you are in a unique position to provide ideas that can have a direct impact on future releases of this and other manuals.If you have comments or suggestions for the product documentation, post your request at http://www.pervasive.com/devtalk.
vii
About This Manual
Who Should Read This Manual This manual provides information for developers who are using Pervasive.SQL V8 to develop applications for the NetWare or Windows 32-bit operating environments.
viii
Manual Organization
Manual Organization The following list briefly describes each chapter in the manual:
Chapter 1—“What’s New in the Installation Toolkit” This chapter provides an overview of the changes in this release of the Installation Toolkit.
Chapter 2—“Embedding Pervasive.SQL in Your Product Installation” This chapter includes conceptual and procedural information about how to use the Pervasive.SQL Installation Toolkit so you can bundle all or part of a Pervasive install with your application’s installation procedure.
This manual also includes an index.
ix
About This Manual
Conventions Unless otherwise noted, command syntax, code, and code examples use the following conventions:
x
Case
Commands and reserved words typically appear in uppercase letters. Unless the manual states otherwise, you can enter these items using uppercase, lowercase, or both. For example, you can type MYPROG, myprog, or MYprog.
[ ]
Square brackets enclose optional information, as in [log_name]. If information is not enclosed in square brackets, it is required.
|
A vertical bar indicates a choice of information to enter, as in [file name | @file name].
< >
Angle brackets enclose multiple choices for a required item, as in /D=<5|6|7>.
variable
Words appearing in italics are variables that you must replace with appropriate values, as in file name.
...
An ellipsis following information indicates you can repeat the information more than one time, as in [parameter...].
::=
The symbol ::= means one item is defined in terms of another. For example, a::=b means the item a is defined in terms of b.
chapter
What’s New in the Installation Toolkit
1
An Overview of New Features in the Pervasive.SQL Installation Toolkit
The chapter summarizes features and differences in behavior between the Installation Toolkit for Pervasive.SQL V8 and the previous release. The following features or differences are new:
“Licensing” on page 1-2 “Example InstallShield Project for Workgroup Engine” on page 1-3 “PSA Installation” on page 1-4 “Environment Variables Required To Build Your Media” on page 1-5 “Uninstall Functionality” on page 1-6 “Easy Updates” on page 1-7
1-1
What’s New in the Installation Toolkit
Licensing License keys are now human-readable text (a string of letters and numbers). Previous releases used a license key binary file provided on the CD or on a diskette. You may provide a license key during installation in one of two ways:
Specify the license key in ptksetup.ini (see the [License] section in the file) Display an input dialog on which the end-user enters a key. The dialog does not display if you specify a license key in ptksetup.ini and set HideLicenseInput in the INI file to “yes.”
By default, the Installation Toolkit example projects display an input dialog. If you create your install image using the ptkmerge utility, you must add your own input dialog to your InstallShield project. See “Applying a License Key” on page 2-21.
1-2
Example InstallShield Project for Workgroup Engine
Example InstallShield Project for Workgroup Engine The Installation Toolkit now includes an example InstallShield project for the Workgroup Engine. This example project is located under ptk\examples along with the examples for the Pervasive.SQL V8 Server engines and clients.
1-3
What’s New in the Installation Toolkit
PSA Installation The Pervasive System Analyzer (PSA) contains its own installation. See the following sections to determine how include or exclude PSA in an installation:
1-4
“Configure InstallShield for PSA Directory” on page 2-8 “Call-out to Pervasive System Analyzer” on page 2-14
Environment Variables Required To Build Your Media
Environment Variables Required To Build Your Media You must set up several environment variables before building your disk image media. A batch file is provided to help you. See “Environment Variables” on page 2-20.
1-5
What’s New in the Installation Toolkit
Uninstall Functionality In prior releases of the Installation Toolkit, Pervasive Software included the “C” source code for the uninstall DLL. With the current release, the “C” source code is not provided. The uninstall DLL now performs certain functionality using sections and keys in the ptksetup.ini file. Working with INI entries is easier than changing and compiling “C” source code. For a complete discussion of the uninstall functionality, see “Uninstalling the Pervasive.SQL Products” on page 2-73.
1-6
Easy Updates
Easy Updates The Pervasive.SQL installer can install additional Pervasive.SQL file updates, such as hot fixes, during the course of the installation. This feature is called “Easy Updates” because you can add files to the Pervasive.SQL installation program simply by dropping them into a specific directory location in the installation image. You do not need to change a single line of code in your installation program. This feature is very convenient because it allows your customer to install the main product as well as updates during a single installation procedure. There is no need for your customer to install additional updates separately. See “Easy Updates” on page 2-69 for a complete discussion.
1-7
What’s New in the Installation Toolkit
1-8
chapter
Embedding Pervasive.SQL in Your Product Installation
2
How to Customize and Embed the Pervasive Installation Programs
This chapter includes conceptual and procedural information about the Pervasive Installation Toolkit. The Toolkit enables you to bundle all or part of a Pervasive.SQL product with your application. This chapter contains the following sections:
“Pre-Installation Notes” on page 2-2 “Installing the Pervasive Installation Toolkit” on page 2-4 “Working with Pervasive.SQL Smart Components” on page 2-6 “Call-out Installations” on page 2-10 “Using the Pervasive Installation Toolkit API” on page 2-20 “Function Reference” on page 2-33 “Easy Updates” on page 2-69 “Uninstalling the Pervasive.SQL Products” on page 2-73 “Manual File Installations” on page 2-88 “Performing Simple Installation Customizations” on page 2-90 “Pkg Layout” on page 2-91 “Frequently Asked Questions” on page 2-92
2-1
Embedding Pervasive.SQL in Your Product Installation
Pre-Installation Notes The Toolkit is designed for use with InstallShield 5.5 that has service pack 3 installed. The Toolkit also provides methods for integrating with other installation tools. Installing software onto Windows machines has grown more complex. Configuration and registration of file components can be time-consuming and code-intensive. The Pervasive.SQL Installation Toolkit is designed to make the task of creating your application’s installation development faster and easier. The Toolkit allows you to seamlessly include Pervasive.SQL in your product’s installation without having to learn the individual configuration steps required for the software to function correctly. The Installation Toolkit is a set of InstallShield project files, code, examples and Pervasive.SQL components that you can redistribute. The Toolkit is designed to be used on the following platforms:
Windows NT, 2000, or XP
The installation programs that you create using the Installation Toolkit can be used to install your application and Pervasive.SQL on the following platforms:
Windows 98, ME, or XP Windows NT or 2000 NetWare 4.1x, 5.x, of 6.0
The Installation Toolkit provides three methods to integrate the installation with your application:
2-2
Call out to the existing Pervasive.SQL installation program. The installation can be run silently so that it only displays your GUI to the user. Install options can be controlled through the ptksetup.ini configuration file. This method also works with non-InstallShield projects. Integrate your new or existing application installation with the Pervasive.SQL Installation Toolkit by including Toolkit API calls in your installation scripts and importing InstallShield project elements from the Toolkit project. The supplied InstallShield project merge utility can automate most of the steps required.
Pre-Installation Notes
Manually install the desired Pervasive.SQL components to your customer’s system and perform the required configuration steps. This method also works with non-InstallShield projects.
This chapter will walk you through an example of each of the three integration methods. Note When integrating Pervasive.SQL V8 into your applications, make sure you also install the SQL Relational Database Engine. The SRDE is required if your end-users need to access databases through ODBC.
Path Length
Ensure that the full install path for the Pervasive.SQL database engine is no more than 42 characters. The full path includes the drive letter, colon, and back slash (for example, C:\). If the install path exceeds 42 characters, the DEMODATA sample database is not installed. This restriction on path length is required by Pervasive.SQL’s relational interface, the SQL Relational Database Engine (SRDE). With call-out installations, a warning displays if the path exceeds 42 characters. (See “Call-out Installations” on page 2-10.)
2-3
Embedding Pervasive.SQL in Your Product Installation
Installing the Pervasive Installation Toolkit The Pervasive Installation Toolkit comes on a single CD that contains all the projects, files and components needed to create embedded installations. To launch the installation program on your Windows machine: 1
Insert the Pervasive Installation Toolkit CD in the CD-ROM drive of your machine.
2
If the installation does not start automatically, click Start, select Run, and type drive:setup where drive is the drive letter of your CD-ROM device.
Assuming that you have elected to install all of the Toolkit and have selected the default options, the Installation Toolkit files reside in the following directory structure: C:\pvsw\ Ptk\
// Installation Toolkit projects, code and examples Ptkdoc\
// On-line Toolkit documentation
Examples\
// Example InstallShield projects that embed Pervasive.SQL V8 components Ntsrv\ Nwsrv\ W32clnt\ Wge
Install\
Complete set of Pervasive.SQL V8 installation programs. Nt\ Nw\ Psa\ Wge\
Manual\
2-4
// DOS batch file installation examples
Installing the Pervasive Installation Toolkit
Pkg\
// Directory structure of Pervasive.SQL V8 components used in install projects Psa\ Psql\ Ptk\
Psa\
// Pervasive System Analyzer InstallShield project component definitions\ file groups\ media\ registry entries\ script files\ setup files\ shell objects\ string tables\ text substitutions\
Psql\Pervasive.SQL\
// Full Pervasive.SQL InstallShield project
ptkenv.bat
// Batch file to set environment variables
ptkmerge.exe
//Utility to embed Pervasive.SQL into other projects
readme.txt
// Readme file for the Installation Toolkit
2-5
Embedding Pervasive.SQL in Your Product Installation
Working with Pervasive.SQL Smart Components Pervasive.SQL offers a component architecture called Smart Components which improves installation and run-time reliability and makes application troubleshooting easier. This design feature addresses component management issues and difficulty in identifying the components’ function, version, and patch level. Each “smart” component has a unique component name that contains the component’s function, version, and patch level. This feature ensures that updated components never overwrite previous versions. The Smart Component architecture also includes the following features:
Dynamic Binding. Pervasive.SQL does not load a fixed set of program files into memory. Dependent components are loaded only if another component specifically requires its functionality, version, and patch level. Incompatible components are never accidentally loaded, reducing or eliminating version-related failures. Error Code Clarification. Error codes from underlying layers are passed through to the message log, rather than hidden within an umbrella status code. Because the root causes of certain errors can be quickly determined, troubleshooting is easier. Pervasive.SQL Event Logging. All components report errors and messages to a central log, easing the burden of troubleshooting.
For more information on Smart Component architecture, refer to Advanced Operations Guide.
2-6
Example Installation Projects
Example Installation Projects The Installation Toolkit provides an example InstallShield project for the following:
Server Engine for Windows Server Engine for NetWare Workgroup Engine Pervasive.SQL clients
The example projects are provided solely as learning tools. They are not used by call-out installations, in merged projects, or for manual file installations. For all examples, you must configure InstallShield to include the update directory and Pervasive System Analyzer (PSA).
Configure InstallShield for Update Directory
The InstallShield examples are designed to copy files during installation from a directory named update, which is located at the root of your install image. The update directory contains two subdirectories, support and system. You must configure InstallShield to ensure that the update directory is created. Otherwise, errors result when you run the setup.exe file. To configure InstallShield to ensure Update directory is created 1
In the Components pane of InstallShield, open the properties for Ptk\System\Update. Set the properties for CD-ROM Folder to Update.
2
In the InstallShield Media Build Wizard, check the option Data as Files. This option ensures that the files in the update directory remain uncompressed. Refer to the InstallShield help for details. Note Errors result when you run setup.exe if you do not configure InstallShield to include the update directory. You will see errors similar to the following: Setup could not properly run HHUPD>EXE. The Pervasive.SQL online help files might not work properly.
2-7
Embedding Pervasive.SQL in Your Product Installation Unable to copy file c:\pvsw\ptk\examples\ntsrv\media\ntserver\disk images\disk1\update\system\win16\nwlocale.dll to c:\windows\system\nwlocale.dll Error number -1
Configure To include PSA with the examples, configure InstallShield to ensure InstallShield for that the psa directory is created. PSA Directory To configure InstallShield to ensure PSA directory is created
Suppress Registration Form
1
In the InstallShield Media Build Wizard, ensure that the option Data as Files is checked. This option ensures that the files remain uncompressed. Refer to the InstallShield help for details.
2
Click the Advanced button beside the option Data as Files.
3
In the tree, click on the folder PSAInstall.
4
Click OK.
A registration form displays at the end of the Pervasive.SQL installation. Use the following steps if you wish to suppress the display of the registration form. To suppress display of registration form 1
Open ptk.rul in InstallShield.
2
Locate the function PtkRunPSA.
3
Comment out the following line: WriteLine(nvShelcfg, "COMMANDLINE=\"" + WINDIR ^ "hh.exe " + szCommandLine2 + "\"");
Suppress Execution of PSA
The Pervasive System Analyzer runs at the end of the Pervasive.SQL installation. Use the following steps if you wish to suppress the execution of PSA. To suppress execution of PSA
2-8
1
Open setup.rul in InstallShield.
2
Locate the function CleanUpInstall.
3
Comment out the following lines:
Example Installation Projects PtkPutRegistry(PTK_REG_RUN_ONCE_KEY, PTK_SHEL_EXE, REGDB_STRING, "\"" + szPtkTempDir ^ PTK_SHEL_EXE + "\" " + "\"" + szPtkTempDir ^PTK_SHEL_CFG + "\"", -1); if ((!BATCH_INSTALL) &&( MODE != SILENTMODE))then SizeWindow ( BACKGROUND , 5 , 5 ); ChangeDirectory(szPtkTargetDir ^ PTK_DEST_BINDIR ); LaunchApp("\"" + szPtkTempDir ^ PTK_SHEL_EXE + "\"","\"" + szPtkTempDir ^ PTK_SHEL_CFG + "\""); endif;
2-9
Embedding Pervasive.SQL in Your Product Installation
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. If you do not wish to use the Installation Toolkit API, or if you are using an installation program other than InstallShield 5.5, then a call-out installation is the easiest method to use. The Toolkit includes copies of the complete installation programs for all Pervasive.SQL Server, Workgroup, and client products. The installation programs can be included on your distribution media and called 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: Pervasive.SQL V8
Pervasive.SQL 2000 and 2000i
Pervasive.SQL NT Server
Pervasive.SQL 2000 NT Server
Pervasive.SQL NetWare Server
Pervasive.SQL 2000 NetWare Server
Pervasive.SQL Workgroup
Pervasive.SQL 2000 Workstation
Pervasive.SQL Client
Pervasive.SQL 2000 Client
If a particular key does not exist, then that Pervasive.SQL product is not installed.
2-10
Call-out Installations
If the key(s) exists, you may further refine your check by determining the following values under InstallInfo: Key Value
Description
VersionLevel
The database engine version number of the installed product
PatchLevel
The Service Pack (SP) number of the installed product
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 Callout Installations
There are several different install options you can call from your own installation program. If you installed the Toolkit to the default location (C:\pvsw), and included the complete Toolkit suite, the programs can be found at the following locations: Table 2-1 Call-Out Installations Product
Location
Pervasive.SQL V8 Server for Windows NT or 2000
C:\pvsw\ptk\install\nt
Pervasive.SQL V8 Server for NetWare
C:\pvsw\ptk\install\nw
Pervasive.SQL V8 Workgroup
C:\pvsw\ptk\install\wge
Pervasive System Analyzer
C:\pvsw\ptk\install\psa
Pervasive.SQL V8 Client for Windows 9X/NT/ 2000/XP
C:\pvsw\ptk\install\nt\clients\win1
1 The NetWare server installation directory contains an identical Pervasive.SQL client installation program.
Note The DOS client files in c:\pvsw\ptk\install\nt\clients\dos do not include an installation program. Instead, these files should be manually copied to the DOS client.
2-11
Embedding Pervasive.SQL in Your Product Installation
Running a Call- To prepare your product installation to call the Pervasive.SQL out Installation 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 2-1) to the directory on your CD image. The command to call-out to a Pervasive.SQL installation located in a “psql” subdirectory is: psql\setup.exe -SMS
Note The -SMS options keep the setup.exe in memory until the installation is complete. This is useful because the setup.exe is simply an InstallShield loader application that terminates as soon as the installation is loaded. It is also possible to omit the -SMS options and wait for the _ISDEL module to terminate.
This command can be included in an installation batch file or as an InstallShield parameter to the DoInstall() function: DoInstall("psql\\setup.ins", "", WAIT);
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. 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 installation directory, which, by default, is PVSW. 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]
2-12
Call-out Installations
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.”
A silent install requires the “-s” command line option. The command to call-out to a Pervasive.SQL installation and have it run silently is: psql\setup.exe -s -SMS
The command to perform the same function from an InstallShield script is: DoInstall("psql\\setup.ins", "-s", "-SMS", WAIT);
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 numerous settings that can be modified programmatically or with a text editor. You can modify these settings to specify the components that do or do not get installed when the installation program is executed. For more detailed information on the ptksetup.ini file, please see “Performing Simple Installation Customizations” on page 2-90. A command line option is available to allow setup to use a ptksetup.ini file that is not located at the root of the CD. This can be used together with the -s option for silent installations. The
command to call out to a Pervasive.SQL installation with an alternate ptksetup.ini file is: psql\setup.exe -i"c:\temp" -SMS
The command to perform the same function from the InstallShield script is: DoInstall("psql\\setup.ins", "-i\"c:\\temp\"", WAIT);
2-13
Embedding Pervasive.SQL in Your Product Installation
Note The “-i” option must be placed before other options in the command line because of an InstallShield limitation.
Let’s assume that you are installing Pervasive.SQL and do not want the program icons that will be created to be located in a folder with the default name, “Pervasive.” Instead, you want to create a more generic folder name, “Data Engine.” The ptksetup.ini file contains a setting called “Folder” that allows this, located in the “Common” section. The entry to accomplish this is: [Common] Folder=Data Engine
The ptksetup.ini file provides a wide variety of other settings for customization including:
Installation location Engine start mode Included engine, client, utility and documentation components Icon creation for installed components Folder formatting (nested or non-nested folders) Installation validation
For an exhaustive list of ptksetup.ini settings and valid values please see “Performing Simple Installation Customizations” on page 2-90.
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. To include Pervasive System Analyzer (PSA), you must configure InstallShield to ensure that the psa directory is created. See “Configure InstallShield for PSA Directory” on page 2-8 for details. 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 -SMS
2-14
Call-out Installations
Note The -SMS options keep the setup.exe in memory until the installation is complete. This is useful because the setup.exe is simply an InstallShield loader application that terminates as soon as the installation is loaded. You may also omit the -SMS options and wait for the _ISDEL module to terminate.
This command can be included in an installation batch file or as an InstallShield parameter to the DoInstall() function: DoInstall("psa\\setup.ins", "", WAIT);
The command to call-out to a PSA installation and have it run silently is: psa\setup.exe -s -SMS
For example, the command to perform the same function from an InstallShield script is: DoInstall("psa\\setup.ins", "-s", WAIT);
The command to call out to a PSA installation with an alternate ptksetup.ini file is: psa\setup.exe -i"c:\temp" -s -SMS
The “-i” option must be placed before other options in the command line because of an InstallShield limitation. In an InstallShield script, the command to call out to a PSA installation with an alternate ptksetup.ini file is: DoInstall("psa\\setup.ins", szCommandLine, WAIT);
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, but before the function PtkRunPSA executes in Ptk.rul. 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.
2-15
Embedding Pervasive.SQL in Your Product Installation
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 V8 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): Table 2-2 Required System Components
2-16
File Name
Minimum Version Number
msvcrt.dll
6.0.8267.0
msvcp60.dll
6.0.8168.0
mfc42.dll
6.0.8665.0
comctl32.dll
5.80.2614.3600
Call-out Installations
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. Include the suppress reboot parameter, “-b,” in the call-out command.
Suppress Reboot Parameter You may use the “-b” parameter to suppress a reboot under certain conditions. The following table explains the affect of using the “-b” parameter. Table 2-3 Affect of Using Suppress Reboot Parameter Installation Condition
Affect of -b Parameter
Successful install, no reboot required
Control is returned to your installation.
System files require updating, reboot required
The reboot is not suppressed. The “-b” parameter is added to RunOnce registry key. The Pervasive.SQL installation continues after reboot, but control does not return to your installation.
Fatal error during installation, reboot required
A message about the fatal error is shown to the user and control returns to your installation.
Successful install but files were locked, reboot required
Control is returned to your installation. Actions that normally occur after a reboot, such as running PSA and displaying the registration page, do not occur.
The following examples show how to use the “-b” parameter in callout commands: psql\setup.exe -b -SMS DoInstall("psql\\setup.ini", "-b -SMS", WAIT); psql\setup.exe -i"c:\temp” -b -s -SMS DoInstall("psql\\setup.ini”, "-i\"c:\\temp\"", "-b -s SMS", WAIT);
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
2-17
Embedding Pervasive.SQL in Your Product Installation
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: HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\RunOnce -> x:\install\setup.exe -s
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. Custom PTKSETUP.INI File If you are using a custom ptksetup.ini file, you must modify the RunOnce registry value to enable the automatically loaded installation to use the custom ptksetup.ini file. The value is a regular string value and some minor string manipulation needs to be performed on it due to a limitation of InstallShield. You need to insert the -i parameter immediately after setup.exe in the command line. The original command might look like this: HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\RunOnce ->
x:\install\setup.exe -s
and you need to change it to look like this: HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\RunOnce ->
x:\install\setup.exe -i"c:\temp" -s
where c:\temp is the location of the customized ptksetup.ini file.
2-18
Call-out Installations
Installations Without Direct Dependencies on Pervasive.SQL In some cases, your product installation does not directly depend on the Pervasive.SQL installation. Instead of forcing a reboot in the beginning or middle of your product installation, you can do the following (this works seamlessly only for silent call-out commands): 1
Start your installation.
2
Call out to the Pervasive.SQL installation. The call-out command must include the “-b” parameter to suppress a reboot.
3
After the Pervasive.SQL installation process exits, continue your installation.
4
Initiate a reboot or tell your users to reboot at the end of your installation if: a. you cannot find the latest ptksetup.ini file in the Pervasive.SQL installation directory (this happens if a system reboot is required). b. you can find the latest ptksetup.ini file in the Pervasive.SQL installation directory, and the NeedReboot=Yes under the [Common] section. (This happens if the install succeeded but needs to update other locked files).
5
After the reboot (if a pre-installation reboot was required), the Pervasive.SQL installation completes.
6
The installation is now fully operational.
2-19
Embedding Pervasive.SQL in Your Product Installation
Using the Pervasive Installation Toolkit API The Pervasive.SQL Installation Toolkit is most useful when you use InstallShield 5.5 to install your own product. Since Pervasive uses InstallShield 5.5 for all of its Windows and NetWare installations, the code and configuration steps can easily be included in your installation. The Installation Toolkit includes a utility, ptkmerge, which modifies an existing InstallShield project that was created using the InstallShield project wizard. Ptkmerge automatically inserts Toolkit API calls, script files, file groups and file components used to install Pervasive.SQL products. Note This discussion of how to merge the Installation Toolkit with an InstallShield project assumes that your existing project was created with the InstallShield 5.5 project wizard. Ptkmerge merges the Pervasive System Analyzer, but you must configure InstallShield to ensure the PSA directory gets created when you create your media. See “Configure InstallShield for PSA Directory” on page 2-8.
Environment Variables
Before you create your install image with the merged InstallShield project, you must set several environment variables. You may set these environment variables manually at the operating system, or use the batch file ptkenv.bat. The batch file is located in the ptk directory and is created when you install the Installation Toolkit. The environment variables in ptkenv.bat are set based on the system on which you installed the Installation Toolkit. The batch file also starts InstallShield, ensuring that the environment variables are in effect.
2-20
Using the Pervasive Installation Toolkit API
The following table explains the environment variables that must be set. Table 2-4 Environment Variables Required Merged InstallShield Project Environment Variable
Description and Example Usage
CMBLDIR
Identifies the root directory used for the toolkit installation. For example, set CMBLDIR=”d:\PVSW\ptk”
PKGDIR
Identifies the top-level directory where the package files are located. All Toolkit installations use this directory structure to construct the InstallShield cabinet file from which files are installed to the user’s disk. For example, set PKGDIR=d:\pvsw\ptk\pkg See also “Pkg Layout” on page 2-91.
Applying a License Key
PSQLPKG
Identifies the location of the PSQL directory under the package directory. The location contains the package files used for Pervasive.SQL (in contrast, for example, to the package files used for PSA). For example, set PSQLPKG=%PKGDIR%\psql
MEDIA_LOCALE
Identifies the media type being built. The only valid settings are 0009-english for media in English and 0011-japanese for media in Japanese. For example, set MEDIA_LOCALE=0009-english
PSAINSTALLDIR
Identifies the directory that contains the installation files for the Pervasive System Analyzer (PSA). For example, d:\PVSW\ptk\install\psa
A license key is required to run the Pervasive.SQL database engine. The Installation Toolkit provides a temporary license key for the Server engine and Workgroup engine. This temporary license key is valid for one day and provides a user count of one. If you do not specify a license key in ptksetup.ini or through an input dialog, the one-day temporary license is installed. You may provide a license key during installation in one of two ways:
Specify the license key in ptksetup.ini (see the License section in the INI file) Display an input dialog on which the end-user enters a key. The dialog does not display if you specify a license key in ptksetup.ini and set HideLicenseInput key in the INI file to “yes.”
2-21
Embedding Pervasive.SQL in Your Product Installation
If you want to display an input dialog, you must add your own to the merged InstallShield project. The Merge utility does not create InstallShield dialogs. To apply a license key by using your own input dialog 1
Pass the license key string to the function PtkProcessLicense as the first parameter. For example, suppose you use the InstallShield dialog sdRegisterUserEx as the input dialog. You would pass the value for svSerial to PtkProcessLicense as the first parameter.
Merging the Pervasive.SQL Installation Toolkit with an Existing Project
Ptkmerge is a Win32 GUI utility that incorporates Pervasive.SQL Installation Toolkit components into an existing InstallShield project. You may run the utility in one of two ways (all examples assume the Toolkit resides in c:\pvsw\ptk\):
Click StartRun, type c:\pvsw\ptk\ptkmerge, then click OK. Double-click the Merge Utility icon in the Pervasive.SQL Installation Toolkit program folder.
Once the utility is executed the following dialog appears. Figure 2-1 Merge Utility User Interface
The ptkmerge utility fields and elements are:
2-22
Your installation project location – The directory in which your InstallShield project’s.ipr file is located. This is the InstallShield project into which Installation Toolkit components will be inserted.
Using the Pervasive Installation Toolkit API
Backup your install project before merging – If this option is checked, the ptkmerge utility will back up your InstallShield project files before inserting the Installation Toolkit components. Installation Toolkit project location – This is the directory in which the source Installation Toolkit InstallShield project file resides. This InstallShield project is the source of all Installation Toolkit components. Status bar – This progress bar provides feedback during the project merge. Merge button – Perform the project merge from the Toolkit installation project location to your installation project location. Exit button – Quit the utility.
The ptkmerge utility does not merge the Pervasive System Analyzer (PSA), which has its own installation. If you wish to include PSA, use a call-out to the PSA installation in your InstallShield project. See “Call-out to Pervasive System Analyzer” on page 2-14. Once the ptkmerge utility is finished, open up your installation in the InstallShield IDE and note the new features of the project. These should include:
File components under the “Ptk” parent component File groups beginning with the “PTK_” prefix Script files beginning with the “ptk” prefix The setup.rul file used by Pervasive.SQL is also copied to your project. It has been renamed psqlstp.rul and is included for your reference only (it will not be compiled into your script). Additional function calls and include statements in setup.rul
You should also have several files copied to your project’s “setup files” directory structure. At this point it would be a good idea to perform a script compilation and media build to ensure that everything builds normally.
Calling the Pervasive.SQL Install API
The ptkmerge utility placed several Installation Toolkit API calls into your original project’s setup.rul file. These are placed in each of the main function calls of the InstallShield wizard generated “program” section of the file. These included function calls use a naming scheme similar to that used by InstallShield to make them easily identifiable. They are:
2-23
Embedding Pervasive.SQL in Your Product Installation
PtkCheckRequirements() PtkUpdateSystem() PtkSetupInstall() PtkSetupScreen() PtkProcessBeforeDataMove() PtkMoveFileData() PtkProcessAfterDataMove() PtkSetupRegistry() PtkSetupFolders() PtkCompleteSetup() PtkCleanUpInstall()
Ptkmerge also included two #include statements so that your project’s main setup script would include the Pervasive.SQL Installation Toolkit code. Note When compiling with the Pervasive.SQL Installation Toolkit, you may get warning messages concerning string/array sizes exceeding the recommended limit or functions that are defined but never called. These are not errors and will not affect your installations. You can avoid these warnings by changing your InstallShield compile warning level to 1, though it is not recommended.
If your project does not show some or all of the function calls and include statements, there is a chance that your InstallShield project was not created with the InstallShield project wizard or has been substantially altered from its original wizard-generated form. The Installation Toolkit function calls and includes can be added manually but should be called in the order in which they appear above. In some cases, the placement of the Installation Toolkit calls within the InstallShield functions is important, and we’ll discuss each now.
2-24
Using the Pervasive Installation Toolkit API
Note The order of the function calls as they exist in setup.rul are not the same as the order in which they are called. For this discussion, we will introduce the Installation Toolkit API calls in the order in which they should be called.
Caution Do not remove the comment lines beginning with PSQL_BEGIN and PSQL_END. These lines mark the code added by the ptkmerge utility, so that it can identify such code. Removing these lines will cause problems for any future attempts to run the ptkmerge utility.
Placement of the Installation Toolkit calls This section describes the placement of the calls.
The first code portion that needs to be included in setup.rul is a #include for the Installation Toolkit include file. This statement should be inserted immediately after the Wizard-generated #include statements, such as the one to include sddialog.h, as shown below: #include "sddialog.h" // PSQL_BEGIN - Inserted by Pervasive.SQL Install Toolkit - DO NOT REMOVE THIS LINE #include "ptk.h" // PSQL_END - Inserted by Pervasive.SQL Install Toolkit - DO NOT REMOVE THIS LINE
PtkCheckRequirements() should be called within the InstallShield function CheckRequirements(). It requires no parameters and should be called at the beginning of the function: // PSQL_BEGIN - Inserted by Pervasive.SQL Install Toolkit - DO NOT REMOVE THIS LINE // perform the requirements check Toolkit operations nvResult = PtkCheckRequirements(); if (nvResult != PTK_SUCCESS) then return nvResult; endif;
2-25
Embedding Pervasive.SQL in Your Product Installation // PSQL_END - Inserted by Pervasive.SQL Install Toolkit - DO NOT REMOVE THIS LINE
PtkUpdateSystem() should be called within the InstallShield function CheckRequirements(). It requires no parameters and
should be called at the end of the function immediately before the end command. It is very important that bPtkSystemUpdateReboot is checked and, if TRUE, that a system reboot is performed before continuing the setup. Certain system files must be updated before setup can be run. For an example on how to automatically restart setup after a system reboot, please look at our solution in the psqlstp.rul file. // PSQL_BEGIN - Inserted by Pervasive.SQL Install Toolkit - DO NOT REMOVE THIS LINE // perform the system file update Toolkit operations nvResult = PtkUpdateSystem(); if (nvResult != PTK_SUCCESS) then return nvResult; endif; // if a reboot event was detected then reboot before continuing if (bPtkSystemUpdateReboot) then SdFinishReboot(@PTK_FINISH_MS_CORE_TITLE, @PTK_FINISH_MS_CORE_TEXT_REBOOT, SYS_BOOTMACHINE, "", 0 ); abort; endif; // PSQL_END - Inserted by Pervasive.SQL Install Toolkit - DO NOT REMOVE THIS LINE
PtkSetupInstall() should be called within the InstallShield function SetupInstall(). It requires no parameters and should
be called at the beginning of the function immediately after the begin command. This function may return an error. Setup should not be allowed to continue if this function returns an error: // PSQL_BEGIN - Inserted by Pervasive.SQL Install Toolkit - DO NOT REMOVE THIS LINE // perform the install setup Toolkit operations if (PtkSetupInstall() < 0) then return -1;
2-26
Using the Pervasive Installation Toolkit API endif; // PSQL_END - Inserted by Pervasive.SQL Install Toolkit - DO NOT REMOVE THIS LINE
PtkSetupScreen() should be called within the InstallShield function SetupScreen(). It requires no parameters and should
be called at the beginning of the function immediately after the begin command. This function may return an error. Setup should not be allowed to continue if this function returns an error: // PSQL_BEGIN - Inserted by Pervasive.SQL Install Toolkit - DO NOT REMOVE THIS LINE // perform the screen setup Toolkit operations if (PtkSetupScreen() < 0) then return -1; endif; // PSQL_END - Inserted by Pervasive.SQL Install Toolkit - DO NOT REMOVE THIS LINE
PtkProcessBeforeDataMove() should be called within the InstallShield function ProcessBeforeDataMove(). It should be called at the end of the function immediately before the end command: // PSQL_BEGIN - Inserted by Pervasive.SQL Install Toolkit - DO NOT REMOVE THIS LINE // perform the pre data move Toolkit operations if (PtkProcessBeforeDataMove(WINSYSDIR, "", svSetupType) < 0) then return -1; endif; // PSQL_END - Inserted by Pervasive.SQL Install Toolkit - DO NOT REMOVE THIS LINE PtkProcessBeforeDataMove() requires three parameters.
Ptkmerge writes out three values that are valid for most installations but you may have to modify some or all of them depending upon your installation requirements.
The first parameter is the location in which system components should be installed. For installations on Windows, this should always be the InstallShield variable WINSYSDIR. For NetWare installations, this parameter should point to the directory location that corresponds to the SYS:SYSTEM volume on the NetWare machine.
2-27
Embedding Pervasive.SQL in Your Product Installation
The second parameter is the location in which the Pervasive.SQL engines (with the exception of NetWare), requesters, utilities, and documentation should be installed. The default value, an empty string, causes Pervasive.SQL to be installed to the Pervasive default installation location. This is recommended since it allows your product—and potentially other products owned by your customer—to install Pervasive.SQL components to a common location. This could save disk space and ensure proper operation of the Pervasive.SQL components. You may also change the second parameter to inform the Toolkit to install Pervasive.SQL to your product’s installation location or another location specified by the user.
Note For Netware installations the second parameter should be set to the InstallShield variable TARGETDIR. This will allow all the Pervasive.SQL requesters, utilities, documentation and even Client Install images to reside on the server as well. With these files on the Server, clients can perform Network installs from the server, thus conserving large amounts of disk space on you network.
The third parameter, svSetupType, informs the Installation Toolkit which type of installation is going to be performed. Currently the only value that has any effect on the Installation Toolkit is “Network”, which causes the installation to attempt to use already installed Pervasive.SQL components on a remote server instead of installing them locally on the client. Only Pervasive.SQL client installation uses this feature. PtkMoveFileData() should be called within the InstallShield function MoveFileData(). It requires no parameters and should be called at the end of the function immediately before the return command. This function should only be called if the InstallShield ComponentMoveData() call was successful. The setup should not be allowed to continue if this function returns an error:
// PSQL_BEGIN - Inserted by Pervasive.SQL Install Toolkit - DO NOT REMOVE THIS LINE // perform the data move Toolkit operations - only if the IS call succeeded if (nResult = 0) then
2-28
Using the Pervasive Installation Toolkit API nResult = PtkMoveFileData(); endif; // PSQL_END - Inserted by Pervasive.SQL Install Toolkit - DO NOT REMOVE THIS LINE
PtkProcessAfterDataMove() should be called within the InstallShield function ProcessAfterDataMove(). It requires no parameters and should be called at the end of the function immediately before the return command. The setup should not be allowed to continue if this function returns an error. // PSQL_BEGIN - Inserted by Pervasive.SQL Install Toolkit - DO NOT REMOVE THIS LINE // perform the post data move Toolkit operations if (PtkProcessAfterDataMove() < 0) then return -1; endif; // PSQL_END - Inserted by Pervasive.SQL Install Toolkit - DO NOT REMOVE THIS LINE
PtkSetupRegistry() should be called within the InstallShield function SetupRegistry(). It requires no parameters and
should be called at the end of the function, immediately before the return command. This function should only be called if the InstallShield CreateRegistrySet() call was successful: // PSQL_BEGIN - Inserted by Pervasive.SQL Install Toolkit - DO NOT REMOVE THIS LINE // perform the registry Toolkit operations - only if the IS call succeeded if (nResult = 0) then nResult = PtkSetupRegistry(); endif; // PSQL_END - Inserted by Pervasive.SQL Install Toolkit - DO NOT REMOVE THIS LINE
PtkSetupFolders() should be called within the InstallShield
function SetupFolders(). It requires no parameters and should be called at the end of the function, immediately before the return command. This function should only be called if the InstallShield CreateShellObjects() call was successful: // PSQL_BEGIN - Inserted by Pervasive.SQL Install Toolkit - DO NOT REMOVE THIS LINE // perform the program folder Toolkit operations only if the IS call succeeded
2-29
Embedding Pervasive.SQL in Your Product Installation if (nResult = 0) then nResult = PtkSetupFolders(); endif; // PSQL_END - Inserted by Pervasive.SQL Install Toolkit - DO NOT REMOVE THIS LINE
PtkCompleteSetup() should be called within the InstallShield
main program. It should be called towards the end, but before the end_install: label and before the CleanUpInstall() function. // PSQL_BEGIN - Inserted by Pervasive.SQL Install Toolkit - DO NOT REMOVE THIS LINE // perform the completion Toolkit operations if (PtkCompleteSetup(UNINST_LOGFILE_NAME)<0) goto end_install; // PSQL_END - Inserted by Pervasive.SQL Install Toolkit - DO NOT REMOVE THIS LINE PtkCompleteSetup() takes one parameter, which the Ptkmerge
utility defaults to the UNINST_LOGFILE_NAME constant. This informs the Installation Toolkit of the name of the uninstall log file, which is used to delete files at uninstall time. If your installation script chooses not to use the constant uninstall log file name specified by the InstallShield wizard, this parameter should be replaced with the variable name containing the proper log file name.
PtkCleanUpInstall() should be called within the InstallShield function CleanUpInstall(). It requires one parameter, nResult, which can contain any numeric status code that might
have been detected up to that point. If this status is non-zero, the Toolkit logs the status and behaves as if a non-successful setup has completed. Pass “0” to let the Toolkit know that everything has succeeded during setup. Please see the file psqlstp.rul for an example on how this status code detection and passing works. // PSQL_BEGIN - Inserted by Pervasive.SQL Install Toolkit - DO NOT REMOVE THIS LINE // perform the cleanup Toolkit operations // pass in any detected st. code so it gets logged PtkCleanUpInstall(0); // PSQL_END - Inserted by Pervasive.SQL Install Toolkit - DO NOT REMOVE THIS LINE
2-30
Using the Pervasive Installation Toolkit API
Finally, the last code portion that needs to be included in setup.rul is a #include for the Installation Toolkit script file. This statement should be inserted immediately after the Wizardgenerated #include statements, such as the one to include sddialog.h, as shown below: #include "sddialog.h" // PSQL_BEGIN - Inserted by Pervasive.SQL Install Toolkit - DO NOT REMOVE THIS LINE #include "ptk.rul" // PSQL_END - Inserted by Pervasive.SQL Install Toolkit - DO NOT REMOVE THIS LINE
These function calls, along with the #include directives, constitute the minimum amount of work required to embed a Pervasive.SQL product into your product’s installation.
Creating a Database After Installation
You may use Pervasive.SQL Distributed Tuning Interface (DTI) to create a database following a successful installation of the Pervasive.SQL product. The Pervasive.SQL engine must be running before you can create a database. The following code illustrates how to use the DTI function PvCreateDatabase in your InstallShield project to create a database. You may create a database only on the local machine (the machine on which InstallShield is running). See also PvCreateDatabase in API Programmer’s Reference, which is part of the Pervasive.SQL Software Developer’s Kit (SDK). // This line accesses a DLL required to process // DTI functions nRet = UseDLL(szPtkTargetDir ^ PTK_DEST_BINDIR ^ "w3dbav80.dll"); // This line starts a DTI session, which is required before any DTI calls are made nBTIRET = PvStart(nM); // If the DLL can be accessed then continue if (nRet = PTK_SUCCESS) then // If any existing databases need to be deleted, // uncommment and use the following IF structure. // bDeleteOld is a user-defined variable. // if (bDeleteOld) then // nBTIRET = PvDropDatabase(-1,szDatabaseName,0); // -1 represents local connection // 1 means delete DDFs, 0 means retain DDFs // endif; // This flag sets database options
2-31
Embedding Pervasive.SQL in Your Product Installation nDBFLAG = 0; // 2 means to enforce referential integrity nDBFLAG = nDBFLAG | 2; // The following function creates a new database nBTIRET = PvCreateDatabase(-1, szDatabaseName, szDatabasePath, szDatabasePath, nDBFLAG ); // -1 represents local connection // szDatabasePath is used twice: once for the // database and once for the DSN // If the database or DSN already exists, then a // failure message is written to the install.log // and a failure return code is returned if !( nBTIRET = 0 || nBTIRET = PTK_STATUS_DBNAME_ALREADY_EXISTS ) then Sprintf(szMsg, @PTK_ERR_CREATE_DEMODBNAME, nBTIRET); PtkAddToLogFile(szMsg,@PTK_STAMP_DBCONFIG); nRet =PTK_FAILURE; else // If the database and DSN were created, a success // return code is returned nRet = PTK_SUCCESS; endif; endif; // This line releases the DLL nRet = UnUseDLL(szPtkTargetDir ^ PTK_DEST_BINDIR ^ "w3dbav80.dll");
Running PSA During Setup
2-32
To use the file archiving and connectivity testing capabilities of Pervasive System Analyzer (PSA), it must be invoked in your setup.rul file by calling the function PtkRunPSA(). PSA can run in two phases. The first phase analyzes the system and archives files. The second phase performs engine connectivity testing. Please refer to the file psqlstp.rul to see our implementation of calling this function. Please note that the third parameter is reserved and only “0” should be passed.
Function Reference
Function Reference The functions of the Pervasive.SQL Installation Toolkit are as follows:
“PtkAddControlCenterApp()” on page 2-35 “PtkAddControlCenterTool()” on page 2-36 “PtkAddToLogFile()” on page 2-37 “PtkCheckRequirements()” on page 2-38 “PtkCleanUpInstall()” on page 2-39 “PtkCompleteSetup()” on page 2-40 “PtkConfigDatabase()” on page 2-41 “PtkCopyFileEx()” on page 2-42 “PtkGetProfile()” on page 2-43 “PtkGetSelectedComponentSize()” on page 2-44 “PtkGetUncRoot()” on page 2-45 “PtkInitComponents()” on page 2-46 “PtklsComponentEnabled()” on page 2-47 “PtkIsDCOMRequired()” on page 2-48 “PtkKeyEnabled()” on page 2-49 “PtkMessage()” on page 2-50 “PtkMoveFileData()” on page 2-51 “PtkMyInstallService()” on page 2-52 “PtkMyRemoveService()” on page 2-53 “PtkMyStartService()” on page 2-54 “PtkMyStopService()” on page 2-55 “PtkProcessAfterDataMove()” on page 2-56 “PtkProcessBeforeDataMove()” on page 2-57 “PtkPutProfile()” on page 2-58 “PtkPutRegistry()” on page 2-59 “PtkRunPSA()” on page 2-60 “PtkSetInstallMode()” on page 2-61 “PtkSetKey()” on page 2-62 “PtkSetupFolders()” on page 2-63 “PtkSetupInstall()” on page 2-64
2-33
Embedding Pervasive.SQL in Your Product Installation
2-34
“PtkSetupRegistry()” on page 2-65 “PtkSetupScreen()” on page 2-66 “PtkShowMsg()” on page 2-67 “PtkUpdateSystem()” on page 2-68
Function Reference
PtkAddControlCenterApp() Syntax: PtkAddControlCenterApp(szDisplayName, szExePath, szParameters, szEnabled, nAccess);
Parameters: szDisplayName
Label displayed in the Control Center.
szExePath
Full path of the program executable.
szParameters
List of optional parameters to szExePath.
szEnabled
Indicates whether the external routine should be visible in the Control Center name space.
nAccess
Can be either PTK_PCC_COMMON or PTK_PCC_USER. This value determines whether the external utilities in PCC can be seen by a single user or all users.
Return Value:
PTK_SUCCESS Errors:
None Description:
PtkAddControlCenterApp() registers an application with the Pervasive Control Center so that it and other applications can be started from a central location. The added application appears as an icon on the tree view of the Control Center and can be identified by the text contained in the szDisplayName parameter.
2-35
Embedding Pervasive.SQL in Your Product Installation
PtkAddControlCenterTool() Syntax: PtkAddControlCenterTool(szPath, szFileName, szParam);
Parameters: szPath
Directory where file is located.
szFileName
Name of file to add to PCC as a COM object tool.
szParam
The parameters that need to be passed to the executable file to register itself.
Return Value:
PTK_SUCCESS Errors:
None Description:
PtkAddControlCenterTool() registers executable COM objects with the Pervasive Control Center so that it can be loaded from within the Control Center.
2-36
Function Reference
PtkAddToLogFile() Syntax: PtkAddToLogFile(szLogText, szStampText);
Parameters:: szLogText
Log message.
szStampText
Stamp string (the empty string, "", causes no stamp to be applied).
Return Value:
None Errors:
None Description:
PtkAddToLogFile() writes text lines to the log file with an optional stamp. With the stamp: szStampText: szLogText
With no stamp: szLogText
2-37
Embedding Pervasive.SQL in Your Product Installation
PtkCheckRequirements() Syntax: PtkCheckRequirements();
Parameters:
None Return Value:
PTK_SUCCESS or Error Code Errors:
PTK_ERRNO_SYSTEM_INI Description:
PtkCheckRequirements() checks for and sets up all of the Toolkit requirements in this function.
2-38
Function Reference
PtkCleanUpInstall() Syntax: PtkCleanUpInstall(nResult);
Parameters: nResult
Status code returned by any previous function call.
Return Value:
PTK_SUCCESS or PTK_FAILURE Errors:
PTK_FAILURE Description:
PtkCleanUpInstall() performs general Toolkit cleanup steps. If any errors were detected during Setup, they can be passed in via the nResult parameter. This allows the Toolkit to perform some recovery steps in case of an installation failure. The following operations are attempted even in the case of an installation failure:
Copies ptksetup.ini. Writes a “succeeded” tag (@PTK_LOG_INST_SUCC) or a “failed” tag (@PTK_LOG_INST_FAIL) to the installation log file. Closes out the installation log file (and makes a program icon).
There is no guarantee that any of these operations will succeed.
2-39
Embedding Pervasive.SQL in Your Product Installation
PtkCompleteSetup() Syntax: PtkCompleteSetup(szLogFile);
Parameters: szLogFile
The full path name of the uninstallation log file.
Return Value:
PTK_SUCCESS or a return error code Errors:
PTK_ERRNO_ENGINE_LOAD Description:
PtkCompleteSetup() updates the environment, starts any engines that were installed and performs some final configuration steps. It also creates/updates the uninstall registry key and icon. Note The value passed to PtkCompleteSetup() is obtained from the second parameter returned by the InstallShield DeinstallStart() function. Win32 installations can pass an empty string as the parameter since InstallShield creates the “add/remove programs” entry automatically.
2-40
Function Reference
PtkConfigDatabase() Syntax: PtkConfigDatabase(szDatabaseName, szDatabasePath, nEngineType, bDeleteOld);
Parameters: szDatabaseName
The ODBC DSN label to name the database.
szDatabasePath
The location of the database.
nEngineType
The type of Pervasive.SQL engine creating the database (either PTK_DBN_ENGINE_TYPE_SERVER or PTK_DBN_ENGINE_TYPE_WKSTN).
bDeleteOld
If set to “true,” first deletes the database associated with szDatabaseName, then creates a DSN and DBName.
Return Value:
PTK_SUCCESS or PTK_FAILURE Errors:
None Description:
PtkConfigDatabase() creates a DSN and DBName for a database located in the szDatabasePath directory. This function uses the same value, szDatabaseName, for both the DSN and DBName. Note PtkConfigDatabase() is applicable only to database server installations on Windows. It does not apply to either Client or NetWare Server installations.
2-41
Embedding Pervasive.SQL in Your Product Installation
PtkCopyFileEx() Syntax: PtkCopyFileEx(szFromDir, szFromFile, szToDir, szToFile, nFlags);
Parameters: szFromDir
Directory from which you are copying the files.
szFromFile
The source file mask.
szToDir
Directory to which you are copying the files.
szToFile
The target file mask.
nFlags
The file copy flags.
Return Value:
Ptk_SUCCESS or Error code Errors:
PTK_ERRNO_NO_COPY Description:
PtkCopyFileEx() is a wrapper for the InstallShield XCopyFile function. It logs and checks to see if the source file exists.
2-42
Function Reference
PtkGetProfile() Syntax: PtkGetProfile(szPath, szSection, szKey, svValue);
Parameters: szPath
Path of the INI file to be queried.
szSection
Name of section in szPath file for this component.
szKey
Name of key in szSection section to use for value.
svValue
Value associated with szKey key.
Return Value:
Same as for the InstallShield GetProfString() function Errors:
Same as for the InstallShield GetProfString() function Description:
PtkGetProfile() receives the value of the key szKey in the section szSection of the szPath INI file. The value is returned in the svValue parameter and is also written to the installation log file.
2-43
Embedding Pervasive.SQL in Your Product Installation
PtkGetSelectedComponentSize() Syntax: PtkGetSelectedComponentSize(szMedia, szComponent);
Parameters: szMedia
The media in which the szComponent resides.
szComponent
Component to be checked.
Return Value:
The size of the component or 0 Errors:
None Description:
PtkGetSelectedComponentSize() checks if szComponent is selected. If so, the function returns the size of szComponent. If szComponent is not selected, the function returns 0.
2-44
Function Reference
PtkGetUncRoot() Syntax: PtkGetUncRoot(szPath, szUncRoot);
Parameters: szPath
Path from which to extract UNC root.
szUncRoot
Return parameter with UNC root.
Return Value:
PTK_SUCCESS or PTK_FAILURE Errors:
None Description:
PtkGetUncRoot() gets the UNC root from a path passed to the function.
2-45
Embedding Pervasive.SQL in Your Product Installation
PtkInitComponents() Syntax: PtkInitComponents(szSetupType, szIniFile);
Parameters: szSetupType
The setup type selected by the user (typically one of "Typical," "Custom," or "Network")
szIniFile
The ptksetup.ini file that should be used to initialize components.
Return Value:
PTK_SUCCESS Errors:
None Description:
PtkInitComponents() sets the Installation Toolkit internal variable recording the type of installation being performed. It also reads the INI file and initializes each of the InstallShield File Components based on the values found. This function should be called after an InstallShield SetupType has been selected so the INI file settings overwrite any initialization performed by the IDE.
2-46
Function Reference
PtklsComponentEnabled() Syntax: PtkIsComponentEnabled(szComponentName, szClientDir, szFileName);
Parameters: szComponentName
The InstallShield component name to test
szClientDir
The directory location of the installed component
szFileName
The file name of the installed component
Return Value:
TRUE or FALSE Errors:
None Description:
PtkIsComponentEnabled() checks to see if a given component has been enabled. Since not all components may be copied to disk during a Network install, ComponentIsItemSelected() may not be usable in all cases.
2-47
Embedding Pervasive.SQL in Your Product Installation
PtkIsDCOMRequired() Syntax: PtkIsDCOMRequired();
Parameters:
None Return Value:
TRUE if DCOM is required and could not be found on this machine; FALSE otherwise. Errors:
None Description:
PtkIsDCOMRequired() determines whether the Pervasive.SQL product being installed requires that DCOM be installed. If it is required and DCOM can not be detected in the machine, TRUE is returned. PtkIsDCOMRequired() should only be called once for the Pervasive.SQL product to be installed. This function always returns FALSE for Windows NT, 2000, and XP.
2-48
Function Reference
PtkKeyEnabled() Syntax: PtkKeyEnabled(szSection, szKey);
Parameters: szSection
Name of the section in the ptksetup.ini file.
szKey
Name of the key in the specified section.
Return Value:
TRUE if the key specified by szKey has an “On” or “Yes” value; otherwise FALSE. Errors:
None Description:
PtkKeyEnabled() verifies whether the key szKey in the section szSection of the ptksetup.ini file is set to “On” or “Yes.” If the key is not present or has an empty value (that is, key=), InstallShield considers the key set to PTK_NO. This function performs a caseinsensitive comparison test on the key values.
2-49
Embedding Pervasive.SQL in Your Product Installation
PtkMessage() Syntax: PtkMessage(szString, nType);
Parameters: szString
Message string that is to be displayed to the user
nType
Message type (one of INFORMATION, WARNING, SEVERE)
Return Value:
PTK_SUCCESS Errors:
None Description:
PtkMessage() displays a temporary dialog on the screen that can be used to present the user with status information during an installation. This function does not require that the user click an OK button when nType INFORMATION, but does when nType is WARNING or SEVERE. If the szString parameter is greater than 120 characters, PtkMessage() uses the InstallShield MessageBox() function to display the string since it can support the longer string. This function will log execution to the installation log file but will not be able to do so before PtkSetupInstall() or after PtkCleanUpInstall() has been called.
2-50
Function Reference
PtkMoveFileData() Syntax: PtkMoveFileData();
Parameters:
None Return Value:
PTK_SUCCESS or an Error Code Errors:
None Description:
PtkMoveFileData() performs file copy functions that can not be handled by the InstallShield ComponentMoveData() function. These functions include:
Copying the readme file from the installation source directory. Copying PSA files to common files (not logged).
2-51
Embedding Pervasive.SQL in Your Product Installation
PtkMyInstallService() Syntax: PtkMyInstallService(szServiceName, nServiceType, nStartMode, szExePath, szInstallMode);
Parameters: szServiceName
The name of the service to be installed.
szServiceType
The type of the service.
nStartMode
The start mode for the service.
szExecPath
The full path and executable name of the program to be started. Should be quoted to ensure that paths with embedded spaces work as expected.
szInstallMode
Pass PTK_SERVICE_NORMAL if you want to see a status message displayed to the screen while the service is installing. Otherwise pass PTK_SERVICE_SILENT.
Return Value:
PTK_SUCCESS or PTK_FAILURE Errors:
PTK_FAILURE Description:
Installs the service named in szServiceName with service type nServiceType, start mode nStartMode, and executable szExePath.
2-52
Function Reference
PtkMyRemoveService() Syntax: PtkMyRemoveService(szServiceName, szKillMode);
Parameters: szServiceName
The name of the service to be removed.
szKillMode
Pass PTK_SERVICE_NORMAL if you want to see a status message displayed to the screen while the service is being removed. Otherwise pass PTK_SERVICE_SILENT.
Return Value:
PTK_SUCCESS or PTK_FAILURE Errors:
PTK_FAILURE Description:
Removes the service named in szServiceName.
2-53
Embedding Pervasive.SQL in Your Product Installation
PtkMyStartService() Syntax: PtkMyStartService(szServiceName);
Parameters: szServiceName
The name of the service to be started.
Return Value:
PTK_SUCCESS or PTK_FAILURE Errors:
PTK_FAILURE Description:
Starts the service named in szServiceName.
2-54
Function Reference
PtkMyStopService() Syntax: PtkMyStopService(szServiceName);
Parameters: szServiceName
The name of the service to be stopped.
Return Value:
PTK_SUCCESS or PTK_FAILURE Errors:
PTK_FAILURE Description:
Stops the service named in szServiceName.
2-55
Embedding Pervasive.SQL in Your Product Installation
PtkProcessAfterDataMove() Syntax: PtkProcessAfterDataMove();
Parameters:
None Return Value:
PTK_SUCCESS or PTK_FAILURE Errors:
None Description:
PtkProcessAfterDataMove() performs any configuration operations for Pervasive.SQL components installed by the MoveFileData() function. It does this by calling a sequence of PtkConfig functions that know how to configure specific components that have been installed. These operations include creating program folders and icons, setting Registry or INI file settings, installing engines, and so on. This function also registers all self-registering files with the BATCH method.
2-56
Function Reference
PtkProcessBeforeDataMove() Syntax: PtkProcessBeforeDataMove(szSystemDir, szTargetDir, szSetupType);
Parameters: szSystemDir
Location where system components will be installed.
szTargetDir
Location where non-system components will be installed.
szSetupType
The installation type (usually one of Typical, Custom or Network).
Return Value:
PTK_SUCCESS or PTK_FAILURE Errors:
None Description:
PtkProcessBeforeDataMove() performs tasks in preparation for actual file copying. It sets internal Toolkit variables concerning the proper installation locations for Pervasive.SQL components. It creates the program folders, calls “prepare” functions for the engine and client components, and records component selection information in ptksetup.ini.
2-57
Embedding Pervasive.SQL in Your Product Installation
PtkPutProfile() Syntax: PtkPutProfile(szPath, szSection, szKey, szValue);
Parameters: szPath
Path of the ptksetup.ini file to be modified. (Path only, the file name is defined as “ptksetup.ini.”)
szSection
Name of INI file section to be modified.
szKey
Key to receive the new value.
szValue
New value to be assigned to the key.
Return Value:
Same as for the InstallShield function WriteProfString() Errors:
Same as for the InstallShield function WriteProfString() Description:
PtkPutProfile() inserts the value szValue into the specified section and key of the ptksetup.ini file. The value is also recorded in the installation log file.
2-58
Function Reference
PtkPutRegistry() Syntax: PtkPutRegistry(szKey, szName, nType, szValue, nSize);
Parameters: szKey
Full key path in Registry.
szName
String name to receive the key value.
nType
Type of data being placed in szName.
szValue
Data to be placed in szName.
nSize
Size of the data to be written.
Return Value:
Same as for the InstallShield function RegDBSetKeyValueEx() Errors:
Same as for the InstallShield function RegDBSetKeyValueEx() Description:
PtkPutRegistry() inserts the value szName=szValue pair into the Registry key specified in szKey, and writes the key name and value to the installation log file.
2-59
Embedding Pervasive.SQL in Your Product Installation
PtkRunPSA() Syntax: PtkRunPSA(nPhase, szSysDir, bReserved);
Parameters: nPhase
The phase of PSA that should be executed, either PTK_PSA_PHASE_1 (system analysis) or PTK_PSA_PHASE_2 (database engine and connectivity testing).
szSysDir
The system directory where BTI.INI or BTI.CFG is located (%WinSysDir% or NetWare SYS:\SYSTEM)
bReserved
This is an internal parameter. Only pass 0.
Return Value:
PTK_SUCCESS or an Error Code Errors:
PTK_ERRNO_INVALID_PHASE Description:
PtkRunPSA() runs PSA to perform either system analysis (phase 1) or engine connectivity and database engine testing (phase 2). The function calls PSA with the correct command line based on information stored in the ptksetup.ini file.
2-60
Function Reference
PtkSetInstallMode() Syntax: PtkSetInstallMode(nMode);
Parameters: nMode
The new mode to use, one of: PTK_INSTALL_MODE_READ PTK_INSTALL_MODE_NORMAL PTK_INSTALL_MODE_SILENT
Return Value:
PTK_SUCCESS or PTK_FAILURE Errors:
None Description:
PtkSetInstallMode() sets the installation output behavior (referred to as the “mode” of the install) for the rest of the installation or until the next call to this function. If PTK_INSTALL_MODE_READ is passed in nMode, then the installation program reads the installation mode (either NORMAL or SILENT, whichever is set in the file) from ptksetup.ini file. Using this function, the calling script can modify the mode of the installation from Ptk function to Ptk function by changing the mode. Note The mode cannot be set back to READ or NORMAL after setting it to SILENT within the same installation procedure.
2-61
Embedding Pervasive.SQL in Your Product Installation
PtkSetKey() Syntax: PtkSetKey(szFile, szSection, szKey, bValue);
Parameters: szFile
Full path of the INI file to be modified.
szSection
Name of the INI file section to be modified.
szKey
Key to receive the new value.
bValue
TRUE if key is to be enabled (PTK_YES), otherwise set to FALSE.
Return Value:
Same as the function PtkPutProfile() Errors:
Same as the function PtkPutProfile() Description:
PtkSetKey() sets the value of the szKey in szSection of the INI file szFile to PTK_YES if bValue is TRUE; otherwise to PTK_NO.
2-62
Function Reference
PtkSetupFolders() Syntax: PtkSetupFolders();
Parameters:
None Return Value:
PTK_SUCCESS Errors:
None Description:
PtkSetupFolders() initializes and creates all of the necessary program folders and icons.
2-63
Embedding Pervasive.SQL in Your Product Installation
PtkSetupInstall() Syntax: PtkSetupInstall();
Parameters:
None Return Value:
PTK_SUCCESS or PTK_FAILURE Errors:
None Description:
PtkSetupInstall() initializes a number of global variables used throughout the installation. It also records information about the installation to the INI file as well and the log file. Note In a Win32 install, PtkSetupInstall() enables CORECOMPONENTHANDLING. If you want this feature disabled for any installation actions you invoke, you should disable it after you call PtkSetupInstall(). This function should only be called once during an install.
2-64
Function Reference
PtkSetupRegistry() Syntax: PtkSetupRegistry();
Parameters:
None Return Value:
PTK_SUCCESS or PTK_FAILURE Errors:
None Description:
PtkSetupRegistry() calls functions that write required values to the Windows registry. Not all registry entries are made through function calls from this routine, however.
2-65
Embedding Pervasive.SQL in Your Product Installation
PtkSetupScreen() Syntax: PtkSetupScreen();
Parameters:
None Return Value:
PTK_SUCCESS Errors:
None Description:
PtkSetupScreen() is a placeholder for the Ptk version of the InstallShield SetupScreen() function, created to maintain consistency with InstallShield and other Pervasive Installation Toolkits.
2-66
Function Reference
PtkShowMsg() Syntax: PtkShowMsg(szMessage, bDisplay);
Parameters: szMessage
Message string to display / remove.
bDisplay
Display or remove flag.
Return Value:
PTK_SUCCESS Errors:
None Description:
PtkShowMsg() is a wrapper for the InstallShield SdShowMsg() function. It displays nothing to the user if a silent installation is being performed or in the event of an empty message. The message is also logged to the installation log file.
2-67
Embedding Pervasive.SQL in Your Product Installation
PtkUpdateSystem() Syntax: PtkUpdateSystem();
Parameters:
None Return Value:
PTK_SUCCESS or PTK_FAILURE Errors:
None Description:
PtkUpdateSystem() updates the system components to match the requirements. If critical system files were updated and were locked in memory, the bPtkSystemUpdateReboot flag gets set and a log entry is made. If this flag is tripped, we strongly recommended that you perform a reboot at this point before continuing the setup. If noncritical files were updated and were locked in memory, only the BATCH_INSTALL flag is tripped, and a simple “end of install” reboot is triggered.
2-68
Easy Updates
Easy Updates The Pervasive.SQL installer allows the end-user customer to install the main product as well as updates, such as hot fixes, during a single installation procedure. There is no need for the customer to install updates separately. This feature is called “Easy Updates.” “Easy Updates” is convenient because you can add files to be installed by the Pervasive.SQL installation program simply by dropping the files into a specific directory location in the installation image. You do not need to change a single line of code in your installation program. offers the capability to install additional Pervasive.SQL file updates, such as hot fixes, during the course of the installation. This feature can be very convenient because it This feature is called “Easy Updates” because you can add files to be installed by the Pervasive.SQL installation program simply by dropping the files into a specific directory location in the installation image. You do not need to change a single line of code in your installation program.
How Easy Updates Works
After the Pervasive.SQL installation program copies the main installation files from the CAB archives to the installation target folders, it checks the installation media for a subfolder called UPD. This subfolder must reside in the same folder as the Pervasive.SQL installation program, SETUP.EXE. The UPD folder must be at the same level of the installation image as the folders named ACROREAD, CLIENTS, and UPDATE. Note UPD and UPDATE are two different folders. Do not confuse them. The UPD folder, which you manually create, is used for Easy Updates. The UPDATE folder is part of the default structure required to install Pervasive.SQL.
If the UPD folder exists at the specified location, then the installation program copies the contents of the folder to corresponding locations in the installation target folder using InstallShield’s xcopy. This feature is also available for the client installation program. In this case, the UPD folder must be in the same folder as the client
2-69
Embedding Pervasive.SQL in Your Product Installation
SETUP.EXE program. In other words, the client UPD folder must be created in the folder CLIENTS\WIN on the server installation image. For example, if the engine installation program has been instructed to install Pervasive.SQL to target location D:\DB_PRODUCTS\PSQL, then the contents of UPD\PVSW\BIN are copied to D:\DB_PRODUCTS\PSQL\BIN. If the target folder already contains a file with the same name as a given “update” file, the installation program checks to see which file has a higher version number. If the existing file has a higher version, the installation program does not install the “update” file. This behavior prevents errors that can occur when a newer component is accidentally overwritten by an older one. To maintain consistency of installed files and prevent misuse of this feature, only the following subfolders of the UPD folder are recognized by the installation program: Table 2-5 UPD Subfolders Recognized by the Installation Program Subfolder
Location on Target System Where Files Copies
ODBC
For NetWare only: The ODBC folder, usually F:\ODBC, if drive F: is mapped to the NetWare SYS folder.
PVSW
Main Pervasive.SQL target installation folder. For example, if you specified C:\DB\PSQL as the installation target, then the contents of UPD\PVSW\BIN are copied to C:\DB\PSQL\BIN.
SYSTEM
For NetWare only: The NetWare system folder, usually F:\SYSTEM, if drive F: is mapped to the NetWare SYS folder.
Note Any other subfolders in the UPD folder are ignored.
How to Use Easy Updates
This section describes step-by-step how to add Pervasive.SQL file updates to your installation program. 1
2-70
On your installation media image, create the folder UPD in the same folder as the Pervasive.SQL client and/or engine SETUP.EXE program(s).
Easy Updates
2
Populate the UPD folder(s) you just created with the Pervasive.SQL folders and files that you want updated in the installation. Within the UPD folder, each file and subfolder must correspond to the same location and file of the installation target. For example, if you want to install an update for a file that normally resides in the BIN directory of the installation location for Pervasive.SQL, then you must put this file in UPD\PVSW\BIN. Within the UPD folder, you should always use “PVSW” to represent the main installation target folder, even if you are installing to a custom location, such as D:\MYDB\DBFILES, rather than the default location C:\PVSW. The installation program automatically determines the folder to which you are installing. Caution Do not mix files for different products in the same directory. For example, do not put Workgroup Engine and Server Engine DLLs in the same UPD\PVSW\BIN directory. As well, do not mix files for different platforms in the same directory. For example, do not put NetWare Server Engine files and Windows Server Engine files in the same UPD\PVSW\BIN directory. You must store all files for each type of installation separately. If you do not store the update files separately, your engine components may be improperly validated by the user count administrator, and your engine may not function. Keep in mind that Pervasive Field Test Files (FTFs) are shipped with all platforms/ components in the same directory, so if you are using files from an FTF, you must separate the files appropriately.
Example of Using Easy Updates for an Engine DLL You want to install engine DLL W3MIF109.DLL, because it contains a fix for a defect in W3MIF107.DLL, which is installed by the main installation program. 1
In your installation media image, create the folder UPD in the same folder as the Pervasive.SQL SETUP.EXE program.
2
Within the UPD folder you have created, create the subfolder PVSW. Within the PVSW subfolder, create another subfolder named BIN.
2-71
Embedding Pervasive.SQL in Your Product Installation
3
Copy your desired file update, in this case W3MIF109.DLL, to UPD\PVSW\BIN.
4
Re-master your installation media with the updated image.
Example of Using Easy Updates for a Client DLL You want to install client DLL W3MIF109.DLL, because it contains a fix for a defect in W3MIF107.DLL, which is installed by the main client installation program. 1
In your installation media image, create the folder UPD in the same folder as the Pervasive.SQL client SETUP.EXE program. In other words, create a folder UPD in the folder CLIENTS\WIN.
2
Within the UPD folder you have created, create the subfolder PVSW. Within the PVSW subfolder, create another subfolder named BIN.
3
Copy your desired file update, in this case W3MIF109.DLL, to the folder CLIENTS\WIN\UPD\PVSW\BIN that you have created.
4
Re-master your installation media with the updated image.
When the installation program runs, W3MIF107.DLL is installed from the main CAB archive, then W3MIF109.DLL is also installed from the UPD folder. W3MIF107.DLL is not deleted, but the Pervasive.SQL Smart Components architecture ensures that only the higher-numbered MIF component is ever used. If the update file is not a Smart Component (that is, it does not use an incremental numbering scheme in the file name), the existing file is overwritten by the update file.
2-72
Uninstalling the Pervasive.SQL Products
Uninstalling the Pervasive.SQL Products The Pervasive.SQL Installation Toolkit uses an uninstall DLL to provide added functionality to the InstallShield uninstaller, such as stopping services and deleting files and registry entries. The Installation Toolkit automatically includes the uninstall DLL in the command line used to uninstall Pervasive.SQL or any product that embeds Pervasive.SQL in its install. If your product’s installation has no specific uninstallation requirements, you may use the uninstall DLL as is. If your installation has specific uninstallation requirements, you may customize the uninstall process by using the ptksetup.ini file.
Ptksetup.ini File
The uninstall DLL controls certain uninstall functionality through the use of sections and keys in the ptksetup.ini file. You may perform the following operations through the INI file:
Sections
Run a command line process (used to unregister executables and DLLs) Remove files and directories Remove keys and values from the registry
A section is a group of related items called keys. The ptksetup.ini file provides pre-defined sections and also allows you to add your own user-defined sections. Section names must be enclosed in brackets. For example, a section named “Common” appears in the ptksetup.ini as [Common]. (Section names and key names conform to the Microsoft format for Windows INI files.) If a section has more than one key with the same name, each key must be appended with an integer value. The keys appear in the INI file with the format of key name[n]. The uninstall DLL sorts the keys by the appended integer values and refers to the keys in the sorted order. The main pre-defined sections are pre-uninstall and postuninstall. Pre-Uninstall and Post-Uninstall Sections The uninstall DLL is called by the InstallShield uninstaller before InstallShield performs the actual uninstallation. The DLL returns a
2-73
Embedding Pervasive.SQL in Your Product Installation
value to the InstallShield uninstaller that causes the uninstaller to either continue or abort. After InstallShield performs the uninstallation, the uninstall DLL is called a second time. The first time the uninstall DLL is called, it performs operations from the section pre-uninstall. The second time the DLL is called, it performs operations from the section post-uninstall. Both the pre-uninstall and post-uninstall sections recognize three key types:
Run-process Filesystem-remove Registry-remove
All user-defined sections must be referenced by values within these three key types. See “Keys Used with the Pre-uninstall and Post-uninstall Sections” on page 2-81. Caution Do not delete or rename the sections pre-uninstall or post-uninstall in the ptksetup.ini file.
User-defined Sections You may add your own sections, called user-defined sections, to ptksetup.ini. The uninstall DLL supports the following types of user-defined sections:
Run-process Filesystem-remove Registry-remove Test Registry-value
All user-defined sections must be referenced within the preuninstall and post-uninstall sections.
2-74
Uninstalling the Pervasive.SQL Products
Note Each user-defined section type, except for “Test” and “Registryvalue,” must include the keys “Product” (page 2-83) and “Supportedos” (page 2-84). Otherwise, the uninstall DLL will not perform the operations specified in the section.
Run-process
“Run-process” sections contain keys with information necessary to run a command line process. The primary purpose of “Run-process” sections is to unregister DLLs and executable files. Sections of this type may use any of the test keys (see Table 2-7). “Name” (page 2-85) is a required key. It specifies the name of the executable to be run. The optional keys are “Run-parameters” (page 2-85), “Rundirectory” (page 2-85), and “Path-name-root” (page 2-85). The optional keys may contain path expansion values. “Run-parameters[n]” contains the values that are passed as command line parameters to the executable. If you use “Run-directory,” the DLL changes directories to the value specified for run-directory before running the process. The DLL then returns to the previous directory once that process completes. Example of a “Run-process” Section The following example runs the Pervasive Control Center executable in the Pervasive.SQL installation directory. The executable receives one command line parameter to initiate an uninstallation. This section is set to run if the user specifies that additional files should be cleaned up. (See “Cleanup-only” on page 2-83.) [pcc.exe] cleanup-only=yes run-directory=[install-directory] name=bin\pcc.exe run-parameters=-uninstall product0=nt-server product1=workgroup product2=client supported-os=[all]
2-75
Embedding Pervasive.SQL in Your Product Installation
Filesystem-remove
“Filesystem-remove” sections contain information necessary to remove files or directories. Sections of this type may use any of the test keys (see Table 2-7). “Name” (page 2-85) is a required key. It specifies the name of the file system element to remove (a file or directory). The optional keys are “Path-name-root” (page 2-85), “Is-directory” (page 2-84), and “Remove-children” (page 2-85). If “Path-name-root” is provided, its value is pre-pended to each instance of the “Name” element. “Is-directory” accepts a Boolean value (see “Boolean Values” on page 2-81). Setting “Is-directory” to true indicates that the “Name” element is a directory, and the uninstall DLL removes the directory. If “Is-directory” is set to false and the “Name” element is a directory, the directory is not removed. “Remove-children” accepts a Boolean value and is only used if “Isdirectory” is true. If both “Is-directory” and “Remove-children” are true, the directories referred to by “Name[n]” are removed recursively. Example of a“Filesystem-remove” Section The following example removes all files named config.pi* from the NetWare system directory (SYS:SYSTEM:). [WinSysDirFilesCleanup] cleanup-only=yes path-name-root=[system-directory] name0=config.pi_ name1=config.pu_ supported-os=[all] product0=nt-server product1=client product2=workgroup
Registry-remove
“Registry-remove” sections contain information necessary to remove registry keys or registry values. Sections of this type may use any of the test keys (see Table 2-7).
2-76
Uninstalling the Pervasive.SQL Products
The required keys are “Name” (page 2-85) and “Registry-root” (page 2-85). “Name” is the complete path name to a registry key, without the root value specified by “Registry-root.” If the optional key “Value-name” is not used, the uninstall DLL removes the entire registry key. Therefore, multiple instances of “Name[n]” can be used. If “Valuename” is used, only one instance of “Name” may be used. “Registry-root” specifies the root key in the registry. The only permissible values are the following:
HKEY_CLASSES_ROOT HKEY_CURRENT_USER HKEY_LOCAL_MACHINE HKEY_USERS HKEY_CURRENT_CONFIG
The optional keys are “Remove-children” (page 2-85) and “Valuename” (page 2-86). “Remove-children” accepts a Boolean value and is used only if “Value-name” is not used. If “Remove-children” is set to true, the registry keys and keys referred to by “Name” are removed recursively. “Value-name[n]” is the name of the value referenced within a registry key. You may use multiple instances of this key (in which case all instances of “Value-name” are removed from the registry). “Name” and “Value-name” may contain path expansion values (see “Path Expansion Values” on page 2-80). Examples of “Registry-remove” Sections The following example recursively removes all registry entries under HKEY_LOCAL_MACHINE\SOFTWARE\Pervasive Software\Control Center and HKEY_LOCAL_MACHINE\SOFTWARE\Pervasive Software\Pervasive.SQL. [LocalMachineKeysCleanup] cleanup-only=yes registry-root=HKEY_LOCAL_MACHINE name0=SOFTWARE\Pervasive Software\Control Center name1=SOFTWARE\Pervasive Software\Pervasive.SQL supported-os=[all] product0=nt-server
2-77
Embedding Pervasive.SQL in Your Product Installation product1=client product2=workgroup remove-children=yes
The following example removes the keys Pervasive ODBC Client Interface and Pervasive ODBC Engine Interface from HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBCINST.INI\ODBC Drivers. [ODBCDriverValuesCleanup] registry-root=HKEY_LOCAL_MACHINE name=SOFTWARE\ODBC\ODBCINST.INI\ODBC Drivers value-name0=Pervasive ODBC Client Interface value-name1=Pervasive ODBC Engine Interface supported-os=[all] product0=nt-server product1=client product2=workgroup
Test
Test sections provide a means by which you may test conditions to decide whether to perform an operation. The name of a test section does not require a specific naming convention. The ptksetup.ini file, however, names all test sections with “test-” as the first five characters. The uninstall DLL identifies a test section by how it is used in a section (how it is “called”). The key “test=” identifies a test section by specifying a test section on the right of the equals sign. For example, in “test=test-pcc-count,” the test section is “test-pcccount.” Test sections require at least one “Element” (page 2-84) key. You may use multiple “Element” keys. The first element key must be element0 (element zero). The uninstall DLL sorts and evaluates the element keys using Reverse Polish Notation. The value of “Element” may be another section, such as a “Registryvalue” section, or one of the following pre-defined values:
2-78
[equals] [is-less-than] [is-greater-than]
Uninstalling the Pervasive.SQL Products
[is-less-than-or-equals] [is-greater-than-or-equals] [does-not-equal] [or] [and] [not] [true] [false]
If the value of “Element” is a section, that section must return a value when evaluated. The only types of sections that evaluate to a value are “Registry-value” or another test section. The optional key is “Reuse-result” (page 2-86). If the value of “Reuse-result” is set to true, the uninstall DLL saves the result obtained after the first time the test is evaluated. Subsequent references to the test section return the saved state. Example of a Test Section The following example tests if pcc-count is less than two (element0 is tested less than element1.) Note that pcc-count is a “Registryvalue.” [test-pcc-count] reuse-result=yes element0=pcc-count element1=2 element2=[is-less-than]
Registry-value
“Registry-value” sections are used to specify a complete registry value. A “Registry-value” section may be referenced only within a test section (see “Test” on page 2-78). The required keys are “Name” (page 2-85), “Registry-root” (page 285), and “Value-name” (page 2-86). The combination of the required keys evaluates to a single value. “Name” is the complete path name to a registry key, without the root value specified by “Registry-root.” “Registry-root” specifies the root key in the registry. The only permissible values are the following:
2-79
Embedding Pervasive.SQL in Your Product Installation
HKEY_CLASSES_ROOT HKEY_CURRENT_USER HKEY_LOCAL_MACHINE HKEY_USERS HKEY_CURRENT_CONFIG
“Value-name” is the name of the value referenced within a registry key. “Name” and “Value-name” may contain path expansion values. Example of a Registry-value Section The following example sets a complete registry entry for the Pervasive Control Center executable. [pcc-count] registry-root=HKEY_LOCAL_MACHINE name=SOFTWARE\Microsoft\Windows\CurrentVersion\ SharedDLLs value-name=[install-directory]\bin\pcc.exe
Keys
Keys are the information building blocks of sections. A key uses the format of key=value. All key values are case insensitive. Value can be a user-defined value or a pre-defined value. You may use both user-defined and pre-defined values in the same key. If you mix the two types, enclose the pre-defined value in brackets. For example, “run-directory=[install-directory]\bin” mixes a predefined value, “[install-directory],” with a user-defined value, “\bin.” Path Expansion Values Ptksetup.ini supports the use of path expansion values, as
defined in Table 2-6. These are values that evaluate to a drive designation or a path depending on the value. All of the path
2-80
Uninstalling the Pervasive.SQL Products
expansion values refer to the machine on which Pervasive.SQL is installed. Table 2-6 Path Expansion Values Value
Refers to
[system-directory]
The NetWare system directory (for example, SYS:SYSTEM)
[windows-sys-directory]
The Windows system directory (for example, WINNT\system32 for Windows NT)
[windows-directory]
The directory where the operating system is installed (for example, WINNT for Windows NT)
[system-drive]
The drive on the machine on which Pervasive.SQL is installed (for example, by default, C:)
[install-directory]
The directory where Pervasive.SQL is installed (for example, by default, PVSW)
[temp-directory]
The directory referred to by the TEMP environment variable.
Path expansion values may be embedded in a value that evaluates to a path. For example, “run-directory=[install-directory]\bin.” Boolean Values Value may also be set to a Boolean value. The uninstall DLL supports the following Boolean values in ptksetup.ini:
yes or true = true no or false = false
Keys Used with the Pre-uninstall and Post-uninstall Sections The pre-uninstall and post-uninstall sections recognize only three key types:
run-process[n]=user named run-process section filesystem-remove[n]=user named filesystem-remove section registry-remove[n]=user named registry-remove section
If a section has more than one key with the same name, each key must be appended with an integer value. The keys appear in the INI
2-81
Embedding Pervasive.SQL in Your Product Installation
file with the format of key name[n]. The uninstall DLL sorts the keys by the appended integer values and refers to the keys in the sorted order. Run-process[n]
This key identifies a run-process section. See “Run-process” on page 2-75. Filesystem-remove[n]
This key identifies a filesystem-remove section. See “Filesystemremove” on page 2-76. Registry-remove[n]
This key identifies a registry-remove section. See “Registry-remove” on page 2-76. Keys Used for Tests Certain keys are used to test whether operations within a userdefined section should be performed. Any user-defined section except a “test” section, must include the keys “Product” and “Supported-os.” Otherwise, the operations defined in the section will fail. “Test” sections are excluded because they are a special type of section devoted to testing. The pre-uninstall and post-uninstall sections are also excluded because they are pre-defined sections.
2-82
Uninstalling the Pervasive.SQL Products
The following table lists the keys that are used to test whether operations within a section should be performed. Table 2-7 Keys Used To Test Whether Operations Should be Performed Key
Description
Cleanup-only
This is an optional key. When the uninstall DLL is called before InstallShield performs the actual uninstallation, the DLL looks for the nocleanup flag on the command line. If the flag is not found, the state of cleanup is considered to be true. When the DLL is called after uninstallation, the user is asked if additional files should be cleaned up. The DLL sets the state of cleanup based on user input. Set this key to true if you want to perform cleanup conditionally based on the nocleanup flag. If set to true, and the state of cleanup is also true, then the actions defined in the section are performed.
Product
This is a required key for user-defined sections “Run-process,” “Filesystem-remove,” “Registry-remove,” and “Registry-value.” This key indicates the product to which an action applies. The only permissible values are: nt-server (refers to the Pervasive.SQL Server product for
Windows) workgroup (refers to the Pervasive.SQL Workgroup
product) nw-server (refers to the Pervasive.SQL Server product for
NetWare) client (refers to the Pervasive.SQL client product) supported-os (see the table entry “Supported-os” below) [all] (refers to all supported operating systems)
If [all] is not used, then each “Product” key is evaluated to ensure its value matches the product being uninstalled.
2-83
Embedding Pervasive.SQL in Your Product Installation
Table 2-7 Keys Used To Test Whether Operations Should be Performed Key
Description
Supported-os
This is a required key for user-defined sections “Run-process,” “Filesystem-remove,” “Registry-remove,” and “Registry-value.” The value assigned to this key can be a section or the predefined value [all]. If [all] is used, then the operations in the section are performed on all operating systems on which the uninstall DLL is running. If [all] is not used, each key in the assigned section must contain the keys “major-version” and “minor-version.” Optionally, the assigned section may include the key “suitemask.” The keys “major-version,” “minor-version,” and “suite-mask” represent values assigned by Microsoft to their operating systems. Refer to Microsoft documentation for how to determine these values. The values specified for the keys must match the values for the operating system on which the DLL is running.
Test
This is an optional key that identifies a test section. See “Test” on page 2-78.
Other Keys The following table lists the additional keys supported in ptksetup.ini (keys not specific to the pre-uninstall section, post-uninstall section, or categorized as a test key.) Table 2-8 Additional Keys Supported in Ptksetup.ini Key
Description
Element
Refers to a value or operator, or used in a test section that returns a value. Element0 is the first element of a test and is used by the uninstall DLL to determine if the section is a test section. Section to which this key applies: “Test” on page 2-78
Is-directory
Accepts a Boolean value. Setting “Is-directory” to true indicates that the “Name” element is a directory, and the uninstall DLL removes the directory. If “Is-directory” is set to false and the “Name” element is a directory, the directory is not removed. Section to which this key applies: “Filesystem-remove” on page 2-76
2-84
Uninstalling the Pervasive.SQL Products
Table 2-8 Additional Keys Supported in Ptksetup.ini Key
Description
Name
Names a file, directory, or a path to a registry key, depending on the type of section in which it is used. Sections to which this key applies: “Run-process” on page 2-75 “Filesystem-remove” on page 2-76 “Registry-remove” on page 2-76 “Test” on page 2-78
Path-name-root
Used to append a user-defined or a pre-defined path to the value for a “Name” key. Sections to which this key applies: “Run-process” on page 2-75 “Filesystem-remove” on page 2-76
Registry-root
Refers to the name of a registry entry root. The only permissible values are: HKEY_CLASSES_ROOT HKEY_CURRENT_USER HKEY_LOCAL_MACHINE HKEY_USERS HKEY_CURRENT_CONFIG
Sections to which this key applies: “Registry-remove” on page 2-76 “Test” on page 2-78
Remove-children
Accepts a Boolean value. Indicates whether to delete registry entries or directories recursively. Sections to which this key applies: “Filesystem-remove” on page 2-76 “Registry-remove” on page 2-76
2-85
Embedding Pervasive.SQL in Your Product Installation
Table 2-8 Additional Keys Supported in Ptksetup.ini Key
Description
Reuse-result
Accepts a Boolean value. If set to true, the uninstall DLL saves the result obtained after the first time a test is evaluated. Subsequent references to the same test section return the saved state. Section to which this key applies: “Test” on page 2-78
Run-directory
Specifies a directory to change to before the uninstall DLL performs the operations in the section. Section to which this key applies: “Run-process” on page 2-75
Run-parameters
Specifies values passed as command line parameters to an executable. The “Name” key specifies the executable. Sections to which this key applies: “Run-process” on page 2-75
Value-name
Refers to all or part of the name for a registry entry value. Section to which this key applies: “Registry-remove” on page 2-76
Using an Uninstall DLL That You Create In addition to using ptksetup.ini, the Pervasive.SQL uninstall DLL performs the following actions:
Stops the database engines Stops and deletes services Deletes the DEMODATA sample database Removes changes from configuration batch files Removes changes to the PATH and CLASSPATH Tests administrative privileges of a user, if required Invokes a user-defined uninstall DLL, if desired
If you need functionality in the uninstall process that is not provided through ptksetup.ini or by the Pervasive.SQL uninstall DLL, you must create your own uninstall DLL.
2-86
Uninstalling the Pervasive.SQL Products
You may then link to and execute functions from your DLL. This is controlled by exporting functions from your DLL and by a key in ptksetup.ini. Export of UninstInitialize and UninstUnInitialize Functions
You must make the functions UninstInitialize and UninstUnInitialize in your DLL available to the Pervasive.SQL uninstall DLL. You do this by exporting the functions as explained in the InstallShield documentation. The following is an example of how the functions are declared as external in the source code of your DLL: extern "C" { LONG N_APIENTRY UninstInitialize(HWND hwndDlg, HANDLE hInstance, LONG lReserved); LONG N_APIENTRY UninstUnInitialize(HWND hwndDlg, HANDLE hInstance, LONG lReserved); }
The Pervasive.SQL uninstall DLL contains functions with the same names that load and execute the functions from your DLL. If the user-defined function UninstInitialize returns a value of –1, the value is immediately returned to the InstallShield uninstaller and the uninstall operation is aborted. Use of UninstallDLL Key
You must provide the path to your DLL in ptksetup.ini. This is accomplished with the use of the UninstallDLL key, which must be listed in the Uninstall section. The path may include path expansion values (see “Path Expansion Values” on page 2-80). The following is an example of using the key: [Uninstall] UninstallDLL=[install-directory]\MyUninsDll.dll
2-87
Embedding Pervasive.SQL in Your Product Installation
Manual File Installations If your installation program does not use InstallShield 5.5, the Pervasive Installation Toolkit can still be helpful. As mentioned in the section entitled “Call-out Installations” on page 2-10, your installation program can spawn a Pervasive.SQL installation that silently installs itself using the parameters specified in the ptksetup.ini file. Any installation program that can execute Windows commands can use this method. If you desire complete control over the installation and do not wish to use InstallShield, you can also manually install the files and perform the configuration steps required to install all or a subset of the Pervasive.SQL components. Note The Pervasive.SQL DLLs in the directory program files\common files\pervasive software shared\pvswcore must be installed as shared DLLs. For these DLLs, increment the usage count by one on install and decrement by one on uninstall.
The Installation Toolkit includes DOS batch files that explain the exact file copy and configuration steps required to install Pervasive.SQL components. These steps can be translated into code in your installation tool of choice. The batch files are documented with comments about what is being done and why. Some commands and configuration steps are documented but do not execute because they cannot be properly run in a DOS command prompt. For instance, environment variable updating is not performed since the changes would not be visible to any process outside of the command prompt. The installation batch files can be found in the c:\pvsw\ptk\manual\ directory. The included DOS batch file examples are: Table 2-9 DOS Batch File Examples
2-88
File
Description
Ntsrv.bat
Installs Pervasive.SQL Server components on Windows
Manual File Installations
Table 2-9 DOS Batch File Examples Nwsrv.bat
Installs Pervasive.SQL Server components on NetWare
Wsg.bat
Installs Pervasive.SQL Workgroup components on Windows
W1clnt.bat
Installs Pervasive.SQL 16-bit requester components
W3clnt.bat
Installs Pervasive.SQL 32-bit requester components
W3util.bat
Installs Pervasive.SQL 32-bit utilities
When creating a complete Pervasive.SQL installation one or more of the DOS batch files must be run. For instance, to duplicate a Pervasive.SQL Server for Windows NT installation like that of our shipped installation programs the following DOS batch files would apply:
Ntsrv.bat W1clnt.bat W3clnt.bat W3util.bat
The included registry file examples are: Table 2-10 Registry examples File
Description
Ntsrv.reg
Sets up the Installation information keys for the NT/2000 server engine.
Odbcclnt.reg
Sets up the ODBC client driver’s keys.
Odbceng.reg
Sets up the ODBC engine driver’s keys.
Wsg.reg
Sets up the Installation information keys for the Workgroup engine.
W3clnt.reg
Sets up the Installation information keys for the 32-bit client.
Nwsrv.reg
Sets up the Installation information for the NetWare server engine.
Pcctools.reg
Adds external tools (additional Pervasive.SQL tools) to PCC.
Note Please see the comments and suggestions in the batch files on how these registry keys should be applied.
2-89
Embedding Pervasive.SQL in Your Product Installation
Performing Simple Installation Customizations The Pervasive.SQL installation programs are designed so that you can perform a variety of basic customizations without having to recompile the programs. You can perform these customizations by editing the file ptksetup.ini. Here are a few of the customizations you can perform by editing the file:
specify overall installation parameters, such as Custom or Typical, whether to create a nested program group on the Start menu, the name of the root Pervasive folder on the Start menu, and so on. specify which utilities and components are installed. specify whether a program group icon is created for each utility, and whether it should be registered with PCC. specify whether to install the online documentation.
The keys and sections in the ptksetup.ini file are commented to help you understand their purpose. Please refer to one of the ptksetup.ini files included with the Installation Toolkit.
2-90
Pkg Layout
Pkg Layout The pkg subdirectory contains the Pervasive.SQL engine, requester, utility, and documentation files. All Pervasive Installation Toolkit compatible installations use this directory structure to construct the InstallShield cabinet file from which files are installed to the user’s disk. The manual installation examples also use the files in this directory structure. You need not concern yourself with the layout and rationale behind the pkg layout. The Installation Toolkit file groups already contain the proper path to obtain the relevant files provided that you have set up your environment variables. See “Environment Variables” on page 2-20. If you wish to limit the size of your data1.cab InstallShield file by not including Pervasive.SQL files you do not plan to install, you should edit the InstallShield project’s file groups. Remove unwanted file groups but do not remove them from pkg. Removing them from pkg and not modifying your InstallShield project causes build errors. In addition, other InstallShield projects that depend on pkg may fail to build.
2-91
Embedding Pervasive.SQL in Your Product Installation
Frequently Asked Questions This section answers some of the most frequently-asked questions about the Toolkit.
“How can I choose the files that get installed with Pervasive.SQL?” on page 2-92 “How can I install MicroKernel (Btrieve) components without ODBC?” on page 2-94 “Where should I install Pervasive.SQL components?” on page 294 “How can I limit the size of my project’s cabinet file?” on page 296
How can I choose the files that get installed with Pervasive.SQL? There are several options for customizing the set of files that get installed by the Pervasive.SQL V8 Installation Toolkit. They include modification of the ptksetup.ini file, programmatically disabling components in InstallShield scripts, and removing files from the InstallShield project IDE file groups. The ptksetup.ini file contains numerous sections of installation options for Pervasive.SQL components. Many of these can be excluded from installation by setting a component’s Install flag to No. For example, if you wish to exclude the Monitor utility from your product’s installation, you should edit the [Monitor] section of ptksetup.ini to look like this: [Monitor] ComponentName=Monitor Icon=Yes Install=No ControlCenter=Yes
When a section’s Install value is set to No, the other values are ignored, so there is no need to change the Icon and ControlCenter values to No. Using ptksetup.ini to exclude certain components from installation works for all forms of embedding, including call-out installations. For more information, see “Performing Simple Installation Customizations” on page 2-90.
2-92
Frequently Asked Questions
The second option for excluding components from an embedded installation is to disable them in your InstallShield scripts. The Installation Toolkit represents all of the definable file sets in the form of file components. Each of these file components has an Installation Toolkit #define label to identify them. Using InstallShield’s ComponentSelectItem() call, any given component can be disabled. Continuing with our example of disabling the Monitor utility, your InstallShield script code in setup.rul would look like: PtkProcessBeforeDataMove(WINSYSDIR, "", "Typical"); // ... Some additional Install code // To disable both 16 and 32-bit versions of Monitor ComponentSelectItem(MEDIA, PTK_COMP_UTILS_MONITOR_WIN16, FALSE); ComponentSelectItem(MEDIA, PTK_COMP_UTILS_MONITOR_WIN32, FALSE); // ... Some additional Install code MoveFileData();
Note that the call to disable the installation of the Monitor utility must take place after the call to PtkProcessBeforeDataMove(), which performs a number of initializations that would undo the operation to turn off the installation of the Monitor component. The third option to exclude certain components from being installed is to remove them from the InstallShield IDE’s file groups. This option is risky, because the Toolkit was not designed to handle all possible cases of missing files. In other words, you should use this technique with caution. Each Installation Toolkit file component is accompanied by one or more file groups, which actually store pointers to the files that are to be installed. Every file located in a file group is included in the _data1.cab file that is generated by the InstallShield build media operation. Some file groups include files that are not required for all situations. For example, the Win32 requesters file group (PTK_REQ_WIN32_BTRV) includes legacy files for compatibility with previous versions of Pervasive products. If you are installing on a machine where you know this will not be an issue, you elect to trim down the file group and save your users some additional disk space. To do this, edit the PTK_REQ_WIN32_BTRV file group from within the InstallShield IDE and delete the “Btcompat.bck” subdirectory located under the “Bin” directory. Now installations of Win32 requesters will take up about 150K less disk space.
2-93
Embedding Pervasive.SQL in Your Product Installation
The technique of removing files from file groups is also useful in reducing the size of _data1.cab file. If your installation is intended only for Win32 machines and you never intend to support the Novell NetWare or Win16 platform, you could delete all files from the NW and WIN16 file groups. Note For safety, removing files from file groups should not be used as the only method to exclude files from an install. In order to ensure proper installation functionality, the removal of files from file groups should be guarded by InstallShield script code or changes to ptksetup.ini to ensure that the installation never attempts to install or configure those files.
How can I install MicroKernel (Btrieve) components without ODBC? The Installation Toolkit scripts are designed to install both the transactional and the relational components together. Many Pervasive.SQL utilities, including the Control Center, rely on ODBC being installed. It is recommended you install ODBC when installing the transactional engine. The only alternative to not installing ODBC is by manually copying the files to the desired directory as highlighted in the section “Manual File Installations” on page 2-88. Simply omit any steps that refer to ODBC and/or the SQL Relational Data Engine (SRDE). Where should I install Pervasive.SQL components? When using the Installation Toolkit default settings the following directories are used (assuming, on Windows machines, that c:\ is the machine’s system drive letter and on NetWare that x: is the first mapped network drive): Table 2-11 Windows NT/2000 Installation Locations
2-94
Type of Component
Default target installation directory
Non-Pervasive system components
c:\winnt\system32\
Pervasive.SQL engine and client components
c:\pvsw\
Frequently Asked Questions
Table 2-11 Windows NT/2000 Installation Locations Type of Component
Default target installation directory
Pervasive.SQL documentation components
c:\program files\common files\pervasive software shared\doc
Pervasive System Analyser components
c:\program files\common files\pervasive software shared\psa
PVSW core components
c:\program files\common files\pervasive software shared\pvswcore
Table 2-12 Windows 9x/ME/XP Installation Locations Type of Component
Default target installation directory
Non-Pervasive system components
c:\windows\system\
Pervasive.SQL engine and client components
c:\pvsw\
Pervasive.SQL documentation components
c:\program files\common files\pervasive software shared\doc
Pervasive System Analyser components
c:\program files\common files\pervasive software shared\psa
PVSW core components
c:\program files\common files\pervasive software shared\pvswcore
Table 2-13 NetWare Installation Locations Type of Component
Default target installation directory
Pervasive.SQL engine components
x:\system\
Pervasive.SQL client, and documentation components
x:\pvsw\
It is recommended that you always install Pervasive.SQL components into the default location. Doing so helps ensure that your Pervasive.SQL-enabled application peacefully coexists with other applications that rely on Pervasive.SQL. The Ptkmerge utility inserts code into your project that already contains function calls that produce an embedded installation that installs Pervasive.SQL to the default location on a Windows
2-95
Embedding Pervasive.SQL in Your Product Installation
machine. If you are producing an installation for NetWare machines you will have to modify the parameters of the PtkProcessBeforeDataMove() function. How can I limit the size of my project’s cabinet file? The Installation Toolkit includes all of the components for installing any Pervasive.SQL product. Unchanged, the InstallShield file components that get included in the built cabinet file may include many files that are not applicable to your installation. Removing them from the cabinet file can significantly cut down the size of the data1.cab file. In this example we’ll exclude the NetWare server components from an installation build which is targeting Windows Workgroup only. 1
Start up the InstallShield IDE and open your project, into which you have already merged the Installation Toolkit.
2
Click the Components tab to view all of the project’s file components.
3
Expand the Ptk component hierarchy to display the Ptk\Engines\NW Server\System component.
4
Double-click the Include in Build field in the right pane and change its value to "No".
5
Perform the same steps for the Ptk\Engines\NW Server\NonSystem
6
component.
Rebuild your project media.
Now your cabinet file should be 1.5 to 2 MB smaller.
2-96
Index C
I
Cabinet file size 2-96 Choosing whether to install each utility 2-90 whether to install online documentation 2-90 Choosing which components to install 2-13 Cleanup functions 2-73 comctl32.dll 2-16 Component location 2-94 Creating a database after installation of Pervasive.SQL 2-31 Customizing a call out installation 2-13 installation, simple 2-90 Start menu program group 2-90
Database creating after installation of Pervasive.SQL 2-31 Documentation online choosing whether to install 2-90 Dynamic binding 2-6
Install path restriction on length 2-3 Installation different types call out or encapsulated 2-10 manual 2-88 scripted or coded 2-20 how to customize 2-13 simple customizations 2-90 Installation toolkit 2-1 call out installations 2-10 installing 2-4 integration methods 2-2 manual installation 2-88 ptksetup.ini 2-90 pkg directory 2-91 Ptksetup.ini 2-90 Smart Components 2-6 Installing only certain files 2-13 Installing the Toolkit 2-4 Installing without ODBC 2-94 InstallShield 5.5 2-1
E
L
Error code clarification 2-6
Limiting files installed 2-92
F
M
Frequently asked questions 2-92 Function reference 2-33
mfc42.dll 2-16 msvcp60.dll 2-16 msvcrt.dll 2-16
D
O OEM Partner Program overview 1-1 product distribution 1-1
Index 1
P Path length restriction on 2-3 Pervasive Install Toolkit API 2-20 calling 2-23 merging with an existing project 2-22 Pervasive product distribution 1-1 Pervasive System Analyzer running during setup 2-32 Pervasive.SQL event logging 2-6 Pervasive.SQL Installation Toolkit 2-1, 2-4 call out installations 2-10 integration methods 2-2 manual installation 2-88 ptksetup.ini 2-90 pkg directory 2-91 Ptksetup.ini 2-90 Smart Components 2-6 Pkg directory 2-91 Program group customizing 2-90 PSA, see Pervasive System Analyzer Ptksetup.ini 2-90
S Setup running PSA during 2-32 Smart Components 2-6 dynamic binding 2-6 error code clarification 2-6 Pervasive.SQL event logging 2-6
T Toolkit 2-1 call out installations 2-10 integration methods 2-2 manual installation 2-88 ptksetup.ini 2-90 pkg directory 2-91 Ptksetup.ini 2-90 Smart Components 2-6
2 Index
Troubleshooting 2-92 cabinet file size 2-96 component location 2-94 Installing without ODBC 2-94 limiting files installed 2-92
U Uninstall DLL, customizing 2-73 UnInstallShield 2-73 Utilities choosing not to install 2-90
W Windows 98 DCOM 2-17
