Pervasive PSQL v11

Getting Started with Pervasive PSQL

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.pervasivedb.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, Pervasive PSQL, 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 2003, Windows 2008, Windows 7, 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.
Sun, Sun Microsystems, Java, all trademarks and logos that contain Sun, Solaris, or Java, are
trademarks or registered trademarks of Sun Microsystems.
All other company and product names are the trademarks or registered trademarks of their
respective companies.
© Copyright 2010 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/).
This product uses the free unixODBC Driver Manager as written by Peter Harvey
([email protected]), modified and extended by Nick Gorham ([email protected]), with
local modifications from Pervasive Software. Pervasive Software will donate their code changes to the
current maintainer of the unixODBC Driver Manager project, in accordance with the LGPL license
agreement of this project. The unixODBC Driver Danager home page is located at
www.unixodbc.org. For further information on this project, contact its current maintainer: Nick
Gorham ([email protected]).
A copy of the GNU Lesser General Public License (LGPL) is included on the distribution media for
this product. You may also view the LGPL at www.fsf.org/licensing/licenses/lgpl.html.
Getting Started with Pervasive PSQL
General Release September 2010
138-004428-001
 Contents

Contents
About This Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi
Who Should Read This Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii
Manual Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii
Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv

1 Welcome to Pervasive PSQL . . . . . . . . . . . . . . . . . . . . . 1-1

A Basic Introduction to Pervasive PSQL v11
About Pervasive PSQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2
Competitive Advantages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2
Relational or Transactional Access . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3
The Pervasive PSQL Transactional Interface . . . . . . . . . . . . . . . . . . . . . . . . 1-4
Benefits of the Transactional Interface . . . . . . . . . . . . . . . . . . . . . . . . 1-4
Transactional Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5
The Pervasive PSQL Relational Interface . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6
Benefits of the Relational Interface . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6
Relational Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6
About the Pervasive PSQL Engines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-8
Pervasive PSQL Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-8
Pervasive PSQL Workgroup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-8
Engine Feature Comparison. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-9
Pervasive PSQL SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-10
Development Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-11

2 Preparing to Install Pervasive PSQL . . . . . . . . . . . . . . . . . 2-1

Preparation Needed for Pervasive PSQL v11 Installation
Installation Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2
Installation Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3
Complete Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3
Custom Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3
Pervasive PSQL v11 Products . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4
Server Engine (64-bit) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4
Server Engine (32-bit) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4
Workgroup Engine (32-bit) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4
Client (64-bit) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5
Client (32-bit) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5
Pervasive PSQL v11 Optional Features . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6
Xtreme I/O (Server 32-bit Only) . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6
Pervasive Access Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6
Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-7
Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8

iii
Contents

Java Runtime Environment (JRE) . . . . . . . . . . . . . . . . . . . . . . . . . . 2-9

Installation Review . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-10
Quick Checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-10
Common Pre-Installation Questions . . . . . . . . . . . . . . . . . . . . . . . . 2-11

3 Upgrading Your Pervasive PSQL Installation for Windows . . . . . 3-1

Considerations for Users Upgrading to Pervasive PSQL v11
Upgrading to Pervasive PSQL v11 From a Previous Version . . . . . . . . . . . . . . . 3-2
Considerations When Upgrading to Pervasive PSQL v11 . . . . . . . . . . . . . 3-2
Common Questions After Upgrading to Pervasive PSQL . . . . . . . . . . . . . . . . 3-4

4 Installing Pervasive PSQL Server for Windows . . . . . . . . . . . 4-1

Instructions for Installing the Pervasive PSQL Server Engine on Windows
Before You Install the Windows Server Engine . . . . . . . . . . . . . . . . . . . . . . 4-2
Platform Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2
Installation Tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2
Installing Pervasive PSQL Server for Windows . . . . . . . . . . . . . . . . . . . . . . 4-4

5 Installing Pervasive PSQL Clients for Windows . . . . . . . . . . . 5-1

Instructions for Installing the Pervasive PSQL Client on Windows
Before You Install the Windows Client Engine . . . . . . . . . . . . . . . . . . . . . . 5-2
Installing the Pervasive PSQL Client for Windows . . . . . . . . . . . . . . . . . . . . 5-3
Installing the BTRBOX Requester . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7
Win32 DOS Box Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7
Understanding Client Requesters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-8
Types of Windows Requesters . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-8
Where To Go From Here . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-9

6 Installing Pervasive PSQL Workgroup for Windows . . . . . . . . . 6-1

Instructions for Installing the Pervasive PSQL Workgroup Engine on Windows
Before You Install the Windows Workgroup Engine . . . . . . . . . . . . . . . . . . . 6-2
Installation Tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2
Installing the Pervasive PSQL Workgroup for Windows . . . . . . . . . . . . . . . . . 6-3
Authorization of Workgroup Key on Vista and Windows 7 . . . . . . . . . . . . 6-6

7 After Installing Pervasive PSQL for Windows . . . . . . . . . . . . 7-1

Answers to Common Post Installation Questions for Pervasive PSQL on Windows
Common Questions After Installing Pervasive PSQL . . . . . . . . . . . . . . . . . . . 7-2
Where To Go From Here . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-5
Uninstalling Pervasive PSQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-6

iv
 Contents

8 Configuring the Workgroup Engine . . . . . . . . . . . . . . . . . . 8-1

Understanding the Available Workgroup Engine Configurations
Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-2
Installation Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-2
Operating System Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-2
When to Use Workgroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-2
What is a Gateway Engine? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-3
Setting Up a Small Client/Server Configuration . . . . . . . . . . . . . . . . . . . . . . 8-5
Setting Up a Peer-to-Peer Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . 8-7
Setting Up a Gateway Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-9
Floating or Fixed Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-9
Working with the Gateway Locator Utility. . . . . . . . . . . . . . . . . . . . . . 8-11
Running the Workgroup Engine as a Service . . . . . . . . . . . . . . . . . . . . . . . . 8-15
Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-15
Stopping the Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-16

9 Configuring Engine Network Communications . . . . . . . . . . . 9-1

How to Set Up Network Communication for Pervasive PSQL Engines
Determining What Kind of Network You Have . . . . . . . . . . . . . . . . . . . . . . 9-2
Database Engine on Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-2
Engine Network Communication Settings . . . . . . . . . . . . . . . . . . . . . . . . . 9-3
Setting Up TCP/IP Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-4
Setting Up SPX Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-6
Setting Up NetBIOS Support (Workgroup only). . . . . . . . . . . . . . . . . . . . . . 9-8
Avoiding Unavailable Protocols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-9

10 Configuring Network Communications for Clients . . . . . . . . . 10-1

How to Configure Network Communications for Your Pervasive PSQL Clients
Client Network Communication Settings. . . . . . . . . . . . . . . . . . . . . . . . . . 10-2
Network Path Formats Supported by Pervasive Requesters . . . . . . . . . . . . . . . . 10-3
Universal Naming Convention (UNC) Path Formats. . . . . . . . . . . . . . . . 10-3
Drive-based Formats. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-8
Linux Path Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-8
Using TCP/IP to Connect to a Windows Server . . . . . . . . . . . . . . . . . . . . . . 10-10
Configuring a Client for the Server IP Address . . . . . . . . . . . . . . . . . . . 10-10
Using SPX to Connect to a Windows Server . . . . . . . . . . . . . . . . . . . . . . . . 10-12
Configuring Pervasive PSQL to use SPX . . . . . . . . . . . . . . . . . . . . . . . 10-12
Changing the Default Communication Ports. . . . . . . . . . . . . . . . . . . . . . . . 10-13
Windows FireWalls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-13
Services File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-14
Using TCP/IP to Connect a Windows Client to a Linux Server . . . . . . . . . . . . . . 10-16
Configuring a Client for the Server’s IP Address . . . . . . . . . . . . . . . . . . 10-16
Data Encoding. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-18
Database Code Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-18

v
Contents

Client Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-19

Encoding Interaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-19
Legacy Conversion Methods for OEM Data . . . . . . . . . . . . . . . . . . . . 10-20
Using the DOS Requester . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-25
Supported Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-25
DOS Box Support on Windows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-26
Running DOS Applications on Windows 32-bit Platforms . . . . . . . . . . . . 10-26

11 Application Configuration Scenarios . . . . . . . . . . . . . . . . . 11-1

Common Scenarios for Setting up Your Database Engine
Terminal Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-2
Disabling Administrative Functions . . . . . . . . . . . . . . . . . . . . . . . . . 11-2
Terminal Server as Network Server . . . . . . . . . . . . . . . . . . . . . . . . . 11-2
Workgroup Engine Running as a Service . . . . . . . . . . . . . . . . . . . . . . 11-3
Active Directory Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-4
Pervasive Administrative Authority . . . . . . . . . . . . . . . . . . . . . . . . . 11-4
Active Directory Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-5
Multiple Client Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-12
Settings Affected by Multiple Applications . . . . . . . . . . . . . . . . . . . . . 11-12
Concurrent Local and Remote Applications . . . . . . . . . . . . . . . . . . . . . . . . 11-14
Using the Server and Workgroup Engines Concurrently . . . . . . . . . . . . . 11-15
Accessing Data on Other Computers . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-17

12 Installing Pervasive PSQL for Linux . . . . . . . . . . . . . . . . . 12-1

Instructions for Installing and Uninstalling Pervasive PSQL on Linux
Before You Install Pervasive PSQL for Linux . . . . . . . . . . . . . . . . . . . . . . . 12-2
Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-2
Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-2
Full Installations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-3
Installing Pervasive PSQL Using RPM . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-4
Installing Pervasive PSQL Server for Linux - RPM . . . . . . . . . . . . . . . . . 12-4
Installing the Pervasive PSQL Client for Linux - RPM . . . . . . . . . . . . . . . 12-6
Installing Pervasive PSQL Using TAR . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-8
Installing Pervasive PSQL Server for Linux - TAR . . . . . . . . . . . . . . . . . 12-8
Installing Pervasive PSQL Client for Linux - TAR . . . . . . . . . . . . . . . . . 12-10
After Installing Pervasive PSQL for Linux . . . . . . . . . . . . . . . . . . . . . . . . . 12-12
Verifying Installed Products With RPM . . . . . . . . . . . . . . . . . . . . . . . 12-12
Verifying Database Engine is Running . . . . . . . . . . . . . . . . . . . . . . . 12-12
Server Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-12
Client Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-12
User Count License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-13
Common Questions After Installation . . . . . . . . . . . . . . . . . . . . . . . 12-13
Uninstalling Pervasive PSQL for Linux. . . . . . . . . . . . . . . . . . . . . . . . . . . 12-17

vi
 Contents

RPM Version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-17

TAR Version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-17

13 Using Pervasive PSQL on Linux . . . . . . . . . . . . . . . . . . . 13-1

Working With the Products on Linux
Finding What You Need . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-2
Accessing the User Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . 13-2
Man Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-2
Exclusions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-2
Pervasive PSQL Account Management on Linux. . . . . . . . . . . . . . . . . . . . . . 13-4
After Installation Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-4
The User Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-4
Using Utilities from Users Other than psql . . . . . . . . . . . . . . . . . . . . . 13-5
Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-6
Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-6
Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-6
Supported Path Formats for Samba . . . . . . . . . . . . . . . . . . . . . . . . . 13-6
Client Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-8
Authentication to Remote Machines . . . . . . . . . . . . . . . . . . . . . . . . . 13-8
Creating a Client DSN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-8
Setting Up Web-based Data Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-9
ODBC Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-9
Configuring Web Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-9
PHP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-10
Perl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-13
Using Perl and ODBC with Pervasive PSQL . . . . . . . . . . . . . . . . . . . . . . . . 13-17
Code Snippet for Perl and DBI . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-17

14 Troubleshooting After Installation . . . . . . . . . . . . . . . . . . 14-1

How to Proceed When You Encounter Errors During Installation
Troubleshooting Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-2
Troubleshooting Strategies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-3
Checklist for Problems. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-3
Troubleshoot the Problem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-3
Configuration for Special Installation Situations . . . . . . . . . . . . . . . . . . . . . . 14-4
Diagnosing Problems with Pervasive System Analyzer (PSA) . . . . . . . . . . . . . . . 14-5
Verifying Database Engine is Running . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-6
Windows Server (Non-Vista) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-6
Windows Workgroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-7
Linux Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-7
Obtaining File, Client, and Engine Version Number. . . . . . . . . . . . . . . . . . . . 14-8
Determining Client and Engine Version . . . . . . . . . . . . . . . . . . . . . . . 14-8
Determining a File Version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-9
Engine and Client Version Conflicts . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-13

vii
Contents

Troubleshooting Common Pervasive PSQL Issues . . . . . . . . . . . . . . . . . . . . 14-14

Issues After Uninstalling Pervasive PSQL on Windows . . . . . . . . . . . . . . . . . . 14-17
How to Get Additional Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-18
Technical Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-18

viii
Figures

5-1 Engine Installation Mode Dialog Box . . . . . . . . . . . . . . . . . . . . . . . . 5-4

6-1 Engine Installation Mode Dialog Box . . . . . . . . . . . . . . . . . . . . . . . . 6-4
8-1 Gateway Locator Main Dialog Box . . . . . . . . . . . . . . . . . . . . . . . . . . 8-12
8-2 Gateway Locator Browse Dialog Box . . . . . . . . . . . . . . . . . . . . . . . . . 8-13
8-3 Gateway Assignment Dialog Box . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-13
8-4 Browse for Computer Dialog Box . . . . . . . . . . . . . . . . . . . . . . . . . . 8-14
14-1 Displaying the Services Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-6
14-2 Selecting the Btrieve Version Info button . . . . . . . . . . . . . . . . . . . . . . 14-8
14-3 Btrieve Version Info Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-9
14-4 Obtaining a File Version with the Pervasive PSQL Control Center . . . . . . . . 14-10
14-5 Table Properties Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-10
14-6 File Statistics in Function Executor . . . . . . . . . . . . . . . . . . . . . . . . . . 14-12

ix
Tables

1-1 Comparison of Server and Workgroup Features . . . . . . . . . . . . . . . . . . . 1-9

3-1 How to Proceed After Installing Workgroup . . . . . . . . . . . . . . . . . . . . . 3-4
7-1 Pervasive PSQL v11 Default Windows Installation Locations . . . . . . . . . . . . 7-2
10-1 IPv6 Unicast Address Formats Supported by Pervasive PSQL. . . . . . . . . . . . 10-4
10-2 IPv6 Restrictions With Pervasive PSQL . . . . . . . . . . . . . . . . . . . . . . . . 10-7
10-3 Interaction Between Database Encoding and Client Encoding . . . . . . . . . . . 10-19
11-1 Summary of Network Configurations . . . . . . . . . . . . . . . . . . . . . . . . . 11-17
12-1 Full and Client Linux Installations. . . . . . . . . . . . . . . . . . . . . . . . . . . 12-3
12-2 Linux Server Package Names - RPM. . . . . . . . . . . . . . . . . . . . . . . . . . 12-4
12-3 Linux Client Package Names - RPM . . . . . . . . . . . . . . . . . . . . . . . . . . 12-6
12-4 Linux Server Package Names - TAR . . . . . . . . . . . . . . . . . . . . . . . . . . 12-8
12-5 Linux Client Package Names - TAR . . . . . . . . . . . . . . . . . . . . . . . . . . 12-10
12-6 RPM Commands To Verify Pervasive PSQL Packages Installed . . . . . . . . . . 12-12
12-7 Primary Directories and Files for Pervasive PSQL Products Installed on Linux . . 12-14
12-8 RPM Commands to Uninstall the Pervasive PSQL Packages . . . . . . . . . . . . 12-17
12-9 TAR Commands to Uninstall the Pervasive PSQL Packages. . . . . . . . . . . . . 12-17
14-1 Pervasive Tools that Assist in Installation and Problem Determination . . . . . . 14-2

x
About This Manual

This manual contains information about installing the Pervasive

PSQL v11 database system. Pervasive PSQL v11 is a complete
database management system, providing the best of both worlds. It
combines a transactional interface designed for high-performance
data handling and improved programming productivity with an
embeddable and scalable relational interface.
This manual also contains information about common installation
issues, general network protocol information, and Pervasive PSQL
v11 optional features.
For information on using Pervasive PSQL utilities, see Pervasive
PSQL User's Guide. For information about configuring the Pervasive
PSQL v11 engine, see Advanced Operations Guide.

xi
About This Manual

Who Should Read This Manual

This manual provides information for users who install and run
Pervasive PSQL v11. This manual is also useful for system
administrators who are responsible for maintaining databases on a
network and for those who are using Pervasive PSQL to develop
server applications.
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 the Community Forum on the Pervasive Software Web
site.

xii
Manual Organization
This manual is arranged in the order of the main installation
sequence. You complete the installation by following the chapters in
order (skipping the chapters that do not apply to your installation
platform). Getting Started With Pervasive PSQL is divided into the
following sections:
„ Chapter 1—Welcome to Pervasive PSQL
This chapter provides a basic introduction to Pervasive PSQL
v11.
„ Chapter 2—Preparing to Install Pervasive PSQL
This chapter discusses important preparations that you should
undertake before attempting to install Pervasive PSQL v11.
„ Chapter 3—Upgrading Your Pervasive PSQL Installation for
Windows
This chapter describes how to upgrade a previous version of
Pervasive PSQL on Windows.
„ Chapter 4—Installing Pervasive PSQL Server for Windows
This chapter describes how to install Pervasive PSQL Server for
the first time.
„ Chapter 5—Installing Pervasive PSQL Clients for Windows
This chapter describes how to install Pervasive PSQL Client for
the first time.
„ Chapter 6—Installing Pervasive PSQL Workgroup for Windows
This chapter describes how to install Pervasive PSQL Workgroup
for the first time.
„ Chapter 7—After Installing Pervasive PSQL for Windows
This chapter answers post installation questions you may have
about Pervasive PSQL for Windows.
„ Chapter 8—Configuring the Workgroup Engine
This chapter describes how to configure the Pervasive PSQL
Workgroup engine.

xiii
About This Manual

„ Chapter 9—Configuring Engine Network Communications

This chapter describes how to configure your network for use
with the Server engine on Windows.
„ Chapter 10—Configuring Network Communications for
Clients
This chapter describes how to configure the client network
settings for use with the PSQL engine. It also offers
implementation notes for specific operating systems.
„ Chapter 11—Application Configuration Scenarios
This chapter describes different application configurations for
special installation scenarios.
„ Chapter 12—Installing Pervasive PSQL for Linux
This chapter describes how to install or upgrade the Pervasive
PSQL Server and Client on Linux.
„ Chapter 13—Using Pervasive PSQL on Linux
This chapter provides information for using Pervasive PSQL on
Linux after you have completed installation.
„ Chapter 14—Troubleshooting After Installation
This chapter provides information on Pervasive PSQL tools that
aid in diagnosing problems. This chapter also gives contact
information for Pervasive PSQL support for the case that you do
not find the answer to your problem.
This manual also contains an index.

xiv
Conventions
Unless otherwise noted, command syntax, code, and examples use
the following conventions:

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.

Bold Words appearing in bold include the following: menu names,

dialog box names, commands, options, buttons, statements,
etc.

Monospaced Monospaced font is reserved for words you enter, such as

font command syntax.

[ ] 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.

xv
About This Manual

xvi
 chapter

Welcome to Pervasive PSQL

1
A Basic Introduction to Pervasive PSQL v11

Thank you for purchasing Pervasive PSQL. We are confident that you
will find this release to be the very best, high performance, low
maintenance database engine on the market.
This chapter contains the following topics:
„ About Pervasive PSQL
„ The Pervasive PSQL Transactional Interface
„ The Pervasive PSQL Relational Interface
„ About the Pervasive PSQL Engines
„ Pervasive PSQL SDK

1-1
Welcome to Pervasive PSQL

About Pervasive PSQL

Pervasive PSQL is a reliable, low-maintenance, high-performance
database management system (DBMS). Thousands of companies
around the world license Pervasive PSQL and distribute it as the
underlying data storage program for their data-intensive software
products. These companies see no reason to build their own DBMS
or license from a competitor once they experience the ease-of-use,
reliability, and value offered by Pervasive PSQL.
No matter whether you received Pervasive PSQL with another
product or purchased it yourself, this section explains a little about
the product and why it is right for you.

Competitive Pervasive PSQL provides a number of advantages over other

Advantages products available on the market. Here are just a few:
„ Lowest total cost of ownership. An independent study conducted
by Aberdeen Group concluded that no major database product
can match Pervasive PSQL's low total cost of ownership. How do
we do it? See the next bullet.
„ No Database Administrator (DBA) required. You can look in the
newspaper any day of the week and see classified ads for Oracle,
Sybase, or SQL Server database administrators, with sky-high
salaries. Pervasive PSQL offers the unique Zero Database
Administrator, or Z-DBA™, architecture. Its easy-to-use tools,
bulletproof installation, and set-it-and-forget-it simplicity make
it the perfect workhorse for desktop, workgroup, and
departmental applications.
„ Scalable from the desktop to the Web. Pervasive PSQL is available
in two editions: the Ultra-light™ Workgroup database engine
supports single-user configurations up to small workgroup
configurations. The Server engine comes with a six-user license
and scales to hundreds of concurrent users, including intranet
and extranet applications. Upgrading to another configuration
requires no changes to the supported application, just plug and
play with the new database engine.

1-2
 About Pervasive PSQL

„ Cross-platform support. Unlike some competitors, Pervasive

PSQL does not lock you in to a single platform. Pervasive PSQL
databases are binary-compatible and supported across
Microsoft Windows and several varieties of Linux. No matter
where your data is or where it is going to be, Pervasive PSQL is
there for you.
„ Big database features at a small price. Pervasive PSQL offers full
security, encryption, management and monitoring tools, and a
host of other features you would expect to see in more expensive
DBMS products.
„ Legendary stability and reliability. There’s no doubt why the
Windows desktop accounting market uses Pervasive PSQL as the
underlying database of choice. When you’ve got to manage
important data, you go for the database engine that won’t let you
down.
„ Multiple access methods. Your application vendor can use the
transactional interface for blazing performance on bulk data
operations, while offering the richness of ODBC, OLE-DB, pure
Java, and JDBC interfaces for data reporting, security, analysis,
and standard compatibility. No other database management
system offers all these access methods.

Relational or Pervasive PSQL offers an architecture that is totally unique in the

Transactional database management market. Our product allows you to access the
Access exact same data through ODBC and OLE DB, supporting
applications like Microsoft ASP, Excel, and Access, or through the
lightning-fast transactional interface called Btrieve. ODBC allows
you to do complex reporting and data mining, while Btrieve
provides massive throughput when you need the ability to view,
update, or create millions of records a day.
Each application vendor chooses which interfaces are used. If you
want to know which access methods are used in your application,
contact your application vendor.

1-3
Welcome to Pervasive PSQL

The Pervasive PSQL Transactional Interface

The Pervasive PSQL transactional interface, built on Btrieve, offers
easy installation, uncomplicated maintenance, and high levels of
performance and reliability. Pervasive PSQL provides a foundation
on which you can run transactional applications or migrate to a
relational database system.

Benefits of the Pervasive PSQL’s transactional interface is Btrieve, which has been
Transactional the data management system of choice for tens of thousands of
Interface applications around the world for more than 25 years now. In the
highly competitive accounting software market—where reliability
and performance are paramount—many of the top 10 vendors
choose Pervasive PSQL. Many application developers choose
Pervasive PSQL for its speed, data integrity, easy scalability, and low
maintenance costs. As part of Pervasive PSQL, Btrieve’s transactional
interface offers:
„ Speed. Pervasive PSQL uses the highly-evolved MicroKernel
Database Engine, capable of sub-second response rates, even
when building multi-gigabyte databases for hundreds of users.
The MicroKernel achieves these high speeds through features
such as internal indexing algorithms that cache pages for fast
data retrieval and updates, and automatic index balancing to
maintain fast data access, even as your files grow.
„ Data Integrity. The MicroKernel guarantees data integrity
through rich transaction processing support, referential
integrity controls, and automatic file recovery. In the event of a
server or system failure, logging features and roll forward
utilities allow you to recover data up to your last completed
transaction.
„ Scalability. Many client/server database applications begin on
the desktop and scale with corporate growth. Pervasive PSQL
provides easy scalability from workstation to large client/server
environments.
„ Low Cost. The low support costs experienced by Pervasive PSQL
developers translate into low maintenance costs realized by
Pervasive PSQL application end users. Pervasive PSQL
eliminates the need for sustained database administration
through automatic data recovery functions and easy-to-use
utilities.

1-4
 The Pervasive PSQL Transactional Interface

Transactional Pervasive PSQL provides a comprehensive transactional database

Features management system that offers many features, including the
following:
„ MicroKernel Database Engine as the underlying data manager.
„ Access to databases distributed across multiple engines.
„ Robust transactions for both single-server systems and
distributed, multi-server systems.

1-5
Welcome to Pervasive PSQL

The Pervasive PSQL Relational Interface

Pervasive PSQL’s relational interface, built on the SQL Relational
Database Engine (SRDE), offers easy installation, uncomplicated
maintenance, and high levels of performance and reliability.

Benefits of the Many relational database application developers choose Pervasive

Relational PSQL because it provides scalability, maintenance-free operation,
Interface and a small memory footprint:
„ Standard Interface. SQL and ODBC provide a well-known and
standardized foundation upon which to build useful
applications.
„ Speed. Pervasive PSQL offers direct ODBC access to the database
engine. Many competitive products use a translation layer to
translate ODBC calls to proprietary “native” relational API calls
that then access the database engine. In contrast, the Pervasive
PSQL ODBC driver calls the database engine directly, without
translating ODBC calls to a proprietary relational API.
„ Scalability. Pervasive PSQL allows you to scale applications from
single-user to large client/server environments without
changing the application or the database.
„ Maintenance-free Operation. Pervasive PSQL is simple to install
and use. It requires no extensive performance setup or ongoing
tuning by a database administrator.
„ Small Memory Footprint. Pervasive PSQL has a small footprint,
requiring only a small amount of memory.

Relational The Pervasive PSQL relational interface provides a flexible

Features architecture that helps you easily scale your database applications
from large client/server systems to single-user environments without
additional coding. Pervasive PSQL offers easy installation,
uncomplicated maintenance, high levels of performance and
reliability, and a smooth migration path for data. In addition,
bundling Pervasive PSQL with your application is easy with the
Pervasive PSQL distribution component, which provides multi-user
and single-user run-time support.

1-6
 The Pervasive PSQL Relational Interface

Pervasive PSQL has a comprehensive relational database

management system interface that offers many features, including
the following:
„ Application scalability from standalone to client/server.
„ Fully functional Workgroup and client/server engines.
„ Declarative Referential Integrity.
„ Bi-directional, updateable, and scrollable cursors.
„ Named database support providing location transparency for
applications.
„ Comprehensive, industry standard data type support.
„ Programming extensions such as triggers and stored procedures.
„ Cost-based optimization from statistical analysis and enhanced
fetch algorithms.
„ Transaction processing enhancements such as full transactional
logging.
„ Standards enhancements, including ODBC support.
„ Other features include additional Windows utilities, large file
support (up to 256 GB), and additional data type variables such
as TIMESTAMP, UNSIGNED, and CURRENCY.

1-7
Welcome to Pervasive PSQL

About the Pervasive PSQL Engines

This section provides some basic information about the Pervasive
PSQL Server and Workgroup engines. For a detailed discussion of
Pervasive PSQL architecture, please refer to Pervasive Products and
Services.

Pervasive The Pervasive PSQL Server database engine is designed to support

PSQL Server up to many hundreds of concurrent network users when installed on
the required hardware. It is capable of supporting web, corporate,
departmental, and other client/server or web-based applications
where reliability and performance are critical.
The Pervasive PSQL Server engine may be installed with license
blocks for 6, 10, 20, 50, 100, 250, 500, or an unlimited number of
users, depending on the number of user licenses you purchased. The
server engine is capable of scaling to hundreds of concurrent users
with the purchase of additional licenses.

Pervasive The Pervasive PSQL Workgroup database engine is designed to

PSQL support single-user or small workgroup installations.
Workgroup Pervasive PSQL Workgroup offers the same level of reliability and
features as the Server engine. The only differences lie in networking
and performance in mid- and large-size environments.
Pervasive PSQL Workgroup offers a flexible approach to accessing
data on remote servers, allowing a variety of small network
configurations. If you have data files on a remote file system with no
database engine present, you can configure Pervasive PSQL
Workgroup so that a particular engine is always used to access the
remote data, or you can set it up so that the first engine to access the
files then “serves” those files until there are no more requests for
data. After this point, again the first engine to access the files then
owns the files while requests are coming in.
A Pervasive PSQL engine cannot be installed on more than one
machine. Your user count license refers to the number of client
connections allowed to that engine, not to the number of machines
to which you are allowed to install the Pervasive PSQL engine. In a
Workgroup environment, every machine that will access Pervasive
PSQL data should have a Workgroup engine installed.

1-8
 About the Pervasive PSQL Engines

Engine Feature All Pervasive database engines offer the same powerful feature set
Comparison and full-functioned support for programming interfaces. The chart
below shows the major differences between the different editions of
the product.
Table 1-1 Comparison of Server and Workgroup Features

Feature Server Workgroup

Supports Btrieve, ODBC, OLE DB, Java, JDBC, PDAC  

and ActiveX interfaces

Full-featured relational support (online backup,  

security, referential integrity, management tools, and
so on)

Binary compatible data files across all platforms and  

engine editions

Easy plug and play upgrading, no application changes  

required to change engines.

Includes complete online documentation  

Can access data on a file server where no database 
engine is installed

Supports remote ODBC client connections  

Requires a Workgroup engine on all computers N/A 
expected to access remote data

Engine runs on Windows  

Engine runs on Linux 
Multi-user for small groups  
Scales to thousands of users 
Extranet license available 
Enforces Operating System Security 

1-9
Welcome to Pervasive PSQL

Pervasive PSQL SDK

The Pervasive PSQL SDK includes many features to ease the burden
of application development. These include:
„ Low-level APIs. Direct programming to the Btrieve API gives
you the fastest possible data access and the most control over the
way in which your application reads and writes data. If these
considerations are important to you and you are willing to
develop the code that incorporates your business rules, you may
find direct API programming highly useful. For relational access
to data, you may also code directly to the Microsoft ODBC API.
„ ODBC. Pervasive PSQL offers a native ODBC driver.
„ Pervasive PSQL ADO.NET data provider. The data provider
provides support for the Microsoft .NET Framework, and is an
ADO.NET managed data provider, built with 100% managed
code.
„ Java. The Java Interface gives you the option of developing
Btrieve applications in an object-oriented, platform-
independent manner. It includes support for true null and
Unicode values as well as for Binary Large Objects (BLOBs).
„ Distributed Tuning Interface and Objects. These two related
interfaces allow applications to tune and manage the database
engine itself, including configuration parameters and aspects of
security.
„ OLE-DB. The OLE-DB provider offers access to both the
relational and transaction interfaces.
„ The ActiveX Interface. The ActiveX Interface allows you to
leverage the power and speed of the Pervasive PSQL engine with
a minimum of manual coding. These controls are designed for
easy use with third-party grid controls as well.
„ Complete sample application. Pervasive PSQL SDK includes a
complete sample application designed to run a video rental
store. Full sample code in Visual Basic, Delphi, Java, and C/C++
is supplied. Examples using ODBC, ActiveX RDO, third party
controls, and direct API calls are shown.
„ The Pervasive PSQL Web site is an online resource that gives you
access to the latest component downloads and code samples.

1-10
 Pervasive PSQL SDK

Development Pervasive PSQL provides an open interface that allows you to

Environment develop many front-end applications, all of which can share a
common, transactional, or relational database. You can use popular
programming languages and environments such as Java, Delphi,
BASIC, Visual BASIC, .NET, C, C++, COBOL, Pascal, ODBC,
PowerBuilder (through ODBC), and FoxPro (through ODBC). In
addition, bundling a Pervasive PSQL engine with your application is
easy with a Derivative Software License.

1-11
Welcome to Pervasive PSQL

1-12
 chapter

Preparing to Install
Pervasive PSQL 2
Preparation Needed for Pervasive PSQL v11 Installation

This chapter prepares you to install Pervasive PSQL v11 by providing

an overview of the requirements, the major components included in
Pervasive PSQL, the installation options available, a detailed
checklist to help you gauge your readiness to proceed with the
Pervasive PSQL v11 installation.
This chapter contains the following sections:
„ Installation Requirements
„ Installation Options
„ Pervasive PSQL v11 Products
„ Pervasive PSQL v11 Optional Features
„ Installation Review

2-1
Preparing to Install Pervasive PSQL

Installation Requirements
This section provides an overview of any special requirements you
may need to know about in order to complete the Pervasive PSQL
v11 installation. The following overview is intended to accompany
the software and hardware requirements listed on the Pervasive
Software web site for Pervasive PSQL v11.

2-2
 Installation Options

Installation Options
On Windows operating systems, Pervasive PSQL v11 offers
Complete and Custom installation options. On Linux distributions,
each major component has its own separate installation.

Complete The Complete installation, which is recommended for most users,

Installation takes default actions for the operations performed during the
installation and installs Pervasive PSQL v11 and all optional features
to the default installation location.

Custom The Custom installation is recommended for users that need control
Installation over their Pervasive PSQL v11 installation. The Custom installation
allows you to install Pervasive PSQL v11, along with only the features
you need, in directory locations you specify.
The following sections describe the Pervasive PSQL v11 products
and optional features you can install using either of the installation
options described here.

2-3
Preparing to Install Pervasive PSQL

Pervasive PSQL v11 Products

Pervasive PSQL v11 is available in a Server, Workgroup (32-bit only)
and Client installations. This section lists each of the Pervasive PSQL
v11 products and the base components inherent to each specific
product installation.

Server Engine „ 64-bit MicroKernel Database Engine (MKDE), which provides

(64-bit) Btrieve/MicroKernel API support for Pervasive PSQL
applications.
„ 64-bit SQL Relational Database Engine (SRDE), which provides
ODBC/SQL API support for Pervasive PSQL applications.
„ 64-bit Client Requesters and required components to access a
MicroKernel engine for Windows or Linux.
„ 32-bit Client Requesters and components needed to access a
MicroKernel engine for Windows or Linux.
„ Pervasive Distributed Tuning Interface (DTI) is used to
configure and monitor the Pervasive components from low-level
(compiled) applications.

Server Engine „ 32-bit MicroKernel Database Engine (MKDE), which provides

(32-bit) Btrieve/MicroKernel API support for Pervasive PSQL
applications.
„ 32-bit SQL Relational Database Engine (SRDE), which provides
ODBC/SQL API support for Pervasive PSQL applications.
„ 32-bit Client Requesters and components needed to access a
MicroKernel engine for Windows or Linux.
„ Pervasive Distributed Tuning Interface (DTI) is used to
configure and monitor the Pervasive components from low-level
(compiled) applications.

Workgroup „ 32-bit MicroKernel Database Engine (MKDE), which provides

Engine (32-bit) Btrieve/MicroKernel API support for Pervasive PSQL
applications.
„ 32-bit SQL Relational Database Engine (SRDE), which provides
ODBC/SQL API support for Pervasive PSQL applications.
„ 32-bit Client Requesters and components needed to access a
MicroKernel engine for Windows or Linux.

2-4
 Pervasive PSQL v11 Products

„ Pervasive Distributed Tuning Interface (DTI) is used to

configure and monitor the Pervasive components from low-level
(compiled) applications.

Note If you have a Workgroup engine running on a 64-bit

machine, and you have 64-bit Btrieve or DTI applications, you
may install both the Workgroup (32-bit) and Client (64-bit)
engines on the same machine.

Client (64-bit) „ 64-bit Pervasive PSQL v10 Client Requesters and required
components to access a MicroKernel engine for Windows or
Linux (Btrieve and DTI only).

Note The Client (64-bit) installation does not include any

utilities or documentation. To install documentation and
utilities, you need to install both the Client (64-bit) and Client
(32-bit) products.

Client (32-bit) „ 32-bit Pervasive PSQL v11 Client Requesters and components
needed to access a MicroKernel engine for Windows or Linux.
„ Pervasive Distributed Tuning Interface (DTI) is used to
configure and monitor the Pervasive components from low-level
(compiled) applications.
„ Pervasive PSQL v11 Cache Engine

2-5
Preparing to Install Pervasive PSQL

Pervasive PSQL v11 Optional Features

During a Custom install, Pervasive PSQL v11 features may be
excluded with the Pervasive PSQL v11 product you are installing.
The features listed here are optional, so if all the features in this
section are excluded from the install, the Pervasive PSQL v11
product is still installed by default.
The following lists the optional features available with each Pervasive
PSQL installation, unless noted otherwise.

Xtreme I/O Xtreme I/O (XIO) is a database accelerator included with Pervasive
(Server 32-bit PSQL v11. XIO increases database performance by accelerating disk
Only) access time for Pervasive PSQL data files. XIO can be installed only
on Windows Server 32-bit platforms meeting the minimum system
requirements for XIO. See System Requirements in Advanced
Operations Guide.

Pervasive Pervasive Access Methods include the Pervasive PSQL v11 Software
Access Developer’s Kit (SDK) and the DOS Requester.
Methods
ActiveX Interface Controls
A set of nine custom controls that enable development environments
that support ActiveX to easily access Btrieve data. The interface
includes a data source control and eight bound data controls.

ADO.NET Provider
ADO.NET is a .NET managed data provider, built with 100%
managed code. The data provider is a native wire protocol provider,
which means that the data provider will not have to call out to
unmanaged code-code outside of the .NET Framework-in the form
of a database client.

Btrieve DOS
The DOS VxD (Virtual eXtended Driver) (DOS client requester) is
the Btrieve requester used for running DOS based applications via a
Windows Command window. (Transactional access only)

2-6
 Pervasive PSQL v11 Optional Features

DTO
The Pervasive Distributed Tuning Objects (DTO) are used from
visual development environments.

JCL
The Java Class Library (JCL) is used for direct transactional access to
data files via Java.

JDBC Driver
The JDBC driver is used for relational access to data files using the
Java programming language.

OLE DB
The OLE DB access method includes runtime binaries used for
transactional and relational access to data files.

PDAC
The Pervasive Direct Access Components (PDAC) includes a set of
Visual Component Library (VCL) components that allow direct
access to Pervasive Database Engines from within the Borland
Delphi and C++ Builder Environments.

Note Design time component and sample downloads will be

available for each access method on the Pervasive Software web
site.

Utilities The minimum set of utilities used to manage, configure and

maintain the various components of the Pervasive PSQL v11
database engines. The utilities included in this base set are installed
as a set for all Pervasive PSQL v11 products and may not be
individually excluded from installation.
„ Monitor
„ Function Executor
„ Btrieve Maintenance
„ Rebuild
„ Query Plan Viewer

2-7
Preparing to Install Pervasive PSQL

„ License Administrator
„ Gateway Locator (Workgroup Engine only)

Cobol Schema Executor

The Pervasive Cobol Schema Executor utility is used for providing
SQL access to COBOL based applications.

Data Dictionary File Builder

Pervasive PSQL Data Dictionary File Builder is used for creating and
modifying Data Dictionary Files (DDFs).

Pervasive Control Center

The Pervasive Control Center is used for creating and manipulating
database objects and accessing database tables via SQL.

Pervasive System Analyzer

The Pervasive System Analyzer utility is used for testing and
troubleshooting network connectivity, viewing loaded modules and
performing a component search.

Documentation The Pervasive PSQL v11 Engine and SDK user documentation is
integrated into Pervasive PSQL Control Center (PCC). The
documentation library is accessed through the PCC interface on the
Welcome view, in the Help menu, by pressing F1 (Windows) or Shift
F1 (Linux). Printed copies of the Pervasive PSQL v11 Engine
documentation may be purchased from Pervasive Software. The
Pervasive PSQL v11 SDK documentation titles are only available
online.

Note If you choose to not install the documentation, context

sensitive (F1) help will be unavailable from all of the Pervasive
PSQL v11 utility graphical user interfaces.

2-8
 Pervasive PSQL v11 Optional Features

Java Runtime The components of the JRE needed by the following features are
Environment installed as part of Pervasive PSQL:
(JRE) „ PCC
„ DDF Builder
„ Core utilities
„ Documentation
The PSQL features use the local version of the JRE installed by
Pervasive PSQL.

Note The installation of a local version of the JRE is for use only
by the Pervasive PSQL features listed above. The local version of
the JRE does not affect the requirements for developing Java
applications using the Pervasive PSQL access methods Java Class
Libraries (JCL) or JDBC. Those requirements, such as
components obtained from java.sun.com, are discussed in the
Pervasive PSQL software development kit (SDK)
documentation. See Java Class Library Guide and JDBC Driver
Guide.

2-9
Preparing to Install Pervasive PSQL

Installation Review
This section provides you with a checklist to prepare you for
installation and a set of commonly asked questions you should
consider prior to installation. Please use this section as a review and
a guide for a successful installation.

Quick Checklist This checklist provides a review of the requirements needed in order
to install Pervasive PSQL v11. Each of these items should be met
prior to beginning the install process.

R Your system hardware meets the minimum requirements to

install Pervasive PSQL v11.

R Your operating system and network environment is supported

by Pervasive PSQL v11.

R You have full administrator-level rights on the system where you

plan to install Pervasive PSQL.

R You understand the different options available in the Complete

and Custom installation setup so you can install only the set of
components you need.

R You have reviewed the release notes in readme.htm on the

installation media for important, late-breaking warnings and
information that could not be included as part of the user
documentation but may be essential to your installation and use
of the product.

R Your application vendor supports the Pervasive PSQL v11

engine.

Tip If you are uncertain, contact your application vendor or

review the documentation provided by your vendor to ensure
that they support the Pervasive PSQL v11 engine version and
mode that you want to install.

2-10
 Installation Review

Windows Vista Checklist

In addition to the items in the Quick Checklist, Windows Vista users
should also have a clear understanding of the differences and
limitations of Standard Users versus Administrators and have the
appropriate permissions to install on Windows Vista.

Common Pre- This section contains some of the most common questions asked
Installation prior to installing Pervasive PSQL v11. These questions represent
Questions special case scenarios that could possibly prevent a successful first-
time installation. Before you begin installation, consider the
situations represented by these questions, along with the Quick
Checklist to determine if you have met all the requirements and if
there are situations that need special attention.

Where do I install the Pervasive PSQL v11 Server?

The Server engine must be installed on the same computer where the
database files are located.

What about the Server’s client software?

The Pervasive PSQL v11 Client is installed with every engine. So if
you have a Pervasive PSQL v11 engine installation, you can use your
machine to connect to other remote engines as a client.
The Pervasive PSQL v11 Client software must be installed on every
computer that is expected to access the database.

Where do I install the Pervasive PSQL v11 Workgroup?

Pervasive PSQL Workgroup can be installed on the same computer
where the database files are located, or it can be installed on other
computers to access the data over the network.

What about the Workgroup’s client software?

The Pervasive PSQL v11 Client (32-bit) is installed with every
engine. If you access remote files through another Workgroup
engine, the client software is already installed, so you do not need to
install the client separately.

2-11
Preparing to Install Pervasive PSQL

How do I install Pervasive PSQL v11 in a Microsoft Cluster

Services environment?
If you plan to install Pervasive PSQL to a clustered environment
using Microsoft Cluster Service, you should first refer to Failover
Cluster Support in the Advanced Operations Guide. That chapter
provides information about installing Pervasive PSQL in a clustering
environment.

How do I install Pervasive PSQL v11 in a Microsoft

Terminal Services or Citrix MetaFrame environment?
If you plan to install Pervasive PSQL to a Microsoft Terminal Server
or Citrix MetaFrame environment, you must be logged on to the
console of the server as a user with system administrator rights to
install. This can either be the physical console on the server or a
remote console session.

Caution If you are installing the Workgroup or Client Engine on

a Terminal Services environment, the engine is installed by
default to run as a service.

Only one instance of the database engine may run on any terminal
server platform. You cannot run separate copies of the database
engine within two or more terminal sessions.
Pervasive PSQL is supported for Server, Workgroup and Client on
the following Terminal Server Environments:
„ Citrix Presentation Server 4.0 (32-bit and 64-bit)
„ Citrix Presentation Server 4.5 (32-bit and 64-bit)
„ Microsoft Windows Server 2003 Terminal Services

Note If a user starts the Workgroup Engine or Cache Engine in

a Terminal Services session or in a multi-user environment
where fast-user switching is used, other users on the system
cannot access that engine nor can they start their own copy of
the engine.

Status code 3032 results if a second user attempts to access

2-12
 Installation Review

another user's engine through the transactional interface.

If it is desirable to have multiple local users accessing a local

engine, install the Workgroup or Cache Engine as a service.

How do I install my Pervasive PSQL v11 database engine

in a Microsoft Active Directory environment?
The installation of the Pervasive PSQL database engine in an Active
Directory environment requires no special steps. Follow the
installation steps as described in this manual for the product you
have purchased.
You may install the Pervasive PSQL database engine on a domain
controller if you choose. Be aware, however, that activity on the
domain controller may affect the performance of the database
engine. For this reason, you may prefer to install Pervasive PSQL on
a server that is not a domain controller.

Where do I install my Pervasive PSQL v11 clients

accessing web applications?
In the case of web applications, the client must be installed on the
same computer as the web server. Multiple web server platforms
require a client on each platform.

Does it matter if I use client requesters that are of a

different version than that of the database engine?
Pervasive recommends that you use client requesters that are the
same version as the database engine. If you choose, you may use a
client requester that is an older version than the database engine with
which it interacts. In some situations, depending on the type of SDK
access method used by your application, an older version requester
will not work with the database engine. Your application will be
unable to communicate with the database engine. For those
situations, you must use client requesters that are the same version as
the database engine.
Client requesters that are a newer version than the database engine
may or may not function correctly. Pervasive does not guarantee that
newer versions of client requesters will function correctly with older

2-13
Preparing to Install Pervasive PSQL

versions of the engine. Therefore, Pervasive recommends that you

avoid the use of newer version client requesters with an older engine.

Will my licenses from older versions of Pervasive PSQL

be migrated to Pervasive PSQL v11?
No, licenses for older versions of the product cannot be migrated to
Pervasive PSQL v11.

Does it matter where I download the Pervasive PSQL v11

install file?
Yes, it does matter. If you are installing a downloaded version of
Pervasive PSQL v11, do not place the install file in a location that is
listed in the PATH environment variables, as this can cause issues
with file copying during install. Place the setup files in a location
such as the Windows TEMP directory.

My system runs 24/7, is any time better than another for

installing or upgrading to Pervasive PSQL v11?
The installation and upgrade should be performed during a period
when all users are logged off the system and all data files are closed.
As with any significant software installation, be sure to back up any
important files on the target hard drive, including data files, before
you begin the installation.
If you are performing an upgrade, keep the installation media and
instructions from the old installation, in the unlikely event that you
need to fall back to the previous version of the product.

How can I restrict users running in Terminal Services

from changing Pervasive PSQL configuration settings,
creating DSNs, and using the Monitor utility?
Pervasive PSQL clients running within Terminal Services client
sessions can perform Pervasive PSQL administrative functions by
default. For example, a user with such a client can change
configuration settings for Pervasive PSQL, create DSNs, and use the
Monitor utility. In prior releases, the ability to perform
administrative functions was prohibited from the client.

2-14
 Installation Review

To restrict this capability, a system administrator should follow these

steps:
1 From PCC, open the properties for the MicroKernel Router
under Local Client.
2 On the Properties dialog, check the option Restrict
Administrative Functions from a WTS Client.
3 Click OK, then exit PCC and start it again for the setting to take
effect.

Are there any special settings I need to make for my

configuration that aren’t listed here?
Yes, there are some default settings in Pervasive PSQL that need to be
adjusted if your configuration includes certain qualities. For
example, the default settings need adjustment if you have:
„ Multiple network interfaces
„ Database Files that must not include Embedded Spaces
„ Microsoft Active Directory Service
„ A Network that is subject to outages
Please review Configuration for Special Installation Situations for
these or other relevant issues, especially if you encounter problems
after installation.

2-15
Preparing to Install Pervasive PSQL

2-16
 chapter

Upgrading Your Pervasive PSQL

Installation for Windows 3
Considerations for Users Upgrading to Pervasive PSQL v11

This chapter contains information about upgrading to Pervasive

PSQL v11 from a supported previous version. The configuration
settings that are migrated during an upgrade from a previous version
to Pervasive PSQL v11 are also detailed in this chapter.
The following sections are included in this chapter:
„ Upgrading to Pervasive PSQL v11 From a Previous Version
„ Common Questions After Upgrading to Pervasive PSQL
Throughout this document, when an explicit version number is not
specified (for example: Pervasive.SQL 7, Pervasive.SQL 2000, or
Pervasive PSQL v11), all versions are included.

3-1
Upgrading Your Pervasive PSQL Installation for Windows

Upgrading to Pervasive PSQL v11 From a Previous Version

If you are upgrading a previous version of Pervasive PSQL to
Pervasive PSQL v11, follow the same procedure as you would if you
were installing for the first time. Pervasive PSQL v11 archives the
previous version of Pervasive PSQL during installation. See Chapter
4, Installing Pervasive PSQL Server for Windows for detailed
installation procedures.
If you are upgrading from older versions such as Pervasive.SQL 2000i
and wish to make use of all the new version features, you must
rebuild your data files so they use the v9.5 file formats. See
Converting Data Files in Advanced Operations Guide for detailed
information on how to use the Rebuild Utilities to convert your data
files.
Licenses from any previous Pervasive products will not be migrated
to Pervasive PSQL v11.

Considerations Once you have reviewed the latest product information, review this
When list of considerations to complete your upgrade installation
Upgrading to preparation.
Pervasive
PSQL v11 R Pervasive PSQL Applications - Be aware of what applications you
have currently using previous versions of Btrieve or Pervasive
PSQL in your environment. Don’t forget to include both client
and server-based applications, such as ArcServe.

R Vendor-Specific Information - Check with your application

vendors for any specific information regarding their product
with Pervasive PSQL.

R TCP/IP Protocol - Make sure that your TCP/IP network is

configured correctly (you should be able to PING the server by
name), and that any firewalls between the clients and server
(including firewalls on those computers) are configured to pass
database traffic. See Windows FireWalls.

3-2
 Upgrading to Pervasive PSQL v11 From a Previous Version

R DOS Requester - DOS applications are only supported via the

BTRBOX requester. Native DOS machines should be migrated
to a Win32 platform before upgrading. DOS applications are not
supported on 64-bit Windows platforms. Therefore, BTRBOX is
not supported on 64-bit Windows platforms.

R New Features and File Rebuilding - In order to make use of all the
new version features, you must rebuild your data files so that
they use the newest version file format. Advanced Operations
Guide includes a chapter that details using the Rebuild Utility to
rebuild your data files.

R Back Up Data Files - Make sure you have a current backup of all
your data, database engine files and configuration prior to
beginning upgrade installation

3-3
Upgrading Your Pervasive PSQL Installation for Windows

Common Questions After Upgrading to Pervasive PSQL

This section contains information that you should read after
running the installation program. If you are having problems with
your installation, go to Chapter 14, Troubleshooting After
Installation, or get help online from the Knowledge Base at the
Pervasive Software website.

How to Handle Data Source Names (DSNs)

The following table describes the procedures for upgrading your
DSNs after you have installed the Pervasive PSQL upgrade.
Table 3-1 How to Proceed After Installing Workgroup

If your situation is like this . . . . . . then you should do this next:

You have existing You must delete all existing Pervasive.SQL 7

Pervasive.SQL 7 DSNs already DSNs before you upgrade. Once you have
defined. upgraded, re-create the DSNs to access the
existing databases. Follow the instructions
provided in Pervasive PSQL User's Guide
Chapter 2, sections Deleting DSNs and Setting
Up Database Access on Windows.

You have existing You should be able to access your databases by

Pervasive.SQL 2000 DSNs connecting to the existing DSNs. Follow the
already defined. instructions provided in Pervasive PSQL User's
Guide, Chapter 2, section Accessing Data via
ODBC From Other Applications.

You do not have any Pervasive You should be able to connect to the sample
PSQL DSNs defined DEMODATA database now. Refer to Pervasive
PSQL User's Guide for general information on
working with Pervasive PSQL. Refer to
Advanced Operations Guide for detailed
information on working with databases and
database engines.

How Do I Convert My Files From Previous Pervasive

Products?
Converting your data files to 9.x format is not required, but you must
convert them if you wish to take advantage of new features offered by
the Pervasive PSQL v11 engine.

3-4
 Common Questions After Upgrading to Pervasive PSQL

Users of previous Btrieve versions: Use the Rebuild utility to convert

your existing pre-6.0 or 6.x files to 7.x, 8.x, or 9.x format. For more
information, refer to the Advanced Operations Guide.

What User License Was Installed with Pervasive PSQL?

A trial license is installed if you leave the license number blank
during installation.
There is no configuration necessary for the license. After installation,
you can use the License Administrator utility to view your installed
licenses. See the Pervasive PSQL User's Guide for more information
on the License Administrator utility.

3-5
Upgrading Your Pervasive PSQL Installation for Windows

3-6
 chapter

Installing Pervasive PSQL

Server for Windows 4
Instructions for Installing the Pervasive PSQL Server Engine on Windows

This chapter contains procedures for installing and running

Pervasive PSQL v11. The chapter contains the following sections:
„ Before You Install the Windows Server Engine
„ Installing Pervasive PSQL Server for Windows

4-1
Installing Pervasive PSQL Server for Windows

Before You Install the Windows Server Engine

Before installing Pervasive PSQL v11, begin by reviewing the
following documents:
„ Chapter 2, Preparing to Install Pervasive PSQL - This chapter
provides important information, including system requirements
and platform specific notes, relevant to your operation.
„ Release Notes - The release notes are located in readme.htm on
the distribution media and contain late-breaking news that
could not be included in the user documentation.

Platform Notes This section contains installation information specific to the

Windows platform.
„ To install Pervasive PSQL for Windows, you must have full
administrator-level rights on the machine where you will install
Pervasive PSQL.

Installing the Engine on Terminal Server

To install Pervasive PSQL on a terminal server, you must be logged
on to the console of the server as a user with system administrator
rights to install. This can either be the physical console on the server
or a remote console session.
Install Pervasive PSQL as you normally would, using the steps
discussed in this manual. The operating system automatically
handles the changing of terminal server modes.

Running the Engine on Terminal Server

Only one instance of the database engine may run on any terminal
server platform. You cannot run separate copies of the database
engine within two or more terminal sessions.

Installation „ When installing Pervasive PSQL v11 for the first time on a
Tips system, Setup checks if all of the needed system files meet the
minimum requirements. In some cases, these files are locked by
the operating system and a reboot is required before Setup can
continue.

4-2
 Before You Install the Windows Server Engine

Caution You must reboot your system if you encounter the

reboot message. If you do not reboot your system, Setup
encounters failures during engine and utilities configuration.

„ If you have any trouble with the following installation, see

Chapter 14, Troubleshooting After Installation.

4-3
Installing Pervasive PSQL Server for Windows

Installing Pervasive PSQL Server for Windows

You must install the Pervasive PSQL Server for Windows at the server
itself; you cannot install it remotely from a client machine.

Note If the installation fails for any reason, the installation log
file can be found in the Windows %Temp% directory.

The following steps explain how to install Pervasive PSQL Server

from its media using the default interactive installation.

³ To install Pervasive PSQL Server for Windows

1 Launch the installation program from your Windows machine.
a. Insert the Pervasive PSQL Server for Windows CD in the
CD-ROM drive of your Windows server.
b. If the installation does not start automatically, click Start
then Run, and type drive:\autorun\autorun where
drive is the drive letter of your CD-ROM device.

The installation selection dialog displays.

2 Click Server installation for the desired bit architecture (32-bit
or 64-bit).
The installation program begins its initial preparation. After the
preparation completes, the Welcome screen appears.
3 If prompted, close or uninstall any running applications that
may interfere with the Pervasive PSQL installation.

Note If you wish to leave one or more programs running that

may interfere, you must click Ignore to continue. Unpredictable
results may occur during the Pervasive PSQL installation if you
ignore programs that may interfere.

4 At the Welcome screen, click Next.

4-4
 Installing Pervasive PSQL Server for Windows

5 On the License Agreement page, read and accept the Software

License Agreement, then click Next.
6 Select the setup type: Complete (default) or Custom.
The Complete setup (recommended for most users) installs all
the Pervasive PSQL v11 components using the default options
and locations.
Š If you choose a Complete install, click Next and continue
with step 10.
The Custom setup (recommended for advanced users) allows
you to specify the installation location, select the optional
features and associated subfeatures to install, and determine the
space requirements for the components.
Š If you choose Custom, click Next and continue with the
following steps.
7 To specify different installation locations, click Change for any of
the folders listed, then enter or browse for a different folder.
Click OK to accept the location.
8 Click Next to continue.
9 Select the optional features and associated subfeatures you want
to exclude from the installation and click Next. All of the
Pervasive PSQL optional features and subfeatures, except for
Xtreme I/O, are selected for installation by default.
„ Xtreme I/O
(This feature is only available on Windows 32-bit Server
platforms meeting system requirements)
„ Data Access
Š ActiveX Interface Controls
Š ADO.NET Providers
Š Btrieve DOS (32-bit only)
Š DTO
Š JCL
Š JDBC Driver
Š OLE DB
Š PDAC
„ Utilities

4-5
Installing Pervasive PSQL Server for Windows

Š Java Utilities
Š Pervasive Control Center
Š Documentation
Š Data Definition File Builder
Š Other Utilities
Š Cobol Schema Exec
Š Pervasive System Analyzer
10 Click Install to begin installation.
11 A dialog displays when the installation wizard completes. The
product has been installed with a trial key that expires at the end
of its trial period.
You have two choices at this point: continue and authorize the
product with a permanent key, or end the installation (and later
authorize the product with a permanent key).
Š If you choose to continue and authorize the product, an
Internet connection is required. Click Next and continue
with step 12. (If you have no Internet connection, click Next
then click Finish. See Alternative Authorization Tasks in in
Pervasive PSQL User's Guide.)
Š If you choose to end the installation at this point, click Next
then click Finish. (You may run the License Administrator
utility at a later time to apply a key. See License
Administration in Pervasive PSQL User's Guide.)
12 Enter your license key and click the button to apply the key.
(If you decide not to authorize the product at this point, click
Finish. You may run the License Administrator utility at a later
time to apply a key. See License Administration in Pervasive
PSQL User's Guide.)
13 A message box displays with the status of the authorization
action. Perform one of the following actions depending on the
status:
Š If the authorization status message is “key is authorized,”
click OK, then click Finish to complete the installation.
Š If the authorization status message reports an error or
warning, click OK, and repeat step 12, ensuring that you
enter a valid license key.

4-6
 Installing Pervasive PSQL Server for Windows

14 Register your product (recommended) as explained on the

Registration page that displays, then close the Registration page.
If you are prompted to reboot your system, please do so in order
to ensure proper operation of your Pervasive PSQL v11 product.

Note The installation program modifies some of the

environment variables. On Windows platforms, environment
variables are stored in the Control Panel under System
information.

4-7
Installing Pervasive PSQL Server for Windows

4-8
 chapter

Installing Pervasive PSQL

Clients for Windows 5
Instructions for Installing the Pervasive PSQL Client on Windows

This chapter contains the following topics:

„ Before You Install the Windows Client Engine
„ Installing the Pervasive PSQL Client for Windows
„ Installing the BTRBOX Requester
„ Understanding Client Requesters
„ Where To Go From Here

5-1
Installing Pervasive PSQL Clients for Windows

Before You Install the Windows Client Engine

This section contains information with which you need to be
familiar to successfully install Pervasive PSQL. If you have not
already, review the following documents before installing Pervasive
PSQL client requesters:
„ Chapter 2, Preparing to Install Pervasive PSQL - This chapter
provides important information, including system requirements
and platform specific notes, relevant to your operation.
„ Release Notes - The release notes are located in readme.htm on
the distribution media and contain late-breaking news that
could not be included in the user documentation.

5-2
 Installing the Pervasive PSQL Client for Windows

Installing the Pervasive PSQL Client for Windows

You must install the Pervasive PSQL Client for Windows at the client
machine itself; you cannot install it remotely from a server machine.
The Pervasive PSQL Client is installed by default with the Server and
Workgroup engines; a separate installation is no longer necessary.

Note If the installation fails for any reason, the installation log
file can be found in the Windows %Temp% directory.

The following steps explain how to install Pervasive PSQL Client

from its media using the default interactive installation.

³ To install Pervasive PSQL Client for Windows

1 Launch the installation selection program from your Windows
machine.
a. Insert the Pervasive PSQL product CD in the CD-ROM
drive of your Windows server.
b. If the installation does not start automatically, click Start
then Run, and type drive:\autorun\autorun where
drive is the drive letter of your CD-ROM device.

The installation selection dialog displays.

2 Click Client installation for the desired bit architecture (32-bit
or 64-bit).
The installation program begins its initial preparation. After the
preparation completes, the Welcome screen appears.
3 If prompted, close or uninstall any running applications that
may interfere with the Pervasive PSQL installation.

Note If you wish to leave one or more programs running that

may interfere, you must click Ignore to continue. Unpredictable
results may occur during the Pervasive PSQL installation if you
ignore programs that may interfere.

4 At the Welcome screen, click Next.

5-3
Installing Pervasive PSQL Clients for Windows

5 For the 32-bit Client only, select the engine installation mode ():
Run as an Application (default) or Run as a Service.
Figure 5-1 Engine Installation Mode Dialog Box

Caution Running the engine as a service requires the Log On as

Service privilege. If you select to run the engine as a service
under a user account other than the default Local System
account, you will need to modify the Log On Properties for the
Service using the Windows Control Panel.

6 On the License Agreement page, read and accept the Software

License Agreement, and then click Next.
7 Select the setup type: Complete (default) or Custom.
The Complete setup (recommended for most users) installs all
the Pervasive PSQL v11 components using the default options
and locations.
Š If you choose a Complete install, click Next and continue
with step 11.
The Custom setup (recommended for advanced users) allows
you to specify the installation location. For the 32-bit client only,
you may also select the components and associated subfeatures
to install, and determine the space requirements for the
components.
Š If you choose Custom, continue with the following steps.
8 To specify different installation locations, click Change for any of
the folders listed, click Change for any of the folders listed, then
enter or browse for a different folder. Click OK to accept the
location.
9 Click Next to continue.

5-4
 Installing the Pervasive PSQL Client for Windows

10 For the 32-bit client only, select the components and associated
subfeatures you want to exclude from the installation and click
Next. All of the Pervasive PSQL components and subfeatures are
selected for installation by default.
Š Pervasive Control Center
Š Documentation
Š Data Access
Š ActiveX Interface Controls
Š ADO.NET Provider 2.1
Š ADO.NET Provider 3.0
Š Btrieve DOS
Š DTO
Š JCL
Š JDBC Driver
Š OLE DB
Š PDAC
Š Utilities
Š Cobol Schema Exec
Š Data Definition Builder
Š Pervasive System Analyzer

Note The Client 64-bit installation does not include the utilities,
documentation, or SDK components listed above. To install
them, you need to install both the Client 64-bit and Client 32-bit
products.

11 Click Install to begin installation.

12 Once the installation is complete, the final dialog of the
Installation Wizard displays. Click Finish.
If you are prompted to reboot your system, please do so to
ensure proper operation of your Pervasive PSQL v11 product.

5-5
Installing Pervasive PSQL Clients for Windows

Note The installation program modifies some of the

environment variables. On Windows platforms, environment
variables are stored in the Control Panel under System
information.

5-6
 Installing the BTRBOX Requester

Installing the BTRBOX Requester

Pervasive PSQL v11 supports DOS Btrieve applications with the
BTRBOX requester for Windows platforms. Use this Requester for
legacy DOS applications.
A separate installation is no longer needed for the DOS Requester.
The DOS Requester is automatically installed during a complete
Pervasive PSQL v11 engine installation. In the case of a Custom
installation, you must select the Btrieve DOS optional feature in the
Pervasive Access Methods group to install the DOS Requester.

Note Clients using the DOS operating system will have only
transactional access to the data files. No relational access is
available for this platform.

Win32 DOS Box BTRBOX allows a DOS application to run in a DOS box on a
Support Windows workstation. This enables direct communication to the
Windows 32-bit workstation components rather than to the
database engine. This configuration can be used with either a local
Pervasive PSQL v11 Workgroup engine, or a remote Pervasive PSQL
v11 server engine. The TCP/IP or SPX protocol supported for client/
server access depends on the configuration of the Windows 32-bit
components.
DOS applications are not supported on 64-bit Windows platforms.
Therefore, BTRBOX is not supported on 64-bit Windows platforms.

5-7
Installing Pervasive PSQL Clients for Windows

Understanding Client Requesters

A workstation that needs to access database files is considered a client
to the machine running the Pervasive PSQL Server. A piece of
software called a client requester, or requester for short, is required
to access database files from a Pervasive PSQL database server. Your
application’s Pervasive PSQL calls go through the requester, which
sends them to the Pervasive PSQL Server for processing and then
returns the reply to your application.
Refer to the release notes provided with the product for a list of the
platforms on which Pervasive PSQL requesters are supported. The
requesters use the TCP, SPX or NetBIOS protocols to communicate
with the server MicroKernel, depending on the type of server you
have. Ensure that your workstation has the appropriate network
protocol software installed.

Note Clients using DOS operating systems will have only

transactional access to the data files. No relational access is
available for this platform.

Types of Pervasive PSQL includes the following types of requesters for

Windows Windows:
Requesters „ DOS
„ Trace
You do not load or unload the Requester explicitly; the system loads
the Requester with the first application call to Pervasive PSQL and
unloads the Requester when you exit your application.

DOS Requesters
This type of requester is used for applications that run under the
DOS operating system.

Trace Requesters
Trace requesters are used for troubleshooting (tracing) client
problems at a low level. Generally, you will never need to perform
this type of tracing. The low-level tracing is intended for use by

5-8
 Understanding Client Requesters

trained support staff. Your product vendor or Pervasive Software

Support will direct you on how to conduct low-level client tracing,
which includes how to use the trace requesters.
Note that the tools provided with Pervasive Software solve most
troubleshooting issues. For example, you would run the network
connectivity tests in Pervasive System Analyzer to verify network
connectivity. Also at your disposal is the Knowledge Base at the
Pervasive Software website, through which you may search for
information about particular client issues.

Where To Go A proper configuration is essential to smooth operation of your

From Here requester software. See Chapter 10, Configuring Network
Communications for Clients for detailed information on how to
configure Pervasive PSQL requesters.

5-9
Installing Pervasive PSQL Clients for Windows

5-10
 chapter

Installing Pervasive PSQL

Workgroup for Windows 6
Instructions for Installing the Pervasive PSQL Workgroup Engine on Windows

This chapter contains procedures for installing the Pervasive PSQL

v11 Workgroup engine. The chapter contains the following sections:
„ Before You Install the Windows Workgroup Engine
„ Installing the Pervasive PSQL Workgroup for Windows

6-1
Installing Pervasive PSQL Workgroup for Windows

Before You Install the Windows Workgroup Engine

Before installing Pervasive PSQL v11 Workgroup, begin by reviewing
the following documents for important information:

R Chapter 2, Preparing to Install Pervasive PSQL - This chapter

provides important information including system requirements and
platform specific notes that are relevant to your operation.

R Release Notes - The release notes are located in readme.htm on the

distribution media and contain late-breaking news that could not be
included in the user documentation.

Installation „ When installing Pervasive PSQL v11 for the first time on a
Tips system, Setup will check if all of the needed system files meet the
minimum requirements. In some cases, these files are locked by
the operating system and a reboot is required before Setup can
continue. Click Yes to reboot the system. Setup is then
automatically restarted.
„ It is strongly recommended that you reboot your system if you
encounter this message. If you do not reboot your system, Setup
will encounter failures during engine and utilities configuration.
„ If you have any trouble with the following installation, see
Chapter 14, Troubleshooting After Installation.

6-2
 Installing the Pervasive PSQL Workgroup for Windows

Installing the Pervasive PSQL Workgroup for Windows

Note If the installation fails for any reason, the installation log
file can be found in the Windows %Temp% directory.

The following steps explain how to install Pervasive PSQL

Workgroup from its media using the default interactive installation.

³ To install Pervasive PSQL Workgroup for Windows

1 Launch the installation program from your Windows
workstation:
a. Insert the Pervasive PSQL v11 Workgroup CD in the CD-
ROM drive of your Windows workstation.
b. If the installation does not start automatically, click Start,
select Run, and type drive:\autorun\autorun where
drive is the drive letter of your CD-ROM device.

The installation selection dialog displays.

2 Click Workgroup installation.
The installation program begins its initial preparation. After the
preparation completes, the Welcome screen appears.
3 If prompted, close or uninstall any running applications that
may interfere with the Pervasive PSQL installation.

Note If you wish to leave one or more programs running that

may interfere, you must click Ignore to continue. Unpredictable
results may occur during the Pervasive PSQL installation if you
ignore programs that may interfere.

4 At the Welcome screen, click Next.

5 On the License Agreement page, read and accept the Software
License Agreement, and then click Next.
6 Select the Workgroup Engine installation mode: Run as an
Application (default) or Run as a Service.

6-3
Installing Pervasive PSQL Workgroup for Windows

Figure 6-1 Engine Installation Mode Dialog Box

Caution Running the engine as a service requires the Log On as

Service privilege. If you select to run the engine as a service
under a user account other than the default Local System
account, you will need to modify the Log On Properties for the
Service using the Windows Control Panel.

7 Select the setup type: Complete (default) or Custom.

The Complete setup (recommended for most users) installs all
the Pervasive PSQL v11 components using the default options
and locations.
Š If you choose a Complete install, click Next and continue
with step 11.
The Custom setup (recommended for advanced users) allows
you to specify the installation location, select the components
and associated subfeatures to install, and determine the space
requirements for the components.
Š If you choose Custom, click Next and continue with the
following steps.
8 To specify different installation locations, click Change for any of
the folders listed, then enter or browse for a different folder.
Click OK to accept the location.
9 Click Next to continue.
10 Select the components and associated subfeatures you want to
exclude from the installation and click Next. All of the Pervasive
PSQL components and subfeatures are selected for installation
by default.
„ Data Access

6-4
 Installing the Pervasive PSQL Workgroup for Windows

Š ActiveX Interface Controls

Š ADO.NET Providers
Š Btrieve DOS (32-bit only)
Š DTO
Š JCL
Š JDBC Driver
Š OLE DB
Š PDAC
„ Utilities
Š Java Utilities
Š Pervasive Control Center
Š Documentation
Š Data Definition File Builder
Š Other Utilities
Š Cobol Schema Exec
Š Pervasive System Analyzer
11 Click Install to begin installation.
12 A dialog displays when the installation wizard completes. The
product has been installed with a trial key that expires at the end
of its trial period.
You have two choices at this point: continue and authorize the
product with a permanent key, or end the installation (and later
authorize the product with a permanent key).
Š If you choose to continue and authorize the product, an
Internet connection is required. Click Next and continue
with step 13. (If you have no Internet connection, click Next
then click Finish. See Alternative Authorization Tasksin in
Pervasive PSQL User's Guide.)
Š If you choose to end the installation at this point, click Next
then click Finish. (You may run the License Administrator
utility at a later time to authorize a key. See License
Administration in Pervasive PSQL User's Guide.) See also
Authorization of Workgroup Key on Vista and Windows 7.
13 Enter your license key and click the button to apply the key.

6-5
Installing Pervasive PSQL Workgroup for Windows

(If you decide not to authorize the product at this point, click
Finish. You may run the License Administrator utility at a later
time to authorize a key. See License Administration in Pervasive
PSQL User's Guide.))
14 A message box displays with the status of the authorization
action. Perform one of the following actions depending on the
status:
Š If the authorization status message is “key is authorized,”
click OK, then click Finish to complete the installation.
Š If the authorization status message reports an error or
warning, click OK, and repeat step 13, ensuring that you
enter a valid license key.
15 Register your product (recommended) as explained on the
Registration page that displays, then close the Registration page.
If you are prompted to reboot your system, please do so in order
to ensure proper operation of your Pervasive PSQL v11 product.

Note The installation program modifies some of the

environment variables. On Windows platforms, environment
variables are stored in the Control Panel under System
information.

Authorization You can encounter difficulty authorizing a permanent key for

of Workgroup Pervasive PSQL Workgroup on Windows Vista or Windows 7 if the
Key on Vista following conditions are all true:
and Windows 7 „ Pervasive PSQL Workgroup was installed as an application.
„ The Workgroup database engine is running without
administrative privileges. Note that, by default, applications run
with privileges of a standard user unless the privileges are
elevated. That is, even if you are a member of the administrator’s
group and you start the Workgroup database engine without using
Run as Administrator to elevate privileges, the engine runs with
privileges of a standard user.
„ A permanent key for Pervasive PSQL Workgroup was not
supplied during the installation process. That is, you chose to
authorize the permanent key after installation by using a
licensing utility.

6-6
 Installing the Pervasive PSQL Workgroup for Windows

Complete the following steps to ensure a permanent key is correctly

authorized:
1 If the Pervasive PSQL Workgroup application is running, close
the application (stop the database engine by right-clicking on
the engine tray icon then clicking stop).
2 From File Explorer, locate the file w3dbsmgr.exe. Look for the
file under <install_drive>\Program Files\Pervasive
Software\PSQL\bin.
3 Right-click w3dbsmgr.exe then click Run as Administrator. You
must have administrative rights or know the password and name
of a user with administrative rights. You need to elevate the
privileges of the database engine before authorizing a key with a
licensing utility.
4 Start License Administrator from the Pervasive group in the
Start menu (or use the command line interface licensing utility
if you prefer).
5 Type, or paste, the permanent key for Pervasive PSQL
Workgroup in the Key field, then click the button to apply the
key.
6 Optionally, stop the database engine and re-start it without
elevated privileges.
Note that elevating the privileges for a license administrator utility is
not the solution. The database engine itself, w3dbsmgr.exe, is what
requires elevated privileges.

6-7
Installing Pervasive PSQL Workgroup for Windows

6-8
 chapter

After Installing Pervasive

PSQL for Windows 7
Answers to Common Post Installation Questions for Pervasive PSQL on Windows

The chapter contains the following sections:

„ Common Questions After Installing Pervasive PSQL
„ Uninstalling Pervasive PSQL

7-1
After Installing Pervasive PSQL for Windows

Common Questions After Installing Pervasive PSQL

This section contains information that you should read after
running the installation program. If you are having problems with
your installation, go to Chapter 14, Troubleshooting After
Installation, or get help online from the Knowledge Base at the
Pervasive Software website.

What happened to PVSW\BIN on Windows platforms?

Starting with Pervasive PSQL v10, files are no longer installed to
<drive>:\pvsw\bin on Windows platforms. This change comes as
Pervasive PSQL adapts to suggested guidelines from Microsoft.

Where are the Pervasive PSQL files installed?

Table 7-1 lists the default locations where Pervasive PSQL installs the
program and application data files on Windows platforms. Table 12-
7 lists similar information for Linux platforms.
Table 7-1 Pervasive PSQL v11 Default Windows Installation Locations

Platform File Types Default Installation Location

Windows Vista Application <drive:>\ProgramData\Pervasive Software\PSQL\

and later1 (64-bit) Data

Program Files <drive:>\Program Files\Pervasive Software\PSQL\

(64-bit)

Program Files <drive:>\Program Files (x86)\Pervasive Software\PSQL\

(32-bit)

Windows pre- Application <drive:>\Documents and Settings\All Users\Application Data\Pervasive

Vista2 (64-bit) Data Software\PSQL\

Program Files <drive:>\Program Files\Pervasive Software\PSQL\

(64-bit)

Program Files <drive:>\Program Files (x86)\Pervasive Software\PSQL\

(32-bit)

Windows Vista Application <drive:>\ProgramData\Pervasive Software\PSQL\

and later1 (32-bit) Data

Program Files <drive:>\Program Files\Pervasive Software\PSQL\

7-2
 Common Questions After Installing Pervasive PSQL

Table 7-1 Pervasive PSQL v11 Default Windows Installation Locations

Platform File Types Default Installation Location

Windows pre- Application <drive:>\Documents and Settings\All Users\Application Data\Pervasive

Vista2 (32-bit) Data Software\PSQL\

Program Files <drive:>\Program Files\Pervasive Software\PSQL\

Note: The DOS Requester files are installed by default on all Windows platforms at
<drive:>\%WINDIR%\SYSTEM32\
1
Windows Vista and later refers to Windows Vista and any Windows operating system released after
Windows Vista that is currently supported by Pervasive PSQL.
2
Windows pre-Vista refers to any Windows operating system currently supported by Pervasive PSQL that
was released prior to Windows Vista.

What is an Application Data file?

Application data files are typically files to which the system can write.
Examples of Application Data files include log files, tutorial files, and
sample database files, such as DEMODATA and TEMPDB.

What is a Program File?

Program files are typically files the system requires in order to
function. Examples of program files include binary system files,
executable files, dynamic link libraries and JAR files.

What is the difference between 32-bit and 64-bit Program

Files?
Microsoft guidelines recommend that 64-bit components are
installed in a separate location to 32-bit components. Pervasive
PSQL 64-bit components are installed in the 64-bit program files
location and are registered in the Windows registry under the 64-bit
hive. 32-bit components are installed in the 32-bit program files
location and are registered in the Windows registry under the 32-bit
(x86) hive.

What if I need a 64-bit Client in a Workgroup

environment?
By default, the 32-bit Client is installed with the Workgroup engine.
If you have a Workgroup engine running on a 64-bit machine, and
you have 64-bit applications (Btrieve or DTI) that you need to access

7-3
After Installing Pervasive PSQL for Windows

with a client, you may install both the Workgroup (32-bit) and
Client (64-bit) engines on the same machine. Install each product as
you would normally; no special configuration is required.

What happened to the Client install image?

Previous versions of Pervasive PSQL contained an image used for
installing the client software needed to access the Pervasive PSQL
database. This image is no longer needed since Pervasive PSQL v11
now installs the Client (32-bit) components with the Server and the
Workgroup editions. Use the Pervasive PSQL v11 Client (32-bit or
64-bit) to install on individual Client machines.

Do I need to install the Client with a Workgroup engine?

If you are installing the Workgroup engine, you must have a license
for and install the software on every computer that is expected to
share data within your workgroup. Because every computer must
have the Workgroup engine installed and the client software is
installed with every engine by default, there is no need to install the
client software separately.

Note Only the 32-bit Client components are installed.

How Do I Read the Online Documentation?

The viewer for the documentation library is integrated into Pervasive
PSQL Control Center (PCC). Access the documentation library
through the PCC interface on the Welcome view, in the Help menu,
by pressing F1 (Windows) or Shift F1 (Linux).
You can also view the documentation in the form of Adobe Acrobat
(PDF) files. These PDF files are available on the Pervasive PSQL
installation media in the Books directory.

How Do I Verify or Update My User License?

Licenses from previous versions of Pervasive PSQL are not migrated
or transferable to Pervasive PSQL v11. You must have a license
applicable for Pervasive PSQL v11, unless you choose to install using
the trial version of the product.

7-4
 Common Questions After Installing Pervasive PSQL

The License Administrator utility is documented in Pervasive PSQL

User's Guide in the section License Administration. Please refer to
that document for information on user licenses.

What User License Was Installed with Pervasive PSQL?

A trial license is installed if you leave the license number blank
during installation.
There is no configuration necessary for the license. After installation,
you can use the License Administrator utility to view your installed
licenses. See the Pervasive PSQL User's Guide for more information
on the License Administrator utility.

Where To Go If you had trouble during installation, see Troubleshooting After

From Here Installation.
If you completed installation successfully, continue with your
Pervasive PSQL deployment by installing and configuring the clients
for the machines that will connect to your servers. Review Chapter 5,
Installing Pervasive PSQL Clients for Windows.

7-5
After Installing Pervasive PSQL for Windows

Uninstalling Pervasive PSQL

The uninstall program removes the Pervasive PSQL engine, and all
related components from your system that were added by the
installation program, including registry settings, configurations and
Pervasive PSQL system and sample databases.
The uninstall program does not remove the following:
„ Databases that you create under the Pervasive PSQL Server
installation directory.
„ DSNs and database names associated with those databases.
„ Databases in locations other than the Pervasive PSQL Server
installation directory.
„ DSNs and database names associated with those databases.

³ To uninstall Pervasive PSQL

1 In the Windows Control Panel, select Add/Remove Programs.
2 Select the installed Pervasive PSQL v11 product from the list.
3 Click Change then Next.
4 Click Remove then Next and follow any prompts during the
uninstall.
If prompted, close or uninstall any running applications that
may interfere with uninstalling Pervasive PSQL.

Caution Unpredictable results may occur during the uninstall if

you ignore programs that may interfere.

Reboot your system, if prompted to do so.

7-6
 chapter

Configuring the Workgroup

Engine 8
Understanding the Available Workgroup Engine Configurations

This chapter discusses the concepts behind using the Workgroup

engine. The configurations available for the Workgroup engine are
covered, as well as the procedures for setting up those configurations.
Instructions for setting up a Gateway configuration using the
Gateway Locator Utility are included.
The sections in this chapter include:
„ Overview
„ Setting Up a Small Client/Server Configuration
„ Setting Up a Peer-to-Peer Configuration
„ Setting Up a Gateway Configuration
„ Running the Workgroup Engine as a Service

8-1
Configuring the Workgroup Engine

Overview
This section explains the basic concepts and requirements of
Workgroup engines. If you need more in-depth information about
the Workgroup engine, refer to the Advanced Operations Guide. The
Advanced Operations Guide contains detailed technical information
about the Workgroup engine, setting up a Gateway configuration,
and re-directing locator files.

Installation Every computer that may be used to access the same data at the same
Requirements time must have a Workgroup engine installed on it.

Operating Only database server engines can enforce OS level file security based
System on the privileges assigned to the login user name. The Workgroup
Security engine does not attempt to do this. In a small office, where
Workgroup engines are most common, this can be considered a plus
because they are usually short on networking experts, and the fewer
barriers to successful data access the better.

When to Use There are three main configurations in which you would want to use
Workgroup the Workgroup engine.

Small Client/Server Configuration

The first configuration takes place when all the data is located on a
single computer with a Workgroup engine installed, and there is
limited sharing of data. This configuration is roughly equivalent to a
small client/server configuration.

Peer-to-Peer Configuration
Another situation when you would want to use the Workgroup
engine is when the data is distributed among the workstations. This
is called a peer-to-peer topology. This configuration is used when
each application typically stores much of its own data on the local
hard drive, but periodically needs to access data from other
workstations or share its own data with others.
In this configuration, each computer shares its data directory or
directories. Any computer that needs access to that data maps one or
more drives to the shared data directories. Then the Workgroup

8-2
 Overview

engine on each computer acts as a mini-server engine to read/write

all changes to the data files on that machine.

Gateway Configuration
The third topology requiring the use of the Workgroup engine is
when the data is stored on a file server where there is no MicroKernel
engine. This can be a UNIX server or other type of network file server
that gets backed up regularly, but cannot support a MicroKernel
engine. In this situation, the first Workgroup engine that opens files
in a directory on the server becomes the Gateway to each file in that
directory. The other workstations access the data in a client-server
fashion through that Gateway engine.
The Gateway engine for a given directory identifies itself by creating
a file named ~PVSW~.LOC in that directory. This file is called a
Gateway locator file and contains the network name of the computer
where the Gateway engine is located. Other Workgroup engines
attempting to access this data read the locator file to find the name of
the engine they must communicate with in order to access the data.
You can ensure that the same engine always services the files in a
given directory by making the locator file read-only. This is called a
static gateway, also referred to as a fixed gateway. See To Set up a Fixed
Gateway for more information.
The Gateway engine acts as a server engine as it reads and writes
pages to the data files, allowing it to make the most use out of its
cache. The Gateway feature is designed so that the ownership of any
particular directory can change whenever the current gateway
engine has no more client applications with any files open in that
directory. When the last data file is closed in a directory by a given
database engine, the engine releases and deletes the locator file.
When the next engine opens a data file, that engine becomes the new
gateway to the directory where the data file(s) resides.

What is a A Gateway engine is a Workgroup engine that acts as the sole point
Gateway of access to all data files in a particular directory on a remote file
Engine? server. If several Workgroup engines are accessing the same database
at the same time, they do not all open the files simultaneously, nor
do they share the files. Rather, the first Workgroup engine to access
that database becomes the temporary “owner” of those files, and all
other Workgroup engines must access the data by contacting the
Gateway engine. Only the Gateway engine has the files open and

8-3
Configuring the Workgroup Engine

reads/writes the files. The other Workgroup engines act as clients,

making requests to the Gateway engine acting as a mini-server
engine.

Caution Make certain the Gateway computer is NOT shut down

while users are still using it as a Gateway, or data loss can occur.

A Gateway engine only comes into play when no database engine is

installed on the machine where the data files are, or when the
database engine on that machine is not operating.

8-4
 Setting Up a Small Client/Server Configuration

Setting Up a Small Client/Server Configuration

As explained in Small Client/Server Configuration, you should use
this set up when you have only a few workstations sharing data
located on a central computer where you have a Workgroup engine
installed.
If you have data located on many computers, or if you do not or
cannot install a database engine on the computer where the data is
located, you should use one of the other configurations.

³ To Set Up a Small Client/Server Configuration

1 You must have the Workgroup engine installed both on the
central computer where the data is and on all computers
expected to access the data.
Ensure that the Workgroup engine on the central computer
where the data is located is operational each time the computer
is started, before any other database engines attempt to access
the data. If the Workgroup engine was installed as an
application, ensure that the application starts if the computer is
restarted. A Workgroup engine starts by default if installed as a
server. See Running the Workgroup Engine as a Service.

Note You may inadvertently fall into a Gateway configuration if

the database engine on the machine where the data is located is
not started when the computer is started. If another Workgroup
engine attempts to access the data and the local database engine
is not running, the other database engine may establish itself as
the Gateway for those data files.

You can resolve this situation by shutting down the computer

where the data is located, and starting it again, while ensuring
that no other computers request data before the local
Workgroup engine is restarted. You may need to remove the file
~PVSW~.LOC from the data directory to ensure the Gateway is
not re-established.

8-5
Configuring the Workgroup Engine

The best way to ensure that only the Gateway services the file is
to set a static gateway locator file using the Gateway Locator
Utility.

2 Share the directory where the data is located so that other

computers can map a drive to the data directory.
3 Ensure that each workstation expected to access the data can
access the named database on the central computer. See Named
Database in Advanced Operations Guide.
Setup is complete. The Workgroup engine on the machine where
the data is located now acts as a mini-server, to fulfill all requests
for data on that machine.

8-6
 Setting Up a Peer-to-Peer Configuration

Setting Up a Peer-to-Peer Configuration

As explained in Peer-to-Peer Configuration, you should use this set
up when you have workstations sharing local data as well as data
located on many different machines, and each machine has the
Workgroup engine installed.
This configuration is similar to the small client/server configuration
discussed above, except that now every Workgroup engine is sharing
data as a server.
If you have data located on only one computers, or if you do not or
cannot install a database engine on the computer where the data is
located, you should use one of the other configurations.

³ To Set Up a Peer-to-Peer Configuration

1 You must have the Workgroup engine installed on each
computer where data is located, and installed on all computers
expected to access the data.
Ensure that the Workgroup engine on each computer where the
data is located is operational each time the computer is started,
before any other database engines attempt to access the data. If
the Workgroup engine was installed as an application, ensure
that the application starts if the computer is restarted. A
Workgroup engine starts by default if installed as a server. See
Running the Workgroup Engine as a Service.

Note You may inadvertently fall into a Gateway configuration if

the database engine on a machine where data is located is not
started when the computer is started. If another Workgroup
engine attempts to access the data and the local database engine
is not running, the other database engine may establish itself as
the Gateway for those data files.

You can resolve this situation by shutting down the computer

where the data is located, and starting it up again, while ensuring
that no other computers request data before the local
Workgroup engine is restarted. You may need to remove the file
~PVSW~.LOC from the data directory to ensure the Gateway is
not re-established.

8-7
Configuring the Workgroup Engine

The best way to ensure that only the Gateway services the file is
to set a static gateway locator file using the Gateway Locator
Utility.

2 On each computer where data is located, share the directory

where the data is located so that other computers can map a
drive to the data directory.
3 Ensure that each workstation expected to access the data can
access the named database to which the data belongs. See Named
Database in Advanced Operations Guide.
Also, ensure that each Workgroup engine can access any local
data from its own physical drive.
4 Set up is complete. The Workgroup engine on each machine
where data is located now acts as a mini-server, to fulfill all
requests for data on that machine.
Each Workgroup engine also handles any local data access, that
is, database requests from applications on that machine for data
that resides on the same machine.

8-8
 Setting Up a Gateway Configuration

Setting Up a Gateway Configuration

As explained in Gateway Configuration, you should use this set up
only when you have data files on a computer where no database
engine is installed.
If you have database engines installed on all machines, you should
use one of the other configurations.

Note You may inadvertently fall into a Gateway configuration if

the database engine on a machine where data is located is not
started when the computer is started. If another Workgroup
engine attempts to access the data and the local database engine
is not running, the other database engine may establish itself as
the Gateway for those data files.

You can resolve this situation by specifying a permanent

Gateway as described in this section, or by shutting down the
computer where the data is located, and starting it up again,
while ensuring that no other computers request data before the
local Workgroup engine is restarted. You may need to remove
the file ~PVSW~.LOC from the data directory to ensure the
Gateway is not re-established.

The best way to ensure that only the Gateway services the file is
to set a static gateway locator file using the Gateway Locator
Utility.

Floating or You can set up two different Gateway configurations. The default
Fixed Gateway behavior is a floating Gateway configuration. In this configuration,
the first engine to open the remote data files becomes the Gateway
engine for that directory until all files in the directory are closed.
Then the next engine to open the data files becomes the new
Gateway. This configuration is the most flexible, but also can entail
delays upon initial connection to the database, as the engine tries the
different network protocols and checks for an existing Gateway
engine.

8-9
Configuring the Workgroup Engine

Note Using a floating Gateway in a peer-to-peer configuration

with multiple shared data sources is not recommended. This
configuration is supported and it operates as designed, however,
with multiple engines shuffling ownership among multiple data
locations, connection delays may be significant. It is also possible
to create a situation where a Workgroup engine on a remote
machine serves as a the Gateway for data located on your local
hard drive. Obviously there is no reason to endure this delay
when your local Workgroup engine can serve this data with
higher performance.

You can avoid this situation by ensuring that the Workgroup

engine on every computer is started when the computer is
started. You must also ensure that someone logs on to each
computer, because normally the Workgroup engine doesn’t start
until a user logs on.

You can also avoid this situation by permanently assigning each

machine as the Gateway for the data files located on it. See To Set
up a Fixed Gateway for information on how to perform this task.

The second configuration is called a fixed or permanent Gateway

configuration. In this configuration, a specific engine is permanently
assigned as the Gateway engine for a specific directory. If that engine
is not running when another engine attempts to access the data, an
error code results and the data is not available.

³ To Set up a Floating Gateway

1 This is the default behavior. Ensure that each Workgroup
computer can access the named database (and therefore its
data). See Named Database in Advanced Operations Guide.
The Gateway assignment now floats dynamically as different
Workgroup engines access the remote data.

³ To Set up a Fixed Gateway

To specify a permanent Gateway engine for a given directory, you
need only change the attributes of the ~PVSW~.LOC file to read-
only, once it contains the name of the desired engine. There are
several ways to perform this task.

8-10
 Setting Up a Gateway Configuration

Use the Gateway Locator Utility

1 On the Start menu select Gateway Locator from the Pervasive
PSQL v11 program group.
2 In the Target Directory area, type in or browse for the directory
containing the data files for which you wish to set up a
permanent Gateway.
3 In the Directory Status area, click Change. In the dialog box that
appears, click Assign a Gateway, then type in or browse for the
network name of the computer that you want to be the Gateway.
Click OK.
4 Back in the main Gateway Locator window, check Permanent
assignment. Click Exit.

Use the DOS Command Line

1 Use the ATTRIB +R command at a DOS command prompt to
change the attributes of the ~PVSW~.LOC file.
For example, if your current directory is the directory where the
file is located, you can type the following command:
ATTRIB +R ~PVSW~.LOC

Use the Windows Explorer

1 Right-click the ~PVSW~.LOC file in the directory for which you
want to make a permanent Gateway assignment. Choose
Properties from the pop-up menu.
2 In the Properties window, on the General tab, click Read-only in
the section labeled Attributes. Click OK.

Working with The Gateway Locator Utility provides control of and insight into any
the Gateway Gateway configuration you have on your network. This section
Locator Utility explains how to use the utility for a variety of purposes.
This utility enables users to determine or change the Workgroup
Engine which is being used as the gateway for the data files in a
particular directory. The Gateway Locator utility is used only with
Pervasive PSQL v11 Workgroup Engine.
The Gateway Locator operates by reading and manipulating the
locator file, ~PVSW~.LOC, which resides in any directory which is
assigned a Gateway engine. If this file is locked (in use), the Gateway

8-11
Configuring the Workgroup Engine

Locator can only locate, not change, the Workgroup engine being
used as a Gateway for that particular directory.

³ To start the Gateway Locator Utility

1 On the Start menu select Gateway Locator from the Pervasive
PSQL v11 program group.
Figure 8-1 Gateway Locator Main Dialog Box

Note The Gateway Locator can be used to set the gateway for any
data directory. Data directory locations are not stored with the
tool. Consequently, you must always set the directory path
before you click Change.

2 In Target Directory, enter or browse for the directory path which

contains the data files for which you wish to locate or change the
Gateway engine.
3 The default target directory is the current working directory.
Clicking the browse (...) button allows you to browse for the
target directory, by bringing up the following dialog box:

8-12
 Setting Up a Gateway Configuration

Figure 8-2 Gateway Locator Browse Dialog Box

³ Locating the Gateway Workgroup Engine

Once the target directory is selected, clicking the Refresh button
causes the name of the Gateway engine for that directory (if such
exists) to appear in the Gateway Assigned To box. If no Gateway
exists for a particular directory, the box reads “unassigned.”

³ Changing the Gateway Workgroup Engine

Once the target directory is selected, click Change to choose the
Workgroup engine which you wish to serve as Gateway for a
particular directory (this button is disabled if the locator file for that
directory is locked.) The following dialog box appears:
Figure 8-3 Gateway Assignment Dialog Box

Enter or browse for the machine name you wish to serve as gateway.

8-13
Configuring the Workgroup Engine

Figure 8-4 Browse for Computer Dialog Box

8-14
 Running the Workgroup Engine as a Service

Running the Workgroup Engine as a Service

By default, the Workgroup engine is installed to run as an
application. During a Custom installation you may configure your
workstation to run the Workgroup engine as a service rather than as
a console application. Running the engine as a service allows the
engine to start automatically when the operating system starts. A
user is not required to log in to start the engine.
No tray icon appears when you run the Workgroup engine as a
service.

Configuration In order to configure your Workgroup engine to run as a Service as

opposed to an application, you must reinstall the Pervasive PSQL v11
Workgroup engine. Choose the Custom install and select Run As
Service on the Engine Settings dialog box during install.

Caution Running the engine as a service requires the Log On as

Service privilege. If you select to run the engine as a service
under a user account other than the default Local System
account, you will need to modify the Log On Properties for the
Service using the Windows Control Panel.

Note that on Windows platforms, a valid user name and password

are required to access Pervasive PSQL databases on another machine.
"System Account" has no rights on other machines to Pervasive
PSQL databases.
If you want the Pervasive Workgroup service to access databases on
another machine, then you must specify a valid user name and
password for the other machine, unless there is a running Pervasive
Workgroup available locally on the other machine that can be used
to access the databases instead. Access the properties for the
Pervasive Workgroup service. (Double-click the service on the
Services dialog.) In the Log On As section, check This Account and
specify a valid user name and password.

8-15
Configuring the Workgroup Engine

Stopping the If you want to stop and then restart the service (and not permanently
Service remove the service), then just reboot the machine.
You stop the service on Windows platforms just as you would any
other service.

³ Stopping the Engine as a Service on Windows

1 In the Windows Control Panel, click Administrative Tools, then
double-click Services.
2 Right-click the service name assigned to the Workgroup engine
and click Stop.

8-16
 chapter

Configuring Engine Network

Communications 9
How to Set Up Network Communication for Pervasive PSQL Engines

This chapter reviews the types of network communication protocols

supported with Pervasive PSQL and how to set protocol support for
your network, if you require different settings.
„ Determining What Kind of Network You Have
„ Engine Network Communication Settings
„ Setting Up TCP/IP Support
„ Setting Up SPX Support
„ Setting Up NetBIOS Support (Workgroup only)
„ Avoiding Unavailable Protocols

9-1
Configuring Engine Network Communications

Determining What Kind of Network You Have

This section explains how to determine the network protocol that
you should use with the database engine. If you already know what
protocol or protocols are supported on your network, you can skip
this section.

Database If your network is 100% Microsoft, and you have a database Server
Engine on engine, then your network probably uses TCP/IP. The Server engine
Windows does not support NetBIOS.
You can run applications over SPX on Microsoft networks if the
applications use only the Pervasive PSQL transactional interface
(Btrieve or ODBC).
If your network is 100% Microsoft, and you are using Workgroup
engines, then you can use either NetBIOS or TCP/IP.

9-2
 Engine Network Communication Settings

Engine Network Communication Settings

This section lists the configuration settings used by the Pervasive
PSQL engines for network communication. These settings may be
changed using a command line utility or from within PCC on the
engine properties.
The Advanced Operations Guide provides detailed information about
each of the settings. See the following configuration settings in
Advanced Operations Guide for network communication:
„ Auto Reconnect Timeout
„ Enable Auto Reconnect (Windows only)
„ Listen IP Address
„ Supported Protocols
„ TCP/IP Multihomed
„ TCP/IP Port
„ NetBIOS Port (Workgroup engines only)

9-3
Configuring Engine Network Communications

Setting Up TCP/IP Support

By default, TCP/IP is supported between Pervasive PSQL clients and
remote database engines or between multiple Workgroup engines. If
you have modified the default settings or need to verify that TCP/IP
support is available, refer to this section.

Note To perform any of the tasks in this section, you must have
full administrator-level rights on the machine where the
database engine is running, or be a member of the
Pervasive_Admin group defined on the machine where the
database engine is running.

³ To Enable TCP/IP Support

Complete the following steps to ensure that the database engine can
communicate with clients over TCP/IP networks.
1 On the Start menu select Control Center (PCC) from the
Pervasive PSQL v11 program group.
2 In the Pervasive PSQL Explorer, double-click Engines to display
a list of the engines registered with PCC.
3 Right-click the target engine and click Properties. Login if
prompted.
4 Click Communication Protocols, and the list of Supported
protocols displays. If the list of Supported protocols shows the
value TCP/IP checked, then TCP/IP is already supported.
5 Click TCP/IP then restart the database engine for the changes to
take effect.

Tip Remember that you also need to confirm that your client
computers or the client software on your other Workgroup
computers are configured to use TCP/IP, as well. See Chapter 10,
Configuring Network Communications for Clients.

9-4
 Setting Up TCP/IP Support

³ To Enable Multihomed TCP/IP Support

Completing the following steps configures your Windows server to
use two installed network cards.
1 On the Start menu select Control Center (PCC) from the
Pervasive PSQL v11 program group.
2 In the PCC Pervasive PSQL Explorer, double-click Engines to
display the list of registered engines with PCC.
3 Right-click the target engine and click Properties. Login if
prompted.
4 Click Communication Protocols and click TCP/IP Multihomed
to configure the server engine to listen for client connections on
multiple network interfaces.
If you only have one network interface, this setting is ignored.
5 Restart the server engine for the changes to take effect. You do
not need to make any changes to client settings.

Note If your server computer has two network interfaces, and

you set the value of TCP/IP Multihomed to Off, you must edit
the setting Listen IP Address and specify the TCP/IP address of
the interface on which you want the database engine to listen.

If you do not specify an IP address, the database engine will

receive communications only from the first network interface to
bind to the operating system. Because this can vary with driver
installation, a working system can easily break after receiving
driver updates. To avoid this problem, always set the Listen IP
Address.

9-5
Configuring Engine Network Communications

Setting Up SPX Support

SPX is supported between Pervasive PSQL clients and servers. If you
have modified the default settings or need to verify that SPX support
is available, refer to this section.
Your network’s SPX Frame Type setting does not have any effect on
Pervasive PSQL. All computers communicating over SPX should be
configured for the same SPX Frame Type. The Ethernet_802.2 frame
type is the default and is recommended.

Note In order to perform any of the tasks in this section, you

must be a member of the Pervasive_Admin group defined on the
server.

³ To Enable SPX Support

Complete the following steps to ensure that the database server
engine can communicate with clients over SPX networks.

Note In an all-Microsoft environment, SPX can be used with

applications that use only the Pervasive PSQL transactional
interface. Applications that use only the transactional interface
do not require name resolution with SPX.

1 On the Start menu select Control Center (PCC) from the

Pervasive PSQL v11 program group.
2 In the PCC Pervasive PSQL Explorer, double-click Engines to
display a list of the engines registered with PCC.
3 Right-click the target engine then click Properties. Login if
prompted.
4 Click Communication Protocols, and the list of Supported
protocols displays. If SPX is checked, then SPX is already
supported.
5 Click SPX then restart the database engine for the changes to
take effect.

9-6
 Setting Up SPX Support

Tip Remember that you also need to confirm that your client
computers are configured to use SPX, as well. See Chapter 10,
Configuring Network Communications for Clients.

9-7
Configuring Engine Network Communications

Setting Up NetBIOS Support (Workgroup only)

By default, NetBIOS is supported among Pervasive PSQL
Workgroup engines. If you have modified the default settings or
need to verify that NetBIOS support is available, refer to this section.

Note In order to perform any of the tasks in this section, you

must be seated at the console of the machine running the
Workgroup engine. You cannot remotely configure the
Workgroup engine.

³ To Enable NetBIOS Support

Complete the following steps to ensure that the database engine can
communicate with clients over NetBIOS networks.
1 On the Start menu select Control Center (PCC) from the
Pervasive PSQL v11 program group.
2 In the Pervasive PSQL Explorer, double-click Engines to display
a list of the engines registered with PCC.
3 Right-click the target engine then click Properties. Login if
prompted.
4 Click Communication Protocols, and the list of Supported
protocols displays. If NetBIOS is checked, then NetBIOS is
already supported.
5 Click NetBIOS then restart the database engine for the changes
to take effect.

Tip Remember that you also need to confirm that the client
software on your other Workgroup computers are configured to
use NetBIOS, as well. Please refer to Chapter 10, Configuring
Network Communications for Clients.

9-8
 Avoiding Unavailable Protocols

Avoiding Unavailable Protocols

It may be possible to improve performance on the initial connection
to the database by disabling database communications support for
any protocols that are not available on your network or that you do
not wish to use.
In order to perform any of the procedures in this section you must
have one of the following:
„ full administrator-level rights on the machine where the
database engine is running
„ membership in the Pervasive_Admin group defined on the
machine where the database engine is running.

Note In order to perform any of the tasks in this section, you

must be seated at the console of the machine running the
Workgroup engine. You cannot remotely configure the
Workgroup engine.

³ To Remove Support for a Network Protocol

Note This procedure does not affect your operating system

configuration in any way. This procedure only prevents the
database communications system from attempting
communications on unavailable or undesired protocols.

1 On the Start menu select Control Center (PCC) from the

Pervasive PSQL v11 program group.
2 In the PCC Pervasive PSQL Explorer, double-click Engines to
display a list of the engines registered with PCC.
3 Right-click the target engine then click Properties. Login if
prompted.
4 Click Communication Protocols, and the list of Supported
protocols displays. Selected protocols are considered available
for use by the engine.
5 Clear the check box for any of the selected protocols that are not
supported on your network or that you do not wish to use.

9-9
Configuring Engine Network Communications

You must leave at least one protocol selected.

6 Click OK then restart the database engine for the changes to take
effect.

Tip Remember that you also need to confirm that your client
computers are configured to use the protocol remaining in the
Supported protocols list. Please refer to Chapter 10, Configuring
Network Communications for Clients.

9-10
 chapter

Configuring Network
Communications for Clients 10
How to Configure Network Communications for Your Pervasive PSQL Clients

To access network files from a machine using a Pervasive PSQL

application, you must use the appropriate client requester at that
machine. Your application’s Pervasive PSQL calls go through the
client requester, which sends them to the server for processing and
then returns the reply to your application.
Generally, the default configuration settings for Pervasive PSQL
Server and Client are sufficient. You typically do not have to
configure any settings for the database engine and clients to
communicate and function together correctly.
This chapter contains the following sections.
„ Client Network Communication Settings
„ Network Path Formats Supported by Pervasive Requesters
„ Using TCP/IP to Connect to a Windows Server
„ Using SPX to Connect to a Windows Server
„ Changing the Default Communication Ports
„ Using TCP/IP to Connect a Windows Client to a Linux Server
„ Data Encoding
„ Using the DOS Requester
„ DOS Box Support on Windows

10-1
Configuring Network Communications for Clients

Client Network Communication Settings

This section lists the configuration settings used by the Pervasive
PSQL Clients for network communication. These settings may be
changed using a command line utility or from within PCC on the
engine properties.
The Advanced Operations Guide provides detailed information about
each of the settings. See the following configuration settings in
Advanced Operations Guide for network communication:
„ Enable Auto Reconnect (Windows only)
„ Supported Protocols
„ Connection Timeout

10-2
 Network Path Formats Supported by Pervasive Requesters

Network Path Formats Supported by Pervasive Requesters

When using your Requester, you connect to the Pervasive server
engine to access data files. This section shows the variations on
network file syntax you can use to access files on your network using
Btrieve or SQL applications.
Pervasive PSQL supports the Universal Naming Convention (UNC)
and Drive path formats (explicit and current) across the majority of
operating environments.
For more information on the path formats, see the sections that
follow:
„ Universal Naming Convention (UNC) Path Formats
„ Drive-based Formats
„ Linux Path Formats

Universal The following UNC path formats are supported on all clients to all
Naming servers:
Convention \\ServerName or IP address\share\path\file
(UNC) Path \\ServerName or IP address\share:[\]path\file
Formats UNC syntax is resolved correctly regardless of the actual type of
network operating system (NOS) running on the target server. If you
use an IP address, it must be a dotted IPv4 address or one of the two
formats supported for IPv6. See IPv6 With UNC Paths and URI
Connections.

Note In all instances above, backslashes (\) can be interchanged

with forward slashes (/) except for the double backslash (\\). The
syntax [\] indicates that the backslash is optional.

IPv6
A Pervasive PSQL Client connects to a IPv6 host running the
Pervasive PSQL database engine the same way as for IPv4. That is,
the Client specifies a server and connects through DTI or by
specifying a URI or UNC. The server can be either the name or IP
address of the machine running Pervasive PSQL Server or
Workgroup.

10-3
Configuring Network Communications for Clients

UNC paths do not allow certain special characters, such as colons,

that are part of IPv6 addresses. The use of IPv6 with UNC paths is
discussed below. First, however, a brief summary of IPv6 formats
supported is useful to orient you to IPv6.
Raw IPv6 addresses can be written as 8 colon-separated segments
where each segment is a a 4-digit hexadecimal value. For example,
1234:5678:90ab:cdef:1234:5678:90ab:cdef.
Pervasive PSQL supports only unicast addresses. The following are
the unicast address formats that can be used with Pervasive PSQL.
Table 10-1 IPv6 Unicast Address Formats Supported by Pervasive PSQL

Unicast Address Description

Format

Loopback The local loopback address, which in IPv6 is 0:0:0:0:0:0:0:1.

The loopback address can be abbreviated to ::1.

The IPv6 loopback address is equivalent to the IPv4 loopback

address of 127.0.0.1.

Global Global addresses have a 64-bit prefix where the first 3 bits
are always 001, the next 45 bits are set to the global routing
prefix, the next 16 bits are set to the subnet ID and the last
64-bits are the interface ID.

Example: 2001:db8:28:3:f98a:5b31:67b7:67ef

Link Local Link Local addresses are used by nodes when

communicating with neighboring nodes on the same link. Link
Local addresses have a 64-bit prefix where the first 10 bits
are set to 1111 1110 10, the next 54 bits are set to 0 and the
last 64 bits are the interface ID. The link local prefix is often
represented as FE80::/64.

Example: fe80:0:0:0:713e:a426:d167:37ab (which may also

be specified as fe80::713e:a426:d167:37ab)

See also Restrictions.

10-4
 Network Path Formats Supported by Pervasive Requesters

IPv6 Address Modifiers

IPv6 includes address modifiers which can act as shortcuts, or to
specify the destination in more detail. Pervasive PSQL supports the
following ones for IPv6.

Modifier Explanation

:: Represents one or more colon-separated zeroes. For example,

::1 is equivalent to 0:0:0:0:0:0:0:0:1. The :: modifier can be used
only once within an IPv6 address.

% Represents the ZoneID or interface of a destination node. A

ZoneID is an integer that specifies the zone of the destination for
IPv6 traffic.

See Restrictions.

IPv6 With UNC Paths and URI Connections

UNC paths do not allow certain special characters, such as colons.
Since raw IPv6 addresses use colons, different methods of handling
UNC paths are available. Pervasive PSQL supports the following
methods:
„ IPv6-literal.net Names
„ Bracketed IPv6 Addresses

IPv6-literal.net Names
An ipv6-literal.net name is a raw IPv6 address with three changes:
„ ":" is replaced with "-"
„ "%" is replaced with "s"
„ The whole address is appended with ".ipv6-literal.net"
Examples:

Initial Addresses fe80::713e:a426:d167:37ab%4

2001:db8:28:3:f98a:5b31:67b7:67ef

Modified Addresses fe80--713e-a426-d167-37abs4.ipv6-literal.net

2001-db8-28-3-f98a-5b31-67b7-67ef.ipv6-literal.net

IIpv6-literal.net names are allowed in a URI or UNC used with

Pervasive PSQL.

10-5
Configuring Network Communications for Clients

Bracketed IPv6 Addresses

A bracketed IPv6 address is a raw IPv6 address with square brackets
around it. This format is also referred to as a UNC-safe address.
Examples:

Initial Addresses fe80::713e:a426:d167:37ab%4

2001:db8:28:3:f98a:5b31:67b7:67ef

Modified Addresses [fe80::713e:a426:d167:37ab%4]

[2001:db8:28:3:f98a:5b31:67b7:67ef]

The use of square brackets is required for raw IPv6 addresses used in
a URI or UNC with Pervasive PSQL. See Restrictions. Note that if
you use an address with a ZoneID in a URI, the ZoneID character
“%” must use the escape characters “%25.” See Restrictions.

10-6
 Network Path Formats Supported by Pervasive Requesters

Restrictions
The following table lists the restrictions on the use of IPv6 with
Pervasive PSQL.
Table 10-2 IPv6 Restrictions With Pervasive PSQL

Restriction Discussion

The Pervasive The Pervasive PSQL Server Engine is not supported in an

PSQL Server IPv6-only environment on Windows Server 2003 or
Engine in an IPv6- Windows XP operating systems. The Server Engine may be
only environment used with IPv6 on Windows Vista, Windows 7, and Windows
Server 2008.

With Windows Server 2003 or Windows XP, status code 170

is returned when a PSQL Client attempts to connect to the
PSQL Server. NetBIOS over TCP (NetBT) is not
implemented for IPv6 on Windows Server 2003 or Windows
XP.

If you want to use PSQL Server on Windows Server 2003 or

Windows XP, the network environment must be IPv4 or a
combination of IPv4 and IPv6.

This restriction applies only to the Server Engine. Pervasive

PSQL Workgroup may be used with IPv6 on Windows
Server 2003, Windows XP, Windows Vista, Windows 7, and
Windows Server 2008.

Square brackets Raw IPv6 addresses, abbreviated or not, must be enclosed

are required for by square brackets if the address is used in a URI or UNC.
raw IPv6
addresses when Examples:
the address is • btrv://czjones@[2001:b1::23]/demodata
used in a URI or • btrv://abanderas@[2001:12:34:56:78:90:12:23]/
UNC demodata
• \\[2001:12:34:56:78:90:12:23]\acctsvr1\Domestic\file.mkd

Failure to bracket the IPv6 address results in status code

3014 or 3103 for Btrieve calls using a URI, or status code 11,
94, or 170 for Btrieve calls using a UNC.

In a URI, if you If you use a btrv:// connection with an IPv6 address, you
include a ZoneID must escape the ZoneID for the host name.
to a server
address, the “%” Example:
ZoneID character
A UNC-safe addresses like
must be escaped
with “%25” btrv://@[fe80::20c:29ff:fe67:2ee4%4]

must be changed to

btrv://@[fe80::20c:29ff:fe67:2ee4%254]

10-7
Configuring Network Communications for Clients

Table 10-2 IPv6 Restrictions With Pervasive PSQL

Restriction Discussion

PCC usage in an In an IPv6-only environment, PCC allows only the

IPv6-only functionality supported by the transactional or DTI access
environment methods. For example, you can connect a PSQL Client from
an IPv6-only machine to a database engine on an IPv6-only
server machine. PCC allows you to view and set Engine and
Client properties because those features use DTI. However,
you cannot browse databases or use Table Designer
because those feature use other access methods, such as
the relational interface, which are not yet supported for IPv6.

License The Pervasive licensing server does not yet support IPv6.
Administrator (and Because of this, you can use License Administrator over
clilcadm) IPv6 to administer licenses but you cannot authorize a
license with the utility. To authorize a license, you must use
an IPv4 network, remote authorization, or telephone
authorization.

Drive-based The following drive representations are supported on all clients to all
Formats servers:
drive:file
drive:[\]path\file
file
[\]path\file
..\file

Linux Path Incoming paths on a Linux server using Samba will be processed as
Formats follows in order of relative priority:

Share names
\\<server>\<sharename>\<path>

The smb.conf file must be configured to accept <sharename>,

otherwise it will default to the following:

Absolute paths
\\<server>\<absolute_path>

If the smb.conf file is not configured properly or not found on the

target server, the absolute path is used.
For more information on the Linux version of Pervasive PSQL v11,
see Using Pervasive PSQL on Linux.

10-8
Network Path Formats Supported by Pervasive Requesters

10-9
Configuring Network Communications for Clients

Using TCP/IP to Connect to a Windows Server

This section documents the use of TCP/IP when connecting to a
Pervasive PSQL server running on a Windows server platform.

Configuring a When Pervasive PSQL operates in a TCP/IP network, your client

Client for the must be able to obtain the IP address of your Windows server from
Server IP the name given to that server. There are two mechanisms that enable
Address this address-to-name translation:
„ DNS (Domain Naming Service)
„ Editing the Hosts file
The following procedures provide an overview for how to set up the
IP address using each method. For details about network
configuration and set up, refer to the documentation for the
operating system.

Using DNS to Configure the Server IP Address

When you use DNS, you specify settings that allow your computer to
look up the address of the server in a database of servers. Your
network administrator can provide the information you need to
configure DNS.

³ To configure your Windows clients to use DNS to

resolve the server IP address
1 From the operating system, access the Network information.
2 Select the Properties for Local Area Connection.
3 Select the Properties of the TCP/IP connection being used (IPv4
or IPv6, for example).
4 Enable DNS and enter the appropriate server information.

Using the Hosts File to Configure the Server IP Address

The Hosts file is a way to manually enter a relationship between a
name and an IP address. Use this method if DNS is not used in your
organization.

10-10
 Using TCP/IP to Connect to a Windows Server

³ To Edit the Hosts file on your Windows client

1 Find the Hosts file on your Windows machine.
For example, on certain Windows platforms it is located here:
%WINDIR%\SYSTEM32\DRIVERS\ETC\HOSTS

2 Edit the Hosts file with a text editor such as Notepad.

3 Enter your server’s IP address and name in the hosts file as a new
line as shown in the following example. Your network
administrator can provide you with the IP address of your server.
# the following is an example of a Hosts file entry
for IPv4 address
146.23.45.2 acctserver

Preventing the Windows Dial-Up Network Dialog Box

from Displaying When Using a Pervasive Application with
TCP/IP
Depending on the settings for your browser, the Windows Dial-Up
Networking dialog box can display when a TCP/IP request is made.
Usually, this is to make an Internet connection, but this feature can
be an annoyance when using Pervasive applications and TCP/IP.

³ To Prevent the Dial-Up Networking Dialog Box from

Displaying Automatically
1 In Control Panel, double-click Internet Options.
2 Click the Connections tab.
3 Clear the Dial whenever a network connection is not present
option (select one of the other options, such as Never Dial a
Connection).

10-11
Configuring Network Communications for Clients

Using SPX to Connect to a Windows Server

This section documents the use of SPX when connecting to a
Pervasive PSQL server running on a Windows machine.

Configuring SPX is not a native protocol on the Windows platforms. If you want
Pervasive to use SPX, perform the following procedures to ensure proper
PSQL to use operation with Pervasive PSQL.
SPX
Changing Pervasive’s configuration to use SPX with a
Windows platform
If you have both TCP/IP and SPX installed, you must remove TCP/
IP from the Pervasive PSQL Client configuration to make SPX
function with Pervasive applications
1 On the Start menu select Control Center (PCC) from the
Pervasive PSQL v11 program group.
2 In the Pervasive PSQL Explorer, expand Local Client.
3 Right-click MicroKernel Router and select Properties. Login if
prompted.
4 Click Communication protocols. In the window to the right, a
list of Supported protocols displays.
5 Clear TCP/IP from the list of selected protocols and click OK.

Changing Windows Configuration to Make SPX Run with

Pervasive PSQL

³ To Ensure that your SPX settings are correct

1 From the operating system, access the Network information.
2 Select the Properties for Local Area Connection.
3 Select the Properties of the SPX connection.
4 In the Frame Type field, ensure that the correct frame type for
your network is selected. Do not use Auto Detect.
5 In the Network number field, enter a non-zero value for your
network address. For information about what your network
address should be, contact your system administrator.

10-12
 Changing the Default Communication Ports

Changing the Default Communication Ports

Pervasive PSQL communicates through three ports. Your firewall(s)
and routers need to allow access to the following ports for remote
access with the server database engine:
„ 3351 for the transactional interface
„ 1583 for the relational interface
„ 139 for named pipes (see note)
Typically, you do not need to modify the ports unless you have a
conflict with them.

Note The Windows operating system uses port 139 for

authentication to the operating system. An alternative to
allowing access to port 139 through a firewall is to enable
security on the Pervasive PSQL database. Once security is
enabled, users such as “Master” are authenticated to the database
through the database’s own security features. See To turn on
security using Pervasive PSQL Explorer and To create a new user
using Pervasive PSQL Explorer, both in Advanced Operations
Guide.

Port assignment 1583 is configurable for the server through the

Pervasive PSQL utilities. This port is manually configurable for
clients. See TCP/IP Port in Advanced Operations Guide.
It is recommended that port assignment 3351 not be changed. If you
must change it, contact Pervasive Support.
Ensure that the port configurations match on both the server and all
clients.
After changing your server listening port, you must stop and restart
your Pervasive PSQL engine for the port assignment changes to take
effect. See the chapter Using Pervasive PSQL in Pervasive PSQL User's
Guide.

Windows Microsoft Windows operating systems Vista and later enable the
FireWalls firewall by default. The Pervasive PSQL Server and Workgroup
installation adds files to the firewall access list to enable access to the
database engine. If the operating system security prompts you to

10-13
Configuring Network Communications for Clients

unblock or allow communication with a Pervasive PSQL

component, select OK (yes).
If you encounter problems with your client/server applications not
working correctly after installation, check the firewall access list or
the ports. You may need to adjust some of the security settings to
enable client/server applications. You can add files to the access list
or open ports. You do not need to do both. Note that opening a port
opens it for all access, not just for Pervasive PSQL.
If you want to add Pervasive PSQL components to the firewall access
list, add the following:
„ For Pervasive PSQL 32-bit Server, ntdbsmgr.exe.
„ For Pervasive PSQL Workgroup, w3dbsmgr.exe.
„ For Pervasive PSQL 64-bit Server, ntdbsmgr.exe and
ntdbsmgr64.exe.

Note The Pervasive PSQL installation adds the Pervasive files to

the access list only for the current profile of your network. If the
profile changes after you install Pervasive PSQL, Pervasive PSQL
may no longer be able to accept communications. Example: a
somewhat lax Private profile is in use when Pervasive PSQL is
installed and you change the profile to a restricted Public profile
after installation.

If you change to a profile that prevents Pervasive PSQL

communications, open the Windows firewall utility (Windows
Firewall with Advanced Security) and select the rules for your
Pervasive PSQL database engine in the Inbound Rules section.
Refer to the operating system documentation and manually
adjust the properties of these rules to allow Pervasive PSQL
communications over the networks you plan to use. Normally,
this is done by selecting the Advanced tab and selecting the
profiles of the networks on which Pervasive PSQL
communicates.

Services File The services file is a text file used by the operating system for network
communications. In the services files, you can manually assign the
ports used by Pervasive PSQL Server and its clients. After changing
port assignments in the services file, you must stop then start the
Pervasive PSQL database engine for the changes to take effect. See

10-14
 Changing the Default Communication Ports

Starting and Stopping the Database Engine in Pervasive PSQL User's

Guide.

10-15
Configuring Network Communications for Clients

Using TCP/IP to Connect a Windows Client to a Linux Server

Your Samba must be properly configured on your Linux server to
properly network with Windows-based clients when using mapped
drives.

Configuring a When Pervasive PSQL operates in a TCP/IP network, your client

Client for the must be able to obtain the IP address of your Linux server from the
Server’s IP name given to that server. There are two mechanisms that enable this
Address address to name translation:
„ DNS (Domain naming service)
„ Editing the Hosts file
The following procedures provide an overview for how to set up the
IP address using each method. For details about network
configuration and set up, refer to the documentation for the
operating system.

Using DNS to Configure the Server IP Address

When you use DNS, you specify settings that allow your computer to
look up the address of the server in a database of servers. Your
network administrator can provide the information you need to
configure DNS.

³ To configure your clients to use DNS to resolve the

server IP address
For clients on Windows platforms:
1 From the operating system, access the Network information.
2 Select the Properties for Local Area Connection.
3 Select the Properties of the TCP/IP connection being used (IPv4
or IPv6, for example).
4 Enable DNS and enter the appropriate server information from
your network administrator.

10-16
 Using TCP/IP to Connect a Windows Client to a Linux Server

Using the Hosts File to Configure the Server IP Address

The Hosts file is a way to manually enter a relationship between a
name and an IP address. Use this method if DNS is not used in your
organization.

³ To Edit the Hosts file on your Windows client

1 Find the Hosts file on your Windows machine.
For example, on certain Windows platforms it is located here:
%WINDIR%\SYSTEM32\DRIVERS\ETC\HOSTS

2 Edit the Hosts file with a text editor such as Notepad.

3 Enter your server’s IP address and name in the hosts file as a new
line as shown in the following example. Your network
administrator can provide you with the IP address of your server.
# the following is an example of a Hosts file entry
for IPv4 address
146.23.45.2 acctserver

Preventing the Windows Dial-Up Network Dialog Box

from Displaying
The Windows Dial-Up Networking dialog box can display when a
TCP/IP request is made to Windows. Usually, this is to make an
Internet connection, but this feature can be an annoyance when
using Pervasive applications and TCP/IP.

³ To Prevent the Dial-Up Networking Dialog Box from

Displaying Automatically
1 In Control Panel, double-click Internet Options.
2 Click the Connections tab.
3 Clear the Dial whenever a network connection is not present
option (select one of the other options, such as Never Dial a
Connection).

10-17
Configuring Network Communications for Clients

Data Encoding
An encoding is a standard for representing character sets. Character
data must be put in a standard format, that is, encoded, so that a
computer can process it digitally. An encoding must be established
between the Pervasive PSQL database engine (server) and a Pervasive
PSQL client application. A compatible encoding allows the server
and client to interpret data correctly.
Pervasive PSQL v11 better handles the complexity of the encoding
between client and server and the various combinations of operating
system, languages, and access method. The encoding enhancements
are divided into database code page and client encoding. The two
types of encoding are separate but interrelated (see Table 10-3).
The use of the two encoding methods is intended for advanced users.
In general, the default encoding settings are sufficient and do not
require changing.
Database code page and client encoding apply only to the relational
interface. The transactional interface is not affected.
This section contains the following topics:
„ Database Code Page
„ Client Encoding
„ Encoding Interaction
„ Legacy Conversion Methods for OEM Data

Database Code Database code page is specified with a new property called database
Page code page, which identifies the encoding to use for data and
metadata. The default database code page is “server default,”
meaning the operating system (OS) code page on the server where
the database engine is running. (The OS code page is generally
referred to as the “OS encoding,” which is the phrase used
throughout the rest of this chapter.)
Database code page is particularly handy if you need to manually
copy Pervasive PSQL DDFs to another platform with a different OS
encoding and still have the metadata correctly interpreted by the
database engine.

10-18
 Data Encoding

Client Client encoding is the data encoding used by an application on a

Encoding Pervasive PSQL client. An application can store data in any encoding
it chooses. But, as mentioned earlier, a compatible encoding must be
established between the database engine and the client application.
Previous versions of Pervasive PSQL provided methods to ensure
compatible encoding between the database engine and clients.
Those methods have been enhanced to take advantage of database
code page. An application can now specify that it wants the Pervasive
PSQL client to translate data automatically between the database
code page and the client application. This is referred to as automatic
translation. Note, however, that automatic translation can translate
characters only if they are present in both code pages (the code page
on the server machine and the code page on the client machine).
Automatic translation is specified when the client application
connects to the database engine. See ODBC Connection Strings in
SQL Engine Reference.
Data translation, if required, occurs at the client. (Translation is not
always required—for example, when the client operating system
(OS) encoding matches the server OS encoding.)

Encoding The following table explains the interaction between database code
Interaction page and client encoding.
Table 10-3 Interaction Between Database Encoding and Client Encoding

If Database Encoding Is And the Client Application The Pervasive PSQL Client
Specifies

Server Default Automatic Translation Translates data and metadata from the
default operating system (OS) encoding on
the server to the OS encoding on the client.

A specific code page Automatic Translation Translates data and metadata from the
database code page to the OS encoding on
the client.

10-19
Configuring Network Communications for Clients

Table 10-3 Interaction Between Database Encoding and Client Encoding

If Database Encoding Is And the Client Application The Pervasive PSQL Client
Specifies

Server Default Nothing (no encoding Sends data to the database engine in the
specified) encoding of the client machine and ignores
or database code page.
(No encoding specified is the
A specific code page default behavior in versions For compatible data interpretation, the
prior to Pervasive PSQL encoding used by the client machine must
v10.10.) match the encoding of the data and
metadata in the database.

Server Default A specific encoding Sends data to the server in the encoding
specified by the client application and
or ignores database code page.
A specific code page For compatible data interpretation, the
encoding specified by the client application
must match the encoding of the data and
metadata in the database.

When a database has OEM character data in it, the legacy solution
was for the access method, such as ODBC using a DSN, to specify
OEM/ANSI conversion. Now it is possible to set the OEM code page
for the database and have the access method specify automatic
translation. See also Encoding Translation in SQL Engine Reference.

Note The database engine does not validate the encoding of the
data and metadata that an application inserts into a database.
The engine assumes that all data was entered using the database
code page as explained in Table 10-3.

Legacy If a database has OEM character data in it, a legacy solution is to

Conversion specify OEM/ANSI conversion in the access method. This topic
Methods for discusses some legacy methods for Linux clients using OEM
OEM Data character data.

Note While the legacy methods are still supported, the

recommendation is to specify the OEM code page for the
database and have the access methods use automatic translation
as discussed above.

10-20
 Data Encoding

Btrieve and DTI

When using the Btrieve API or the Distributed Tuning Interface
(DTI), you must provide file names and paths in the local encoding
used in your application. The Btrieve API and DTI handle the
differences between OS encoding on the server and client.

ODBC
See also OEM/ANSI Conversion in SQL Engine Reference.
When using ODBC, Win32 encoding is expected to be SHIFT-JIS.
Japanese versions of Linux by default have their encodings typically
set to EUC-JP or UTF-8.
When using Japanese versions of Linux, a client can connect to
another Linux server (for example, locally), or to a Win32 SHIFT-JIS
server. It is also possible to connect to a database encoded in SHIFT-
JIS but located on a Linux server.
Use the following instructions for your listed configuration. In each
case, it is assumed that the application itself does not do any
conversion and uses the encoding that is native for the machine.
„ Connecting a Linux EUC-JP Client to a Win32 SHIFT-JIS Server
„ Connecting a Linux UTF-8 Client to a Win32 SHIFT-JIS Server
„ Connecting a Linux EUC-JP Client to a Linux EUC-JP Server
„ Connecting a Linux UTF-8 Client to a Linux UTF-8 Server
„ Connecting a Linux UTF-8 Client to a Linux EUC-JP Server
„ Connecting a Linux EUC-JP Client to a Linux EUC-JP Server,
with SHIFT-JIS Encoding Used to Store Data on the Server

Connecting a Linux EUC-JP Client to a Win32 SHIFT-JIS Server

The server requires that everything is received as SHIFT-JIS. The
client requires that the server send everything as EUC-JP.
To accomplish this, the client DSN settings in ODBC.INI (located by
default in /usr/local/psql/etc) used to connect to the given
database should be set up as follows:
[dbclient]
Driver=/usr/local/psql/lib/libodbcci.so
Description=Pervasive ODBC Client Interface: JPN-
2000SERVER:1583/dbclient
ServerDSN=DEMODATA

10-21
Configuring Network Communications for Clients

ServerName=JPN-2000SERVER:1583
TranslationDLL=/usr/local/psql/lib/libxlate.so.10
TranslationOption=90000932

The TranslationDLL line specifies the translation library that the

ODBC client interface should use.
The TranslationOption line specifies that the translation needs to
occur from 9000 (representing EUC-JP) to 0932 (representing
SHIFT-JIS).
Using this example, all data coming from the client will be translated
into SHIFT-JIS before it gets to the server, and to EUC-JP before the
data is received by the client.

Connecting a Linux UTF-8 Client to a Win32 SHIFT-JIS Server

The server requires that everything is received as SHIFT-JIS. The
client requires that the server send everything as UTF-8.
To accomplish this, the client DSN settings in ODBC.INI (by default
in /usr/local/psql/etc) used to connect to the given database should
be set up as follows:
[dbclient]
Driver=/usr/local/psql/lib/libodbcci.so
Description=Pervasive ODBC Client Interface: JPN-
2000SERVER:1583/dbclient
ServerDSN=DEMODATA
ServerName=JPN-2000SERVER:1583
TranslationDLL=/usr/local/psql/lib/libxlate.so.10
TranslationOption=90010932

The TranslationDLL line specifies the translation library that the

ODBC client interface should use.
The TranslationOption line specifies that the translation needs to
occur from 9001 (representing UTF-8) to 0932 (representing SHIFT-
JIS).
Using this example, all data coming from the client will be translated
into SHIFT-JIS before it gets to the server, and to UTF-8 before the
data is received by the client.

Connecting a Linux EUC-JP Client to a Linux EUC-JP Server

Using this configuration, no changes to the DSN description are
needed. Use the DSN as it was created by the dsnadd utility.

10-22
 Data Encoding

Connecting a Linux UTF-8 Client to a Linux UTF-8 Server

Using this configuration, no changes to the DSN description are
needed. Use the DSN as it was created by the dsnadd utility. See
dsnadd in Pervasive PSQL User's Guide.

Connecting a Linux UTF-8 Client to a Linux EUC-JP Server

The server requires that everything is received as EUC-JP. The client
requires that server send everything as UTF-8.
To accomplish this, the client DSN settings in ODBC.INI (by default
in /usr/local/psql/etc) used to connect to the given database should
be set up as follows:
[dbclient]
Driver=/usr/local/psql/lib/libodbcci.so
Description=Pervasive ODBC Client Interface: JPN-
2000SERVER:1583/dbclient
ServerDSN=DEMODATA
ServerName=JPN-2000SERVER:1583
TranslationDLL=/usr/local/psql/lib/libxlate.so.10
TranslationOption=90019000

The TranslationDLL line specifies the translation library that the

ODBC client interface should use.
The TranslationOption line specifies that the translation needs to
occur from 9001 (representing UTF-8) to 9000 (representing EUC-
JP).
Using this example, all data coming from the client will be translated
into EUC-JP before it gets to the server, and to UTF-8 before the data
is received by the client.

Connecting a Linux EUC-JP Client to a Linux EUC-JP Server,

with SHIFT-JIS Encoding Used to Store Data on the Server
This situation is possible if you have a SHIFT-JIS database on a
Win32 engine, and you want to move all the files to the Linux EUC-
JP server. In this case, the database resides on a EUC-JP Linux
machine, but all the data inside the DDF files and data files are in
SHIFT-JIS.
In this case, your DSN should be set up as follows:
[dbclient]
Driver=/usr/local/psql/lib/libodbcci.so
Description=Pervasive ODBC Client Interface: JPN-
2000SERVER:1583/dbclient

10-23
Configuring Network Communications for Clients

ServerDSN=DEMODATA
ServerName=JPN-2000SERVER:1583
TranslationDLL=/usr/local/psql/lib/libxlate.so.10
TranslationOption=90000932
CodePageConvert=932

The last line specifies that even though the server uses EUC-JP
encoding, it should treat the data on the server as SHIFT-JIS.

10-24
 Using the DOS Requester

Using the DOS Requester

Pervasive PSQL v11 supports DOS Btrieve applications with the
DOS Requestor. The DOS requester supports Btrieve applications
only, not ODBC applications. This section explains how to use the
DOS requester to run Pervasive PSQL-based DOS applications in
Windows.
DOS Box support allows a DOS application to run in a DOS box on
a Windows platform. This enables direct communication to the
Windows 32-bit workstation components rather than to the
database engine. This configuration can be used with either a local
Pervasive PSQL Workgroup engine, or a remote engine. The TCP/IP,
SPX, or NetBIOS protocol supported for client/server access
depends on the configuration of the Windows 32-bit components.

Supported The DOS requester supports both Workgroup and Client to remote
Configurations Server engine configurations.

10-25
Configuring Network Communications for Clients

DOS Box Support on Windows

The Requester for Windows is BTRBOX. You can use this Requester
for DOS applications.

Running DOS All of the components needed to run DOS applications using
Applications on BTRBOX are installed with your client. After the Windows client
Windows 32-bit component installation, you have everything you need to run a DOS
Platforms or Windows 32-bit application. The default DOS application
support installed is the Win32 DOS Box configuration.
DOS applications are not supported on 64-bit Windows platforms.
Therefore, BTRBOX is not supported on 64-bit Windows platforms.

Using DOS Box Support

On Windows platforms, the DOS Box install configures the drivers
to be completely transparent. Thus, you are able to immediately
open a command prompt and run a DOS Btrieve application. The
CONFIG.NT file, located in the %WINDIR%\SYSTEM32 directory,
contains the command that enables DOS application support. This
file is similar to CONFIG.SYS in DOS. The Windows operating
system loads the driver for each DOS session opened. In the
configuration file, the install places the following path to load the
DOS Box driver:
DEVICE = C:\WINDOWS\SYSTEM32\BTRDRVR.SYS

10-26
 chapter

Application Configuration
Scenarios 11
Common Scenarios for Setting up Your Database Engine

This chapter explains the engine configuration settings necessary for

some common environment scenarios. The topics discussed in this
chapter include the following:
„ Terminal Services
„ Active Directory Service
„ Multiple Client Applications
„ Concurrent Local and Remote Applications
„ Accessing Data on Other Computers

11-1
Application Configuration Scenarios

Terminal Services
Microsoft Terminal Services is a multi session environment that
provides remote computers access to Windows-based programs
running on a server. Citrix MetaFrame extends Windows Terminal
Services with additional client and server functionality.

Disabling In prior releases, the ability to perform administrative functions was

Administrative prohibited from the client. In Pervasive PSQL v11, Pervasive PSQL
Functions clients running within Terminal Services client sessions can perform
Pervasive PSQL administrative functions by default. For example, a
user with such a client can change configuration settings for
Pervasive PSQL, create DSNs, and use the Monitor utility.
If you want to restrict this capability, intervention is necessary from
a system administrator.

³ To disable remote administrative functions for

Terminal Services clients
1 From PCC, open the properties for the MicroKernel Router
under Local Client.
See To access configuration settings in PCC for a local client in
Advanced Operations Guide.
2 On the Properties dialog, check Restrict Administrative
Functions from a WTS Client.
3 Click OK, then exit PCC and start it again for the setting to take
effect.

Note Pervasive PSQL Server engines are supported for use with
Microsoft Terminal Server and Citrix MetaFrame running
within an Active Directory environment.

Terminal Server You may use your terminal server as your main network server and
as Network database server. However, if you have high usage of the server as a file
Server server as well as many terminal sessions running at the same time,
you may find the performance less than satisfactory.

11-2
 Terminal Services

Another concern is having all of your mission critical services on the

same machine. If it goes down, all of your services go down at once.
For these reasons, you may wish to consider distributing your
mission critical services on two or more computers.

Workgroup You may configure your server to run the Workgroup engine as a
Engine service. This allows the engine to start automatically when the
Running as a operating system starts. A user is not required to log in to start the
Service engine. Refer to Running the Workgroup Engine as a Service.

Caution Running the engine as a service requires the Log On as

Service privilege. If you select to run the engine as a service
under a user account other than the default Local System
account, you will need to modify the Log On Properties for the
Service using the Windows Control Panel.

11-3
Application Configuration Scenarios

Active Directory Service

Active Directory is a central component of the network architecture
on certain Windows operating systems. Active Directory provides a
directory service specifically designed for distributed networking
environments.
This section describes how to configure Pervasive PSQL in an
environment that has Microsoft Active Directory service installed
and functioning correctly.
Ensure that Active Directory service is installed and functioning
correctly before you install Pervasive PSQL into the environment.

Server and Client Support

Pervasive PSQL Server runs on supported Windows Servers within
an Active Directory environment. The Pervasive PSQL clients run on
all supported Windows platforms within an Active Directory
environment.

Directory and File Permissions

The database engines enforce directory and file permissions set at the
operating system level. An Active Directory environment does not
change this behavior. For example, if you set “read only” permission
on a Pervasive PSQL table file, you will be unable to write to the
table.

Microsoft Terminal Services Support

Pervasive PSQL Server engines are supported for use with Microsoft
Terminal Server and Citrix MetaFrame running within an Active
Directory environment. For more information about Terminal
Services and Citrix MetaFrame, seeTerminal Services.

Pervasive Active Directory service manages the security of the network. You
Administrative must grant the correct access authority at the operating system level
Authority to users who need Pervasive administrative privileges.
See Active Directory Tasks for the steps to set access authority. Users
must have the following authority on the machine running the
database engine:

11-4
 Active Directory Service

„ Log on locally
„ Administrator privileges or belong to the Pervasive_Admin
group
You may grant the Log on locally authority directly to a user or to the
Pervasive_Admin group (and add the user to the group).
You may create the Pervasive_Admin group on the machine running
the database engine (the local machine), on the domain controller
for the local machine, or on both. The database engine checks
privileges first on the domain controller for the local machine then
on the local machine.
An example helps illustrate this. Suppose you have two servers in
your domain that run the Pervasive PSQL database engine, Server A
and Server B. You could create a Pervasive_Admin group on each
server and on the domain controller. You then add User 1 to the
group on Server A, User 2 to the group on Server B, and User 3 to the
group on the domain controller. User 1 has administrative privileges
for the database engine only on Server A. Similarly, User 2 has
administrative privileges only on Server B. User 3, however, has
administrative privileges for the database engines on both Server A
and Server B.
If you create the Pervasive_Admin group on a domain controller,
then the group must be a domain local group. If you create the
Pervasive_Admin group on a machine that is not a domain
controller, then the Pervasive_Admin group must be a local group.

Active This section explains the tasks needed to ensure users have Pervasive
Directory Tasks administrative privileges. The tasks assume the following:
„ Network user IDs have been added for users who need Pervasive
administrative privileges
„ A Pervasive_Admin group has been created on the domain
controller and users added to the group
„ Windows Server 2003 is the operating system on the domain
controller.

³ To Create the Pervasive_Admin Group on a Domain

Controller
1 Click Start Programs Administrative Tool Active
Directory Users and Computers.

11-5
Application Configuration Scenarios

2 Expand the tree for the domain to which you want to add the
Pervasive_Admin group.
For example, the following image shows the expanded tree for
the ADSTEST.com domain.

3 Right-click the Organizational Unit or folder that you are using

in your Active Directory environment to house groups, then
click New Group. For example, the following image shows an
Organizational Unit named “Groups,” but your Organizational
Unit may be named differently.

Note If your Active Directory environment does not have an

Organizational Unit to house groups, you need to create one.
Click the domain root (for example, in the figure above, you
would right-click ADSTEST.com), then click Action New
Organizational Unit. Type a meaningful name for the unit, then
click OK.

11-6
 Active Directory Service

4 For Group name, type Pervasive_Admin. Click Domain local

for group scope.

Note The Pervasive_Admin group must have a scope of Domain

local. Do not use Global or Universal.

5 Click OK.
Now that the Pervasive_Admin group exists, you need to add
users to it.
6 On the Active Directory Users and Computers window, right-
click the Pervasive_Admin group, then click Properties. (You
may also double-click the group.)

7 Click the Members tab on the Properties dialog box.

8 Click Add on the Members tab.
9 Click the user in the Name list that you want to add to the
Pervasive_Admin group, then click Add.

11-7
Application Configuration Scenarios

The user is added to the list on the bottom. For example, the
following image shows that user ADS_USER1 has been added.

10 Click OK.
The user you added now appears as a member of the
Pervasive_Admin group.

11 Click OK to exit the properties dialog box.

12 Add the Pervasive_Admin group to the Log on locally privileges
(complete the task To Grant Log On Locally Privileges to the
Pervasive_Admin Group).

³ To Grant Log On Locally Privileges to the

Pervasive_Admin Group
1 In the Windows Control Panel double-click Administrative
Tools, then double-click Domain Controller Security Policy.

11-8
 Active Directory Service

Note Ensure that you open Domain Controller Security Policy

and not Domain Security Policy.

2 Expand the following security settings:

Š Security Settings
Š Local Policies

3 Click User Rights Assignment.

4 Scroll the policies in the right pane until you locate Log on
locally.

11-9
Application Configuration Scenarios

5 Double-click the Log on locally policy (or right-click the policy

then click Security).
The Security Policy Setting dialog box appears.

6 Click Add.
The Add user or group dialog box displays.
7 Type Pervasive_Admin in the Users and group names field.

You may also specify the group by clicking Browse and

navigating to the group through dialogs.
8 Click OK.
The Security Policy Setting dialog appears with
Pervasive_Admin added.

11-10
 Active Directory Service

9 Click OK to exit the Security Policy Setting dialog.

10 Exit the Domain Controller Security Policy window.

11-11
Application Configuration Scenarios

Multiple Client Applications

Sometimes, two or more client/server applications may use the same
database engine. You will need to configure the database engine
differently depending on whether the applications are used at the
same time.
If your vendors supply configuration guidelines for engine
configuration parameters, you will need to adjust your configuration
based on these guidelines.

If the applications run concurrently (that is, if two or more applications are
using the database server at the same time) ...

You should configure the engine by adding together all the recommended values
for each parameter. For example, if one application vendor suggests Performance
Tuning | Number of Input/Output Threads should be set to 4, and another
application vendor suggests this parameter should be set to 8, then you should set
it to 12.

If the default value is higher than the sum of the recommended settings, then do
not change the default value.

Do not add up the recommended values for any buffer size settings, or log file size
settings. Use the largest recommended setting. Again, do not change the default if
it is larger than any vendor recommendation.

If the applications do not run concurrently (that is, if only one application is
running at any given point in time) ...

You should configure the server by using the largest recommended value for each
parameter. For example, if one application vendor suggests Performance Tuning
| Number of Input/Output Threads should be set to 4, and another application
vendor suggests this parameter should be set to 8, then you should set it to 8.

If the default value is higher than the largest recommended setting, then do not
change the default value.

Settings Most engine settings are not affected when you are running multiple
Affected by applications. This section explains the settings that may need to be
Multiple adjusted for multiple applications.
Applications
Compatibility | Create File Version
Some applications may require that new files be created with version
7.x file format, while other applications may require version 9.x file
format (the default).

11-12
 Multiple Client Applications

These applications can run concurrently only if new files are not
created during runtime. There is no way to toggle the setting back
and forth for each application, unless you wish to do it by hand or
write a program to do so using the Distributed Tuning Objects.
If the applications do not create new files during runtime, then this
setting is not relevant for multiple applications.

Data Integrity | Transaction Durability

Some applications may require durable transactions, while others
may not. If you have two application vendors recommending
different values for this parameter, then you should set it to On.
Generally, having transaction durability turned on does not affect
applications that do not use transactions, but may slow
performance.

11-13
Application Configuration Scenarios

Concurrent Local and Remote Applications

The Server engine allows both remote client requests as well as
communications from applications running on the same computer
as the server.

Note To perform these steps, you must have full administrator-

level rights on the machine where the database engine is
running, or be a member of the Pervasive_Admin group defined
on the machine where the database engine is running.

³ To configure database connections from both remote

and local applications

Tip When changing the Server engine settings, you must be at

the Windows server computer where the database server runs.

1 Click Control Center from the Pervasive program on the Start

menu.
2 In the Pervasive PSQL Explorer, expand Engines to display the
engines registered with Pervasive PSQL Control Center.
3 Right-click the target engine and click Properties. Login if
prompted.
4 Click Access. In the right-hand pane, select the Accept Remote
Requests check box.
If you wish to prevent the server from accepting client
connections from other computers, clear the check box.
5 Click OK.
This configures the server to accept remote requests.
6 In the Pervasive PSQL Explorer, expand Local Client.
7 Right-click MicroKernel Router and click Properties. Login if
prompted.
8 Click Access. In the right-hand pane, select the following check
boxes:

11-14
 Concurrent Local and Remote Applications

Š Use Local MicroKernel Engine. Select this check box to

configure the local engine for local file access.
Š Use Remote MicroKernel Engine. Select this check box to
access databases on other computers.
If you plan to only access data on this computer, clear this
check box.
9 Click OK.
This configures the server to accept local requests.
10 Restart the server engine to implement the changes.

Using the The Workgroup engine can be configured to access files on a remote
Server and file server through a mapped drive on a Windows server.
Workgroup The client software installed with your Workgroup engine can be
Engines used to connect to other server engines on a remote machine.
Concurrently
If you want to use your local engine for local file access and a remote
server for access to files being serviced by the remote Pervasive server,
you must change the settings in your MicroKernel Router. Use the
Pervasive PSQL Control Center to change MicroKernel Router
settings.

³ To configure local and remote access for the

MicroKernel Router
1 On the Start menu select Control Center (PCC) from the
Pervasive PSQL v11 program group.
2 In the Pervasive PSQL Explorer window, expand Local Client.
3 Right-click MicroKernel Router and click Properties. Login if
prompted.
4 Click Access. In the right-hand pane, select the following check
boxes:
Š Use Local MicroKernel Engine. Select this check box to
configure the local engine for local file access.
Š Use Remote MicroKernel Engine. Select this check box to
configure the remote server for access to files being serviced
by the remote Pervasive server.
5 Click OK.

11-15
Application Configuration Scenarios

Note See Advanced Operations Guide for more information on

changing settings using the Pervasive PSQL Control Center.

11-16
 Accessing Data on Other Computers

Accessing Data on Other Computers

The Workgroup engine provides great flexibility for a variety of small
networked environments. The table below explains the most
common configurations and where to look for more information. In
any of the configurations below, a Workgroup engine must be
installed on every computer that is expected to access data.
Table 11-1 Summary of Network Configurations

Configuration Where to look for more information

Small client/server: Setting Up a Small Client/Server

Data resides on a single computer where Configuration
a Workgroup engine is installed.

Peer-to-Peer: Setting Up a Peer-to-Peer

Data resides on two or more computers Configuration
where Workgroup engines are installed.

Gateway: Setting Up a Gateway Configuration

Data resides on a file server where no
database engine is installed, or it is not
running.

11-17
Application Configuration Scenarios

11-18
 chapter

Installing Pervasive PSQL

for Linux 12
Instructions for Installing and Uninstalling Pervasive PSQL on Linux

This chapter explains how to install and uninstall Pervasive PSQL:

„ Before You Install Pervasive PSQL for Linux
„ Installing Pervasive PSQL Using RPM
„ Installing Pervasive PSQL Using TAR
„ After Installing Pervasive PSQL for Linux
„ Uninstalling Pervasive PSQL for Linux

12-1
Installing Pervasive PSQL for Linux

Before You Install Pervasive PSQL for Linux

Before installing or upgrading any of the Pervasive PSQL products,
review the following information:
„ System requirements listed on the Pervasive Software Web site
for Pervasive PSQL v11.
„ Chapter 2, Preparing to Install Pervasive PSQL– This chapter
provides important information including platform specific
notes.
„ Release Notes – The release notes are located in readme.htm on
the distribution media and contain late-breaking news that may
not be included in the user documentation.
You must be logged in as root to install any of the products. If you are
installing from the CD, you must be at the CD root directory.
If you have any trouble with an installation, see Troubleshooting
After Installation.

Server If you are planning to access the Pervasive PSQL transactional

interface across a network from a Windows-based client using drive
mappings, we recommend that the Samba package be installed on
the server. Please refer to the Samba website, http://www.samba.org,
for installation and configuration instructions.
After installing Pervasive PSQL Server, review Supported Path
Formats for Samba for information regarding Samba’s path
configuration.

Client The Linux client can be installed on a Linux machine with no

Pervasive PSQL products currently installed, or on a Linux machine
with a Pervasive PSQL v11 Server engine installed.
If your database server engine does not match certain installation
requirements, your applications may receive the following status
code: “status 3031: Linux requester cannot connect to this server.”
This status code indicates client/server incompatibility. In some
cases, you may receive a permissions error status instead: “94: The
application encountered a permission error.”
The installation scripts perform the following tasks:
„ Verify necessary permissions to complete install

12-2
 Before You Install Pervasive PSQL for Linux

„ Create user psql and group pvsw (if they do no exist)

„ Sets user:group ownership to psql:pvsw for the installed files (if
not already set)

Full Pervasive PSQL offers full installations of both the RPM and TAR
Installations Linux packages. A full installation includes the necessary engine and
client files, utilities, and the complete user documentation. A full
installation does not include the word “full” in the package name.
The following table outlines the installation packages.
Table 12-1 Full and Client Linux Installations

Pervasive PSQL Installation Contains

Product Type

Server 64-bit Full Engine and client files, utilities, and

documentation

Server 32-bit Full Engine and client files, utilities, and

documentation

Client 64-bit Client Client files1

Client 32-bit Client Client files, utilities, and documentation

1
Because of the minimal files included in the 64-bit client, the installation
package name includes the word “core.”

12-3
Installing Pervasive PSQL for Linux

Installing Pervasive PSQL Using RPM

The RPM format allows you to install Pervasive PSQL if your Linux
distribution contains the Red Hat Package Manager (RPM). Version
4 or greater of RPM is required.
This section explains how to install the following Pervasive PSQL
products using RPM:
„ Installing Pervasive PSQL Server for Linux - RPM
„ Installing the Pervasive PSQL Client for Linux - RPM
If you have any trouble with installation, see the chapter
Troubleshooting After Installation.

Installing Determine the package name to use for the installation using the
Pervasive following table and the distribution media.
PSQL Server Table 12-2 Linux Server Package Names - RPM
for Linux - RPM
Installation Package Name
Type

Server 64-bit Pervasive.SQL-yy.yy-zzz.zzz.x86_64.rpm

Server 32-bit Pervasive.SQL-yy.yy-zzz.zzz.i486.rpm

In all cases, the yy.yy designates a release number and zzz.zzz

designates a build number. Refer to the distribution media for the
actual name of the package.
Installation is categorized as either first time, in which no previous
version exists, or upgrade, in which a previous version exists.
„ First Time Installation
„ Upgrade Installation

First Time Installation

The package manager copies all necessary files onto disk (default
location is /usr/local/psql) and runs a post-installation script
which performs the following tasks:
„ Creates user psql and group pvsw
„ Sets user:group ownership to psql:pvsw for the installed files

12-4
 Installing Pervasive PSQL Using RPM

„ Applies a trial license

„ Creates a new ODBC DSN (data source name) for the
DEMODATA test database
„ If Samba configuration file is found
Š Creates a new Samba share PSQLDATA
Š Creates a new Samba share PVPIPE$
„ Creates startup/shutdown scripts for Pervasive PSQL daemons
„ Launches the Pervasive PSQL daemon (mkded)

³ To install Pervasive PSQL Server using RPM

Note If you have a previous version of Pervasive PSQL on your Linux

machine, see Upgrade Installation.

1 Log in as the root user.

2 Assuming the RPM package is in the current directory, enter the
following command:
rpm -ivh <Linux_Server_Package_Name>

Note Refer to Linux Server Package Names - RPM for the package
name to use. You must include the appropriate release and build
number information to perform the installation. Verify the complete
package name from the distribution media.

If the RPM package is in another directory, preface the package

name with a path.

Upgrade Installation
If you have a previous version of Pervasive PSQL already installed,
you must uninstall that product and then install the Pervasive PSQL
v11 product.
See Uninstalling Pervasive PSQL for Linux for information on
uninstalling Pervasive PSQL.

12-5
Installing Pervasive PSQL for Linux

Installing the The name of the Pervasive PSQL Client installation package
Pervasive conforms to the following conventions:
PSQL Client for Table 12-3 Linux Client Package Names - RPM
Linux - RPM
Installation Package Name
Type

Client 64-bit Pervasive.SQL-Client-Core-yy.yy-zzz.zzz.x86_64.rpm

Client 32-bit Pervasive.SQL-Client-yy.yy-zzz.zzz.i486.rpm

In all cases, the yy.yy designates a release number and zzz.zzz

designates a build number. Refer to the distribution media for the
actual name of the package.
Installation is categorized as either first time, in which no previous
version of the product exists, or upgrade, in which a previous version
of the product exists.
„ First Time Installation
„ Upgrade Installation

First Time Installation

³ To install Pervasive PSQL Client Using RPM

1 Log in as the root user.
2 Assuming the RPM package is in the current directory, execute
the following command.
rpm -ivh <Linux_Client_Package_Name>

Note Refer to Linux Client Package Names - RPM for the package
name to use. You must include the appropriate release and build
number information to perform the installation. Verify the complete
package name from the distribution media.

If the RPM package is in another directory, preface the package

name with a path.

12-6
 Installing Pervasive PSQL Using RPM

Upgrade Installation
If you have a previous version of Pervasive PSQL already installed,
you must uninstall that product and then install the Pervasive PSQL
v11 product.
See Uninstalling Pervasive PSQL for Linux for information on
uninstalling Pervasive PSQL.

12-7
Installing Pervasive PSQL for Linux

Installing Pervasive PSQL Using TAR

The tape archive (TAR) format allows you to install Pervasive PSQL
if you have a Linux distribution that does not support the RPM
format or if you prefer not to use RPM.
This section explains how to install the following Pervasive PSQL
products using TAR:
„ Installing Pervasive PSQL Server for Linux - TAR
„ Installing Pervasive PSQL Client for Linux - TAR
If you have any trouble with installation, see the chapter
Troubleshooting After Installation.

Installing The name of the Pervasive PSQL Server installation package

Pervasive conforms to the following conventions.
PSQL Server Table 12-4 Linux Server Package Names - TAR
for Linux - TAR
Installation Package Name
Type

Server 64-bit Pervasive.SQL-yy.yy-zzz.zzz.x86_64.tar.gz

Server 32-bit Pervasive.SQL-yy.yy-zzz.zzz.i486.tar.gz

In all cases, the yy.yy designates a release number and zzz.zzz

designates a build number. Refer to the distribution media for the
actual name of the package.
Installation is categorized as either first time, in which no previous
version exists, or upgrade, in which a previous version exists.
„ First Time Installation
„ Upgrade Installation

First Time Installation

³ To install Pervasive PSQL Server using TAR

1 Log in as the root user.
2 Change to the /usr/local directory.
cd /usr/local

12-8
 Installing Pervasive PSQL Using TAR

3 Enter the following command to copy the tar into /usr/local.

cp <path_to_tar>/<Linux_Server_Package_Name> .

Note Refer to Linux Server Package Names - TAR for the package
name to use. You must include the appropriate release and build
number information to perform the installation. Verify the complete
package name from the distribution media.

For example, if you downloaded the installation package into the

/home/bholly directory:
cp /home/bholly/<Linux_Server_Package_Name> .

4 Unpack the tar using the following command.

tar -xzf <Linux_Server_Package_Name>

5 Change directories to the /usr/local/psql/etc folder where the

installation scripts reside.
cd psql/etc

6 Run the pre-installation script:

sh preinstall.sh

7 Run the post installation script:

sh postinstall.sh

Your tar installation is complete. For additional information, see

After Installing Pervasive PSQL for Linux.

Upgrade Installation
If you have a previous version of Pervasive PSQL already installed,
you must uninstall that product and then install the Pervasive PSQL
v11 product.
See Uninstalling Pervasive PSQL for Linux for information on
uninstalling Pervasive PSQL.

12-9
Installing Pervasive PSQL for Linux

Installing The name of the Pervasive PSQL Client installation package

Pervasive conforms to the following conventions:
PSQL Client for Table 12-5 Linux Client Package Names - TAR
Linux - TAR
Installation Package Name
Type

Client 64-bit Pervasive.SQL-Client-Core-yy.yy-zzz.zzz.x86_64.tar.gz

Client 32-bit Pervasive.SQL-Client-yy.yy-zzz.zzz.i486.tar.gz

In all cases, the yy.yy designates a release number and zzz.zzz

designates a build number. Refer to the distribution media for the
actual name of the package.
Installation is categorized as either first time, in which no previous
version exists, or upgrade, in which a previous version exists.
„ First Time Installation
„ Upgrade Installation

First Time Installation

³ To install Pervasive PSQL Client using TAR

1 Log in as the root user.
2 Change to the /usr/local directory.
cd /usr/local

3 Enter the following command to copy the tar into /usr/local.

cp path_to_tar/<Linux_Client_Package_Name> .

For example, if the installation package resides in the /home/

bholly directory:
cp /home/bholly/<Linux_Client_Package_Name> .

Note Refer to Linux Client Package Names - TAR for the package
name to use. You must include the appropriate release and build
number information to perform the installation. Verify the complete
package name from the distribution media.

12-10
 Installing Pervasive PSQL Using TAR

4 Unpack the tar using the following command.

tar -xzf <Linux_Client_Package_Name>

The unpacking action creates a directory named “psqlclient.”

5 Change directories to the /usr/local/psql/etc folder where
the Pervasive PSQL installation scripts reside.
cd psql/etc

6 Run the pre-installation script:

sh clientpreinstall.sh

7 Run the post installation script:

sh clientpostinstall.sh

Your tar installation is complete. For additional information, see

After Installing Pervasive PSQL for Linux and Configuring Network
Communications for Clients.

Upgrade Installation
If you have a previous version of Pervasive PSQL already installed,
you must uninstall that product and then install the Pervasive PSQL
v11 product.
See Uninstalling Pervasive PSQL for Linux for information on
uninstalling Pervasive PSQL for more information.

12-11
Installing Pervasive PSQL for Linux

After Installing Pervasive PSQL for Linux

The following topics are useful to review after you install Pervasive
PSQL:
„ Verifying Installed Products With RPM
„ Server Configuration
„ Client Configuration
„ User Count License
„ Common Questions After Installation

Verifying The following table provides commands with which you can verify
Installed which packages the RPM packager installed. The commands are case
Products With sensitive.
RPM Table 12-6 RPM Commands To Verify Pervasive PSQL Packages Installed

Pervasive PSQL Package RPM Command to Verify Installation

Server rpm -q Pervasive.SQL

Client rpm -q Pervasive.SQL-Client

The command returns the specific client version

installed (Pervasive.SQL-Client-release-build).

All installed rpm -qa | grep Pervasive

Verifying Optionally, after the installation script finishes, you can verify that
Database the database engine is running with the Linux ps utility. Type the
Engine is following at the command line:
Running ps -e | egrep mkded

Server Generally, the default configuration settings for Pervasive PSQL

Configuration Server are sufficient. See Configuration for settings that you may
want or need to set.
If you want to explore all of the configuration settings, see the
chapter Configuration Reference in Advanced Operations Guide.

Client All configuration settings for the Linux client are discussed in Linux
Configuration Client Configuration Parameters in the Advanced Operations Guide.

12-12
 After Installing Pervasive PSQL for Linux

In this guide, see also Installing Pervasive PSQL Clients for Windows
and Configuring Network Communications for Clients for
additional information about clients.

Linux Clients and the Monitor Utility

This information applies only to Linux clients that use a static IP
address. Ignore this subsection if you use DHCP and have a DSN to
resolve named addresses.
When you monitor Linux clients using the Pervasive PSQL Monitor
utility, the client IP address that gets transmitted across the network
originates from the “hosts” file. If the system name and IP have not
been added to the “hosts” file, network communication uses the
local host's IP address, which is 127.0.0.1 or ::1 (a loopback address).
If you change the loopback address to the correct IP, or if you add the
system’s name and IP to the “hosts” file on the Linux client, the client
name correctly displays when in the Monitor utility.

User Count Once you have completed installation, you may need to update your
License user count license by using the clilcadm utility. The update can be
done anytime before using Pervasive PSQL from a client.
Information about how to do this can be found in Pervasive PSQL
User's Guide (see License Administration). Detailed information
about clilcadm can also be found in the Linux man pages. The
Pervasive PSQL User's Guide also explains clilcadm (see clilcadm and
w64clilcadm).

Note You must be a member of group pvsw to run the clilcadm utility.
See Pervasive PSQL Account Management on Linux for more
information.

Common If you are have problems with your installation, see Troubleshooting
Questions After After Installation or get help online from the Pervasive Knowledge
Installation Base at the Pervasive Web site. The following are common questions
after installation of the products:
„ Where Do Files Reside After Installing Pervasive PSQL?
„ How Do I Access the Documentation?
„ What If I Get Errors Trying To Start the Utilities?

12-13
Installing Pervasive PSQL for Linux

Where Do Files Reside After Installing Pervasive PSQL?

The following table lists the primary directories and files that result
from installing the Pervasive PSQL products on Linux.
$PVSW_ROOT refers to the root directory where the files are
installed. By default it is set to /usr/local/psql. Unless otherwise
noted, the primary directories and files are the same for 32-bit and
64-bit products.
For an upgrade installation, your existing Pervasive PSQL files were
updated to the latest versions.
Table 12-7 Primary Directories and Files for Pervasive PSQL Products Installed on Linux

Path from Primary Files Description Applies to

$PVSW_ROOT Installation of

./ LICENSE License information Server

./bin Binary files, executable utilities and so forth Server and Client

./bin/plugins A directory pertaining to files for the utilities and Server and Client
documentation

./data/DEMODATA Sample Pervasive PSQL database Server

./data/samples Sample Btrieve files, alternate collating Server

sequence file and the DefaultDB system
database

./etc Server and Client

.PSRegistry Pervasive registry of configuration settings (this Server

directory and its subordinate directories)

btpasswd User passwords file Server

dbnames.cfg Master table of database names Server

odbc.ini ODBC settings Server and Client

Shell scripts for the following: Server and Client

‹ pre-product installation

‹ post-product installation

‹ pre-product uninstall

‹ post-product uninstall

./lib Library of 32-bit shared objects Server and Client

12-14
 After Installing Pervasive PSQL for Linux

Table 12-7 Primary Directories and Files for Pervasive PSQL Products Installed on Linux

Path from Primary Files Description Applies to

$PVSW_ROOT Installation of

./lib64 Library of 64-bit shared objects Server and Client

Note: This directory exists only if you install the

64-bit Server or Client

./log Transaction log files directory Server and Client

./man/man1 Man pages for the command-line utilities Server and Client

How Do I Access the Documentation?

The documentation installed with Pervasive PSQL Server includes
the following:
„ Man pages for the command-line utilities
„ Pervasive PSQL Documentation Library
„ Pervasive PSQL Release Notes

Man Pages
Man pages are provided for the command-line utilities. To make
these man pages available, add $PVSW_ROOT/man to your MANPATH
environment variable.
Note that the man pages are installed with Pervasive PSQL Server
and with Pervasive PSQL Client. They are not installed as part of the
user documentation.

Documentation Library
The Pervasive PSQL Documentation Library contains the complete
set of user documentation, including the user documentation for the
Pervasive PSQL engine and software developer’s kit, as well as a
glossary of database terminology.

³ To view the Pervasive PSQL Documentation Library

1 Open a terminal window.
2 Run one of the following:
a. As root user
/usr/local/psql/bin/pcc

12-15
Installing Pervasive PSQL for Linux

b. As the psql user

pcc

Note that the viewer for the documentation library is integrated into
Pervasive PSQL Control Center (PCC). The documentation library
is accessed through the PCC interface on the Welcome view, in the
Help menu, by pressing F1 (Windows) or Shift F1 (Linux).

Release Notes
The release notes in readme.htm contain late-breaking news that
could not be included as part of the user documentation. The release
notes file is located in the /usr/local/psql/docs/ directory.

What If I Get Errors Trying To Start the Utilities?

See Starting PCC On Linux in Pervasive PSQL User's Guide and
Starting DDF Builder from a Command Line in DDF Builder User’s
Guide.

12-16
 Uninstalling Pervasive PSQL for Linux

Uninstalling Pervasive PSQL for Linux

This section explains how to uninstall the RPM and TAR
distributions of Pervasive PSQL.

RPM Version The following table lists the RPM commands to uninstall the various
Pervasive PSQL packages. You must log in as the root user using the
“su” command before executing any of the commands.
Table 12-8 RPM Commands to Uninstall the Pervasive PSQL Packages

To Uninstall This Package Use This RPM Command

32-bit Server or 64-bit Server rpm -e Pervasive.SQL

32-bit Client or 64-bit Client rpm -e Pervasive.SQL-Client

Note The uninstall program does not remove the system databases
DEFAULTDB and SYSTEMDB.

TAR Version The following table lists the shell scripts used to uninstall the various
Pervasive PSQL packages. You must log in as the root user using the
su command before executing any of the commands.

Table 12-9 TAR Commands to Uninstall the Pervasive PSQL Packages

Package To Uninstall Script(s) To Execute1,2

32-bit Server or 64-bit Server sh preuninstall.sh

sh postuninstall.sh

Note: The scripts must be executed in

sequence: preuninstall first followed by
postuninstall.

12-17
Installing Pervasive PSQL for Linux

Table 12-9 TAR Commands to Uninstall the Pervasive PSQL Packages

Package To Uninstall Script(s) To Execute1,2

32-bit Client or 64-bit Client sh clientpreuninstall.sh

Note: If you have both 32-bit and sh clientpostuninstall.sh

64-bit Clients installed, see the
following section. Note: The scripts must be executed in
sequence: clientpreuninstall first
followed by clientpostuninstall.

1
Assumes that the scripts are executed from the directory where they reside:
/usr/local/psql/etc
2
You may want to remove the uninstall scripts themselves after the product
is uninstalled. For example:

rm preunistall.sh
rm postunistall.sh
rm client*.sh

Uninstalling Both 32-bit and 64-bit Clients

If you have installed both the 32-bit and 64-bit clients on your
machine, you may uninstall one or both by passing the architecture
option with the uninstall script. Running the scripts without any
architecture option removes both clients, as the default option is to
remove both clients.

Example
To uninstall only the 64-bit client you would run the following:
/usr/local/psql/etc.clientpreuninstall.sh -a x86_64
/usr/local/psql/etc/clientpostuninstall.sh -a x86_64

The 32-bit client remains fully operational.

To uninstall only the 32-bit client you would run the following:
/usr/local/psql/etc.clientpreuninstall.sh -a x86
/usr/local/psql/etc/clientpostuninstall.sh -a x86

The 64-bit client remains fully operational.

To uninstall both the 32-bit and 64-bit clients you would run the
following:
/usr/local/psql/etc.clientpreuninstall.sh
/usr/local/psql/etc/clientpostuninstall.sh

12-18
 chapter

Using Pervasive PSQL on

Linux 13
Working With the Products on Linux

The chapter contains the following sections:

„ Finding What You Need
„ Pervasive PSQL Account Management on Linux
„ Configuration
„ Client Information
„ Setting Up Web-based Data Access
„ Using Perl and ODBC with Pervasive PSQL

13-1
Using Pervasive PSQL on Linux

Finding What You Need

Accessing the See How Do I Access the Documentation?.
User
Documentation

Man Pages The man pages are installed with Pervasive PSQL Server or Client.
Refer to the directory $PVSW_ROOT/man/man1for the man pages
available.
To make these man pages easily accessible, add $PVSW_ROOT/man to
your MANPATH environment variable. If you need more detailed
information on a utility or application, see the chapter Command
Line Interface Utilities Pervasive PSQL User's Guide.

Note Check the man pages for the most current information. Every
effort is made to ensure that the information in this guide matches that
in the man pages. On occasion, last-minute changes may be included
in the man pages after this guide has been published.

Exclusions Because the Linux platform is unique, the following areas in the
Pervasive PSQL documentation do not apply to Linux.
„ The section Pervasive PSQL Event Logging in Advanced
Operations Guide regarding differs for Pervasive PSQL v11 on
Linux.
Pervasive PSQL v11 uses the standard Linux logging system.
Depending on the configuration of /etc/syslog.conf,
messages are sent to the syslogd daemon, which does one of the
following:
Š logs it in an appropriate system log
Š writes it to the system console
Š forwards it to a list of users
Š forwards it to syslogd on another host over the network
More information can be found in the man pages for syslogd
and syslog.conf.

13-2
 Finding What You Need

„ The chapter, Manipulating Btrieve Data Files with Maintenance

of the Advanced Operations Guide works only on the Windows
client for Pervasive PSQL v11.

13-3
Using Pervasive PSQL on Linux

Pervasive PSQL Account Management on Linux

This section discusses information on Linux user accounts with
respect to operation of Pervasive PSQL.

After „ User psql has no password and can only be accessed through the
Installation root account by using the su command.
Behavior „ You can access the .bash_profile for user psql with ~psql/
.bash_profile.
„ All Pervasive files have user:group ownership psql:pvsw
„ You must be logged in as root to run the start and stop scripts
for the Pervasive PSQL engines.
„ You can run utilities on other user accounts if you add the
necessary environment variables to the user .bash_profile or
system /etc/profile as described in Using Utilities from Users
Other than psql.
„ In addition to the instructions outlined in Using Utilities from
Users Other than psql, users other than ROOT must be a
member of the group pvsw to perform functionality with the
following utilities:
Š Pervasive PSQL Control Center (PCC) to administer the
local server.
Š License Administrator utility (clilcadm) for functions
other than displaying current licenses.
Š Named Database Maintenance utility (dbmaint) for
functions other than displaying current databases.
Š Pervasive Services Registry Editor (psregedit) for
functions other than displaying the registry.
Š Linux command-line configuration (bcfg).

The User The single environment variable $PVSW_ROOT is used to determine

Environment the location of installed components. The generic location for
configuration files are $PVSW_ROOT/etc. For executable files, the
location is $PVSW_ROOT/bin. For shared libraries (32-bit) the
location is $PVSW_ROOT/lib; for shared libraries (64-bit) the
location is $PVSW_ROOT/lib64.

13-4
 Pervasive PSQL Account Management on Linux

It is recommended that you add $PVSW_ROOT/bin to your PATH

environment variable, and $PVSW_ROOT/lib to LD_LIBRARY_PATH as
described in the following section.

Using Utilities To use utilities from user accounts other than psql, you must first
from Users make modifications to the user account configuration. Add the
Other than psql following to either the profile for a specific user or to the profile that
all users inherit.

/home/username/ Profile for the user. Similar to the /etc/

.bash_profile profile file but only for the current user.

Look in /home/username for this file.

/etc/profile Default profile for all user accounts on

the system. Copy the lines below into
this text file if you want all user accounts
on the machine to have access to
Pervasive PSQL utilities.

This does not give the users

administrative privileges or access to
Pervasive PSQL data.

Here is an example of a modified profile:

PVSW_ROOT=/usr/local/psql
PATH=$PATH:$PVSW_ROOT/bin:/bin:/usr/bin
LD_LIBRARY_PATH=$PVSW_ROOT/lib:$PVSW_ROOT/bin:/usr/lib
MANPATH=$MANPATH:$PVSW_ROOT/man

Ensure that you export all variables specific to Pervasive PSQL.

13-5
Using Pervasive PSQL on Linux

Configuration
Generally, the default configuration settings for Pervasive PSQL
Server and Client are sufficient. You typically do not have to
configure any settings for the database engine and clients to
communication and function together correctly. This subsection
discusses two settings that you may want or need to configure:
„ Configuration File
„ Authentication
If you want to explore all of the configuration settings, see the
chapter Configuration Reference in Advanced Operations Guide:

Configuration The Server configuration setting “Configuration File” defines the

File path to the Samba configuration file (smb.conf), which is parsed on
engine startup to determine mapping between share names and
server directory locations. See Configuration File (Linux engines
only) in Advanced Operations Guide.

Authentication This option specifies which type of authentication to use for access
to the server engine. The available options are:
„ Emulate Workgroup Engine. Use this value when Samba is used
to authenticate user access on the system.
„ Proprietary Authentication (using btpasswd). Use this value
when not using Samba and the user does not have an account on
the server. This allows a separate password file to be maintained
when connecting to the Linux system.
„ If you are using BTPASSWD or PAM authentication on your
Linux server, user names and passwords must be set up using the
pvnetpass utility from clients connecting to this server. See
pvnetpass in the Pervasive PSQL User's Guide.
„ Standard Linux Authentication. Use this value when not using
Samba but users have accounts on the Linux system.

Supported Path From a Pervasive PSQL Client on a Windows platform, the order of
Formats for path parsing is as follows:
Samba „ \\server\share\relative\path

13-6
 Configuration

share denotes a valid Samba share, made accessible to a

Windows client.
server reads smb.conf to determine the absolute path to the
shared directory, then combines it with the relative path to get a
full UNIX path. The location of smb.conf is essential for valid
resolution of the file path supplied in this format on the client. If
the relative path is not correct, status 12 is returned.
„ Drive:\path
drive must be a Samba drive mapped on the client. It is the
client responsibility to convert it into the latter format and pass
to a server, which never knows a drive mapping on the client.

Note Client users must be advised that share names on a Linux server
are case sensitive. When mapping drives to a Linux server they must
pay careful attention to the case of the share name if they want all their
utilities to work properly.

„ If neither smb.conf nor the share name are found, the path
defaults to \\server\absolute\path format. If the absolute
path is not correct, status 12 is returned.

13-7
Using Pervasive PSQL on Linux

Client Information
A Pervasive PSQL Client on Linux can connect to any of the
Pervasive PSQL Servers provided the client and server machines can
communicate with a shared protocol.

Authentication To connect to a remote machine using the Linux client, you need to
to Remote have authentication to the remote machines. This is accomplished by
Machines entering a specific username and password for the server using the
pvnetpass utility. This utility stores the username and password in
an encrypted format for that particular server in the Pervasive
registry on the client machine. If you do not specify user names and
passwords, your applications can receive status code 3119.
See pvnetpass in Pervasive PSQL User's Guide.

Creating a A client data source name (DSN) is required if applications on the

Client DSN client use the Pervasive PSQL relational interface through ODBC. To
create a client DSN, you use the dsnadd utility included with the
Pervasive PSQL Client for Linux. See dsnadd in Pervasive PSQL
User's Guide and the man page for dsnadd located in /usr/local/
psql/man/man1.

13-8
 Setting Up Web-based Data Access

Setting Up Web-based Data Access

This section contains information about configuring web servers to
provide access to Pervasive PSQL data and provides connection
snippets and samples for connecting to Pervasive PSQL data from
web applications on Linux.

ODBC Behavior When you first install Pervasive PSQL, the odbc.ini file is written to
/usr/local/psql/etc
If you have other ODBC driver managers such as unixODBC, they
might be using a different odbc.ini file located, for example, at /etc/
odbc.ini.
One way to unify the ODBC setup is to add soft links from where
unixODBC expects the odbc.ini file to be located over to the
Pervasive PSQL directories.
su
cd /etc
ln -s /usr/local/psql/etc/odbc.ini

Configuring This section shows how you should set up the machine where the
Web Server web server such as Apache resides.
You should make the user account under which you run any web
server such as Apache a member of the group pvsw. These user
accounts run under restricted accounts such as nobody
To find the user account, see your Apache configuration file,
typically located at /etc/httpd/conf/httpd.conf
In this file, the following lines show what user the Apache server uses
to operate under.
User nobody
Group nobody
Options ExecCgi Indexes

You should add this user to the pvsw group, substituting the name
used in your Apache configuration file.
/usr/bin/gpasswd -a nobody pvsw

13-9
Using Pervasive PSQL on Linux

PHP PHP allows for easy development of web applications, using a style
that is similar to both ASP in the Microsoft world and JSP in the Java
world. Using PHP, you enclose database calls in special tags and
format the output using HTML.

Pervasive PSQL PHP Requirements

„ PHP - obtain from http://www.php.net
„ DSN pointing to the database (use dsnadd)

PHP Connection Snippet

This code segment shows the essential part of connecting to a
Pervasive PSQL database using PHP.
// connect to DEMODATA database no uid or password
$connect = odbc_connect("demodata", "", "");

// set the query variable to your SQL

$query = "SELECT * from Department";

// obtain a result object for your query

$result = odbc_exec($connect, $query);

PHP Sample
This complete sample presents the user a choice of three
DEMODATA tables and then displays the table.
<HTML>
<HEAD>
<TITLE>PVSW PHP Sample</TITLE>
</HEAD>
<BODY>

<H1>Pervasive Hello World Samples - PHP using PHP

ODBC APIs)</H1>
<P>
This sample will display the DEMODATA database
tables in the following drop-down
by using PHP.
</p>

<?

// -------MAIN MENU----------------------------

// if there is no function specified in the URL

13-10
 Setting Up Web-based Data Access

if (!(isset ($HTTP_GET_VARS["_function"]))):

// --------------------------------------------

?>

<p>Please select from the following tables</p>

<form method=post
action='<?=$PHP_SELF?>?_function=showtable'>
<select name="selecttable">
<option SELECTED value="Department">Department
<option value="Course">Course
<option value="Room">Room
</select>

<p>
<input type=submit value="Show table">
</p>
</form>

<?

// ------SHOWTABLE-----------------------------

Elseif ($HTTP_GET_VARS["_function"] ==
"showtable"):

// --------------------------------------------

print("<p>Return to <a href='$PHP_SELF'>Sample 1

Main menu</a></p>");

$thetable = $HTTP_POST_VARS["selecttable"];
// determine from FORMS data which table to open

$connect = odbc_connect("demodata", "", "");

// connect to DEMODATA database no uid or password
$query = "SELECT * from $thetable";
// set the query variable to contain the SQL you
// want to execute
$result = odbc_exec($connect, $query);
// perform the query

// print out the entire resultset as HTML table

// (uncomment following line)
// odbc_result_all($result);

// or format the output yourself and display

13-11
Using Pervasive PSQL on Linux

// a nicer table (but more code required)

// initialize row counter

$i = 0;

// determine number of columns

$numcols = odbc_num_fields($result);

// start HTML table

print("<table border=1 cellpadding=5>");

// PRINT COLUMN HEADINGS

print("<tr>"); // start of row

while ($i < $numcols)

{
$i++;
$colname = odbc_field_name($result, $i);
print("<th>$colname</th>");
}
$i=0;

print("</tr>"); // end of row

// PRINT TABLE DATA

// while there are still rows

while(odbc_fetch_row($result))
{
print("<tr>"); // start row

while ($i < $numcols)

{
$i++;
$tablecell = odbc_result($result, $i);
print("<td>$tablecell</td>");
}

print("</tr>"); // end row

$i = 0; // reset counter

} // end odbc_fetch_row

print("</table>"); // end HTML table

odbc_close($connect); // CLOSE THE CONNECTION

13-12
 Setting Up Web-based Data Access

// END OF SHOWTABLE

// ---CATCH INVALID MENU OPTIONS-----------------

Else:

// ----------------------------------------------

print("<p>An Invalid function was entered. Please

<a href='$PHP_SELF'>try again</a>.</p>");

Endif;

?>
</BODY>
</HTML>

Additional PHP Sample

A more comprehensive PHP sample application that simulates the
operations of a video store is available online at the Pervasive
Software Web site.
This sample uses the Pvideo database that is included with the
Pervasive PSQL SDK. If you do not have the SDK installed, you can
download the Pvideo database separately with the sample
application.

Perl Perl allows for both command line and web-based applications using
Pervasive PSQL.

Pervasive PSQL Perl Requirements

„ Perl
„ ODBC-DBD library
„ CGI library
„ DSN pointing to the database

Perl Connection Snippet

This code segment shows the essential part of connecting to a
Pervasive PSQL database using Perl.
# specify use of Perl’s database interface (DBI)

13-13
Using Pervasive PSQL on Linux

use DBI;

# connect to DEMODATA database no uid or password

$dbInfo = "DBI:ODBC:DEMODATA";
$dbUserName = "";
$dbPassword = "";

# set the query variable to your SQL

$query = "SELECT * FROM Department";

# Connect to the server

$connect = DBI->connect($dbInfo, $dbUserName,
$dbPassword);

# Prepare the SQL query

$myRecordSet = $connect->prepare($query);

# Execute the query and obtain a recordset

$myRecordSet->execute();

Perl Sample
This complete sample presents the user a choice of three
DEMODATA tables and then displays the table.

# Perl sample

use CGI":cgi-lib";
$cgiquery = new CGI;

$functionreq = $cgiquery->url_param('_function');
# use ‘url_param’ for GET and ‘param’ for POST

print &PrintHeader;
print &HtmlTop("Pervasive PSQL Hello World Sample -
Perl");

print <<ENDOFMENU;
<H1>Pervasive Hello World Samples - Perl</H1>

<P>
This sample will display the DEMODATA database
tables in the following drop-down
by using Perl/DBI.
</p>
ENDOFMENU

# -----MAIN MENU-------------------------------

13-14
 Setting Up Web-based Data Access

# if there is no function specified in the URL

if (!$functionreq) {

# ---------------------------------------

print <<ENDOFTEXT;

<p>Please select from the following tables</p>

<form method=post
action="$ENV{'SCRIPT_NAME'}?_function=showtable">
<select name="selecttable">
<option SELECTED value="Department">Department
<option value="Course">Course
<option value="Room">Room
</select>
<p>
<input type=submit value="Show table">
</p>
</form>

ENDOFTEXT

} # !($function)

# ------SHOWTABLE-------------------------------

elsif ($functionreq eq "showtable") {

print("<p>Return to <a
href='$ENV{'SCRIPT_NAME'}'>Perl Hello World Sample
- Main Menu</a></p>");

# determine from FORMS data which table to open

$thetable = $cgiquery->param('selecttable');

use DBI;

$dbInfo = "DBI:ODBC:DEMODATA";
$dbUserName = "";
$dbPassword = "";

$query = "SELECT * FROM $thetable";

$connect = DBI->connect($dbInfo, $dbUserName,
$dbPassword);

$myRecordSet = $connect->prepare($query);
$myRecordSet->execute();

13-15
Using Pervasive PSQL on Linux

# start HTML table

print "<table border=1 cellpadding=5>";

# PRINT COLUMN HEADINGS

$num_fields = $myRecordSet->{NUM_OF_FIELDS};
$count = 0;

print "<tr >";

while ($count < $num_fields) {
$column_name = $myRecordSet->{NAME}->[$count];
print "<th>$column_name</th>";
$count++;
}
print "</tr>\n";

$count = 0;

# PRINT TABLE DATA

while(@row=$myRecordSet->fetchrow_array) {
print "<tr>\n";
while ($count < $num_fields) {
print "<td>$row[$count]</td>\n";
$count++;
}
print "</tr>\n";
$count = 0;
}

print "</table>"; # end HTML table

# END OF SHOWTABLE
}

# -----CATCH INVALID MENU OPTIONS----------------

else {

print "<p>An Invalid function was entered. Please

<a href='$ENV{'SCRIPT_NAME'}'>try again</a>.</p>";

print &HtmlBot;

13-16
 Using Perl and ODBC with Pervasive PSQL

Using Perl and ODBC with Pervasive PSQL

Note This procedure assumes you have a working installation of

Pervasive PSQL v11, Perl, and an ODBC distribution. A free version of
ODBC is available at http://www.iODBC.org. Perl can be found at
http://www.perl.org

³ To Get Pervasive PSQL to work with Perl's ODBC

Interface
1 Download the DBI (database interface) support for Perl.
Read the Readme or INSTALL for instructions.
2 Download the ODBC DBD database driver for Perl.
Please see the installation instructions in the Readme or
INSTALL file.
3 Make sure you have the proper environment variables set, as
shown in the following example. Note, this is also explained in
the iODBC docs.

Code Snippet print "using odbc...\n";

for Perl and DBI use DBI;
$dbName = "DBI:ODBC:DEMODATA";
$dbUserName = "";
$dbPassword = "";
print "connecting...\n";
$sql = "SELECT * FROM class";
$dbh = DBI->connect($dbName, $dbUserName,
$dbPassword);
$dataObject = $dbh->prepare($sql);
$dataObject->execute();
while(@row=$dataObject->fetchrow_array)
{
print "$row[0]\t$row[1]\t$row[2]\n\n"
}

13-17
Using Pervasive PSQL on Linux

13-18
 chapter

Troubleshooting After
Installation 14
How to Proceed When You Encounter Errors During Installation

Pervasive Software provides several features and tools in Pervasive

PSQL v11 that help to prevent configuration and installation
problems.
Some of these utilities are installed and run as part of the installation
process and all can be run later to evaluate configuration and registry
settings and to troubleshoot problems. They are shown in Table 14-
1.
This chapter contains the following sections:
„ Troubleshooting Tools
„ Troubleshooting Strategies
„ Configuration for Special Installation Situations
„ Diagnosing Problems with Pervasive System Analyzer (PSA)
„ Verifying Database Engine is Running
„ Obtaining File, Client, and Engine Version Number
„ Engine and Client Version Conflicts
„ Troubleshooting Common Pervasive PSQL Issues
„ Issues After Uninstalling Pervasive PSQL on Windows
„ How to Get Additional Help

14-1
Troubleshooting After Installation

Troubleshooting Tools
The following table describes some tools that can help you avoid or
solve problems.
Table 14-1 Pervasive Tools that Assist in Installation and Problem
Determination

Feature/ For More

Component Function Information

Pervasive System Analyzes system components and See Diagnosing

Analyzer runs communication tests. Problems with
Pervasive System
Analyzer (PSA).

Gateway Locator Determines or changes the See Configuring the

Gateway being used for a particular Workgroup Engine.
data dictionary (only in Pervasive
PSQL v11 Workgroup Edition.)

Knowledge Base Provides information about many Search the Pervasive

Pervasive software configurations Knowledge Base at:
and common environments. www.pervasivedb.co
m

14-2
 Troubleshooting Strategies

Troubleshooting Strategies
Pervasive Software hopes that your installation process completes
without experiencing any problems. However, this depends on a
number of factors, including proper network support, and operating
system configuration.
If something does go wrong during an installation, Pervasive offers
some tools that can help in diagnosing the problem. This chapter
explores some of the troubleshooting techniques that you can use.

Note If the installation fails for any reason, the installation log
file can be found in the Windows %Temp% directory.

Checklist for R Did you see any error messages displayed during installation?
Problems R Does the Network function correctly?
R Do you have the appropriate administrator-level privileges?
R Is the Engine running?
R Is the Client software correctly functioning?
R Are there errors in your PVSW.LOG file?

Troubleshoot The rest of this section contains procedures that you can use in
the Problem verifying your installation.
„ Configuration for Special Installation Situations
„ Diagnosing Problems with Pervasive System Analyzer (PSA)
„ Verifying Database Engine is Running
„ Obtaining File, Client, and Engine Version Number
„ How to Get Additional Help

14-3
Troubleshooting After Installation

Configuration for Special Installation Situations

This section lists some scenarios where the default configuration
settings for Pervasive PSQL need adjusting for proper database
operation.
The following table summarizes some of these situations. If you find
that your configuration matches an issue, please see the reference
included for more information.

If your computing Then you need to:

environment includes...

Microsoft Active Directory Read the following section:

Service
Active Directory Service

Multiple network Enable a configuration setting for Multi-homed setting

interfaces
In Advanced Operations Guide, see:
• TCP/IP Multihomed
• Listen IP Address

A network that is subject Enable a configuration setting that tries to auto-

to outages reconnect to a server when a network outage occurs
• In Advanced Operations Guide, see Pervasive
Auto-Reconnect.

Database filenames that Enable a configuration setting that instructs Pervasive

must not include PSQL to reject files with embedded spaces in the
embedded spaces name.
• In Advanced Operations Guide, see Embedded
Spaces and Long File Names and Embedded
Spaces Support.

14-4
 Diagnosing Problems with Pervasive System Analyzer (PSA)

Diagnosing Problems with Pervasive System Analyzer

(PSA)
Pervasive System Analyzer is a diagnostic utility included with
Pervasive PSQL v11.
Pervasive System Analyzer (PSA) is conveniently integrated into the
product installation and available as a stand-alone diagnostic tool to
help you with a the following tasks:
„ Troubleshoot network problems
„ Detect previous installations of Btrieve or Pervasive PSQL on
your system
„ Note other factors that influence your networking environment
„ View current component set and versions
PSA replaces the features that were previously offered by SmartScout
and InstallScout.

Note For detailed in formation on using Pervasive System

Analyzer, refer to the Pervasive PSQL User's Guide.

14-5
Troubleshooting After Installation

Verifying Database Engine is Running

To verify that the Pervasive PSQL engine is running, see the
procedure for your platform and engine:
„ Windows Server (Non-Vista)
„ Windows Workgroup
„ Linux Server

Windows You can use the Services function of the Windows control panel.
Server (Non-
Vista) ³ To check Pervasive Services on Windows servers
using the Control Panel
1 At the operating system, open Services under Administrative
Tools.
2 Scroll the list of services until you reach the following services.
Š Pervasive PSQL Transactional Engine
Š Pervasive PSQL Relational Engine
Both of these services must be started if Pervasive PSQL is to
function correctly.
The Status column displays whether or not the service is
currently running. The Startup column indicates whether the
service is set to automatically start on system startup or start
manually.
Figure 14-1 Displaying the Services Status

3 If a service is not started, right-click the service name, then click

Start.

14-6
 Verifying Database Engine is Running

Windows To verify that the Pervasive PSQL v11 workgroup engine is running:
Workgroup
³ To start the Pervasive Workgroup engine
1 From the Start menu, select Engines from the Pervasive
program.
2 Click Start Workgroup Engine.
By default, the MicroKernel allocates resources and is ready to
service local application database requests.

³ To stop the Pervasive Workgroup engine

1 From the Start menu, select Engines from the Pervasive
program.
2 Click Stop Workgroup Engine.

Note You will receive a warning message when trying to stop the
engine if any of the following is true:

- There are active clients.

- No activity took place since the engine loaded.
- 10 seconds has not elapsed since the last operation took place.

Linux Server You can verify that the engine (mkded) is running with the Linux ps
utility:
Type the following at a command line:
ps -e | egrep ‘mkded’

³ To start the Pervasive PSQL services in Linux

Enter the following at the command line under the root user
account:
etc/init.d/psql start

14-7
Troubleshooting After Installation

Obtaining File, Client, and Engine Version Number

You can use Pervasive PSQL utilities to verify that the client and
engines have the version number you expect, or to check the version
of a particular file.

Determining You can check the engine and client versions using Function
Client and Executor on Windows platforms or using the BUTIL command-line
Engine Version utility on all platforms. Function Executor is a utility that simulates
Btrieve client operations using the Pervasive PSQL requesters.

Using Function Executor

Use Function Executor to determine the version of the client, local
and remote engines.

³ To Determine the Engine Version using Function

Executor
1 On the Start menu select Function Executor from the Pervasive
PSQL v11 Utilities program group.
2 Do one of the following:
a. Click View Version from the File menu.
b. Select the Btrieve Version Info toolbar button, as shown in
Figure 14-2.
Figure 14-2 Selecting the Btrieve Version Info button

3 After choosing either of the Version options, a dialog box

displays that indicates the version of the client requesters and the
local engine. If a file is open when the Version option is selected,
the remote engine version displays as well.

14-8
 Obtaining File, Client, and Engine Version Number

Figure 14-3 Btrieve Version Info Display

Using the BUTIL Utility

From a command prompt, enter the following:
BUTIL -VER

The requester and engine versions are then displayed. You cannot
determine the version of a remote server engine with this tool.

Determining a You can determine the file version of a MicroKernel data file using
File Version the Pervasive PSQL v11 utilities. On the Windows platform, use
Control Center, Function Executor, DDF Builder, or Btrieve
Maintenance. On any platform, use the BUTIL command-line
utility. The following provides information on using a few of these
methods.

Using the Pervasive PSQL Control Center

You can use the Pervasive PSQL Control Center to determine a file
version.

³ To Determine the File Version of a Table Using

Pervasive PSQL Control Center
1 On the Start menu select Control Center (PCC) from the
Pervasive PSQL v11 program group.
2 Find the database by expanding its name in the Pervasive PSQL
Explorer on the left.
3 Do one of the following:
a. Click File Properties from the File menu.
b. Right-click a table name and select Properties as shown in
Figure 14-4.

14-9
Troubleshooting After Installation

Figure 14-4 Obtaining a File Version with the Pervasive PSQL Control Center

4 The table properties are displayed, which includes the file

version of the underlying MicroKernel data file version.
Figure 14-5 Table Properties Page

14-10
 Obtaining File, Client, and Engine Version Number

Using Btrieve Maintenance

If you are unfamiliar with the command line, you can use the GUI-
based Btrieve Maintenance tool.

³ To Determine the File Version of a Table Using Btrieve

Maintenance Utility
1 From the Start menu click Maintenance from the Pervasive
Utilities program group.
2 From the File menu, click Options and select Show Information
Editor.
The File Information Editor dialog box displays.
3 Click Load Information and the Select File dialog box displays.
4 Enter or browse for the file for which you need to determine the
version.
The version displays in the upper right-hand corner of the dialog
box.

Using Function Executor

The Function Executor utility can simulate Btrieve operations and
can be used to determine the file version by performing a statistics
report against the file.

³ To Determine the File Version of a Table Using

Function Executor
1 From the Start menu click Function Executor from the
Pervasive Utilities program group.
2 From the File menu, click File Open.
The Open Btrieve File dialog box displays.
3 Enter or browse for the file for which you need to determine the
version.
4 With the file open in Function Executor, click View File
Statistics.
The File Statistics dialog box displays the file version in the top
portion of the screen, as seen in Figure 14-6.

14-11
Troubleshooting After Installation

Figure 14-6 File Statistics in Function Executor

The Function Executor utility is documented in more detail in

Advanced Operations Guide.

Using BUTIL command-line utility

Use the -stat parameter of BUTIL to query the file statistics, which
includes information about:
„ File version
„ Pages
„ Records
„ Keys
Type the following at a command prompt:
butil -stat <filename>

For example, to query the statistics of the file DEPT.MKD of the

DEMODATA database included with Pervasive PSQL:
butil -stat dept.mkd

The BUTIL utility (available on Windows and Linux) is documented

in more detail in Advanced Operations Guide.

14-12
 Engine and Client Version Conflicts

Engine and Client Version Conflicts

If you update your engine to the latest Pervasive PSQL version
without also updating your client requesters, you may encounter
warning messages from Pervasive PSQL indicating the version
conflict. The message displayed is:
An engine to client component mismatch was found

When you receive such a message, it is also logged to your Pervasive

Event Log (PVSW.LOG).
This message is a warning. The client is not prevented from
connecting to the engine in this situation. Note, however, that
Pervasive recommends that you use client requesters that are the
same version as the database engine. If you choose, you may use a
client requester that is an older version than the database engine with
which it interacts. In some situations, depending on the type of SDK
access method used by your application, an older version requester
will not work with the database engine. Your application will be
unable to communicate with the database engine. For those
situations, you must use client requesters that are the same version as
the database engine.
Client requesters that are a newer version than the database engine
may or may not function correctly. Pervasive does not guarantee that
newer versions of client requesters will function correctly with older
versions of the engine. Therefore, Pervasive recommends that you
avoid the use of newer version client requesters with an older engine.
If circumstances in your organization dictate that you cannot
upgrade the clients for some time, you may want to disable the dialog
boxes that appear when your client components are authorized.
However, you cannot disable the entries in the Pervasive Event Log,
and you should note that over time this log could grow to a large size
as these entries are logged.
To permanently solve the problem, update your client requesters to
the same version as your server engine.

14-13
Troubleshooting After Installation

Troubleshooting Common Pervasive PSQL Issues

This section outlines problems you may encounter during the
installation or when first using the Workgroup product.

I fail to see the effects of my configuration changes.

Try stopping and then restarting the database engine. Whenever you
make a change to engine configuration components, you must stop
and restart the database engine for the changes to take effect. For
information on how to start and stop the database engine, see
Verifying Database Engine is Running.

Why do I receive Status 7012 when trying to create a new

database with the Workgroup Engine using PCC on
Windows Vista?
When PCC creates a new database, the new database name is added
to dbnames.cfg and an entry is added to the ODBC.INI registry in
order to create a corresponding System DSN.
Due to Microsoft Vista operating system constraints on registry
access, the Workgroup Engine should be run in an elevated mode, so
that the database System DSN can be created.
Once the System DSN is created successfully, any user may start the
Workgroup Engine and use the DSN.

Note In Windows Vista, standard users may create User DSNs

without this restriction.

Why do I (now) receive Status 95, after running my

application successfully?
Your application has lost its session with the database engine. This
can happen if you make changes to your configuration settings and
must restart the database engine, as in the troubleshooting example
given above. At the moment the database engine is stopped, any
application that is running loses its session with the database engine.
You must stop all those utilities and restart them in order to
reestablish communication.

14-14
 Troubleshooting Common Pervasive PSQL Issues

See the Status Codes and Messages manual for more cases in which
this status code can be returned.

Installing a Pervasive PSQL application has rendered

another application unusable.
If the latest DLLs have been overwritten, it is possible to restore the
overwritten DLLs using a backup directory that is automatically
created when you install Pervasive PSQL v11.

How do I verify that my DOS components are functioning

properly?
Pervasive provides a DOS version of BUTIL.EXE for purposes of
verifying that your DOS components are functioning properly. This
file is installed in the PSQL\BIN folder of the Pervasive PSQL v11
Program Files default installation directory.

Why can’t I restart my application after an improper

program exit?
Database engine components may remain in memory if the engine is
interrupted improperly.

³ If you cannot restart your program after improperly

aborting the application by using Ctrl-C or stopping
the process:
1 Shut down and restart your system.
2 Avoid terminating applications in an abnormal manner.

Why isn’t my application using the Workgroup engine?

If you previously installed Pervasive PSQL requesters and later
installed the Pervasive PSQL v11 Workgroup engine but your
application is only using the requesters, you may have an outdated
configuration that sets Local Access to Off. The Pervasive PSQL v11
Workgroup engine’s installation does not overwrite existing settings.
To reset Local Access to On, see Using the Server and Workgroup
Engines Concurrently.

14-15
Troubleshooting After Installation

How Do I Access the Pervasive PSQL v11 Online

Manuals?

³ To access the online documentation:

1 Click Control Center & Documentation from the Pervasive
program group off the Start menu.
2 Click the desired manual on the PCC Welcome page. (If the
Welcome page has been closed, click Help then Welcome.)

I received an error message during installation that

begins: “Setup did not update the PATH statement in
autoexec.bat because the new path would be too long for
Windows.”
This message appears when the installation program cannot update
the PATH environment variable because the resulting PATH
definition would be too long (exceeds the environment space). For
info on how to increase the environment space defined in config.sys,
see the Microsoft knowledge base article:
http://support.microsoft.com/?kbid=230205
If you get this error message, then a REM statement (a comment) has
been added to your autoexec.bat file. The REM statement contains
the PATH value that would have been entered. You can change the
PATH statement manually.
The best approach, if possible, is to install the product at a location
with a shorter installation directory so that the value of PATH does
not exceed the environment space.

14-16
 Issues After Uninstalling Pervasive PSQL on Windows

Issues After Uninstalling Pervasive PSQL on Windows

When you uninstall Pervasive PSQL using the Add/Remove
Programs mechanism in Windows, you should not have any
database engine files remaining on your system. However, some
actions such as installing multiple times to the same machine or
restoring archived components can cause a significant number of
files to be left on your system. This is a side effect of how the
installation process works with the Windows operating system.
In the situations described previously, the files are left because
Windows has the files marked with usage counts that indicate that
they are being used by more than one program, and therefore the
uninstallation program does not remove them from your system.
This is expected behavior, but it may lead you to conclude that the
Pervasive PSQL uninstall program is not functioning correctly.

14-17
Troubleshooting After Installation

How to Get Additional Help

Pervasive Software strives to ensure that your product installation is
easy and successful. If you encounter problems during or after the
installation that are not covered in the user documentation, please
contact Pervasive Software and we will address your problem
promptly.
See Table 10-1 in Pervasive PSQL User's Guide for a list of resources
to help you get answers to your questions, troubleshoot problems,
and interact with the Pervasive team as well as with other customers.

Technical If you still have questions or problems relating to your Pervasive

Support PSQL v11 installation, you can obtain help from the Pervasive
Customer Support department.

14-18
Index B
Before you install
common questions 2-11
Pervasive PSQL for Linux 12-2
A Windows client 5-2
About Pervasive PSQL Windows server 4-2
engines 1-8 Windows workgroup 6-2
relational or transactional access 1-3 BTRBOX Requester 10-25
Accessing installation 5-7
data on other computers 11-17 Btrieve
documentation in Linux 12-15, 14-16 file conversion 3-4
documentation in Windows 7-4 older versions, problems with 14-15
remote server engines 11-15 Btrieve DOS
Active Directory 11-4 Pervasive Access Methods 2-6
administrative rights required for 11-4 BUTIL
create Pervasive_Admin group on domain determining file version 14-9
controller 11-5
directory and file permissions 11-4 C
grant log on privileges to Pervasive_Admin group Changes, configuration
11-8 effects not seen 14-14
installation of Pervasive PSQL with 2-13 Changing
Pervasive PSQL clients used with 11-4 default communication ports 10-13
tasks 11-5 Checklist
use of Terminal Services with 11-4 for installation 2-10
ActiveX Interface Controls for installation troubleshooting 14-3
Pervasive Access Methods 2-6 Citrix MetaFrame
Administrative rights installing Pervasive PSQL on 2-12
for Active Directory 11-4 Client
ADO.NET Provider determining version 14-8
Pervasive Access Methods 2-6 DOS support 10-25
After Installing Pervasive PSQL for Linux 12-12 encoding 10-19
behavior 13-4 engine for Windows 2-4
Application data files installation 5-3
in Pervasive PSQL 7-3 installed with Workgroup engine 7-4
Applications network communication settings 10-2
configuration scenarios 8-1 SPX support 10-12
configuring for multiple 11-14 TCP/IP support 10-10, 10-16
developing with Pervasive PSQL 1-10 Client configuration
not using Workgroup engine 14-15 in Linux 12-12
restarting after improper program exit 14-15 on Linux 12-12
Authentication Client encoding 10-18
for Linux 13-6 interaction with database code page 10-19
Authentication to Remote Machines 13-8 Client engine
Automatic encoding 10-18 32-bit for Windows 2-5
64-bit for Windows 2-5
install image 7-4

Index 1
 installation 5-1 server engine with two network cards 9-5
installation location 2-11 SPX support for Windows server 9-6
installed after server 2-13 TCP/IP on Windows server 9-4, 9-8
using 64 bit with Workgroup engine 7-3 web server 13-9
Client Information workgroup engine 8-15
for Linux 13-8 Connectivity
Client installation testing 14-1
on Linux 12-2 Create File Version
Client requesters multiple applications and 11-12
concepts 5-8 Creating a Client DSN 13-8
Client version conflicts Creating, new database
troubleshooting 14-13 with Workgroup engine using PCC (Windows
Client/server configuration Vista) 14-14
workgroup engine 8-2, 8-5 Custom Setup
Cobol Schema Executor installation option 2-3
Utilities 2-8
Code page 10-18 D
Code Snippet for Perl and DBI 13-17 Data
Common Questions After Installation 12-13 accessing on other computers 11-17
Communication ports Data Dictionary File Builder
changing defaults 10-13 Utilities 2-8
Communication, network Data Source Names
client settings 10-2 handling 3-4
Communications Data translation 10-18
testing 14-5 Database code page 10-18
troubleshooting 14-5 interaction with client encoding 10-19
Complete Setup Database encoding 10-18
installation option 2-3 Database engine
Configuration checking status 14-6
database code page 10-18 uninstall on Linux 12-17
on Linux 13-6 uninstalling on Windows 7-6
Configuration changes Default communication ports
effects not seen 14-14 changing 10-13
Configuration File Determining
for Linux 13-6 type of network 9-2
Configuration parameters Developing
for server authentication 13-6 applications with Pervasive PSQL 1-10
Configuration settings Diagnosing
affected by multiple applications 11-12 system problems 14-5
migration of existing, during upgrade 3-4 Disabling administrative functions
other 2-15 in Terminal Services 11-2
to restrict access on Terminal Services 2-14 DNS
Configuring used to configure Server IP address (Linux) 10-16
application scenarios 8-1 used to configure Server IP address (Windows)
for special installation situations 14-4 10-10
multiple applications, for 11-14 Documentation

2 Index
 accessing 14-16 optional in Pervasive PSQL 2-6
accessing in Linux 14-16 File Conversion 3-4
accessing in Windows 7-4 Btrieve 3-4
accessing on Linux 12-15 rebuild utility 3-4
installing as an optional feature 2-8 scalable SQL 3-4
DOS File locations
components 14-15 for Pervasive PSQL 7-2
components, troubleshooting 14-15 File version
utilities 14-15 determining 14-9
DOS box 10-25 Files
preferred for Windows platforms 10-26 difference between 32-bit and 64-bit 7-3
DOS requesters 5-8 installed on Linux 12-14
ODBC not supported 10-25 services 10-14
using 10-25 Finding what you need
with Active Directory 11-4 using Pervasive PSQL on Linux 13-2
Downloading Fixed gateway engine 8-9
Pervasive PSQL installation file 2-14 setting up 8-10
DTO Floating gateway engine 8-9
Pervasive Access Methods 2-7 setting up 8-10
Frame type 9-6
E Full installations for Linux 12-3
Encoding 10-18
ANSI 10-20 G
automatic 10-18 Gateway engine
client 10-18, 10-19 configuration 8-3, 8-9
interaction between client and database code page definition of 8-3
10-19 fixed, definition of 8-9
OEM 10-20 fixed, setting up 8-10
Engine floating, definition of 8-9
checking status 14-6 floating, setting up 8-10
determining version 14-8 locator file, definition of 8-3
features compared 1-9 Gateway Locator File
network communication settings for Pervasive definition of 8-3
PSQL 9-3 Gateway Locator Utility 8-11, 14-2
relational 1-6 changing workgroup engine 8-13
running on Terminal Services 4-2 locating workgroup engine 8-13
running Workgroup as service 8-15 Group
stopping Workgroup as service 8-16 pervasive_admin TCP/IP support on Windows
transactional 1-4, 1-5 9-3
troubleshooting version conflicts 14-13
Environment space 14-16 H
Exclusions Handling
in Linux 13-2 Data Source Names (DSNs) 3-4
Hosts file
F used to configure Server IP address in Linux 10-
Features 17

Index 3
 used to configure Server IP address in Windows Windows client 5-2
10-10 Windows server 4-2
Windows workgroup 6-2
I with Active Directory 2-13
install.log file 4-4, 5-3, 14-3 with Citrix MetaFrame 2-12
for workgroup engine 6-3 with Microsoft Cluster Services 2-12
Installation with Terminal Services 2-12
before you begin on Linux 12-2 workgroup for Windows 6-3
BTRBOX Requester 5-7 IP address, for server
checklist 2-10 configuring using DNS in Linux 10-16
client 5-3 configuring using DNS in Windows 10-10
client for Windows 5-1 configuring using hosts file in Linux 10-17
image for Client engine 7-4 configuring using hosts file in Windows 10-10
location for client software 2-11 IPX/SPX 10-12
location for clients accessing web applications 2-
13 J
location for downloaded file 2-14 Java Runtime Environment (JRE) 2-9
location for server 2-11 JCL
location for workgroup 2-11 Pervasive Access Methods 2-7
log file location 4-4, 5-3, 6-3, 14-3 JDBC Driver
on Terminal Services 4-2 Pervasive Access Methods 2-7
options 2-3
over existing Pervasive products 3-2 L
overview 2-2 License
problems during 14-1 installed with Pervasive PSQL 3-5
requirements 2-2 Licenses
requirements for Workgroup engine 8-2 installed with Pervasive PSQL 7-5
review 2-10 migrating from previous versions 2-14
Samba 12-2 updating or verifying 7-4
scheduling upgrade 2-10, 2-14 Linux
server for Windows 4-1, 4-4 accessing documentation 12-15
sever or client first 2-13 authentication 13-6
tips for Server engine on Windows 4-2 before you install 12-2
tips for Workgroup engine on Windows 6-2 client configuration 12-12
troubleshooting 14-2, 14-3, 14-14 client information 13-8
troubleshooting checklist 14-3 client installation 12-2
Workgroup 6-3 configuration 13-6
workgroup engine for Windows 6-1 configuration file 13-6
Installation, special situations cserver installation 12-2
troubleshooting 14-4 engine status 14-6
Installing exclusions 13-2
Linux client using RPM 12-6 files installed 12-14
Linux client using TAR 12-10 installation 12-1
Linux server using RPM 12-4 man (manual) pages 13-2
Linux server using TAR 12-8 path formats 10-8, 13-6
server on Linux 12-1 platform notes 12-2

4 Index
 pre-installation notes 12-2 testing 14-5
readme 12-16 Network server
user count licenses 12-13 from terminal services 11-2
user environment 13-4
Locations O
for installing client engine 2-11 ODBC
for installing clients accessing web applications 2- Administrator 1-6
13 not supported with DOS requesters 10-25
for installing server engine 2-11 ODBC Behavior 13-9
for installing workgroup engine 2-11 OEM/ANSI 10-20
no longer used by Pervasive PSQL 7-2 OLE DB
of files installed 7-2 Pervasive Access Methods 2-7
Locator file, see Gateway locator file Optional features
ActiveX Interface Controls 2-6
M ADO.NET Provider 2-6
Man pages 13-2 Btrieve DOS 2-6
MicroKernel Database Engine 1-5 Cobol Schema Executor 2-8
Microsoft Cluster Services Data Dictionary File Builder 2-8
installing on 2-12 Documentation 2-8
Migrating DTO 2-7
configuration settings 3-4 in Pervasive PSQL 2-6
licenses from previous versions 2-14 JCL 2-7
Multi-engine systems 11-15 JDBC Driver 2-7
Multiple applications OLE DB 2-7
configuring for 11-14 PDAC 2-7
for clients 11-12 Pervasive Access Methods 2-6
Multiple network cards Pervasive Control Center 2-8
configuring server engine for 9-5 Pervasive System Analyzer(PSA) 2-8
Utilities 2-7
N Xtreme I/O (Server 32-bit Only) 2-6
NetBIOS Options
not supported by Server engine 9-2 for Complete installation 2-3
Network for Custom installation 2-3
determining what type 9-2 for installation 2-3
path formats 10-3 Overview
path formats, UNC 10-3 for installation 2-2
path formats,drive-based 10-8 Pervasive PSQL 1-2
path formats,Linux 10-8 Pervasive PSQL engines 1-8
removing unused protocols 9-9
setting up SPX for Windows server 9-6 P
setting up TCP/IP for Windows server 9-4, 9-8 Path formats
Network cards drive-based 10-8
configuring server engine for multiple 9-5 Linux 10-8
Network communications network 10-3
settings for clients 10-2 UNC 10-3
settings for Pervasive PSQL engines 9-3 PATH too long error 14-16

Index 5
PDAC Pervasive_Admin security group
Pervasive Access Methods 2-7 use with Active Directory 11-4, 11-5, 11-8
Peer-to-peer configuration PHP 13-10
workgroup engine 8-2, 8-7 Platform notes
Perl 13-13 Linux 12-2
Pervasive Access Methods Windows 4-2
ActiveX Interface Controls 2-6 Ports, communication
ADO.NET Provider 2-6 changing default 10-13
Btrieve DOS 2-6 Post installation
DTO 2-7 common questions 7-2
JCL 2-7 Pre-installation notes, Linux 12-2
JDBC Driver 2-7 Previous version
OLE DB 2-7 upgrading from 3-1, 3-2
optional feature 2-6 Program files
PDAC 2-7 difference between 32-bit and 64-bit 7-3
Pervasive Control Center in Pervasive PSQL 7-3
Utilities 2-8 Protocol
Pervasive PSQL determining correct 9-2
about 1-2 IPX/SPX 10-12
about relational or transactional access 1-3 NetBIOS not supported by server 9-2
about the engines 1-8 removing unused 9-9
application data files 7-3 PVSW\BIN
engines 2-4, 2-5 no longer used 7-2
engines, status of 14-6
files location 7-2 R
installation 6-1 Readme
license installed 3-5 for Linux 12-16
licenses installed 7-5 Rebuild utility 3-4
optional features 2-6 Relational engine 1-6
products 2-4 ODBC Interface 1-6
program files 7-3 Release notes
PVSW\BIN location 7-2 as part of installation 4-2, 5-2
relational engine 1-6 Remote
server engine overview 1-8 server engine access 11-15
Software Developer Kit (SDK) 1-10 Remote applications
transactional engine 1-4 concurrent with local 11-14
troubleshooting 14-14 Removing
Pervasive PSQL Account Management on Linux 13- unused network protocols 9-9
4 Requesters
Pervasive PSQL Workgroup engine preferred for Windows platforms 10-26
overview 1-8 trace 5-8
Pervasive Software Website 14-18 types for Windows 5-8
Pervasive System Analyzer (PSA) 14-5 used with Active Directory 11-4
Utilities 2-8 Requesters, client
Pervasive_admin concepts 5-8
and TCP/IP support on Windows 9-3 Requesters, DOS 5-8

6 Index
Requirements Services
for installing 2-2 checking status 14-6
Restarting applications Services File 10-14
after improper program exit 14-15 Setting up
Restricting user access Web-based data access 13-9
on Terminal Services 2-14 Settings
Review for configuration 2-15
for installation 2-10 Setup Type
Rights Complete 2-3
administrative authority for Active Directory 11- Custom 2-3
4 Software Developer Kit (SDK) 1-10
Terminal Services 4-2 environment 1-11
RPM Version 12-17 programming languages 1-11
Running SPX
Workgroup engine as a service 8-15 frame type 9-6
setting up for Windows server 9-6
S support for clients 10-12
Samba installation 12-2 Status 7012, when creating a new database
Scalable SQL with Workgroup engine using PCC (Windows
file conversion 3-4 Vista) 14-14
Security Status 95
pervasive_admin support for TCP/IP on after running applications successfully 14-14
Windows 9-3 Status, of database engine 14-6
workgroup engine and 8-2 Stopping
Server Configuration 12-12 Workgroup engine as a service 8-16
Server engine Supported Path Formats for Samba 13-6
32-bit for Windows 2-4
64-bit for Windows 2-4 T
compared to Workgroup 1-9 TAR Version 12-17
for Windows 2-4 TCP/IP
installation 4-1, 4-4 for clients 10-10, 10-16
installation location 2-11 setting up for Windows server 9-4, 9-8
installed before client 2-13 Technical Support 14-18
mixed engine systems 11-15 Terminal Server
NetBIOS not supported 9-2 as network server 11-2
on Linux 12-1 Terminal Services 11-2
Server installation disabling administrative functions 11-2
on Linux 12-2 installing on 2-12, 4-2
Server IP Address permissions 4-2
configuring using DNS (Linux) 10-16 restricting user access 2-14
configuring using DNS (Windows) 10-10 running the engine with 4-2
configuring using hosts file in Linux 10-17 use within Active Directory environment 11-4
configuring using hosts file in Windows 10-10 Testing
Service network connectivity 14-5
running Workgroup engine as 8-15 Tips
stopping Workgroup engine as 8-16 for installing Server engine on Windows 4-2

Index 7
 for installing Workgroup engine on Windows 6-2 optional features 2-7
Trace Requesters 5-8 Pervasive Control Center 2-8
Transaction Durability Pervasive PSQL 2-6
multiple applications and 11-13 Pervasive System Analyzer (PSA) 2-8
Transactional engine 1-4, 1-5 Rebuild 3-4
Translate data 10-18
Translation V
data encoding 10-18 Verifying
Troubleshooting 14-1 database engine is running 12-12
after installation 7-2 engine status 14-6
after uninstalling 14-17 installed products with RPM 12-12
communications 14-5 licenses 7-4
DOS components 14-15 Version
engine and client version conflicts 14-13 determining in files 14-9
installation 14-14 engine and client 14-8
strategies 14-3 troubleshooting conflicts 14-13
tools 14-2
Types of installation
Complete 2-3
W
Custom 2-3 Web applications
client installation location 2-13
Web Server
U configuring 13-9
Uninstall Web site
Pervasive PSQL Server on Linux 12-17 Pervasive Software 14-18
Uninstalling Win32 DOS Box Support 5-7
files not removed by 14-17 Windows
Pervasive PSQL on Windows 7-6 accessing documentation 7-4
Uninstalling Pervasive PSQL for Linux 12-17 installation error "PATH statement too long" 14-
Universal Naming Convention See Network path 16
formats, UNC. pervasive_admin group and TCP/IP support 9-3
Updating platform notes 4-2
licenses 7-4 types of requesters 5-8
Upgrading Workgroup engine
from a previous version 3-1, 3-2 and Client (64-bit) 7-3
installation 2-10, 2-14 applications not using 14-15
migration of existing configuration settings 3-4 compared to Server engine 1-9
User count licenses configuration 8-15
Linux 12-13 for Windows 2-4
User environment gateway configuration 8-3, 8-9
in Linux 13-4 installation 6-1, 6-3
Using Perl and ODBC with Pervasive PSQL 13-17 installation location 2-11
Using Utilities from Users Other than psql 13-5 installation requirements 8-2
Utilities installing client with 7-4
Cobol Schema Executor 2-8 mixed engine systems 11-15
Data Dictionary File Builder 2-8 peer-to-peer configuration 8-2, 8-7
Gateway Locator Utility 8-11, 8-13, 14-2 running as a service 8-15, 11-3

8 Index
 security and 8-2
small client/server configuration 8-2, 8-5
stopping as a service 8-16

X
Xtreme I/O (Server 32-bit Only)
optional feature 2-6

Index 9
10 Index