Pervasive PSQL v10.

10

User’s Guide
Guide to Using 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.pervasive.com
disclaimer PERVASIVE SOFTWARE INC. LICENSES THE SOFTWARE AND
DOCUMENTATION PRODUCT TO YOU OR YOUR COMPANY SOLELY ON AN “AS
IS” BASIS AND SOLELY IN ACCORDANCE WITH THE TERMS AND CONDITIONS
OF THE ACCOMPANYING LICENSE AGREEMENT. PERVASIVE SOFTWARE INC.
MAKES NO OTHER WARRANTIES WHATSOEVER, EITHER EXPRESS OR IMPLIED,
REGARDING THE SOFTWARE OR THE CONTENT OF THE DOCUMENTATION;
PERVASIVE SOFTWARE INC. HEREBY EXPRESSLY STATES AND YOU OR YOUR
COMPANY ACKNOWLEDGES THAT PERVASIVE SOFTWARE INC. DOES NOT
MAKE ANY WARRANTIES, INCLUDING, FOR EXAMPLE, WITH RESPECT TO
MERCHANTABILITY, TITLE, OR FITNESS FOR ANY PARTICULAR PURPOSE OR
ARISING FROM COURSE OF DEALING OR USAGE OF TRADE, AMONG OTHERS.

trademarks Btrieve, Client/Server in a Box, Pervasive, Pervasive Software, and the Pervasive Software
logo are registered trademarks of Pervasive Software Inc.
Built on Pervasive Software, DataExchange, MicroKernel Database Engine, MicroKernel Database
Architecture, Pervasive.SQL, 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 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 2008 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.
User’s Guide
June 2008
100-004381-002
Contents
About This Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi
Who Should Read This Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii
Manual Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii
Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv

1 Introducing Pervasive PSQL . . . . . . . . . . . . . . . . . . . . . 1-1

Understanding Pervasive PSQL and its Capabilities
Understanding the Pervasive PSQL Database Management System . . . . . . . . . . . 1-2
What is a Database? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2
What is a Database Management System? . . . . . . . . . . . . . . . . . . . . . . 1-3
Components of Pervasive PSQL . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3
Key Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6
Basic Database Structures and Terms . . . . . . . . . . . . . . . . . . . . . . . . 1-6
Unique Benefits of Pervasive PSQL . . . . . . . . . . . . . . . . . . . . . . . . . . 1-9
Understanding the DBMS Products . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-11
Workgroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-11
Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-12
Crystal Reports for Pervasive PSQL. . . . . . . . . . . . . . . . . . . . . . . . . . 1-12
Using Pervasive PSQL Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-13
Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-13
What’s New . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-13
User’s Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-14
Advanced Operations Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-14
SQL Engine Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-14
Status Codes and Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-14
Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-14
File System Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-15

2 Using Pervasive PSQL . . . . . . . . . . . . . . . . . . . . . . . . . 2-1

A Walk-through of Basic User Tasks
Starting and Stopping the Database Engine. . . . . . . . . . . . . . . . . . . . . . . . . 2-2
Starting and Stopping the Server Engine on a Windows Server . . . . . . . . . . 2-2
Starting and Stopping the Workgroup Engine on Windows . . . . . . . . . . . . 2-5
Starting and Stopping the Database Engine on Linux. . . . . . . . . . . . . . . . 2-7
Granting Administrative Rights for the Database Engine . . . . . . . . . . . . . . . . . 2-8
Tasks Requiring Administrative Rights. . . . . . . . . . . . . . . . . . . . . . . . 2-8
How Administrative Rights are Granted . . . . . . . . . . . . . . . . . . . . . . . 2-8
Rights Within an Active Directory Environment . . . . . . . . . . . . . . . . . . 2-9
Rights Provided to non-Administrative Users . . . . . . . . . . . . . . . . . . . . 2-9

iii
Contents

Tasks for Granting Administrative Rights. . . . . . . . . . . . . . . . . . . . . . 2-9

Granting Administrative Rights on a Windows Server . . . . . . . . . . . . . . . 2-9
Granting Administrator Rights on Linux . . . . . . . . . . . . . . . . . . . . . . 2-13
Logging in as Administrator on any platform. . . . . . . . . . . . . . . . . . . . 2-14
Setting Up ODBC Database Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-15
ODBC Standard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-15
Servers and Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-16
Data Source Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-17
Internal Database Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-17
Applications Using the Transactional Interface . . . . . . . . . . . . . . . . . . . 2-17
Pervasive.SQL v7 users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-17
Setting up Database Access with PCC . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-18
Setting Up Database Access on Windows . . . . . . . . . . . . . . . . . . . . . . 2-18
Setting Up Database Access on a Linux Server . . . . . . . . . . . . . . . . . . . 2-19
Setting Up Client Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-21
Setting Up a Client DSN on a Linux Workstation . . . . . . . . . . . . . . . . . 2-25
Accessing Data on a Remote Engine Using PCC . . . . . . . . . . . . . . . . . . . . . 2-26
Accessing Data via ODBC From Other Applications . . . . . . . . . . . . . . . . . . . 2-29
Before You Begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-29
Accessing Data Using Microsoft Excel. . . . . . . . . . . . . . . . . . . . . . . . 2-29
Accessing Data Using Microsoft Access . . . . . . . . . . . . . . . . . . . . . . . 2-31
Deleting DSNs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-35
Using the Fast User Switching Feature of Windows XP. . . . . . . . . . . . . . . . . . 2-37

3 Using Pervasive PSQL Control Center . . . . . . . . . . . . . . . . 3-1

A Tour of Pervasive PSQL Control Center
An Overview of Pervasive PSQL Control Center . . . . . . . . . . . . . . . . . . . . . 3-2
Installing PCC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3
Starting PCC on Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3
Starting PCC On Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4
Editors and Views Within PCC . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6
Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-9
Additional Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-11
External Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-12
Services on Windows Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-13
Services Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-14
Database Engines. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-15
Database Engine Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-16
Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-17
Database Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-17
New Database GUI Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-22
Pervasive PSQL Database Tasks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-25

iv
 Contents

Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-28
Data Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-28
System Tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-28
Table Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-28
Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-31
Creating Data Through PCC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-31
Importing Data with Bulk Data Utility . . . . . . . . . . . . . . . . . . . . . . . . 3-31
Importing Data with Import Data Wizard . . . . . . . . . . . . . . . . . . . . . . 3-31
Exporting Data with Export Data Wizard . . . . . . . . . . . . . . . . . . . . . . 3-32
Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-33
IN DICTIONARY Clause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-33
USING Clause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-34
Plain Statement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-34
Exporting a Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-35
Triggers, Stored Procedures, User-defined Functions, and Views . . . . . . . . . . . . 3-37
Groups, Users, and Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-38
Security Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-39
Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-50

4 License Administrator . . . . . . . . . . . . . . . . . . . . . . . . . 4-1

Working with License Keys and User Counts
License Administrator Concepts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2
License Key Platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2
User Count . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3
Terminal Server Licensing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4
Licenses for Prior Versions of Pervasive PSQL . . . . . . . . . . . . . . . . . . . 4-4
License Administrator Graphical User Interface . . . . . . . . . . . . . . . . . . . . . . 4-5
GUI Visual Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5
License Administrator Command Line Interface. . . . . . . . . . . . . . . . . . . . . . 4-8
CLI Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-8
License Administrator Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-10
GUI Tasks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-11
CLI Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-18

5 Table Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1

A Tour of Pervasive Table Editor
Table Editor Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2
Table Editor Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2
Table Editor Graphical User Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6
Columns Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6
Indexes Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-8
Foreign Keys Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-8
SQL View Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-8

v
Contents

Table Editor Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-9

General Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-9
Columns Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-10
Indexes Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-11
Foreign Keys Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-11
SQL View Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-11

6 SQL Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1

A Tour of the SQL Editor
SQL Editor Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2
Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-3
Displaying Statement Results. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-3
Outline Window View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-7
Working with Common SQL Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-8
SQL Editor Used in SQL View Tab of Table Editor . . . . . . . . . . . . . . . . . . . . 6-10
SQL Editor Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-11
General Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-11
Execution Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-12
Grid Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-12
Text View Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-12
Outline View Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-12
Common SQL Object Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-12

7 Pervasive System Analyzer (PSA) . . . . . . . . . . . . . . . . . . 7-1

Usage Information for the Diagnostic Utility PSA
PSA Concepts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-2
Frequently Asked Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-4
PSA GUI Visual Reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-6
PSA Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-8
General Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-8
View Modules Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-8
Test Active Installation Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-10
Log Files Tasks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-13

8 Command Line Interface Utilities . . . . . . . . . . . . . . . . . . . 8-1

Using Pervasive PSQL Command Line Interface Utilities
CLI Utilities Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-2
Platforms that Include CLI Utilities . . . . . . . . . . . . . . . . . . . . . . . . . 8-2
Where to Find CLI Utilities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-2
Utilities by Platform and Engine Type. . . . . . . . . . . . . . . . . . . . . . . . 8-2
Command Line Interface Utility Reference . . . . . . . . . . . . . . . . . . . . . . . . 8-5

vi
 Contents

9 Basic Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . 9-1

How to Identify and Solve Common Problems
General Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-2
Error Messages from PCC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-9
Frequently Asked Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-13
Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-18
PCC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-19
Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-19
User Counts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-20
Networking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-22
Difficulty Accessing Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-22
ODBC and DDFs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-24
Upgrading from Btrieve 6.15 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-27
Upgrading and Migration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-28
Miscellaneous. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-28

10 Pervasive PSQL Resources and Contacts . . . . . . . . . . . . . . 10-1

A Guide to Pervasive PSQL Customer Information Resources
Thirty-Day Free Technical Support. . . . . . . . . . . . . . . . . . . . . . . . . . 10-3

vii
Figures

2-1 Services Dialog Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4

2-2 Services Dialog Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4
2-3 Connect to Remote Server Dialog Box . . . . . . . . . . . . . . . . . . . . . . . . 2-14
2-4 Example DSN Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-16
2-5 Pervasive ODBC Client DSN Setup Screen . . . . . . . . . . . . . . . . . . . . . . 2-23
2-6 Pervasive ODBC Client DSN Options . . . . . . . . . . . . . . . . . . . . . . . . . 2-23
2-7 Pervasive ODBC Client DSN Setup Screen #2 . . . . . . . . . . . . . . . . . . . . 2-24
2-8 Expanding the Databases List for an Engine . . . . . . . . . . . . . . . . . . . . . 2-26
2-9 Selecting the Dept Table in DEMODATA. . . . . . . . . . . . . . . . . . . . . . . 2-27
2-10 Displaying the Dept Table in DEMODATA. . . . . . . . . . . . . . . . . . . . . . 2-27
2-11 Refining Your Query - Dept Table in DEMODATA . . . . . . . . . . . . . . . . . 2-28
2-12 Accessing Pervasive Data using Microsoft Excel . . . . . . . . . . . . . . . . . . . 2-30
2-13 Excel Display of ODBC Source List . . . . . . . . . . . . . . . . . . . . . . . . . . 2-30
2-14 Create a New Database using Microsoft Access. . . . . . . . . . . . . . . . . . . . 2-31
2-15 Importing External Data Using Access . . . . . . . . . . . . . . . . . . . . . . . . 2-32
2-16 Access Display of ODBC Source List . . . . . . . . . . . . . . . . . . . . . . . . . 2-33
2-17 Using Pervasive Data in Microsoft Access. . . . . . . . . . . . . . . . . . . . . . . 2-34

3-1 Pervasive PSQL Control Center on Windows Platforms. . . . . . . . . . . . . . . 3-2

3-2 Pervasive PSQL Control Center on Linux Platforms . . . . . . . . . . . . . . . . . 3-3
3-3 Example Objects Shown in Pervasive PSQL Explorer . . . . . . . . . . . . . . . . 3-8
3-4 Create New Database Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-22

5-1 Columns Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6

6-1 SQL Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2

6-2 Grid Window View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-4
6-3 Text Window View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-6
6-4 Outline Window View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-7

7-1 PSA Main Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-6

7-2 View Modules Section of PSA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-9

viii
Tables

1-1 Summary of Pervasive PSQL Utilities . . . . . . . . . . . . . . . . . . . . . . . . 1-4

2-1 Action of Dependent Services Based on Action of Database Engine Services . . . 2-3

3-1 Requirements for Starting PCC on Linux . . . . . . . . . . . . . . . . . . . . . . 3-4

3-2 Troubleshooting Guide for Running PCC . . . . . . . . . . . . . . . . . . . . . . 3-5
3-3 Characteristics of PCC Window Views . . . . . . . . . . . . . . . . . . . . . . . . 3-7
3-4 Create New Database GUI Elements . . . . . . . . . . . . . . . . . . . . . . . . . 3-22
3-5 Table Properties on General Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-28

4-1 Restrictions Pertaining To License Key Platform . . . . . . . . . . . . . . . . . . 4-2

4-2 License Administrator Command Line Options and Parameters . . . . . . . . . 4-9

6-1 Description of Common SQL Objects in PCC. . . . . . . . . . . . . . . . . . . . 6-9

8-1 Available Utilities for Client and Server . . . . . . . . . . . . . . . . . . . . . . . 8-3

8-2 Delimiters for Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-7
8-3 Delimiters for Rows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-7
8-4 Bulk Data Utility Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-8

10-1 Pervasive Software Resources and Contact Information . . . . . . . . . . . . . . 10-2

ix
Tables

x
About This Manual

This manual introduces you to Pervasive PSQL utilities for Server

and Workgroup products and shows you how to perform the basic
tasks necessary to work with the application. Topics include starting
and stopping the database engine, setting up access to a database,
and accessing data from other applications. This manual also gives
you a tour of the Pervasive PSQL Control Center (PCC). PCC allows
you to manage Pervasive PSQL utilities within a single, easy-to-use
framework.

xi
Who Should Read This Manual
This manual provides information for users who install and run
Pervasive PSQL client/server and Workgroup products.
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 divided into the following chapters:
„ Chapter 1—“Introducing Pervasive PSQL”
This chapter provides an introduction to Pervasive PSQL, and an
overview of utilities and Pervasive PSQL documentation.
„ Chapter 2—“Using Pervasive PSQL”
This chapter covers the basic tasks required to work with
Pervasive PSQL.
„ Chapter 3—“Using Pervasive PSQL Control Center”
This chapter explains how to get your work done using the
Pervasive PSQL Control Center utility.
„ Chapter 4—“License Administrator”
This chapter explains how to increase user counts and add,
delete, and view license keys.
„ Chapter 5—“Table Editor”
This chapter explains how to work with tables and columns
using Table Editor.
„ Chapter 6—“SQL Editor”
This chapter explains how to use SQL Editor to run SQL
statements against a Pervasive PSQL database.
„ Chapter 7—“Pervasive System Analyzer (PSA)”
This chapter explains how to archive, restore, and remove
Pervasive PSQL components and how to test network
connections and active installations.
„ Chapter 8—“Command Line Interface Utilities”
This chapter explains the utilities that provide a command line
interface.
„ Chapter 9—“Basic Troubleshooting”
This chapter provides information for troubleshooting and
resolving problems.

xiii
 „ Chapter 10—“Pervasive PSQL Resources and Contacts”
This chapter explains the resources and information at your
disposal as a valued customer of Pervasive Software.
The manual also includes 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 you are working with Linux or 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
xvi
 chapter

Introducing Pervasive PSQL

1
Understanding Pervasive PSQL and its Capabilities

This chapter provides an explanation of what Pervasive PSQL is and

what it can do for you. This chapter is divided into the following
sections:
„ “Understanding the Pervasive PSQL Database Management
System” on page 1-2
„ “Key Concepts” on page 1-6
„ “Understanding the DBMS Products” on page 1-11
„ “Using Pervasive PSQL Documentation” on page 1-13
„ “File System Security” on page 1-15

1-1
Introducing Pervasive PSQL

Understanding the Pervasive PSQL Database Management

System
Pervasive PSQL is a comprehensive database management system
built around Pervasive Software’s MicroKernel Database Engine.
Pervasive PSQL offers easy installation, uncomplicated maintenance,
and high levels of performance and reliability.
This section explains the product and its components.

What is a Loosely defined, a database is simply a collection of data. Generally,

Database? the data is structured by dividing it into sub-sets of information that
share the same characteristics. Some examples of a database are:
„ A telephone book
Each entry in the phone book consists of four characteristics:
first name, last name, address, and phone number.
„ A collection of digital photographs
Each picture on your hard disk has two characteristics: a file
name, and the data within the file that represents the image.
„ A list of orchards and the fruit grown by each
Each entry in the orchard list might consist of three
characteristics: orchard name, address, and date founded. The
related list of fruits might have five characteristics: orchard
name, fruit name, fruit type (McIntosh, Fuji, and so on), fruit
price, and a taste rating.
In the particular context of this product, a database is a specific, well-
defined collection of related information. You can probably find one
or more databases available on your computer or your network. For
example, you may have a database of information related to vendors
from whom you purchase supplies or raw materials, and you
probably also have a database containing customer or member
information. Each of these is a distinct, well-defined collection of
related information.

1-2
 Understanding the Pervasive PSQL Database Management System

What is a As citizens of the computer age, we are surrounded by collections of

Database information—databases—everywhere we go. Unfortunately, all this
Management data is of no use to anyone without methods to sort it, search it,
System? analyze it, and keep it current.
A database management system, or DBMS, is a computer program
designed to manage large amounts of data and to allow other
computer programs and people to interact with the data. A DBMS
can also be referred to informally as a database engine or simply an
engine. A DBMS performs the following tasks:
„ Controls access to the data. The DBMS can act as a watchdog to
prevent the wrong people from using the data.
„ Structures the data so it can be interpreted by other applications.
The DBMS ensures that all the data adheres to the database
structure, so that other computer programs can work with the
data using common methods.
„ Keeps the data safe and prevents it from getting garbled or lost. The
DBMS facilitates backing up the data in case of catastrophic loss,
and also accesses it in a consistent manner to prevent the data
from suffering inadvertent damage.
„ Makes it easy to add new information, find it, update it, and delete
it. The DBMS readily accepts new data and provides tools that
you can use to locate, update, and remove information as you see
fit. It verifies that the data inserted fits within defined attributes
for the database fields.
„ Allows you to analyze relationships among different sets of data.
The DBMS stores the data in a way that allows you to examine
how any piece of data relates to any other piece of data.
In summary, the DBMS organizes your data, keeps it safe, and helps
you to use it and understand it.

Components of The Pervasive PSQL DBMS consists of a variety of components

Pervasive designed to help you achieve your data management goals.
PSQL
MicroKernel Database Engine
The MicroKernel Database Engine (MKDE) is the high-performance
heart of Pervasive PSQL. The MKDE works directly with the data
files on your computer’s hard disk. When requested, it directly
inserts new data, deletes unnecessary data, and ensures the safety and

1-3
Introducing Pervasive PSQL

integrity of the data files at all times, even when people and
applications are working with the data.

SQL Relational Database Engine

The SQL Relational Database Engine (SRDE) interacts with the
MKDE and the client (described below). It provides many powerful
features including support for Microsoft ODBC, sophisticated
search and analysis capability, and security.

Client (also called Requester)

In client/server systems, the client resides on the computer
workstation. The client interacts with the client application and
across the network with both the MKDE and the SRDE on the server.

Pervasive PSQL Control Center

The Pervasive PSQL Control Center (PCC) is an easy-to-use,
graphical tool designed to help you create and manipulate databases
and control your DBMS. It allows you to access nearly all the
functions of the product from one place. For a tour of PCC, see
Chapter 3, “Using Pervasive PSQL Control Center.”

Utilities
The Pervasive PSQL database engines come with a variety of
graphical and command-line tools designed to provide support for
testing, configuring, and manipulating the many features and
options provided by Pervasive PSQL. Most of the utilities run on
Windows and allow remote function to Linux database server
engines.
Table 1-1 Summary of Pervasive PSQL Utilities

Utility name Supported Description

platforms

Pervasive PSQL Control Windows and Linux Primary utility for Pervasive PSQL. Lists engines and
Center databases available and allows you to set properties
(configure) objects.

Configuration property Windows and Linux Manipulates settings for Pervasive client and server
dialogs within PCC components.

1-4
 Understanding the Pervasive PSQL Database Management System

Table 1-1 Summary of Pervasive PSQL Utilities continued

Utility name Supported Description

platforms

Monitor Windows Monitors server engine activity. Useful for database

administration and programming diagnostics.

Function Executor Windows Executes Btrieve operations, enabling you to learn how
the Btrieve interface works or test and debug an
application.

Maintenance Windows and Linux Performs common Pervasive PSQL file and data
manipulations, such as importing and exporting data.

BUTIL - command line version

SQL Editor - invoked Windows and Linux Allows you to execute SQL statements interactively and
within PCC add or edit data in tables.

Table Editor - invoked Windows and Linux Allows you to add, delete, or change the characteristics of
within PCC columns within a table, and to create a table.

Rebuild Windows Converts one version of MicroKernel files into another

version.

License Administrator Windows and Linux Manages Pervasive PSQL license keys and user counts.

ODBC Administrator Windows Sets up Data Source Names (DSNs) for client and engine
interfaces.

Gateway Locator Windows Used to configure and maintain gateway locator files for
the Workgroup engine.

Pervasive System Windows Analyzes system components and runs communication

Analyzer tests

Query Plan Viewer Windows Displays query plans selected by the database engine so
you can better determine how to optimize SQL queries.

DDF Builder Windows Allows you to view, create, and change Pervasive PSQL
data dictionary files (DDFs) without modifying the
underlying data file.

Documentation
Pervasive PSQL comes with a complete set of online documentation.
For more information about the documentation, see “Using
Pervasive PSQL Documentation” on page 1-13.

1-5
Introducing Pervasive PSQL

Key Concepts
This section explains some basic concepts of databases and some of
the key concepts that distinguish Pervasive PSQL from other
database products.

Basic Database Most database management systems in use today share a common
Structures and set of basic structures. This section briefly explains those structures.
Terms The descriptions that follow refer to the diagram below:

“Phone Book” Table

Column 1 Column 2 Column 3 Column 4

Col Names Name Address Zip Phone

Row 1 Fred Black 643 Oak 12346 555-2345

Row 2 Jane Doe 112 Elm 12345 555-1212

Row 3 John Doe 112 Elm 12345 555-1212

Value
The most basic element of a database is a value. A value is one piece
of data, one characteristic, for a specific entity. For example, in the
diagram, the name “John Doe” or the phone number “555-1212” is
a value.

Column or Field
Another element is a column, or a field. A column represents a
characteristic with no specific value. Columns generally have names
that describe the given characteristic. For example, in the telephone
book, Name and Phone are columns. They do not have specific
values unless you look up a particular person. Field is sometimes
used to refer to the generic characteristic of a specific row. For
example, someone might point to a specific box in the table above
and ask, “What is the value of that field?”

Row or Record
Another element is called a row, or a record. A row is a collection of
all the values for one particular instance. For example, one entry in

1-6
 Key Concepts

the phone book, complete with name, address, and phone number,
is one record or row.

Cell
A cell is a column within a specific record. You can think of it as the
intersection of a row and a column. Each cell has a specific value. For
example, you might tell a co-worker, “The value of the cell located at
row 2, column 3 is ‘12345’.”

Table
A collection of rows and columns makes up a table. A table is a set of
data that shares exactly the same structure. Tables generally have
names that describe the contents of the table. For example, the table
above is called “Phone Book.” With Pervasive PSQL, each table is
stored as a separate data file on the hard disk.

Index
An index is an ordered list of all the values in a particular column. A
table can have zero or more indexes on it. The database engine uses
indexes to find specific records in the database without having to step
through every record one at a time. Creating indexes on columns
which will frequently be used in database searches is likely to
improve the performance of your database.

Database
A database is a collection of one or more tables. The data in the tables
does not need to be related among the various tables, but usually
there are many relations. For example, a database might consist of
the “Food Preferences” table below, and the “Phone Book” table
above. With Pervasive PSQL, a database consists of one or more data
files and Data Dictionary Files (DDFs) on your hard disk. The DDFs
are special data files that contain all the definitions for tables,
columns, and other attributes that define the structure of your
database.

1-7
Introducing Pervasive PSQL

Schema
The term schema refers to the complete set of definitions that
describe the entire structure of a database. A typical schema includes
definitions for tables, columns, indexes, and many other attributes.
The DDFs for a database contain the database’s schema.

“Food Preferences” Table

Column 1 Column 2 Column 3 Column 4

Col Names Name Meat Grain Drink

Row 1 Fred Black sushi wheat sake

Row 2 Jane Doe steak oats beer

Row 3 Ann Dean cod bran spring water

Remote
The term remote refers to an object, such as a file server or a database,
that is not located in the computer you are using now. When you
connect to a database over the network, you are connecting to a
remote database. Remote is the opposite of local. Remote can refer to
either the client or the server, depending on whether you are
currently seated at the server computer or a client computer. Remote
always refers to an object that is not located on the system you are
using.

Local
The term local refers to the computer you are using right now, or
something stored on this computer. A local database is a database in
which the data files are stored on the hard disk of the computer you
are currently using. Local is the opposite of remote. Local can refer
to either the client or the server, depending on whether you are
currently seated at the server computer or a client computer.

1-8
 Key Concepts

Relational
The term relational refers to the storage of data in the form of related
tables. The related tables allow relationships to be created between
sub-sets of data.
For example, you can see that both our example tables contain the
Name column, and some of the names are the same. Because we can
cross-reference the names in the Phone table with the names in the
Food table, we have the power to ask and answer such questions as,
“What is the phone number of someone who likes steak?” We may
also answer such questions as, “Which consumer profile purchased
the most product B after buying product A?”
You can see how powerful relational data access is. The SRDE
component of Pervasive PSQL provides full relational access to your
data.

Join
A join refers to an association between columns of related tables.
Typically, a join operation is part of a SELECT query, which is used
to obtain information from related tables.

Unique One unique feature of Pervasive PSQL is that it allows applications

Benefits of to access data through either the industry-standard relational
Pervasive method outlined above, or through an ultra-high-speed
PSQL transactional or hierarchical method known as the Btrieve interface.
In fact, Pervasive PSQL allows applications to use both access
methods at the same time to access the same data.

Transactional Interface
The transactional interface is a high-performance, low-overhead
access method, capable of handling updates, inserts, and deletes
much faster than other database products.
Applications that use the transactional interface bypass the relational
interface and communicate directly with the MKDE to maximize
performance.
In the interest of performance, the transactional interface offers only
basic security, including file passwords and encryption. It does not
allow SRDE data access to bypass transactional security.

1-9
Introducing Pervasive PSQL

Relational Interface
The relational interface uses industry-standard ODBC to provide a
rich environment for data definition, security, reporting, stored
procedures, and universal application access without requiring any
application programming. Databases that are ODBC-enabled can be
accessed by any ODBC-standard software program.
As an end user of an application based on Pervasive PSQL, you may
not be able to choose which access method your application uses, but
your application vendor has most certainly taken this into account.
No other DBMS available today offers this combination of flexible
relational access and high-speed transaction throughput.

Additional Access Methods

In addition to the Transactional and Relational interfaces, Pervasive
PSQL provides methods to access data through OLE DB, Java
(JDBC), ActiveX, ADO, and Pervasive Direct Access Components
(PDAC) for Delphi and C++ Builder.

Terminology Revisited
When using the Btrieve interface, the terms table and database are
generally not used, and data files are referred to directly as such. In
addition, Btrieve users normally use the terms records and fields
rather than rows and columns.

1-10
 Understanding the DBMS Products

Understanding the DBMS Products

Pervasive PSQL is available in two different database engine
packages. The major differences between the packages are price and
multi-user features.
„ The Workgroup engine is least expensive, but it provides support
only for small workgroup environments.
„ The Server engine is designed for maximum scalability in high-
volume, mission critical database applications where there is a
dedicated database server. The Server engine quickly becomes
most economical as you increase the number of users.
Both engines are fully compatible with any Pervasive PSQL database.
To upgrade or downgrade from one package to another requires no
changes to your application or to your database. Simply install the
new package and you are ready to go. Both engines were designed
with a common architecture and offer the same features.
In addition, there are several add-on packages that you can use to
expand the capabilities of your database. This section explains the
different packages.

Workgroup The Workgroup engine offers a peer-to-peer network setup designed

for stand-alone single-user installations up to small workgroups.
The Workgroup engine is the only engine that offers multi-user
access to Pervasive PSQL data located on a computer where no
database engine is installed.
A major difference between Workgroup and Server is the Gateway
feature of Workgroup. When there is no database engine running on
the computer where the data is located, normally the first database
engine to connect to that data handles all requests from other
engines to access that data. This feature can be configured so that the
same Workgroup engine always services that data, or the Gateway
designation can be allowed to “float” based on which Workgroup
engine connects to the data first during any given work day.
The Workgroup engine comes with a trial license.

1-11
Introducing Pervasive PSQL

Server The Server engine offers a full client/server architecture providing

excellent performance and scalability for up to thousands of
concurrent users. The Server engine can be monitored and
configured remotely.
The Server engine must be located on the same computer as the data
files it is intended to access.

Crystal Reports Another optional product, Crystal Reports provides rich capabilities
for Pervasive for creating and formatting reports based on Pervasive PSQL
PSQL databases. Reports can be customized in thousands of ways and
published as HTML, Microsoft Word document, Microsoft Excel
document, or other formats.
For more information about Crystal Reports, contact your sales
representative or visit the Pervasive web site at:
http://www.pervasive.com.

1-12
 Using Pervasive PSQL Documentation

Using Pervasive PSQL Documentation

All Pervasive PSQL documentation assumes you are familiar with
the basics of using a computer, such as clicking and dragging,
opening and saving files. If you need assistance with these tasks,
please consult the documentation that came with your computer
and/or operating system.
The viewer for the user documentation is integrated into Pervasive
PSQL Control Center (PCC). Access the documentation through the
PCC interface on the Welcome view, in the Help menu, by pressing
F1 (Windows) or Shift F1 (Linux).
The following is a summary of the most commonly used books in the
documentation library. The library contains other books, all of
which can be accessed through the PCC interface as explained above.

Getting Started Getting Started with Pervasive PSQL helps you get Pervasive PSQL
running with installation, setup, and troubleshooting information.
Getting Started With Pervasive PSQL covers the following topics:
„ Preparing to install Pervasive PSQL v10.10
„ Installing Pervasive PSQL v10.10
„ Upgrading from previous versions of Pervasive PSQL or Btrieve
„ Configuring Pervasive PSQL v10.10
„ Troubleshooting your Pervasive PSQL v10.10 installation
„ Where to go for Pervasive PSQL product information and
technical support

What’s New What's New in Pervasive PSQL provides an overview of the new
features and changed behavior for the current release of Pervasive
PSQL relative to the most recent previous release. This book
provides summary information on new features and directs you to
the locations in the documentation where the new features are fully
discussed.

1-13
Introducing Pervasive PSQL

User’s Guide Pervasive PSQL User's Guide introduces Pervasive PSQL and
describes common user tasks. The guide discusses the database
engine, Pervasive PSQL utilities and other key components; the
differences between Server and Workgroup engines; and the
differences between ODBC and Btrieve access. Pervasive PSQL User's
Guide provides you with the basics to work with Pervasive PSQL
successfully.

Advanced Advanced Operations Guide provides detailed information at the

Operations administrative level, including the steps to perform common
Guide procedures and several new ones. Topics include:
„ checking database consistency
„ performing periodic backups
„ configuring network protocols and understanding network
topologies
„ working with database security
„ basic configuration guidelines
„ configuration options reference
„ moving, renaming, compacting and rebuilding files

SQL Engine SQL Engine Reference gives database programmers a complete

Reference reference guide to the SQL relational database language. It also
covers SQL engine parameters and limitations.

Status Codes Status Codes and Messages documents all possible status codes and
and Messages numbered messages that can be received when using Pervasive
software.
The Status Codes Quick Reference is also included with your complete
documentation set.

Additional You can download the product documentation and related

Information documentation from this address:
http://www.pervasive.com/support/technical/online_manuals.asp
You can also find additional information on the Web site at:
http://www.pervasive.com/support/DataSheets.asp
http://www.pervasive.com/library

1-14
 File System Security

File System Security

The Pervasive PSQL engine adheres to the file system security
defined by the specific operating system (OS), such as Windows File
Sharing.
Only the Server engine can enforce OS-level file security based on the
privileges assigned to the login user name. The Workgroup product
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.

1-15
Introducing Pervasive PSQL

1-16
 chapter

Using Pervasive PSQL

2
A Walk-through of Basic User Tasks

This chapter covers the basic tasks you need to know to work with
Pervasive PSQL databases. Included in this chapter are the following
sections:
„ “Starting and Stopping the Database Engine” on page 2-2
„ “Granting Administrative Rights for the Database Engine” on
page 2-8
„ “Setting Up ODBC Database Access” on page 2-15
„ “Setting up Database Access with PCC” on page 2-18
„ “Accessing Data on a Remote Engine Using PCC” on page 2-26
„ “Accessing Data via ODBC From Other Applications” on page 2-
29
„ “Deleting DSNs” on page 2-35
„ “Using the Fast User Switching Feature of Windows XP” on page
2-37

2-1
Using Pervasive PSQL

Starting and Stopping the Database Engine

This section outlines how to start and stop the Pervasive PSQL
engine. Some engine configuration parameters, you need to stop and
restart the engine in order for a particular change in your
configuration to take effect.
To start and stop the database engine, follow the instructions for
your engine and platform:
„ “Starting and Stopping the Server Engine on a Windows Server”
on page 2-2
„ “Starting and Stopping the Workgroup Engine on Windows” on
page 2-5
„ “Starting and Stopping the Database Engine on Linux” on page
2-7

Starting and On Windows server environments, Pervasive PSQL Server runs as

Stopping the services. The services are loaded as part of the installation process
Server Engine and are set to be always available if you followed the default
on a Windows installation.
Server
Services Dependencies
Additional Pervasive PSQL products such as Pervasive
DataExchange also install services. Pervasive DataExchange depends
on both Pervasive PSQL Transactional Engine and Pervasive PSQL
Relational Engine services.
The following table summarizes the behavior of the dependent
services for start, stop, and restart actions of the database engine
services.

2-2
 Starting and Stopping the Database Engine

Note that the behavior of the dependent services is the same

regardless with which application you start, stop, or restart the
database engine services (PCC, Windows Services, Net Start, PSC).
Table 2-1 Action of Dependent Services Based on Action of Database Engine
Services
Database Engine Service Start Stop Restart Service Action for
Data Exchange

Pervasive PSQL  no action

Transactional Engine
 Stop

 Restart

Pervasive PSQL Relational  no action

Engine
 Stop

 Restart

If you start the service for DataExchange, the Pervasive PSQL

Relational Engine starts as a prerequisite service.

Note The dependent services stop without displaying a message

that they will be stopped.

³ To start the database services on a Windows server

using PCC
See “To start or stop services” on page 3-13.

³ To stop the database services on a Windows server

using PCC
See “To start or stop services” on page 3-13.

2-3
Using Pervasive PSQL

³ To start the database services on a Windows server

using Control Panel
1 In the Windows Control Panel, double-click Administrative
Tools then double-click Services.
A dialog box similar to Figure 2-1 appears.
Figure 2-1 Services Dialog Box

2 Right-click Pervasive PSQL Transactional Engine then click

Start. Right-click Pervasive PSQL Relational Engine then click
Start.

³ To stop the database services on a Windows server

using Control Panel
1 In the Windows Control Panel, double-click Administrative
Tools then double-click Services.
A dialog box similar to Figure 2-1 appears.
Figure 2-2 Services Dialog Box

2-4
 Starting and Stopping the Database Engine

2 Right-click Pervasive PSQL Relational Engine then click Stop.

Right-click Pervasive PSQL Transactional Engine then click
Stop.

³ To start the database services on a Windows server by

using Net Start or PSC
1 Click Start Run.
2 Type one of the following:
a. net start “Pervasive.SQL (<transactional |
relational>)”
b. psc start “Pervasive.SQL (<transactional |
relational>)”

3 Click OK.

³ To stop the database services on a Windows server by

using Net Stop or PSC
1 Click Start Run.
2 Type one of the following:
a. net stop “Pervasive.SQL (<transactional |
relational>)”
b. psc stop “Pervasive.SQL (<transactional |
relational>)”

3 Click OK.

Starting and ³ To start the Workgroup Engine as an application on

Stopping the Windows
Workgroup These steps assume that the Workgroup Engine was installed as an
Engine on application. See “Installing the Pervasive PSQL Workgroup for
Windows Windows” on page 6-3 in Getting Started With Pervasive PSQL.
1 Click Engines from the Pervasive group on the Start menu.
2 Click Start Workgroup Engine.

2-5
Using Pervasive PSQL

³ To stop the Workgroup Engine as an application on

Windows
These steps assume that the Workgroup Engine was installed as an
application. See “Installing the Pervasive PSQL Workgroup for
Windows” on page 6-3 in Getting Started With Pervasive PSQL.
1 On the Windows taskbar, right-click the Pervasive Database
icon: .

2 Click Stop Engines and Exit.

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.

³ To start the Workgroup Engine as a service on

Windows
These steps assume that the Workgroup Engine was installed as a
service. See “Installing the Pervasive PSQL Workgroup for
Windows” on page 6-3 in Getting Started With Pervasive PSQL.
1 Refer to the various methods described in the section “Starting
and Stopping the Server Engine on a Windows Server.”
2 Substitute “Pervasive PSQL Workgroup Engine” as the service
name if you use Windows Services control panel. Substitute
“psqlWGE” as the service name if you use net start or psc.

³ To stop the Workgroup Engine as a service on

Windows
These steps assume that the Workgroup Engine was installed as a
service. See “Installing the Pervasive PSQL Workgroup for
Windows” on page 6-3 in Getting Started With Pervasive PSQL.

2-6
 Starting and Stopping the Database Engine

1 Refer to the various methods described in the section “Starting

and Stopping the Server Engine on a Windows Server.”
2 Substitute “Pervasive PSQL Workgroup Engine” as the service
name if you use Windows Services control panel. Substitute
“psqlWGE” as the service name if you use net start or psc.

Starting and In Linux, the database engine runs as a daemon. The daemon is
Stopping the loaded as part of the installation process and is set to be always
Database available if you followed the complete installation.
Engine on You must be logged in as the root user to start and stop the Pervasive
Linux PSQL v10.10 daemon process. Use the shell script psql to start and
stop the process.

³ To start the database engine on Linux

Enter the following at the command line:
/etc/init.d/psql start

For Pervasive PSQL 64-bit Server, this command starts both the
transactional daemon and the relational daemon. The relational
daemon is 32-bit only.

³ To stop the database engine on Linux

Enter the following at the command line:
/etc/init.d/psql stop

For Pervasive PSQL 64-bit Server, this command stops both the
transactional daemon and the relational daemon.

³ To force stop the database engine on Linux

If the database engine does not start or stop correctly using the psql
start and stop commands, you may need to force stop the engine.
The force stop removes any shared memory and semaphores created
by Pervasive PSQL and stops the Pervasive PSQL relational and
transactional processes. Enter the following at the command line to
force stop the database engine:
/etc/init.d/psql force

2-7
Using Pervasive PSQL

Granting Administrative Rights for the Database Engine

This section begins by outlining those Pervasive PSQL v10.10 tasks
that require administrative-level access at the operating system level
and those that do not. The section then walks you through the steps
to grant a user administrative-level access for each of the supported
operating systems.

Note This section only applies to the Server engine unless

otherwise noted.

Tasks Administrative-level rights are required to:

Requiring „ create and configure named databases and tables
Administrative
„ view or modify a table design with Table Editor
Rights
„ set engine configuration options
„ view and set engine monitoring values
„ view certain engine configuration settings

How To have administrator-level access you must:

Administrative „ possess full administrator-level rights on the machine on which
Rights are the database engine is running (a domain administrator, for
Granted example, may lack full permissions on certain local machines),
or
„ be a member of the operating system group Pervasive_Admin.
To modify a table design with Table Editor, you must have full
administrator rights on the machine on which the database engine is
running even if you are a member of the Pervasive_Admin group.

Note For Linux servers, administrator-level rights can be

granted only by using the btadmin utility to add users and
passwords to the btpasswd file.

2-8
 Granting Administrative Rights for the Database Engine

The Pervasive_Admin option is offered so that you can grant users

administrative rights to the database engine without granting them
administrative rights to the operating system where the database
engine resides.

Rights Within You may use one or more Pervasive_Admin groups within an Active
an Active Directory environment. See “Active Directory Service” on page 11-4
Directory in Getting Started With Pervasive PSQL.
Environment

Rights Runtime-only access enables a user without administrator-level

Provided to rights to perform such functions as:
non- „ extract a list of DSNs
Administrative „ extract a count of DSNs
Users
„ extract information on a DSN
„ extract information on the location of the DBnames
configuration file (dbnames.cfg)
„ connect to databases
„ retrieve, update, insert, and delete data (as permitted by
database security)

Tasks for To grant a user administrative rights, follow the instructions for your
Granting platform:
Administrative „ “Granting Administrative Rights on a Windows Server” on page
Rights 2-9
„ “Granting Administrator Rights on Linux” on page 2-13
„ “Logging in as Administrator on any platform” on page 2-14

Granting Users who are members of Pervasive_Admin or of Administrators

Administrative are permitted to perform administrative tasks on the database
Rights on a engine.
Windows
Server

2-9
Using Pervasive PSQL

³ To grant a user database administrator rights on a

Windows 32-bit Server Platform

Note You must be logged onto the Windows server as a user with
full administrator-level rights on the server or be a member of
the Pervasive_Admin group defined on the server.

1 In the Windows Control Panel, double-click Users and

Passwords.
2 Click the Advanced tab. In the Advanced User Management
area, click Advanced.
3 Click the Groups folder. From the menu, click Action New
Group.
4 Type in Pervasive_Admin as the group name.
(To add users to this group, click Add, select user name, click
Add then OK.)
5 Click Create to create the group.
6 Click Close.

Note If the Log on as setting for the Pervasive PSQL services is

not System Account, see “Services Settings and Log In
Authority” on page 2-10.

Services Settings and Log In Authority

Certain operating system settings for the Pervasive PSQL services
must be in effect for you to log in to the machine running the
database engine. These settings apply whether or not you use a
Pervasive_Admin user group.
The settings apply to the Pervasive PSQL Server engine and to the
Workgroup engine if you are running the Workgroup engine as a
service. See “Running the Workgroup Engine as a Service” on page
8-15 in Getting Started With Pervasive PSQL.

2-10
 Granting Administrative Rights for the Database Engine

Default Setting
By default installation, both the Transactional and Relational
services set Log on to Local System Account.

Logging On as “This Account”

If you change the Log on as setting to This account, you must change
the user rights policy Act as part of the operating system for the
account. Otherwise, remote login fails.
For example, the Monitoring utility requires that you log in to the
operating system on the machine where the database engine is
running. You will receive a message that login failed if the account
specified for This account cannot act as part of the operating system.
Note that even the Administrator account requires that you set the
user rights policy for Act as part of the operating system.
You specify This account on the services property sheet.

User Rights Policy Tasks

The following tasks explain how to change the user rights policy.

³ To Set User Rights Policy on Windows 32-bit

Platforms
1 Click Start Settings Control Panel.
2 Double-click Administrative Tools.
3 Right-click Local Security Policy, then click Open.

2-11
Using Pervasive PSQL

4 Expand the tree for Local Policies, and click on User Rights
Assignment.

5 In the policy pane, right-click Act as part of the operating

system, then click Security.

6 Click Add.

2-12
 Granting Administrative Rights for the Database Engine

7 In the Name pane, click on the user or group for whose account
you want to grant the user policy. (For example, you could grant
the policy to the Pervasive_Admin group.)
8 Click Add.
The user name is added to the bottom pane. For example, the
following image shows that the Administrator has been added.

9 Click OK.
The user name is added to the settings for local security policy.

10 Click OK.
11 Exit the window for Local Security Settings, then exit
Administrative Tools.

Granting ³ To grant a user administrator rights on Linux

Administrator A user cannot remotely administer a server engine on Linux unless
Rights on Linux the user has first been set up as a database user with administrative
rights. You can perform this task by using the btadmin utility at the
server command line.
See also “Pervasive PSQL Account Management on Linux” on page
13-4 in Getting Started With Pervasive PSQL for a complete
discussion of configuring the environment for administrative rights.
1 Login to the Linux server as psql (or as root if the PATH and
LD_LIBRARY_PATH variables have been set and exported). No
other user is permitted to run btadmin.

2-13
Using Pervasive PSQL

2 Create a new user with administrative rights by running

btadmin:
btadmin -p passwd a+ user_name
For example, if you wanted to create an administrative user
“tim” with password “tim56”, you would enter the following
command:
btadmin -p tim56 a+ tim

Note Users created with btadmin are not related to Linux system
users. These users are known only to the database engine.

Logging in as ³ To connect to a remote Pervasive PSQL v10.10 server

Administrator 1 Use the Monitor utility to connect to a remote server. Refer to the
on any platform Advanced Operations Guide for a discussion of this utility.
2 Enter your operating system user name and password, and click
OK.
Figure 2-3 Connect to Remote Server Dialog Box

The password is encrypted before being sent over the network

using a unique and pre-defined encryption key. The Pervasive
PSQL v10.10 engine unpacks and decrypts the user name and
password, and verifies access. It then returns a status code to the
client indicating the success or failure of the verification.

2-14
 Setting Up ODBC Database Access

Setting Up ODBC Database Access

This section reviews some conceptual information on setting up
ODBC access to your database.
Topics covered include the following basic concepts:
„ ODBC Standard
„ Servers and Clients
„ Data Source Names
„ Internal Database Name
„ Pervasive.SQL v7 users

Note The Pervasive PSQL Java utilities do not require client or

engine DSNs. The Pervasive PSQL Control Center, for example,
uses JDBC not ODBC. DSNs are required only if your
application uses ODBC to access the database.

ODBC Standard Pervasive PSQL adheres to the Microsoft standard for ODBC
database connections. According to the standard, applications using
ODBC must connect to databases through Data Source Names
(DSNs) defined in the operating system.

Note Pervasive PSQL does not support File DSNs. You must use
User or System DSNs. System DSNs are generally preferred,
because they are available to all users on a given computer.

Every Pervasive PSQL database that you expect to access using an

ODBC application must have a DSN available on the same computer
as the database engine, and (if applicable) another DSN on the client
computer. A DSN that points to a database engine is called an Engine
DSN. A DSN that points to a client DSN is called a Client DSN.

2-15
Using Pervasive PSQL

Note Pervasive PSQL databases that are accessed only through

the transactional interface do not need DSNs. However, in this
case, the database is not visible in PCC nor can it be manipulated
using PCC. To view table data with PCC in readable form, set up
DSNs. PCC accesses the tables though ODBC.

Figures 2-4 shows possible DSN configurations.

Figure 2-4 Example DSN Configurations

Engine with Local Data

Database
Engine Engine DSN

Data
Files
Computer

Engine with Remote Data

Database
Engine DSN <No server engine
Engine
or server engine
Data
not running>
Files

Computer Network File Server

Database Database
Client DSN Engine DSN Server
Client
Engine
Data
Files

Client Computer or Remote Server Computer

Server Computer with
Client Application

Servers and Pervasive PSQL servers are also clients. The client components of
Clients Pervasive PSQL are installed with every Server engine or Workgroup
engine. So you can use your server machine to connect to other
servers as a client. Pervasive PSQL clients can connect to remote
machines where a Pervasive PSQL Server engine is installed.

2-16
 Setting Up ODBC Database Access

Data Source The ODBC client-server architecture calls for the naming of each
Names specific data set so that it can be referred to by a well-known name.
There are generally three ways to create DSNs:
1 Create an Engine DSN from the server console.
2 Create an Engine DSN remotely from a client machine.
3 Create a Client DSN on each client machine.
While Pervasive tools can access remote databases without a
client DSN present on the client machine, ODBC-based
applications such as Microsoft Excel and Microsoft Access
cannot do so. You must create a client DSN on each client
computer that needs to access network databases from local
ODBC applications.

Internal The method used by Pervasive PSQL to identify a database is an

Database Name internal Database Name (DBNAME). If you are using ODBC to
access the database, you need to create a Data Source Name (DSN)
entry that refers to one DBNAME. You may set up more than one
DSN that refers to the same DBNAME. If the physical location of the
data files on the server is changed, only the DBNAME needs to be
updated. All DSNs remain unchanged.

Applications Applications that use only the transactional interface do not require
Using the DSNs. Also, the Pervasive PSQL Java utilities do not require DSNs.
Transactional The Pervasive PSQL Control Center, for example, uses JDBC not
Interface ODBC.

Pervasive.SQL You must recreate all DSNs created with Pervasive.SQL 7 to access
v7 users them in Pervasive PSQL v10.10. However, you do not need to
rename existing database names. To re-create DSNs, follow the
instructions provides in “Deleting DSNs” on page 2-35.

2-17
Using Pervasive PSQL

Setting up Database Access with PCC

You must know the name of the server where the database is located.
If the database already has a DBNAME, PCC uses it. If you wish to
create a new database but use existing data files, you must know the
location of the data files on the server.
To create up an Engine DSN on a remote machine, you must possess
administrator rights on the remote machine that houses the database
you wish to access. You must have OS system rights to create a System
DSN on the local machine.

Setting Up ³ To set up database access on Windows

Database 1 Follow the steps listed in “To register a remote server engine” on
Access on page 3-15.
Windows
Existing databases with a DBNAME on the registered server can
then be accessed from PCC.
2 Optionally, follow the steps listed in “To create a new database”
on page 3-25.
The new database can then be accessed from PCC.

³ To set up ODBC database access on Windows

1 Follow the steps listed in “To register a remote server engine” on
page 3-15.
Existing databases with a DBNAME and a DSN on the registered
server can then be accessed from PCC.
2 Optionally, follow the steps listed in “To create a new database”
on page 3-25 and ensure that the Create DSN option is selected.

By default, PCC creates a system DSN with the same name as the
database name. The new database has a DSN associated with it
and can be accessed through ODBC.

2-18
 Setting up Database Access with PCC

³ To set up an Engine DSN using ODBC Administrator

1 In PCC, click Tools and select ODBC Administrator.
2 Click the System DSN tab, then Add.
3 In the list, click Pervasive ODBC Engine Interface.
4 Click Finish.
The Pervasive ODBC Engine DSN Setup dialog displays.
5 Type a Data Source Name.
6 For Database Name, click the name of the database in the list for
which you want to create the Engine DSN.
7 Click Options if you want to specify the open mode option.
See “DSN Open Mode Options” on page F-3 in SQL Engine
Reference.
8 Click OK.
9 Click OK.

Setting Up ³ To set up a named database and Engine DSN from a

Database Linux server
Access on a Database names are created in Linux by using the dbmaint utility at
Linux Server the server. For a complete description of dbmaint, see “dbmaint” on
page 8-20 or read the dbmaint man page.

Note This utility can only be run by user accounts belonging to

group pvsw. See Getting Started With Pervasive PSQL for
information on Pervasive PSQL Linux utilities and user
accounts.

1 To create an empty database, use the following at the command

line:
dbmaint a | d | l [-b] [-i] [-e] -nDbname [-ldictpath]
[-ddatapath]

The list of commands for dbmaint include:

a – add database name
d – delete database name
l – list all database names

2-19
Using Pervasive PSQL

Options include:
-b – create Bound database
-i – create database with Relational Integrity enforced
-e – do not create dictionary files for database
-nDBName – specify database name
-lDictpath – specify dictionary path
-dDatapath – specify data path
-a – show full data in the DBNames list
For example, to create DBName TEST with relational integrity,
type:
dbmaint a -i -nTEST

Note Unless datapath is specified, the new database is created in

the default location, $PVSW_ROOT/data. Likewise, if dictpath is
not specified, the dictionary is created in the default location.

Š To delete an existing database, use the following at the

command line:
dbmaint d -nDbname

For example, to delete the newly created database TEST, type

dbmaint d -nTEST

Š To list all existing databases:

dbmaint l [-a]

2 To set up an Engine DSN, modify the following files:

Š ${PVSW_ROOT}/etc/odbc.ini.

SQLMGR required settings:

[SQLManager]
MgrPort=1583
Š ${PVSW_ROOT}/etc/odbc.ini

Note The value of ${PVSW_ROOT} is typically /usr/local/psql.

Server data source – the one to which remote calls will be

redirected:

2-20
 Setting up Database Access with PCC

[DSN name]
Driver=/usr/local/psql/lib/libodbcci.so
Description=Test Pervasive database
DBQ=DBName

In addition, each data source should be mentioned in the

section [ODBC Data Sources] as in the following example:
[ODBC Data Sources]
dsnName1=Pervasive PSQL database
dsnName2=Pervasive PSQL database

For example, if you have in odbc.ini:

[MyDSN]
Driver=/usr/local/psql/lib/libodbccci.so
Description=test
DBQ=MyDB

then your odbc.ini should have:

[ODBC Data Sources]
MyDSN=Pervasive PSQL database

Note Because Linux is case sensitive, the [DSN name] must be

input exactly as listed under [ODBC Data Sources].

Š The engine DSN can also be created using the dsnadd utility
by typing the following at the command line:
% dsnadd -dsn=DSNname -db=DBName

An easy way to verify DBName and DSN configuration

settings is to run the supplied isql program using the psql
user account:
% /usr/local/psql/bin/isql DEMODATA

3 Proceed to setting up client DSNs as explained in “Setting Up

Client Access” on page 2-21.

Setting Up ³ To enable client access to a remote Pervasive PSQL

Client Access database
1 Click Control Center from the Pervasive program on the Start
menu.
2 In the Pervasive PSQL Explorer pane, right-click Engines then
click New Server.

2-21
Using Pervasive PSQL

The Pervasive PSQL Explorer pane is the column on the left side
of the window that contains a list of machines to which you are
connected.

Note The machines listed in your Pervasive PSQL Explorer will

remain between sessions. To remove a machine, right-click the
machine name and click Delete.

3 Enter the Server name where the Pervasive PSQL v10.10

database engine resides.
You need to be authenticated on the remote engine, and a dialog
displays prompting you for a user name and password.
4 Enter the user name and password in the appropriate fields and
click OK.
You are now connected to the remote Pervasive PSQL engine.

³ To set up a Client DSN using ODBC Administrator

1 In PCC, click Tools and select ODBC Administrator.
2 Click the System DSN tab, then Add.

Note Pervasive PSQL does not support File DSNs. You must use
User or System DSNs. System DSNs are generally preferred,
because they are available to all users on a given computer.

2-22
 Setting up Database Access with PCC

3 In the Drivers window, select Pervasive ODBC Client Interface.

The following dialog box appears:
Figure 2-5 Pervasive ODBC Client DSN Setup Screen

4 In the Client section, enter a Data Source Name (DSN) to which

you wish to set up a connection. This DSN will help you identify
the data source. It will be visible only on the current machine.
5 Type a description of the data source, if desired.
6 If you want to enable OEM/ANSI conversion, click Options and
make your selection in the dialog box that appears.
Figure 2-6 Pervasive ODBC Client DSN Options

Do not modify the Network settings or TCP/IP Port Number

unless you have first reviewed the information in “ODBC DSN
Creation Options” on page 1-14 in Advanced Operations Guide.
7 Click OK to return to the Pervasive ODBC Client DSN Setup
dialog box.

2-23
Using Pervasive PSQL

Figure 2-7 Pervasive ODBC Client DSN Setup Screen #2

8 In the Server area, type in the host name of the computer where
the data source resides. You can enter a machine name, TCP/IP
address, or an IPX/SPX MAC address.
9 To use an existing database on the server, click Get DSN List and
select the desired DSN from the drop-down list. In the Server
area, Data Source Name refers to an Engine DSN on the server
computer.
If no databases appear in the drop-down list, either you selected
the wrong server, or you need to have your system administrator
name the server databases and create Engine DSNs for each of
them before you can access them.
10 Click OK.
11 You can now set up another Client DSN or click OK to exit the
ODBC Administrator.

2-24
 Setting up Database Access with PCC

Setting Up a While it is possible to access a database from a Linux server by a

Client DSN on a Linux client, there are no Pervasive PSQL utilities (except dsnadd)
Linux that can be used on the client. A Linux client configuration would be
Workstation used for independent applications, such as web applications.

³ To add a client DSN on a Linux Workstation

To add a client data source, execute the following command:
dsnadd -dsn=myDSN -desc=datasource -host=psqlhost
-sdsn=svDSN
myDSN is a name you want to assign to the new Client DSN.
datasource is any string to describe the data source.
psqlhost is the name of the network host where your Pervasive
PSQL database resides.
svDSN is the name of the Engine DSN on the Pervasive PSQL
host.

Note The datasource on the server must be named first.

For example, to create a Client DSN named TEST on host NewDev,

where the Engine DSN name for the database is NewTest, type
dsnadd -dsn=TEST -host=NewDev -sdsn=NewTest
For more information about the dsnadd utility, please see Getting
Started With Pervasive PSQL.

2-25
Using Pervasive PSQL

Accessing Data on a Remote Engine Using PCC

You can use Pervasive PSQL Control Center to access data on a
remote machine on which a Pervasive PSQL v10.10 engine is
installed.

Tip You will need to login as an administrative user on the

remote engine to perform most functions. This means that you
must have full administrator-level rights on the remote server or
be a member of the Pervasive_Admin group defined on the
remote machine.

³ To access data on a remote Pervasive PSQL engine

1 In the Pervasive PSQL Control Center, double-click the remote
Pervasive PSQL Engines node, then double-click Databases.
Figure 2-8 Expanding the Databases List for an Engine

2 In the Databases list double-click DEMODATA, then double-

click Tables.

2-26
 Accessing Data on a Remote Engine Using PCC

3 Double-click the Dept table from the Tables list.

Figure 2-9 Selecting the Dept Table in DEMODATA

By default, a “SELECT * FROM” query is run and the table

results are displayed in an active grid as shown in Figure 2-10.
The data displayed in the active grid that loads is updateable.
That is, changes you make to the data in that grid are stored to
the database.
Figure 2-10 Displaying the Dept Table in DEMODATA

4 Refine the query to restrict the results to only departments that

start with the letter ‘M’ by altering the query at the top half of the
screen with the following statement:
SELECT * FROM Dept WHERE Name LIKE ‘M%’

2-27
Using Pervasive PSQL

5 Click the Execute in Grid toolbar button or press F9 to display

the results of the revised query shown in Figure 2-11.
Figure 2-11 Refining Your Query - Dept Table in DEMODATA

You have now obtained data from the remote database engine.
For information on advanced operating and maintenance tasks,
including database operations, see the Advanced Operations Guide.

2-28
 Accessing Data via ODBC From Other Applications

Accessing Data via ODBC From Other Applications

This section explains how to access data using Microsoft Access and
Microsoft Excel.
The examples covered in this section are:
„ “Accessing Data Using Microsoft Excel” on page 2-29
„ “Accessing Data Using Microsoft Access” on page 2-31

Before You Does the Database Have a DSN Available?

Begin „ If you are connecting from a client workstation or from a
Workgroup workstation to a server, you must have a Client DSN
defined on your workstation for the given remote database.
Information on how to create a Client DSN is provided in
“Setting Up Client Access” on page 2-21.
„ If you have a Workgroup engine installed on your computer, you
may have an Engine DSN defined on your computer for either
local or remote databases. Information on how to create an
Engine DSN is provided in “Setting Up Database Access on
Windows” on page 2-18.

Note The instructions in this section apply only to Pervasive

PSQL v10.10, not to previous versions.

Accessing Data ³ To access Pervasive data using Excel

Using Microsoft
Excel
Tip You must have the Pervasive PSQL client or any version of
the Pervasive PSQL engine installed on the computer where you
are using Excel.

1 Start Excel.
2 From the Data menu, choose:
Get External Data New Database Query as shown below.

2-29
Using Pervasive PSQL

Figure 2-12 Accessing Pervasive Data using Microsoft Excel

3 The Choose Data Source box lists the defined data sources for
any ODBC drivers that are installed on your computer. From
this list, click on the Client or Server DSN for the Pervasive
database you wish to access, as shown in the example below.
Figure 2-13 Excel Display of ODBC Source List

If the database you want does not appear in the ODBC Source
list, see “Before You Begin” on page 2-29.
4 Click OK. You may be prompted to login to the Pervasive PSQL
database. If the database is not secure, leave the User and
Password fields empty. Otherwise enter your assigned user name
and password.
5 The Query Wizard opens. Simply follow the wizard to select
your options such as which tables to query, how to filter and sort
the data, and how you would like Excel to return the Pervasive
data to you for your use.

2-30
 Accessing Data via ODBC From Other Applications

Accessing Data ³ To access data from Microsoft Access

Using Microsoft 1 Open Microsoft Access.
Access
2 From the Access dialog box, choose Blank Access database as
shown below. Click OK. (Note that you may also add Pervasive
PSQL tables to an existing Access database.)
Figure 2-14 Create a New Database using Microsoft Access

3 Next, the File New Database dialog box opens and asks you to
name the new database. Name the database and click Create.
4 From the Access menu, choose:
File Get External Data Link Tables.

Note You have the option to Import data or Link Tables to the
new database. When you choose Import, you break the link to
the ODBC data source immediately following the import
procedure. Essentially, Import creates a static copy of the data.
When you choose Link Tables, Microsoft Access keeps the
connection open and remains dependent upon the ODBC data
source each time the data is accessed. This way, the data you see
reflects any changes to the data at its source.

2-31
Using Pervasive PSQL

Note If you wish to link to a file on a local area network, make

sure to use a universal naming convention (UNC) path, instead
of relying on the drive letter of a mapped network drive in
Windows Explorer. A drive letter can vary on a computer or may
not always be defined, whereas a UNC path is a reliable and
consistent way for Microsoft Access to locate the data source that
contains the linked table.

Figure 2-15 Importing External Data Using Access

5 In the Link dialog box, in the Files Of Type box, select ODBC
Databases.
6 The Select Data Source box lists the defined data sources for any
ODBC drivers that are installed on your computer. Click the
Machine Data Source tab as shown in the next figure.

2-32
 Accessing Data via ODBC From Other Applications

Figure 2-16 Access Display of ODBC Source List

7 Select the ODBC data source that you want to link. If the ODBC
data source that you selected requires you to log on, enter your
user name and password (additional information might also be
required), and then click OK.

Note To define a new data source for any installed ODBC driver,
click New, and then follow the instructions in the Create New
Data Source dialog box and the dialog boxes that follow it before
proceeding.

Tip If you are linking a table, select the Save The Login ID And
Password check box to store the information for the table in the
current database, so that users will not have to enter it each time.
If you leave the check box cleared, all users must enter the logon
ID and password every time they open the table with Microsoft
Access in each new session. Your network administrator can also
choose to disable this check box, requiring all users to enter a
user name and password each time they connect to the database.

If the database you want does not appear in the ODBC Source
list, see“Before You Begin” on page 2-29.

2-33
Using Pervasive PSQL

8 The Access Link Tables dialog box opens. Click each table that
you want to import or link, and then click OK.

Note Microsoft Access cannot display more than 256 columns in

a table. If you need to display more than 256 columns, you may
wish to use a different tool.

Linking to your Pervasive data is complete. As shown in the

figure below, Access presents you with options for designing the
new database. View the linked tables by double-clicking on the
table name.
Figure 2-17 Using Pervasive Data in Microsoft Access

Note If you are linking a table and it does not have an index that
uniquely identifies each record, then Microsoft Access displays a
list of the fields in the linked table. Click a field or a combination
of fields that will uniquely identify each record, and then click
OK.

2-34
 Deleting DSNs

Deleting DSNs
The procedures in this section do not delete Data Dictionary Files
(DDFs) or data files.
By default, when you delete a database in the Pervasive PSQL
Control Center, the associated DSN entries are removed
simultaneously.

³ To toggle automatic removal of DSN entries when

deleting a database in PCC
1 On the PCC Window menu, click Preferences. Expand the
Pervasive node if it is not already expanded.
2 Click General.
3 Clear the option Always remove associated DSN entries and
click OK.
When you delete a database in PCC, you will be prompted by the
Confirm DSN Removal dialog before deleting it.

You can clear those DSNs that you do not want to delete.
4 You can turn on automatic removal of DSN entries at anytime by
selecting Always remove associated DSN entries in:
Š Confirm DSN Removal dialog
Š General screen of the Preferences dialog.

2-35
Using Pervasive PSQL

³ To Delete a DSN using ODBC Administrator (for

Windows DSNs only)
1 In PCC, click Tools and select ODBC Administrator.
2 In the ODBC Administrator window, click the System DSN tab.
3 Select the DSN you wish to remove, and click Remove
You are prompted to confirm removal of the DSN.
4 Click Yes.
5 After the DSN has been removed, click OK to exit ODBC
Administrator.
If you are simply deleting an unwanted DSN, you are finished. If
you need to re-create the DSN, you should refer to one or more
of the following sections:

If you need to do this .... ... refer to this section:

Re-create an Engine DSN on a Server One of:

engine or a Workgroup engine • “Setting Up Database Access on
Windows” on page 2-18
• “Setting Up Database Access on a
Linux Server” on page 2-19

Re-create a Client DSN on a client “Setting Up Client Access” on page 2-21

workstation

2-36
 Using the Fast User Switching Feature of Windows XP

Using the Fast User Switching Feature of Windows XP

Fast user switching is a feature of Windows XP Home Edition and
Windows XP Professional that allows you to switch between users
without logging off from the computer. Multiple users can share a
computer, switching back and forth among users without closing the
programs each user is running. The users are all local to the
computer, not logged in via a network. Only one user at a time can
use the computer interactively.
(The Pervasive PSQL Server engine is not supported on Windows XP
Professional or Home Edition. This support will be available when
Windows XP Server is released.)
As of this release of Pervasive PSQL, the following Microsoft
restrictions apply when fast user switching is turned on. These are
restrictions of the operating system.
„ The computer cannot be logged on to a network domain.
„ The Serial Keys accessibility feature will not work.
„ Offline files, such as Windows XP Offline Documentation, must
be disabled.
Fast user switching allows only two types of users, classified as
administrators or limited. Only administrators can turn on or turn
off fast user switching.
Windows XP Professional allows two modes of operation, local and
remote desktop. Remote desktop uses an XP client to access an XP
machine from a remote computer. In many respects, the remote
desktop feature is similar to terminal services on other Windows 32-
bit platforms.
(You may also use a Pervasive PSQL client on an XP machine to
communicate with a Pervasive PSQL Server engine across a network.
The client functions the same as it does on any other Windows
platform supported by Pervasive PSQL.)

Fast User Switching in Local Mode with Pervasive PSQL

The following conditions apply when you use a Pervasive PSQL
client and Workgroup engine in local mode. Local mode refers to a
local client communicating with a local engine.

2-37
Using Pervasive PSQL

„ Only one instance of the engine may be run at a time. You cannot
run separate copies of the engine within separate user sessions.
If you attempt to start the engine that has already been started by
another user, the engine will not restart. No error message
appears and no tray icon appears.
Š If started by a user, the engine runs in the session of the first
user to start the engine. The operating system rights of the
first user to start the engine determine access rights to the
database files. For example, a limited user can start the
Pervasive PSQL engine but cannot create a new database.
Š If the Pervasive PSQL Workgroup engine is started as a
service, the operating system rights of the System Account
determine access rights to the database files. See “Running
the Workgroup Engine as a Service” on page 8-15 in Getting
Started With Pervasive PSQL.
„ Changes made to a database in one session are available to users
of the database in other sessions. For example, User A adds a
record to Database 1. User B fast user switches to her session.
User B sees the record in Database 1 added by User A.
„ A database accessed by one user’s session can lock the database
from other users’ sessions. For example, User A has Database 1
open in the PCC. User B fast user switches to her session and
attempts to add security to Database 1. User B is prevented from
adding security to the database.

Caution If you run the Workgroup engine as a console

application, the first user to start the engine should not stop the
engine if other users are accessing the engine. In addition, the
first user must not log off because this causes the engine to
terminate.

As an alternative to running the engine as a console application,

you may run the engine as a service. See “Running the
Workgroup Engine as a Service” in Getting Started With
Pervasive PSQL.

2-38
 chapter

Using Pervasive PSQL

Control Center 3
A Tour of Pervasive PSQL Control Center

Pervasive PSQL Control Center (PCC) is an easy-to-use, graphical

tool designed to help you create and manipulate databases and
control your database engine. It allows you to access nearly all the
functions of the product from one place. This chapter leads you on a
tour of PCC to help you learn the interface and common operations
launched from PCC.
The topics in this chapter include:
„ “An Overview of Pervasive PSQL Control Center” on page 3-2
„ “Services on Windows Servers” on page 3-13
„ “Database Engines” on page 3-15
„ “Databases” on page 3-17
„ “New Database GUI Reference” on page 3-22
„ “Pervasive PSQL Database Tasks” on page 3-24
„ “Tables” on page 3-27
„ “Data” on page 3-30
„ “Triggers, Stored Procedures, User-defined Functions, and
Views” on page 3-36
„ “Groups, Users, and Security” on page 3-37
„ “Configuration” on page 3-49

3-1
Using Pervasive PSQL Control Center

An Overview of Pervasive PSQL Control Center

Pervasive PSQL Control Center (PCC) is an integrated framework in
which users can connect to Pervasive PSQL engines, set up and
modify databases and tables, query and update data, tune engine
performance, and access the Pervasive PSQL documentation library.
PCC uses a file explorer-like motif—a tree of objects—referred to as
the Pervasive PSQL Explorer. This tree of objects can be opened or
expanded to reveal more detail. Examples of objects include engines,
databases, tables, and users. The following figures illustrate PCC
with several window views displayed. The Pervasive PSQL Explorer
is the tree view on the left.
Figure 3-1 Pervasive PSQL Control Center on Windows Platforms

3-2
 An Overview of Pervasive PSQL Control Center

Figure 3-2 Pervasive PSQL Control Center on Linux Platforms

Note that the PCC graphical user interface (GUI) may look
cosmetically different depending on your distribution of Linux.

Installing PCC On Windows platforms, PCC is installed by default when you install
a database engine or a client. See “Pervasive PSQL v10.10 Optional
Features” on page 2-6 in Getting Started With Pervasive PSQL.
On Linux, PCC is included in the full install. See “Full and Core
Installations” on page 12-3 in Getting Started With Pervasive PSQL.

Starting PCC on You start PCC from the Pervasive PSQL group on the Start menu.
Windows You may also run the executable file pcc.exe.

3-3
Using Pervasive PSQL Control Center

Starting PCC You start PCC by running the executable script file pcc from a
On Linux command prompt. The script file is located, by default installation,
in the usr/local/psql/bin directory.
We recommend that you start PCC from a command prompt and
not by double-clicking on the script file using a file browser
application. See Table 3-2, “Troubleshooting Guide for Running
PCC” on page 3-5.
The following requirements must be met to start PCC on Linux.
Table 3-1 Requirements for Starting PCC on Linux
Requirement Discussion

Pervasive PSQL server or client A compatible Pervasive PSQL server or client must already be
installed on the same machine.

X-Server access The xhost command controls which clients can access X-Windows
on the current machine. By default, xhost turns on access control.
This means that only the user who starts X-Windows could start
PCC.

You may turn off X-Windows client restrictions by typing xhost +

at a terminal window.

Java Runtime Environment (JRE) The Standard Edition of the JRE is required to run PCC. You can
download the version from java.sun.com.

Some Linux distributions include gcj, a GNU compiler for the Java
programming language. If your Linux distribution includes the gcj
compiler, check your PATH environment variable. Ensure that the
path to the Standard Edition JRE appears before the path to the
gcj.

Rather than change your PATH variable, you could edit the pcc
script and set the correct path in the script.

Note: The PCC installation informs you if the JRE is required.

To determine if the Standard Edition JRE is installed or if it is in your

PATH variable, enter the following command at a terminal window:

java -version
A return message of "command not found" means that you need
either to install a JRE Standard Edition or add the JRE path to the
PATH environment variable. You can download the JRE from
java.sun.com.

Add the PATH using an EXPORT command similar to the following

(assuming your JRE is installed to /usr/local/java):

export PATH=/usr/local/java/bin:$PATH

3-4
 An Overview of Pervasive PSQL Control Center

If you have met the requirements to run PCC and still are having
difficulty running the utility, refer to the following troubleshooting
guide.
Table 3-2 Troubleshooting Guide for Running PCC
Troubleshooting Condition Discussion

You receive the error This error typically occurs if you try to start PCC by double-clicking
“java.lang.UnsatisfiedLinkError." on the script file using a file browser application. Start PCC from a
command prompt.

This error can result if the LD_LIBRARY_PATH variable is not set.

The PCC script sets this variable for you. You may also explicitly set
the variable with the following command:

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/
usr/local/psql/lib

You receive the error "SWT no more You are not required to log in as user psql or root to run PCC.
handles" when trying to run PCC as However, if you are neither of these users, you must be a member
root or as user psql. of group pvsw.

The "SWT no more handles" error is caused by X-Server denying

a connection to a client. Before switching to user psql or root, open
a console window and type xhost + to allow other clients to
connect to X-Server.

Now you can switch to user psql or root.

Also, sometimes the display environment variables needs to be

set. As user psql or root, type the following command at a console
window:

export DISPLAY=:0.0
or

export DISPLAY=localhost:0.0

You want to view the error log file for By default, the log file of PCC errors is located in a subdirectory of
PCC or redirect the errors to the the user’s home directory (the subdirectory is dir_pcc/
console window. workspace/.metadata). For troubleshooting, you may find it
more convenient to redirect the errors to the console window.

To redirect errors to the console window, use the “-consoleLog”

option when starting PCC:

pcc -consoleLog

You receive the following error The context of this error occurs if you attempt to administer the
message: "Unable to connect to local server.
database engine. Make sure the target
machine is accessible and an engine is To administer the local server, you must be a member of the pvsw
running on the target machine.” group or be the root user.

3-5
Using Pervasive PSQL Control Center

Situations Requiring That You Clear PCC Cache

PCC caches certain information to improve efficiency. The cache
must be cleared after you install or upgrade any other products that
“plug in” to PCC. Otherwise, the installed or upgraded product does
not appear in the Pervasive PSQL Explorer. For example, if you were
to install or upgrade Btrieve 7.0 Data Exchange, you would then need
to clear the PCC cache.
The cache can be cleared only by starting PCC with a parameter from
the command line.

³ To clear PCC cache

1 Exit PCC if it is running (click File Exit).
2 Open a command prompt, or terminal window, at the operating
system.
3 Change directory to the PSQL\bin\ folder in the Pervasive PSQL
installation directory.
For default locations of Pervasive PSQL files, see “Where are the
Pervasive PSQL files installed?” on page 7-2 in Getting Started
With Pervasive PSQL.
4 Type pcc -clean and press Enter.
This starts PCC and clears the cache. The newly installed or
upgraded products should then appear in the Pervasive PSQL
Explorer.

Note Use of the -clean parameter when starting PCC provides

no advantage under normal usage. The parameter is required
only if you install or upgrade a plug-in product.

Editors and The PCC main window comprises editors and views:
Views Within „ “Pervasive PSQL Explorer”
PCC
„ “SQL Editor”
„ “Grid”
„ “Text”
„ “Outline”
„ “Table Editor”

3-6
 An Overview of Pervasive PSQL Control Center

You can display and work with objects through the different editors
and views. Multiple editors of the same type (for example, SQL
Editor) can be open at the same time. Each object being edited is
represented by a tab on top of the editor. The tab contains the name
of the object. Data modified within an editor must be explicitly saved
(for example, with File Save).
Views, such as Pervasive PSQL Explorer, can be opened only one at
a time. Actions performed within a view are applied immediately. No
explicit save is required.

Editor and View Characteristics

The following table summarizes the characteristics of the editors and
views.
Table 3-3 Characteristics of PCC Window Views
Characteristic Pervasive SQL Editor Grid Text Outline Table Editor
PSQL Explorer

Contains icons specific to that   

view

Can be closed     
Can be minimized   
Can be maximized     
Can be restored to previous size  
Can be opened in new window     
Can be rearranged within PCC     
main window

Can be "pulled" from PCC and   

placed on desktop

Pervasive PSQL Explorer

This view displays a tree of objects that can be opened or expanded
to reveal more detail. Click the expand icon to the left of an object to
reveal subordinate objects. The expand icon may be a “+” symbol, a
“ ” symbol, or some other similar symbol. Click the collapse icon

3-7
Using Pervasive PSQL Control Center

to hide subordinate objects. (The collapse icon appears after you

click an expand icon.)
The tree of objects includes a root node named Pervasive PSQL. The
root node contains subordinate objects such as clients, services (if
applicable), engines, databases, tables, views, stored procedures,
user-defined functions, triggers, groups, users, and system objects
(such as system tables).
Figure 3-3 Example Objects Shown in Pervasive PSQL Explorer

Accessing Object Properties

A right-click on an object reveals actions or dialogs applicable to that
object. For example, you can right-click on an object then click
Properties to display configurable settings for the object (provided
properties apply to the object). You may also click an object then
press Alt+Enter to display properties.

SQL Editor
SQL Editor allows you to run Structured Query Language (SQL)
statements against a Pervasive PSQL database. See “SQL Editor” on
page 6-1 for a detailed discussion.

Grid
The Grid window view shows in a matrix format, like a spreadsheet,
the result of running SQL statements. Each field is represented as a

3-8
 An Overview of Pervasive PSQL Control Center

column and the data appears in cells within the columns. You can
change data directly in the Grid cells as well as add additional rows
to the Grid.
Both Table Editor and SQL Editor use the Grid. See “To view table
data” on page 5-13 and “Grid Window View” on page 6-4 for further
details.

Text
The Text window view shows in a text format the result of running
SQL statements. The text is display only. You cannot change data
values by changing the text, but you can copy text. See “Text Window
View” on page 6-5 for a detailed discussion.

Outline
The Outline window view allows you to view the SQL statements in
a tree structure. The root node of the tree is the same name as the
name of the SQL Editor window view. See “Outline Window View”
on page 6-7 for a detailed discussion.
Note that the editor must support an outline or the Outline window
view is not available. Currently, only SQL Editor supports an outline
view.

Table Editor
Table Editor allows you to add, delete, or change the characteristics
of columns within a table. The table may be one newly created or an
existing table that you want to edit. See “Table Editor” on page 5-1
for a detailed discussion.

Preferences You can set general preferences for your experience in PCC. You can
also set preferences for the window views in PCC or for the external
tools.

³ To set general preferences for Grid

1 On the PCC Window menu, click Preferences. Expand the
Pervasive node if it is not already expanded.
2 Click General.

3-9
Using Pervasive PSQL Control Center

The following are the options that can be set in the General
Preferences:
„ Always remove associated DSN entries (see “Deleting DSNs” on
page 2-35)
„ Do not prompt for new database each time a SQL document is
opened (see “To set database context for an SQL query” on page
6-14.
Select Always remove associated DSN entries to have all DSN entries
for any database automatically deleted along with the database
without prompting.
Unselect Do not prompt for new database each time a SQL
document is opened to be prompted to select a database each time
you open a SQL document in the SQL Editor. If this option is
unselected, select it to use the most recently selected database when
you open a SQL document. The selected database is not maintained
across PCC sessions. If you close and reopen PCC, you will have to
select a new default database context.

Preferences for PCC Window Views

You can set preferences for the following PCC window views:
„ Grid
„ SQL Editor
„ Table Editor
„ Text

³ To set preferences for PCC Window Views

1 On the PCC Window menu, click Preferences. Expand the
Pervasive node if it is not already expanded.
2 Perform one of the following actions:
a. To set preferences for Data Grid, click Data Grid.
b. To set preferences for SQL Editor, click SQL Editor.
c. To set preferences for Table Editor, click Table Editor.
d. To set preferences for Text Output, click Text Output.

3-10
 An Overview of Pervasive PSQL Control Center

Additional Some utilities have not yet been tightly integrated within the
Utilities Windows PCC framework. However, they may still be started from
within PCC by selecting them through the Tools menu:
„ Function Executor (see “Testing Btrieve Operations” on page
12-1 in Advanced Operations Guide)
„ Monitor (see “Monitoring Database Resources” on page 11-1 in
Advanced Operations Guide)
„ Maintenance (see “Manipulating Btrieve Data Files with
Maintenance” on page 13-1 in Advanced Operations Guide)
„ DDF Builder (see “Getting Started with DDF Builder” on page
1-1 in DDF Builder User’s Guide)
„ License Administrator (see “License Administrator” on page 4-
1)
„ Rebuild (see “Converting Data Files” on page 14-1 in Advanced
Operations Guide)
„ Pervasive System Analyzer (see “Pervasive System Analyzer
(PSA)” on page 7-1)
„ Query Plan Viewer (see “Query Plan Viewer” on page E-1 in SQL
Engine Reference)
„ Gateway Locator (if PCC installed with Pervasive PSQL
Workgroup) (see “Gateway Configuration” on page 8-3 in
Getting Started With Pervasive PSQL)

Note These utilities appear in the Tools menu only on Windows

platforms. For both Windows and Linux platforms, you can add
your own custom tools to the Tools menu. Refer to the next
section.

3-11
Using Pervasive PSQL Control Center

External Tools You can add your own software programs to the PCC Tools menu.
This provides a convenient way to start the programs from PCC.

³ To add external tools

1 On the PCC Window menu, click Preferences. Expand the
Pervasive node if it is not already expanded.
2 Click External Tools.
3 Click New.
4 Type a name for Tool Label that you want to appear in the Tools
menu.
5 Type the path and file name of the program for Tool Location.
You can click and browse to the file location if your prefer.
6 Optionally, type any parameters for Tool Parameters that should
be passed to the program when the program starts.
7 Click OK.
8 Click OK (or Apply then OK) to close the Preferences dialog.

³ To set preferences for external tools

1 On the PCC Window menu, click Preferences. Expand the
Pervasive node if it is not already expanded.
2 Click External Tools.
3 Click the desired tool in the External Tools list.
4 Perform one of the following actions:
a. To remove the tool from the list, click Remove.
b. To move the tool toward the top of the list, click Up.
c. To move the tool toward the bottom of the list, click Down

3-12
 Services on Windows Servers

Services on Windows Servers

PCC offers a convenient way to work with Pervasive PSQL servers on
Windows machines without having to use the Windows Services
control panel. You can start, stop, and set the startup policy from
within PCC.
You must stop the relational and transactional services to completely
stop Pervasive PSQL. Stopping just one of the services does not stop
the database engine completely.
This section applies only to Windows platforms, not to Linux.

Note Pervasive PSQL products other than the database engine

also run as services. The services of these other products can
have a dependency on the database engine services. See “Services
Dependencies” on page 2-2 for further information.

³ To start or stop services

1 In Pervasive PSQL Explorer, expand the Services node in the
tree.
2 Right-click on the service that you want to stop or start.
3 Perform one of the following actions:
a. Click Start Service to start the service
b. Click Stop Service to stop the service
c. Click Restart Service to stop then start the service.

Tip You can also stop or restart all services with a single
command. Right-click the Services node in the tree, then click
Stop All Services or Restart All Services.

3-13
Using Pervasive PSQL Control Center

³ To set services startup policy

1 In Pervasive PSQL Explorer, expand the Services node in the
tree.
2 Right-click on the service for which you want to set a startup
policy.
3 Click Properties.
4 Click the desired policy:

Startup Policy Meaning

Manual You must manually start the service after the operating system
starts.

Automatic The service automatically starts when the operating system

starts.

Disabled The service is removed from operation and is not affected by

starting the operating system.

5 Click OK (or Apply then OK).

Services See “To set services startup policy by using PCC” on page 4-13 in
Properties Advanced Operations Guide.

3-14
 Database Engines

Database Engines
You can use PCC to work with database engines that are on your
machine or with remote server engines. To work with a remote server
engine, you must introduce it to PCC. This procedure is called
registering the server.
Your local server is automatically registered to PCC when you install
Pervasive PSQL v10.10. The local server appears in the Pervasive
PSQL Explorer as the first entry under the Engines node.

³ To register a remote server engine

1 In Pervasive PSQL Explorer, right-click on the top node in the
tree (Pervasive PSQL).
2 Click New Server.
3 Identify the server that you want to register.
Type the name by which the server is identified on the network
or type the IP address of the server.
4 Click Finish.
The server should now appear in the Pervasive PSQL Explorer
window of PCC under the Engines node.

³ To log out from a database engine

These steps do not erase the data or database from the server. A
logout only disconnects the communication between the
database engine and the PCC on your computer.
1 In Pervasive PSQL Explorer, expand the Engines node.
2 Right-click on the server engine from which you want to log out.
3 Click Logout (name).
Name reflects the name of the user currently logged in to the
server through PCC. Name is anonymous if no specific user
name and password were provided for a login.
Any nodes expanded for the database engine are collapsed.

3-15
Using Pervasive PSQL Control Center

³ To reconnect to a database engine

1 In Pervasive PSQL Explorer, expand the node in the tree for the
server engine.

³ To log in to a database engine

1 Right-click on the database name in the PCC Pervasive PSQL
Explorer then click Logout (name).
Name reflects the name of the user currently logged in to the
server through PCC. By default, name is anonymous, meaning
that no specific user name and password were provided for a
login.
Any nodes expanded for the database engine are collapsed.
2 Right-click on the database name.
3 Click Login.
4 Type a User Name and Password.
You can leave these blank to log in as anonymous.
5 Click OK.

Database See “Configuration” on page 3-49.

Engine
Properties

3-16
 Databases

Databases
A database is a collection of data stored together. Newly created
databases are empty and may be populated with tables. Refer to the
chapter “Pervasive PSQL Databases” in Advanced Operations Guide
for a detailed discussion of databases.
The properties of a database include such items as file locations,
referential constraints, security, and whether the database is bound.

Note If you wish to add a database to a Server engine, you must

have administrative rights on the server operating system. If you
do not have administrative rights, you will not be permitted to
add the database.

³ To log out from a database

1 In Pervasive PSQL Explorer, expand the Engines node.
2 Expand the node for the registered server to display the
databases on that server.
3 Right-click on the database from which you want to log out.
4 Click Logout (name).
Name reflects the name of the user currently logged in to the
database. If the database does not have security enabled, name is
Master. Name may also be Master if the current user is logged in
as Master.
Any nodes expanded for the database are collapsed.

Database You set properties for a database from a Properties dialog in PCC.
Properties The dialog contains a tree with the following property nodes:
„ “Code Page”
„ “Directories”
„ “General”
„ “Relational Constraints”
„ “Security”

3-17
Using Pervasive PSQL Control Center

Code Page
This section details the property settings for Code Page.
„ “Database Code Page” on page 3-18
„ “PCC Connection Encoding” on page 3-18

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 encoding
of the server or the client, as explained in “Encoding Interaction”
on page 10-16 in Getting Started With Pervasive PSQL.

Database Code Page

This property specifies the encoding to use for metadata and is
stored in DBNAMES.cfg. Note that this property applies to the
database, which means that it potentially affects all client
applications that exchange data with that database. A compatible
encoding must be established between the Pervasive PSQL database
engine and a client application. See “Encoding Interaction” on page
10-16 in Getting Started With Pervasive PSQL for the various ways in
which this can be accomplished.

Note Changing the database code page does not convert existing
data or metadata in the database. To avoid data corruption,
ensure that the code page setting matches the current encoding
of any pre-existing data or metadata in the database.

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.
The default code page is “server default,” meaning the operating
system code page on the server where the database engine is running.
The link “Change code page” provides additional information about
the setting and lets you select a specific code page.

3-18
 Databases

PCC Connection Encoding

PCC is, itself, a client application to the database engine. As a client,
PCC lets you specify the code page (the encoding) to use for each
database session when PCC reads and inserts metadata and data. The
default for an existing database is to use the encoding of the machine
where PCC is running. This is the legacy behavior of PCC. The
default for a new database is to use automatic translation.
The following explains the interaction between the settings for “PCC
connection encoding” and “Database code page.”

PCC Connection Encoding Set to a PCC Connection Encoding Set to

Specific Encoding "Automatic Translation"

PCC ignores “Database Code Page” PCC and the database automatically
and uses the encoding specified to read establish compatible encoding.
and insert data and metadata.
The database metadata and data are
(This is the legacy behavior of PCC.) translated from the encoding specified
for “Database Code Page” to the
encoding used on the system where
PCC is running.

Note “PCC connection encoding” applies only to PCC. It has no

affect on other client applications.

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 “Automatic” on page F-6 in SQL Engine
Reference.

Directories
The property settings for Directories specify where certain types of
files reside on physical storage.
„ “Dictionary Location” on page 3-19
„ “Data Directories” on page 3-20

3-19
Using Pervasive PSQL Control Center

Dictionary Location
This location specifies where the dictionary files (DDFs) reside on
physical storage. This location must be on the same server to which
you are connected (and where the database engine is running). The
location must be formatted as though you are working directly at the
server machine.
„ For Windows operating systems, enter a path in the form
drive:\path, where drive is a drive letter on the server.
„ For Linux, enter the standard Linux path format from root.
For example, if you are at a workstation connected to a Windows
server where the database engine is running, and you want to create
a new database on the C:\ drive of the server in the folder “mydata,”
enter the location as “c:\mydata.” You would enter it this way even if
you have a local network drive (for example, F:\) mapped to the
server’s C:\ drive.

Data Directories
The Data Directories list specifies where the data files reside on
physical storage. Add locations to the list by clicking New. Remove
lets you remove locations from the list. The locations must be on the
same server where the database engine is running.
Specify the location in the same manner as for the dictionary
locations.

General
General contains the following property settings:
„ “Bound Database” on page 3-20
„ “Integrity Enforced” on page 3-20
„ “Long Metadata (V2 metadata)” on page 3-21
„ “Relational Constraints” on page 3-21

Bound Database
Indicates whether or not the database is bound. Binding a database
prevents the DDFs or data files from being used in another database
and prevents a data file from having two or more different table
definitions within the same database.

3-20
 Databases

For more information about bound databases, refer to “Bound

Database versus Integrity Enforced” on page 6-13.

Integrity Enforced
Specifies whether integrity constraints (security, RI, and triggers) are
enforced on the database. These constraints apply to Btrieve access
to the data files as well as ODBC/SQL access.
See “Setting Up Referential Integrity” on page 6-1 and “Interactions
Between Btrieve and Relational Constraints” on page 6-11.

Long Metadata (V2 metadata)

This property is read-only and shows whether V2 metadata was
specified when the database was created. If it was, the “Long
Metadata” option is selected. Note that V2 metadata is also referred
to as “long metadata.”

Relational Constraints
Relational Constraints displays a matrix that lists the relational
constraints in effect for the database. See “Interactions Between
Btrieve and Relational Constraints” on page 6-11.

Security
Security contains property settings (tabbed areas) for Database
Security and Btrieve Security. See the chapter “Pervasive PSQL
Security” on page 7-1 for a complete discussion of security.

3-21
Using Pervasive PSQL Control Center

New Database GUI Reference

The following image shows the dialog with which you create a new
database. The table below the image describes the GUI objects. (See
also “To create a new database” on page 3-24.)
Figure 3-4 Create New Database Dialog

Table 3-4 Create New Database GUI Elements

Element Description Related Material

Database The name for the database that you want to appear in the “Identifiers and Object Names”
Name database listing in PCC. on page 1-3

Note: The database name cannot be the same as an

existing data source name (DSN).

Location This location must be on the same server to which you are “Dictionary Location” on page
connected (and where the database engine is running). 3-19 on page 3-19 and “Data
Location must be formatted as though you are working Directories” on page 3-20
directly at the server machine.

Bound Indicates whether or not the database is bound. Binding a “Interactions Between Btrieve
database prevents the DDFs or data files from being used and Relational Constraints” on
in another database and prevents a data file from having page 6-11
two or more different table definitions within the same
database.

For more information about bound databases, refer to

“Bound Database versus Integrity Enforced” on page 6-13.

3-22
 New Database GUI Reference

Table 3-4 Create New Database GUI Elements continued

Element Description Related Material

Create Specifies whether you want data dictionary files (DDF) “Dictionary Location” on page
dictionary files created with the database. Dictionary files are required for 3-19
(if they do not relational (SQL) access to your data.
exist)
By default, the dictionary files and data files are created in
the same location. You may specify different locations for
these types of files after you create the database.

Typically, the only situation for which you would choose not
to create DDF files is when you have an unnamed legacy
database for which DDFs already exist, and you are now
creating a database name for that database. Under these
circumstances, the database engine links the new
database name with the pre-existing DDFs.

Relational Specifies whether integrity constraints (security, RI, and “Setting Up Referential
integrity triggers) are enforced on the database. These constraints Integrity” on page 6-1
enforced apply to Btrieve access to the data files as well as ODBC/
SQL access. “Interactions Between Btrieve
and Relational Constraints” on
page 6-11

Long The database engine supports two versions of metadata, “Versions of Metadata” on
Metadata (V2 referred to as version 1 (V1) and version 2 (V2). (V2 page 2-2 in SQL Engine
metadata) metadata is also referred to as “long metadata.”) Reference

Metadata version is a property of the database and applies “System Tables” on page C-1
to all tables within that database. A database cannot use in SQL Engine Reference
some tables with V1 metadata and others with V2
metadata. The DDFs of different metadata versions
cannot interact.

3-23
Using Pervasive PSQL Control Center

Table 3-4 Create New Database GUI Elements continued

Element Description Related Material

Database Specifies the code page property for the database. The “Database Code Page” on
Code Page default is “server default,” meaning the default operating page 3-18
system code page on the server.

See “Related Material” column for the section where this

property is discussed fully.

Create Engine For ODBC access, you must set up a data source name “DSNs and ODBC
DSN (DSN) to refer to the database name. By default, the name Administrator” on page F-1 in
of the new DSN is the same as the Database Name. SQL Engine Reference
Multiple DSNs may point to the same named database.
“Automatic” on page F-6 in
The default is to create the DSN with an encoding SQL Engine Reference
translation option of “None.”
“None” on page F-5 in SQL
Note: The DSN that you are creating must be unique. You Engine Reference
cannot create a database if the name that you specify for
the database matches an existing DSN.

3-24
 Pervasive PSQL Database Tasks

Pervasive PSQL Database Tasks

The following tasks pertain to databases.
„ “To create a new database” on page 3-24
„ “To modify properties of a database” on page 3-25
„ “To delete a database” on page 3-25
For conceptual information on named databases, see “Pervasive
PSQL Database Concepts” on page 1-2 in Advanced Operations
Guide.

³ To create a new database

Note On Linux, the owner of the directory where you want to

create the database must be psql. If not, error message 7039:
Dictionary path is invalid results. Use the chown command to
change owner of the directory. For example, chown psql
directoryname.

1 In PCC Pervasive PSQL Explorer, right-click on the database

engine for which you want the new database.
2 Click New Database.
The Create New Database dialog box appears (see Figure 3-4).
3 Provide a name for the database and a location (see Table 1-1,
“Identifier Restrictions by Identifier Type” on page 1-3).
The name cannot be the same as an existing DSN.
Also, no two files can share the same file name and differ only in
their file name extension if both files are in the same directory.
For example, do not name a data file Invoice.btr and another one
Invoice.mkd in the same directory. This restriction applies
because the database engine uses the file name for various areas
of functionality while ignoring the file name extension. Since
only the file name is used to differentiate files, files that differ
only in their file name extension look identical to the database
engine.
4 Specify the additional options on the dialog as required for the
database. See Table 3-4 for a discussion of the options.

3-25
Using Pervasive PSQL Control Center

³ To modify properties of a database

1 In PCC Pervasive PSQL Explorer, right-click the database engine
for which you want to modify the properties, then click
Properties.

2 On the Properties dialog, click the tree node for which you want
to specify properties:
Š “Directories” on page 3-19
Š “General” on page 3-20
Š “Relational Constraints” on page 3-21
Š “Security” on page 3-21
3 Set the specific properties as required.

³ To delete a database
You cannot delete the database to which you are currently logged in.
See “To log out from a database engine” on page 3-15 in Pervasive
PSQL User's Guide.
If database security is set to “mixed” or “database,” you must first
remove the security. You cannot delete a database if security on it is
set to “mixed” or “database.” See “To turn off security using
Pervasive PSQL Explorer” on page 3-41 and “To turn off security
using SQL” on page 3-41.
1 In PCC Pervasive PSQL Explorer, right-click on the database
engine that you want to delete.
2 Click Delete.

3-26
 Pervasive PSQL Database Tasks

3 Click Yes to confirm the deletion.

The Confirm DSN Removal dialog appears.

4 If you want to remove a DSN associated with the database,

ensure that the DSN is check marked in the list.
Note that multiple DSNs can be associated with one database. In
such cases, you may remove the DSNs that you want and retain
the ones that you want.
5 Optionally, select the option Always remove associated DSN
entries if you want PCC to set DSN removal as the default action.

Note If you select the option, PCC no longer prompts you for
DSN removal when you delete a database. PCC will
automatically remove all DSNs associated with the database
being deleted.

If you decide later to turn off the option, in PCC click Window
Preferences General.

3-27
Using Pervasive PSQL Control Center

Tables
Tables are the objects in which databases store data. Pervasive PSQL
contains two types of tables: data and system. Data tables are user-
created. Newly created ones are empty and must be populated with
data. System tables are created and populated as required by the
Pervasive PSQL database management system.

Data Tables Refer to the chapter “Table Editor” on page 5-1 for a detailed
discussion of data tables. That chapter also contains the tasks
pertaining to tables, such as creating one, deleting one, working with
columns, foreign keys, and so forth.

Note To create a table in a database, database security must be

turned off or you must have access rights to create tables.

System Tables System tables appear in the Pervasive PSQL Explorer under the
System Objects node. You may view properties of them as explained
in “To view properties of a table.”

Table Table properties provides information about the table. Separate tabs
Properties let you view general properties, columns information, and indexes
information. The following table describes the parameters listed on
the General tab.
Table 3-5 Table Properties on General Tab
Parameter Description

Table Name Shows the name of the table as it appears in the database definition.

Table Location Shows the physical location of the data file associated with the table.

Dictionary Path Shows where the database's DDF files are located.

File Version Shows the file format version of the data file.

Record Length Shows the length of the data file's records.

Page Size Shows the page size (in bytes) of the data file. The page size determines
the maximum number of index segments that can be defined in a table.

Number or Records Shows the number of records currently contained in the data file.

3-28
 Tables

Table 3-5 Table Properties on General Tab continued

Parameter Description

Number of Indexes Shows the number of indexes defined for the table.

Number of Duplicate Pointers Shows the number of linked duplicate indexes that can be added.
(Ptrs)

Number of Unused Pages Shows the number of pre-allocated pages available. If pre-allocation is
enabled, the MicroKernel pre-allocates a specified number of pages
when it creates the data file. Pre-allocation guarantees that disk space
for the data file is available when the MicroKernel needs it.

Variable Records Shows whether the data file contains variable-length records.

Variable Record Blank Truncation Shows whether blank truncation is enabled. If it is, the MicroKernel
truncates the blanks in variable-length records. Blank truncation is
applicable only if the Variable Records statistic is Yes and Data
Compression is set to No.

Record Compression Shows whether record compression is enabled. If it is, the MicroKernel
compresses each record it inserts into the data file. See “Record and
Page Compression” in Advanced Operations Guide.

Key Only File Shows the name of the key-only file for the table, if any. A key-only file
contains no data records but serves as an index to other Btrieve files.

Index Balancing Shows whether balanced indexing is enabled.

FreesSpace Threshold Shows a percentage (5%, 10%, 20% or 30%) if the data file has a free
space threshold. The database engine stores the variable-length
portions of records on their own pages (called variable pages), separate
from the fixed-length portions (which are stored on data pages).

The database engine uses the threshold to determine whether to add

data to an existing variable page or to create a new one. A higher free
space threshold reduces fragmentation of variable-length records across
several pages but uses more disk space.

Uses Alternate Collating Shows whether the table uses an alternate collating sequence for
Sequence sorting.

System Data Key Shows whether the data file has system data keys enabled.

Page Compression Shows whether page compression is enabled. See “Record and Page
Compression” in Advanced Operations Guide.

3-29
Using Pervasive PSQL Control Center

³ To view properties of a table

1 In Pervasive PSQL Explorer, expand the Tables node.
2 Right-click on the desired table, and click Properties.

Tip You can use the table properties to view a list of the indexed
columns for the table.

3-30
 Data

Data
The tables that you create with PCC are initially empty. You can add
data to them through PCC or by importing data. PCC provides a
wizard to export data and one to import data.

Creating Data See “To add rows of data to the Grid” on page 6-22.
Through PCC

Importing Data See “bdu” on page 8-7 in Pervasive PSQL User's Guide.
with Bulk Data
Utility

Importing Data The Import Data Wizard reads delimited data from a text file and
with Import adds the data to a table. The wizard allows you to specify the
Data Wizard following:
„ Text file that contains the data to import.
„ Field delimiter.
„ Encoding of the imported data. The encoding must match the
encoding that was used to export the data. See “Exporting Data
with Export Data Wizard” on page 3-31.
„ Whether or not the first line of the exported data contains the
column names. If the data was exported with column names as
the first line, it be must imported the same way.

Restrictions
The data must use a field delimiter of the comma, colon, or tab
character. A combination of carriage return and line feed must
delimit records.

³ To import data from a database table

1 Right-click a table name under the Tables node.
This is the table into which you want to import the data.
2 Click Import Data.
3 Provide the import characteristics as discussed above, then click
Finish.

3-31
Using Pervasive PSQL Control Center

Exporting Data The Export Data Wizard exports data from a table to a text file. A
with Export combination of carriage return and line feed delimits records.
Data Wizard The wizard lets you specify the following:
„ Name of the file to which the data is exported. If you include a
path with the file name, the directory or directories in the path
must already exist.
„ SQL statement on which the export is based. For example,
SELECT * FROM t1 would export all records from table t1.
„ Field delimiter (character used to separate data items in each
record).
„ Encoding of the exported data. For example, if you select ISO-
8859-1, the data is exported using that code page. The encoding
choices are obtained from the machine on which the utility is
running.
„ Whether or not to write the names of the columns as the first line
of the exported data.

³ To export data from a database table

1 Right-click a table name under the Tables node.
2 Click Export Data.
3 Provide the export characteristics as discussed above then, click
Finish.

3-32
 Metadata

Metadata
Metadata is data about data. The metadata for a Pervasive PSQL
database is called a schema. For a relational database, the schema
defines the tables, the fields in each table, and the relationships
between fields and tables. Schemas are stored as data dictionary files
(DDFs) by Pervasive PSQL.
You can export the schema for one or more tables to a text file. The
exported schema contains the CREATE TABLE SQL statement (and
CREATE INDEX statement if applicable) to create the table and its
indexes. The exported file has a default file extension of “sql” and is
called an SQL script.
The SQL script file can be run (executed) in SQL Editor. See “To
open an SQL script” on page 6-16.
The SQL script contains the text “Unable to open table” if a table
cannot be opened. For example, the error occurs if an owner name is
set on a table or a table has been deleted outside of PCC while PCC
is currently running.
You have three options when exporting a table schema:
„ Include an IN DICTIONARY clause with a USING clause in the
statement
„ Include only the USING clause in the statement
„ Omit both the IN DICTIONARY clause and the USING clause
in the statement (a “plain” statement)

IN DICTIONARY The IN DICTIONARY clause instructs the database engine to

Clause modify only the DDFs, which leaves the underlying physical data
unchanged. Normally, Pervasive PSQL keeps DDFs and data files
synchronized, but this clause allows you to force table dictionary
definitions to match an existing data file.
The clause can be useful when you want to create a definition in the
dictionary to match an existing data file. Another common use is if
you want to duplicate an existing database. You export all the
statements from one database, create a new database and then run
the exported script against the new database.

3-33
Using Pervasive PSQL Control Center

If the SQL script contains IN DICTIONARY clauses, note that the

data file must already exist when you run the SQL script in SQL
Editor.
The IN DICTIONARY clause is always paired with a USING clause.
An exported statement looks similar to the following:
CREATE TABLE "Course" IN DICTIONARY USING 'Course.mkd' (
"Name" CHAR(7) NOT NULL CASE ,
"Description" CHAR(50) CASE ,
"Credit_Hours" USMALLINT,
"Dept_Name" CHAR(20) NOT NULL CASE
);
CREATE UNIQUE INDEX "Course_Name" IN DICTIONARY ON
"Course"("Name");
CREATE INDEX "DeptName" IN DICTIONARY ON
"Course"("Dept_Name");

See also “IN DICTIONARY” on page 3-12 in SQL Engine Reference.

USING Clause The USING keyword allows you to associate a table with a particular
data file.
An exported statement looks similar to the following:
CREATE TABLE "Course" USING 'Course.mkd' (
"Name" CHAR(7) NOT NULL CASE ,
"Description" CHAR(50) CASE ,
"Credit_Hours" USMALLINT,
"Dept_Name" CHAR(20) NOT NULL CASE
);
CREATE UNIQUE INDEX "Course_Name" IN DICTIONARY ON
"Course"("Name");
CREATE INDEX "DeptName" IN DICTIONARY ON
"Course"("Dept_Name");

See “USING” on page 3-14 in SQL Engine Reference.

Plain Statement The “plain” statement omits the IN DICTIONARY clause and the
USING clause. The plain CREATE TABLE syntax is useful to
duplicate an existing table by simply changing the table name or to
create the same table in a different database.
An exported statement looks similar to the following:

3-34
 Metadata

CREATE TABLE "Course"(

"Name" CHAR(7) NOT NULL CASE ,
"Description" CHAR(50) CASE ,
"Credit_Hours" USMALLINT,
"Dept_Name" CHAR(20) NOT NULL CASE
);
CREATE UNIQUE INDEX "Course_Name" ON "Course"("Name");
CREATE INDEX "DeptName" ON "Course"("Dept_Name");

See “CREATE TABLE” on page 3-83 in SQL Engine Reference.

Exporting a You can export a schema for a particular table (or tables) or, at the
Schema database level, for all tables at once.

³ To export a table schema for a particular table

1 In Pervasive PSQL Explorer, expand the Tables node for the
desired database.
2 Click the table name for which you want to export its schema.
If you want to export the schema for additional tables, press and
hold Shift or Ctrl then click the desired table names. (In other
words, use multiple select for the tables you want.)
3 Right-click on the selected table name, then click Export Table
Schema.
4 Type the name (and location if you want) for the exported file.
The default file extension is “sql.”
5 Optionally, select the IN DICTIONARY or the USING option.
6 Click OK.

3-35
Using Pervasive PSQL Control Center

³ To export all table schemas at once

1 In Pervasive PSQL Explorer, expand the Databases node.
2 Right-click the database name for which you want to export all
of the table schemas.
3 Click Export Table Schema.
4 Type the name (and location if you want) for the exported file.
The default file extension is “sql.”
5 Optionally, select the IN DICTIONARY or the USING option.
6 Click OK.

3-36
 Triggers, Stored Procedures, User-defined Functions, and Views

Triggers, Stored Procedures, User-defined Functions, and

Views
PCC provides a way to create, modify, and delete triggers, stored
procedures, user-defined functions, and views. See “SQL Editor
Tasks” on page 6-11.
These objects appear as nodes in the Pervasive PSQL Explorer.

Object Description Related Information

Triggers A type of stored procedure that are “CREATE TRIGGER” on

automatically executed when data page 3-108 in SQL Engine
in a table is modified with an Reference
INSERT, UPDATE, or DELETE.
“Common SQL Object
Tasks” on page 6-12

Stored A collection of one or more SQL “CREATE PROCEDURE”

procedures statements that can take and return on page 3-68 in SQL
user-supplied parameters. Engine Reference

“Common SQL Object

Tasks” on page 6-12

User-defined A scalar routine that returns a “CREATE FUNCTION” on

functions value. page 3-53 in SQL Engine
Reference

“Common SQL Object

Tasks” on page 6-12

Views A database object that stores a “CREATE VIEW” on page

query and behaves like a table. 3-113 in SQL Engine
Reference

“Common SQL Object

Tasks” on page 6-12

3-37
Using Pervasive PSQL Control Center

Groups, Users, and Security

Security is a database property that requires a user to provide a user
name and password to access the database. By default, database
security is turned off.
Database security can be turned on through PCC or by executing an
SQL statement. Once enabled, you may create groups and users and
assign permissions to them. Permissions can include database rights,
table rights, and column rights within tables.
When you turn security on or off, the Master user must have only
one connection open and must be the only user connected.
As soon as you turn security on for the first time, only the Master
user can access the database. The Master user password, as with all
Pervasive PSQL passwords, is case sensitive.

Caution If you turn on security, be sure to specify a password

with a significant length. Do not leave the password field blank
because doing so creates a major security risk for your database.

See “Pervasive PSQL Security” chapter in Advanced Operations

Guide for additional information about security.

3-38
 Groups, Users, and Security

Security Tasks This section contains step-by-step tasks pertaining to security. The
tasks are divided into the following categories:

Category Description

General Tasks Orient you to the overall use of security

• “To log into a database using PCC when you are already logged into that
database as another user” on page 3-39
• “To turn on security using Pervasive PSQL Explorer” on page 3-39
• “To turn on security using SQL” on page 3-40
• “To turn off security using Pervasive PSQL Explorer” on page 3-41
• “To turn off security using SQL” on page 3-41

Btrieve Security Policy Tasks Apply to security policies for the transactional interface
• “To set or change the security policy for a database” on page 3-42
• “To use an existing database, including the pre-defined DefaultDB, with
your Pervasive PSQL files” on page 3-43

User and Group Tasks Apply to creating users and groups

• “To create a new group using Pervasive PSQL Explorer” on page 3-44
• “To create a new user using Pervasive PSQL Explorer” on page 3-44
• “To assign a user to a group using Pervasive PSQL Explorer” on page 3-
45
• “To delete a group or user using Pervasive PSQL Explorer” on page 3-45
• “To work with groups and users using SQL” on page 3-45

Assigning Permissions Tasks Apply to assigning permissions to users and groups

• “To assign permissions for a group using Pervasive PSQL Explorer” on
page 3-46
• “To assign permissions for a user using Pervasive PSQL Explorer” on
page 3-47
• “To assign permissions to all users using Pervasive PSQL Explorer” on
page 3-48
• “To assign permissions for a group or user using SQL” on page 3-48

Encryption Tasks Apply to data encryption

See “Data Encryption” on page 7-23 in Advanced Operations Guide.

3-39
Using Pervasive PSQL Control Center

General Tasks

³ To log into a database using PCC when you are

already logged into that database as another user

Note As the Master user, logging in as another user can aid you
in testing the more restrictive permissions you have assigned this
user.

1 Right-click on the database name in the PCC Pervasive PSQL

Explorer then click Logout (name).
Name reflects the name of the user currently logged in to the
database. If the database does not have security enabled, name is
Master. Name may also be Master if the current user is logged in
as Master.
Any nodes expanded for the database are collapsed.
2 Right-click the database name.
3 Click Login.
4 Type the user name and password, then click OK.

³ To turn on security using Pervasive PSQL Explorer

If the database resides on a remote machine, you must provide a user
name and password of an administrator or of a member of the
Pervasive_Admin group for the remote machine. The user name and
password is not required if the database resides on the local machine
to which you are logged in (and the local machine is not running
Terminal Services).
Turning on security prevents all users from accessing the database
unless they login to it using a valid database user name and
password. User names and passwords cannot be set up until security
is turned on, so the database will be inaccessible to each user for the
period of time until you have set up a user account for that user.
1 In Pervasive PSQL Explorer, expand the Engines node, then the
Databases node.
2 Right-click on the desired database then click Properties.
3 Click Security in the Properties tree.

3-40
 Groups, Users, and Security

4 Click the Security tab.

5 Click Enable Security to check mark the option.
6 Type the password you want for Master Password, then re-type
it for Confirm Password.
7 Click OK.
Database security is now on and you are logged in as the Master
user. For instructions on creating database user accounts, see
“User and Group Tasks” on page 3-44.

³ To turn on security using SQL

You must be logged into the computer as an administrator or as a
member of the Pervasive_Admin operating system security group.
Turning on security prevents all users from accessing the database
unless they login to it using a valid database user name and
password. User names and passwords cannot be set up until security
is turned on, so the database will be inaccessible to each user for the
period of time until you have set up a user account for that user.
1 Turn security on for the database as explained in “General Tasks”
on page 3-39.
2 In the File menu of PCC, click New SQL Document (or click
in the toolbar).
The Select Database dialog box appears.
3 Click the database in the list for which you want to create a group
or user.
4 Click OK.
5 In SQL Editor, issue the SQL statement SET SECURITY=
‘password’ where password is the text string you want to use as
the password for the Master user.
6 Click SQL Execute in Text (or click in the toolbar).
See also “SET SECURITY” on page 3-258 in SQL Engine
Reference.

3-41
Using Pervasive PSQL Control Center

³ To turn off security using Pervasive PSQL Explorer

You must be logged into the computer as an administrator or as a
member of the Pervasive_Admin operating system security group.

Caution Turning off security allow all operating system users to

access the database through the relational and transactional
interfaces if database security is Mixed or Database mode.

Database user names, passwords, and permissions are retained

but not used if security is turn off. If security is re-enabled, the
previous user names, passwords, and permissions take effect
again. (An exception is the Master user. The Master password is
not retained nor re-applied.)

1 In Pervasive PSQL Explorer, expand the Engines node, then the

Databases node.
2 Right-click on the desired database then click Properties.
3 Click Security in the Properties tree.
4 Click the Security tab.
5 Click Enable Security to clear the option.
6 Click OK.
Database security is now off.

³ To turn off security using SQL

Caution Turning off security allow all operating system users to

access the database through the relational and transactional
interfaces if database security is Mixed or Database mode.

Database user names, passwords, and permissions are retained

but not used if security is turn off. If security is re-enabled, the
previous user names, passwords, and permissions take effect
again. (An exception is the Master user. The Master password is
not retained nor re-applied.)

3-42
 Groups, Users, and Security

1 Turn security on for the database as explained in “General Tasks”

on page 3-39.
2 In the PCC File menu, click New SQL Document (or click
in the toolbar).
The Select Database dialog appears.
3 Click the database in the list for which you want to create a group
or user.
4 Click OK.
5 In SQL Editor, issue the SQL statement SET SECURITY=
NULL.
6 Click SQL Execute in Text (or click in the toolbar).
See also “SET SECURITY” on page 3-258 in SQL Engine
Reference.

Btrieve Security Policy Tasks

³ To set or change the security policy for a database

Caution Changing security policy for a database may prevent

current users from accessing the database, if security is turned
on and the given users do not have equivalent user accounts and
rights under the new security policy.

1 Turn security on for the database as explained in “General Tasks”

on page 3-39.
2 In Pervasive PSQL Explorer, expand the Engines node, then the
Databases node.
3 Right-click the desired database then click Properties.
4 Click Security in the Properties tree.
5 Click the Btrieve Security tab.

3-43
Using Pervasive PSQL Control Center

6 Click the desired policy: Classic, Mixed, or Database.

7 Click OK.
See also the chapter “Pervasive PSQL Security” in Advanced
Operations Guide.

Caution If your database has security turned on and you change

from Classic security policy to Mixed or Database, all users are
prevented from accessing the database until you create database
user accounts and privileges for them.

³ To use an existing database, including the pre-defined

DefaultDB, with your Pervasive PSQL files
1 In Pervasive PSQL Explorer, expand the Engines node, then the
Databases node.
2 Right-click on the desired database then click Properties.
3 Click Directories then click New.
4 Type a path for the Pervasive PSQL files then click OK.
If your files are spread over many directories, specify a high-level
directory that they all have in common. You can specify a root
level if necessary, but doing so includes in the database all
Pervasive PSQL+ files at the root level and its subordinate
directories.
You do not need to enter every directory, just the lowest level
directory that is common to all Btrieve files you want to include
in the database.
5 Turn security on for the database as explained in “General Tasks”
on page 3-39.
6 Set permissions for groups and users and explained in “User and
Group Tasks” on page 3-44.

3-44
 Groups, Users, and Security

User and Group Tasks

³ To create a new group using Pervasive PSQL Explorer

Note that you cannot add a group to another group.
1 Turn security on for the database as explained in “General Tasks”
on page 3-39.
2 Expand the nodes for the database.
3 Right-click the Groups node then click New Group.
4 Type the name that you want for the group.
5 Click Finish.

³ To create a new user using Pervasive PSQL Explorer

1 Turn security on for the database as explained in “General Tasks”
on page 3-39.
2 Expand the nodes for the database.
3 Right-click on the Users node then click New User.
4 Type the name that you want for the user.
5 Type a password for Password and re-type it for Confirm
Password.
Passwords are case sensitive. For a list of database object lengths
and invalid characters, see “Identifier Restrictions by Identifier
Type” on page 1-3 in Advanced Operations Guide..
6 Optionally, assign the user to a group.
Click for Group, then click the desired group in the list.
7 Click Finish.

3-45
Using Pervasive PSQL Control Center

³ To assign a user to a group using Pervasive PSQL

Explorer
Note that a given user cannot be a member of more than one group.
All users in a group have exactly the permissions defined for that
group. You cannot grant or revoke individual permissions for a user
who is a member of a group.
1 Turn security on for the database as explained in “General Tasks”
on page 3-39.
2 If the desired group does not exist, create the group as explained
in “To create a new group using Pervasive PSQL Explorer” on
page 3-44.
3 Right-click on a user name under the Users node then click
Properties.
4 Click General in the Properties tree.
5 Click for Group, then click the desired group in the list.
6 Click OK.

³ To delete a group or user using Pervasive PSQL

Explorer
Note that a group can be deleted only if no users are assigned to it.
1 Expand the nodes for the database.
2 Expand the Groups node or Users node.
3 Right-click the desired group or user name.
4 Click Delete.
5 Click Yes.

³ To work with groups and users using SQL

1 Turn security on for the database as explained in “General Tasks”
on page 3-39.
2 In the File menu of PCC, click New SQL Document (or click
in the toolbar).
The Select Database dialog box appears.
3 Click the database in the list for which you want to create a group
or user.

3-46
 Groups, Users, and Security

4 Click OK.
5 In SQL Editor, create the desired statement for the group or user.
Refer to the following statements in SQL Engine Reference:
Š “CREATE GROUP” on page 3-60
Š “ALTER GROUP” on page 3-8
Š “DROP GROUP” on page 3-137
Š “CREATE USER” on page 3-111
Š “ALTER USER” on page 3-26
Š “DROP USER” on page 3-143
Š “GRANT” on page 3-154
Š “REVOKE” on page 3-200
Š “SET PASSWORD” on page 3-250
6 To execute the statement, click SQL Execute in Text (or click
in the toolbar).

Assigning Permissions Tasks

³ To assign permissions for a group using Pervasive

PSQL Explorer

Note Permissions on the Database tab override permissions on

the Table tab.

1 Expand the nodes for the desired database.

2 Right-click the group name under the Groups node then click
Properties.
3 Click Permissions in the Properties tree.

3-47
Using Pervasive PSQL Control Center

4 Click the tab to access permissions for the desired object:

database, tables (and columns), stored procedures, or views. See
also “Permissions on Views and Stored Procedures” on page 3-
158 in SQL Engine Reference.
5 On the tab, click the option for the desired permission.
A check mark indicates that the permission applies.
6 Click OK.

³ To assign permissions for a user using Pervasive

PSQL Explorer

Note You cannot assign specific permissions to a user if the user

is a member of a group. The permissions of the group apply to
the user.

Permissions on the Database tab override permissions on the

Table tab.

1 Expand the nodes for the desired database.

2 Right-click on the user name under the Users node then click
Properties.
3 Click Permissions in the Properties tree.
4 Click the tab to access permissions for the desired object:
database, tables (and columns), stored procedures, or views. See
also “Permissions on Views and Stored Procedures” on page 3-
158 in SQL Engine Reference.
5 On the tab, click the option for the desired permission.
A check mark indicates that the permission applies.
6 Click OK.

3-48
 Groups, Users, and Security

³ To assign permissions to all users using Pervasive

PSQL Explorer

Note Permissions on the Database tab override permissions on

the Table tab.

1 Expand the nodes for the desired database.

2 Right-click on the group PUBLIC under the Groups node then
click Properties.
3 Click Permissions in the Properties tree.
4 Click the tab to access permissions for the desired object:
database, tables (and columns), stored procedures, or views. See
also “Permissions on Views and Stored Procedures” on page 3-
158 in SQL Engine Reference.
5 On the tab, click the option for the desired permission.
A check mark indicates that the permission applies.
6 Click OK.

³ To assign permissions for a group or user using SQL

1 In the PCC File menu, click New SQL Document (or click
in the toolbar).
The Select Database dialog box appears.
2 Expand the nodes for the desired database.
3 Click OK.
4 In SQL Editor, create the desired statement for the group or user.
In SQL Engine Reference, see the following:
Š “GRANT” on page 3-154
Š “REVOKE” on page 3-200
Š “SET PASSWORD” on page 3-250
5 Click SQL Execute in Text (or click in the toolbar).

3-49
Using Pervasive PSQL Control Center

Configuration
Configuration is the process by which you provide settings for
database engines and clients. You can specify configuration settings
with PCC for database engines and the local client.
In PCC, the configuration settings are properties of the engine or
client. In Advanced Operations Guide, see “To access configuration
settings in PCC for an engine” on page 4-4 and “To access
configuration settings in PCC for a local client” on page 4-4.
In addition, refer to the following sections in Advanced Operations
Guide for a discussion of configuration settings that can be
configured through PCC:
„ “Services Configuration Parameters” on page 4-13
„ “Server Configuration Parameters” on page 4-14
„ “Windows Client Configuration Parameters” on page 4-49

3-50
 chapter

License Administrator
4
Working with License Keys and User Counts

This chapter covers the following topics:

„ “License Administrator Concepts” on page 4-2
„ “License Administrator Graphical User Interface” on page 4-5
„ “License Administrator Command Line Interface” on page 4-8
„ “License Administrator Tasks” on page 4-10

4-1
License Administrator

License Administrator Concepts

A Pervasive PSQL license key allows a fixed number of computers
(called a user count) to access a Pervasive PSQL engine concurrently.
A license key is a human-readable string of letters and numbers.
The License Administrator utility allows you to apply license keys,
increase user counts, remove licenses, and view license information.
The utility includes a graphical user interface (GUI) and a command
line interface (CLI).

License Key The license key also controls the conditions under which the
Platform Pervasive PSQL product permits installation of, or access to, the
database engine. The following table summarizes the restrictions
based on license key platform. For example, if your license key has a
platform of "Win64," you can apply that license to a database engine
running only on a Windows 64-bit platform. The license is invalid
for Windows 32-bit platforms and for any Linux platform.
Note that separate Pervasive PSQL Server products exist for each bit
architecture on each operating system. Pervasive PSQL Workgroup
is a 32-bit product that runs only on Windows.
Table 4-1 Restrictions Pertaining To License Key Platform
License Key Pervasive PSQL Server Operating OS Bit
Platform System (OS) Architecture

Windows32 Windows64 Windows 32-bit 64-bit

Any     
Windows     
Win32    1
Win64   
1The Windows 32-bit version of Pervasive PSQL Server installed on a Windows
64-bit machine runs under the Windows-on-Window (WOW) execution layer.

4-2
 License Administrator Concepts

User Count Each license specifies a user count. A user count allows the specified
number of computers to connect to the Pervasive PSQL database
engine concurrently. Users are counted by network address. The IP
address is used for TCP/IP; the IPX address is used for SPX/IPX.
Each computer that accesses Pervasive PSQL as a client counts as one
user. Multiple applications on a single client computer are counted
as one user, not separate users. Each Terminal Server session also
counts as one user.
Collectively, all applications that access the database engine, use the
same network protocol and address, and run on the same machine
as the database engine count as one user.
If one application uses TCP/IP and another application uses SPX/
IPX, two licenses are counted if both applications run on the same
machine. Similarly, if a machine contains multiple network cards, a
user is counted for each unique network address being used.

Obtaining a User Count

A user count is obtained in the form of a software license key issued
by Pervasive Software, or by your application vendor if the Pervasive
PSQL database engine is embedded in an application.
The Pervasive PSQL Server engine includes a temporary trial license
that allocates a fixed user count. The trial license expires within a
specified period and cannot be removed.
Please contact Pervasive Software or your application vendor to
purchase an additional user count.

Increasing the User Count

You increase the user count by applying a user count increase license
key. In order to apply a user count increase license, you must already
have a permanent license key present on the system. A user count
increase is applied immediately when you use the GUI or the CLI.
Note the restrictions on license keys listed in Table 4-1.

4-3
License Administrator

Terminal Server Each terminal server client session with the database engine counts
Licensing as one user. Collectively, all applications that access the database
engine and run on the same machine as the database engine also
count as one user.
Your user count licenses must be sufficient for the number of users
accessing the database engine. For example, suppose that you have a
user license for 20 users and your application runs on the same
machine as the database engine. The application itself counts as one
user. The database engine prohibits more than 19 terminal server
client sessions from accessing the database engine concurrently (19
+ 1 = 20). This applies whether the users connect through terminal
server sessions or remote database sessions.

Licenses for Pervasive.SQL 2000i and prior releases use a different type of license.
Prior Versions License Administrator automatically detects the database engine
of Pervasive version to which you want to apply a license. For Pervasive.SQL
PSQL 2000i and prior releases, you must use the legacy utility, User Count
Administrator, to work with the older license type. User Count
Administrator is installed as part of the prior release’s database
engine.
Refer to the Pervasive PSQL documentation of the prior release for
instructions on how to use User Count Administrator.

4-4
 License Administrator Graphical User Interface

License Administrator Graphical User Interface

The graphical user interface (GUI) License Administrator runs only
on Windows platforms and allows you to apply license keys, increase
user counts, remove licenses, and view license information. You can
start the GUI as a stand-alone application or from within Pervasive
PSQL Control Center (PCC). You may administer licenses for local
or remote database engines with the GUI.
See also “GUI Tasks” on page 4-11 for the tasks specific to the
graphical user interface.

GUI Visual The following image shows the GUI. The table below the image
Reference describes the GUI objects.

GUI Object Description Related Information

Title Bar Shows the name of the utility and the name of the computer
that License Administrator is accessing. By default, the
computer name is the local computer to which you are
currently logged in.

Computer Name By default, shows the name of the computer that the License “To Select a Computer
Administrator is accessing. for License
Administration” on
This object is also an entry field into which you may type the page 4-12
name of a computer. If you have typed in a computer name but
not clicked Connect (or pressed Enter), the field could
contain a computer name that differs from the one in the title
bar. The title bar always shows the computer that License
Administrator is accessing.

The Computer Name field may also be populated if you click

Select Engine and choose a computer.

4-5
License Administrator

GUI Object Description Related Information

Connect Establishes communication between License Administrator “To Select a Computer

and the computer listed in the Computer Name field. for License
Administration” on
page 4-12

Select Engine Allows you to choose a computer on which to administer “To Select a Computer
licenses. for License
Administration” on
page 4-12

License Key Accepts a license key (a combination of letters and numbers) “License Administrator
typed in or pasted. Concepts” on page 4-2

“To Apply a License

Key or User Count
Increase” on page 4-
14

Apply License Key Applies the license key in the License Key field to the “To Apply a License
specified database engine. The title bar shows the computer Key or User Count
on which the database engine is running. Increase” on page 4-
14
This button is enabled if the license key in the License Key
field is valid and a database engine is running on the specified
computer.

Applied Licenses Lists the applied license information for the specified “User Count” on page
computer: 4-3
• Product – The name of the Pervasive PSQL product, such
as Server or Workgroup. “To Display Applied
• License Type – The type of license, such as permanent, Licenses” on page 4-
16
temporary or user count increase.
• User Count – The user count for the specific license.
• Platform – The combination of Pervasive PSQL Server
product, operating system, and bit architecture to which
the license applies. See Table 4-1.
• Expiration Date – The date on which a license expires, if
applicable, or "n/a" if not applicable.
• Vendor – A unique number identifying the vendor software
that installed the license.
• Application – A unique number identifying the application
to which the license applies.

4-6
 License Administrator Graphical User Interface

GUI Object Description Related Information

Hide Expired Hides all expired licenses in the list of licenses for the current “To Hide Expired
session of License Administrator. Licenses” on page 4-
15

Remove License Removes the selected license(s) from the specified computer. “To Remove a
License” on page 4-15
This button is enabled when a Product name is selected in the
Applied Licenses list.

Refresh Re-displays the information for Applied Licenses and removes “To Refresh the List of
any license key information from the License Key field. The Applied Licenses” on
Computer Name field is cleared then displays the machine page 4-17
name to which License Administrator is currently connected.

Help Displays the online help for License Administrator. “To Display Help” on
page 4-18

4-7
License Administrator

License Administrator Command Line Interface

The command line interface (CLI) runs on all platforms supported
by Pervasive PSQL. The CLI is functionally equivalent to the GUI
with two exceptions. You may administer licenses only for local
database engines with the CLI. In addition, the CLI requires that you
know a license key (the string of letters and numbers) to remove the
license.
The GUI, by contrast, lists all applied licenses and allows you to select
a license to remove. The GUI does not list the license keys, just the
information about the applied licenses, such as the type of license,
user count, platform, expiration date, and so forth.
For security, the CLI does not display the license keys themselves.
(You may obtain the license key from the installation media.) You
can, however, just as with the GUI, display information about the
licenses applied to the computer (type of license, user count,
platform and so forth).
You may administer licenses only for the computer on which the CLI
is running. The CLI cannot administer remote licenses.

CLI Syntax The CLI uses the same syntax on all platforms:
utility_name -option parameters
The utility name is one of the following:
„ clilcadm.exe (Windows 32-bit), w64clilcadm.exe (Windows 64-
bit)
„ clilcadm (Linux)

4-8
 License Administrator Command Line Interface

The following table describes the options and parameters.

Table 4-2 License Administrator Command Line Options and Parameters

Options and Parameters Function

-<interpret | i> Displays information about all of the applied

licenses, such as the type of license, user count,
platform, expiration date, and so forth. This option
does not display the license keys themselves (the
string of letters and numbers).

-<interpret | i> license_key Displays information about a specific license, such

as the type of license, user count, expiration date,
and so forth.

-<apply | a> license_key Applies the specified license key to the computer
on which the CLI utility is running.

-<remove | r> license_key Deletes the specified license from the computer on
which the CLI utility is running.

-<help | h> Displays information about the options and

parameters.

no option or wrong option Displays information about the options and

parameters.

See “CLI Tasks” on page 4-10 for the tasks pertaining to the CLI.

4-9
License Administrator

License Administrator Tasks

This section explains the tasks that you can perform with License
Administrator.

GUI Tasks
„ “To Start License Administrator from Pervasive PSQL Control
Center (PCC)” on page 4-11
„ “To Start License Administrator as a Stand-alone Application”
on page 4-12
„ “To Select a Computer for License Administration” on page 4-12
„ “To Apply a License Key or User Count Increase” on page 4-14
„ “To Hide Expired Licenses” on page 4-15
„ “To Remove a License” on page 4-15
„ “To Display Applied Licenses” on page 4-16
„ “To Determine a Total User Count” on page 4-17
„ “To Refresh the List of Applied Licenses” on page 4-17
„ “To Display Help” on page 4-18

CLI Tasks
„ “To Display All Applied Licenses” on page 4-18
„ “To Display a Specific Applied License” on page 4-18
„ “To Apply a License Key or Increase User Count” on page 4-18
„ “To Remove a License” on page 4-19
„ “To Display Help” on page 4-19

4-10
 License Administrator Tasks

GUI Tasks ³ To Start License Administrator from Pervasive PSQL

Control Center (PCC)
1 In PCC Pervasive PSQL Explorer tree, click on a computer name
or on the word “Databases” for a specific computer. Choose a
computer for which you want to administer licenses.
2 Click Tools License Administrator.
License Administrator accesses the selected computer to
determine the type of license required. One of three actions then
occurs:
Š If the selected computer is running a Pervasive PSQL release
issued after Pervasive.SQL 2000i and if you are logged in to
the computer, License Administrator connects to the
database engine. The computer name appears in the License
Administrator title bar and in the Computer Name field.
Š If the selected computer is running a Pervasive PSQL release
issued after Pervasive.SQL 2000i and if you are not logged in
to the computer, a dialog appears from which you log in to
the operating system. Note that you are logging in to the
operating system and not to the database engine.
On the login dialog, type the name of an operating system
user for User Name. The user must have administrative
privileges on the operating system where the database
engine is running. For Password, type the appropriate
password for the user name you specified. Click Login. The
computer name appears in the License Administrator title
bar and in the Computer Name field.
Š If the selected computer is running Pervasive.SQL 2000i or a
prior release, a message displays informing you that License
Administrator does not support the prior release. The
message instructs you to use the legacy utility, User Count
Administrator, to work with the older license type. User
Count Administrator is installed as part of the prior release’s
database engine.
If the computer is not the one you want, select a different
computer as described in “To Select a Computer for License
Administration” on page 4-12.

4-11
License Administrator

Note Pervasive.SQL 2000i and prior releases use a different type

of license. License Administrator automatically detects the
license type on the machine being accessed. For Pervasive.SQL
2000i and prior releases, you must use the legacy utility, User
Count Administrator, to work with the older license type. User
Count Administrator is installed as part of the prior release’s
database engine.

Refer to the Pervasive PSQL documentation of the prior release

for information on how to use User Count Administrator.
Pervasive PSQL documentation is located on the Web at http://
www.pervasive.com/support/technical/online_manuals.asp.

³ To Start License Administrator as a Stand-alone

Application
1 From the Pervasive group on the Start menu, click License
Administrator.
This step assumes that License Administrator was installed as
part of a Pervasive PSQL default installation. A vendor
application that uses an embedded database engine may require
that you start License Administrator with different menu
commands. (The GUI executable is named guilcadm.exe.)
The utility connects to the local computer on which the database
engine is running.
If the computer is not the one you want, select a different
computer as described in “To Select a Computer for License
Administration” on page 4-12.

³ To Select a Computer for License Administration

The database engine must be running on the computer you specify
so that License Administrator can connect to the engine.
1 In the Computer Name field, type the name of the computer for
which you want to administer database licenses.
As an alternative to typing a computer name, you may click
Select Engine to display a list of network computers. Expand the
list of computers as needed. Click on the computer for which
you want to administer database licenses, then click OK.

4-12
 License Administrator Tasks

2 Click Connect (or press Enter).

License Administrator accesses the specified computer to
determine the type of license required. One of three actions then
occurs:
Š If the selected computer is running a Pervasive PSQL release
issued after Pervasive.SQL 2000i and if you are logged in to
the computer, License Administrator connects to the
database engine. The computer name appears in the License
Administrator title bar and in the Computer Name field.
Š If the selected computer is running a Pervasive PSQL release
issued after Pervasive.SQL 2000i and if you are not logged in
to the computer, a dialog appears from which you log in to
the operating system. Note that you are logging in to the
operating system and not to the database engine.
On the login dialog, type the name of an operating system
user for User Name. The user must have administrative
privileges for the database engine. For Password, type the
appropriate password for the user name you specified. Click
Login. The computer name appears in the License
Administrator title bar and in the Computer Name field.
Š If the selected computer is running Pervasive.SQL 2000i or a
prior release, a message displays informing you that License
Administrator does not support the prior release. The
message instructs you to use the legacy utility, User Count
Administrator, to work with the older license type. User
Count Administrator is installed as part of the prior release’s
database engine.

4-13
License Administrator

Note Pervasive.SQL 2000i and prior releases use a different type

of license. License Administrator automatically detects the
license type on the machine being accessed. For Pervasive.SQL
2000i and prior releases, License Administrator gives you the
option of starting the legacy utility, User Count Administrator,
to work with the older license type.

Refer to the Pervasive PSQL documentation of the prior version

for how to use User Count Administrator. Pervasive PSQL
documentation is located on the Web at http://
www.pervasive.com/support/technical/online_manuals.asp.

³ To Apply a License Key or User Count Increase

1 Ensure that the computer name in the title bar is the computer
for which you want to add a database license. If not, select a
different computer as described in “To Select a Computer for
License Administration” on page 4-12.
2 Type, or paste, the license key into the License Key field.
Lowercase letters are automatically converted to uppercase.
Paste the key into the first (the left) field.

The key is distributed across the remaining fields.

4-14
 License Administrator Tasks

3 Press Enter or click Apply License Key.

The License Key field is cleared if the license key is successfully
applied.
4 Verify the new license information that appears in the Applied
Licenses list. (If necessary, click Refresh to refresh the list.)
The license is now active. You do not have to restart the database
engine.

Note When applying a user count increase, a permanent license

key must already exist.

³ To Hide Expired Licenses

1 Ensure that the computer name in the title bar is the computer
for which you want to hide expired licenses. If not, select a
different computer as described in “To Select a Computer for
License Administration” on page 4-12.
2 Click Hide Expired.
The list of licenses changes to exclude all expired licenses.

Note Once you click Hide Expired, the button remains disabled
for the duration of the License Administrator session. If you exit
License Administrator, then restart it, the button is again
enabled and all expired licenses once again show in the list.

³ To Remove a License

Note Temporary licenses cannot be removed. They expire at the

end of their activation period.

1 Ensure that the computer name in the title bar is the computer
from which you want to delete a database license. If not, select a
different computer as described in “To Select a Computer for
License Administration” on page 4-12.

4-15
License Administrator

2 Click on a Product name in the Applied Licenses list.

You may select multiple licenses by holding down the Shift or

Control keys and clicking on the desired product names.
3 Click Remove License.

³ To Display Applied Licenses

1 Ensure that the computer name in the title bar is the computer
for which you want to administer database licenses. If not, select
a different computer as described in “To Select a Computer for
License Administration” on page 4-12.
2 View the information for the applied licenses in the Applied
Licenses list.

Note You must first apply a license to display information about

it, such as user count, license type, expiration date and so forth.
Once applied, if the license key is not what you want, you may
remove it provided the license is not a temporary license.
Temporary licenses expire on their own and cannot be removed.

See “To Apply a License Key or User Count Increase” on page 4-

14 and “To Remove a License” on page 4-15.

4-16
 License Administrator Tasks

³ To Determine a Total User Count

1 Ensure that the computer name in the title bar is the computer
for which you want determine a database user count. If not,
select a different computer as described in “To Select a
Computer for License Administration” on page 4-12.
2 For a particular product, total the user count values that appear
in the Applied Licenses list, excluding any values for expired
temporary licenses. For example, total all values for the Pervasive
PSQL Server product that are permanent licenses, user count
increases or temporary licenses that have not expired.
The sum is the total number of users who can concurrently
connect to the database engine on the computer.

³ To Refresh the List of Applied Licenses

1 Ensure that the computer name in the title bar is the computer
you want. If not, select a different computer as described in “To
Select a Computer for License Administration” on page 4-12.
2 Click Refresh.
The information for Applied Licenses is re-displayed, and any
license key information is removed from the License Key field.
The Computer Name field is cleared then displays the machine
name to which License Administrator is currently connected.
For example, suppose License Administrator is connected to
PVSW1 and you attempt to connect to PVSW2, which does not
have a database engine running. License Administrator displays
a message that it could not connect, and PVSW2 is displayed in
the Computer Name field. After you click Refresh, PVSW1 is
displayed in the field.

4-17
License Administrator

³ To Display Help
1 Click Help from the menu bar of the License Administrator.
2 Click the desired area:
Š License Administrator Concepts — to understand the basics
of License Administrator
Š License Administrator Graphical User Interface — to
identify and understand the purpose of the objects on the
GUI
Š License Administrator Command Line Interface — to
understand the options and parameters for the CLI
Š License Administrator Tasks — to perform activities with
License Administrator.

CLI Tasks ³ To Display All Applied Licenses

1 Enter the following command:
clilcadm -<interpret | i>

Note The 64-bit version is named w64clilcadm. The license key

is located on the Pervasive PSQL product installation media.

³ To Display a Specific Applied License

1 Enter the following command:
clilcadm -<interpret | i> license_key

Note The 64-bit version is named w64clilcadm.

³ To Apply a License Key or Increase User Count

1 Enter the following command:
clilcadm -<apply | a> license_key

Note The 64-bit version is named w64clilcadm. The license key

is located on the Pervasive PSQL installation media.

4-18
 License Administrator Tasks

Tip When applying a user count increase, a permanent license

key must already exist.

³ To Remove a License
1 Enter the following command:
clilcadm -<remove | r> license_key

Note The 64-bit version is named w64clilcadm. The license key

is located on the Pervasive PSQL installation media.

³ To Display Help
1 Enter either of the following commands:
clilcadm -<help | h>
clilcadm

Note The 64-bit version is named w64clilcadm.

4-19
License Administrator

4-20
 chapter

Table Editor
5
A Tour of Pervasive Table Editor

The topics in this chapter include:

„ “Table Editor Concepts” on page 5-2
„ “Table Editor Graphical User Interface” on page 5-6
„ “Table Editor Tasks” on page 5-9

5-1
Table Editor

Table Editor Concepts

This section contains the following topics:
„ “Overview” on page 5-2
„ “Table Editor Pages” on page 5-2
„ “Data Types” on page 5-3
„ “Null Values” on page 5-3

Overview Table Editor is one of the editor windows within Pervasive PSQL
Control Center (PCC). Table Editor is a special type of editor that
contains multiple pages. The pages are represented by tabs across the
bottom of the editor. The editor allows you to add, delete, or change
the characteristics of columns within a table. The table may be one
newly created or an existing table that you want to edit.
To modify tables with Table Editor, you must have full administrator
rights on the machine on which the database engine is running even
if you are a member of the Pervasive_Admin group. See “Granting
Administrative Rights for the Database Engine” on page 2-8 and
“Database Security” on page 2-4 in Advanced Operations Guide.

Caution Backup all your data definition files (DDFs) and data
files before you perform functions through Table Editor. This
tool gives you the ability to modify your database table
definitions and data. If you inadvertently set the options
incorrectly or enter incorrect data, you could change your files in
an irreversible manner. Full recovery is possible if you have
performed a backup.

Table Editor Table Editor contains the following pages that you use as work areas:
Pages „ Columns
„ Indexes
„ Foreign Keys
„ SQL View
You select a page by clicking on its page name tab.

5-2
 Table Editor Concepts

Note Save your changes before switching pages.

Columns Page
The Columns page lets you add, delete, modify columns, and set
primary keys. See “Columns Page” on page 5-6 for a description of
the areas on the Columns page. See “Columns Tasks” on page 5-10
for the tasks that you perform on the page.

Data Types
Refer to “Pervasive PSQL Supported Data Types” on page A-2 in SQL
Engine Reference for a list of the data types supported by the database
engine. That section lists the Pervasive PSQL data types for the
transactional and relational interfaces and the equivalent ODBC
data types. You may use any data types listed in “Pervasive PSQL
Supported Data Types” and that appear in the “Type” selection list
on the Columns page in Table Editor.

Null Values
The ability to modify the null attribute of a column is subject to the
following restrictions:
„ The target column cannot have a PRIMARY/FOREIGN KEY
constraint defined on it.
„ If converting the old type to the new type causes an overflow
(arithmetic or size), the ALTER TABLE operation is aborted.
„ If a nullable column contains NULL values, the column cannot
be changed to a non-nullable column.
If you must change the data type of a key column, you can do so by
deleting the index key, changing the data type, and re-adding the key.
Keep in mind that you must ensure that all associated index key
columns in the database remain synchronized.
For example, if you have a primary index key in table T1 that is
referenced by foreign keys in tables T2 and T3, you must first delete
the foreign keys. Then you delete the primary key and change all
three columns to the same data type and size. Finally, you must re-
add the primary key and then the foreign keys.

5-3
Table Editor

For additional information on nulls, see the following:

„ “Rebuild Utility Concepts” on page 14-2 in Advanced Operations
Guide
„ “INSERT” on page 3-172 in SQL Engine Reference
„ “Null Value” on page 4-17 in Pervasive PSQL Programmer's
Guide, which is part of the Pervasive PSQL Software Developer’s
Kit (SDK).

Indexes Page
The Indexes page lets you add and modify indexes and index
segments. See “Indexes Tasks” on page 5-11 for the tasks that you
perform on the page.

Foreign Keys Page

The Foreign Keys page lets you add and modify foreign keys. See
“Foreign Keys Tasks” on page 5-11 for the tasks that you perform on
the page.

SQL View Page

The SQL View page lets you view the CREATE TABLE and ALTER
TABLE statements that apply to the table. Note that SQL View is
display only. You cannot modify the SQL statements but you can
copy them. See “SQL View Tasks” on page 5-11 for the tasks that you
perform on the page.
The SQL View page reflects changes made on the other pages as
explained below.

CREATE Statements
The CREATE TABLE statement shows the SQL used to create the
table. For a new table, one that has not yet been saved, the CREATE
TABLE statement reflects the SQL used to implement edits from the
other three tabbed dialogs. For example, if you were to create a new
table named “MyNewTable,” SQL View initially shows the following
CREATE statement:
CREATE TABLE MyNewTable(
);

5-4
 Table Editor Concepts

If you were to add two CHAR columns to the new table on the
Columns page, SQL View reflects this in the CREATE statement:
CREATE TABLE MyNewTable(
"FirstName" CHAR(20),
"LastName" CHAR(30)
);

If a table has been saved (already exists), the CREATE TABLE

statement shows the SQL required to create the table. For example, if
you were to edit the “Course” table provided with the sample
database DEMODATA, SQL View shows the following CREATE
statements:
CREATE TABLE Course(
"Name" CHAR(7) NOT NULL ,
"Description" CHAR(50),
"Credit_Hours" USMALLINT,
"Dept_Name" CHAR(20) NOT NULL
);
CREATE INDEX Course_Name ON Course("Name");
CREATE UNIQUE INDEX DeptName ON Course("Dept_Name");

ALTER Statements
When you are editing an existing table, the ALTER TABLE
statements show what SQL is used to implement edits from the other
three Table Editor pages. For example, suppose that you edit the
“Course” table provided with the sample database DEMODATA. On
the Index page, you change the sort order for the “Name” index
segment from ascending to descending. SQL View shows the
following ALTER statements:
DROP INDEX Course.Course_Name;
CREATE INDEX Course_Name ON Course("Name" DESC);

Saving a table clears the ALTER TABLE statements because no

changes are pending.

5-5
Table Editor

Table Editor Graphical User Interface

The Table Editor graphical user interface (GUI) provides work areas
(called pages) for the following:
„ “Columns Page” on page 5-6
„ “Indexes Page” on page 5-8
„ “Foreign Keys Page” on page 5-8
„ “SQL View Page” on page 5-8

Columns Page The Columns page can be considered the primary page of Table
Editor just as columns and rows are central to tables. The following
image shows the Columns page of Table Editor. The table below the
image describes the GUI objects.
See also “Columns Tasks” on page 5-10 for the tasks that you
perform on the page.
Figure 5-1 Columns Page

5-6
 Table Editor Graphical User Interface

GUI Object Description Related Information

Column Specifies the alpha-numeric name for the column. “To specify a column name” on page 5-16
Name
“Relational Interface Limits” on page 2-2
in SQL Engine Reference

“Versions of Metadata” on page 2-2 in

SQL Engine Reference

“Identifier Restrictions by Identifier Type”

on page 1-3 in Advanced Operations
Guide

Type Specifies the data type of the column. “Pervasive PSQL Supported Data
Types” on page A-2 in SQL Engine
Reference

“To set a column data type” on page 5-17

Size Specifies how many bytes are permitted for the “To set a column size” on page 5-17
data type. A shaded cell indicates that size does
not apply.

Precision Specifies the number of significant digits for “To set column precision” on page 5-19
floating point values. A shaded cell indicates that
precision does not apply.

Scale Specifies the number of significant digits that are to “To set a column scale” on page 5-19
the right of the decimal point for floating point
values. A shaded cell indicates that scale does not
apply.

Null Specifies whether NULL values are allowed for the “To set a column to allow or disallow
data type. A shaded square ( ) indicates that nulls” on page 5-20
nulls do not apply to the data type. A checked
square ( ) indicates that NULL values are
allowed for the data type.

Case Specifies whether the database engine uses case- “To set case sensitivity for a column” on
sensitive or case-insensitive comparisons when page 5-20
searching for character values in the database. A
checked square ( ) indicates that case-
insensitive values are used. A shaded square
( ) indicates that case sensitivity does not apply
to the data type.

5-7
Table Editor

GUI Object Description Related Information

Collate Specifies that an alternating collating sequence “To set a column collating sequence” on
(ACS) is used for sorting. Contains the path and page 5-21
ACS file name.

Default Specifies a default value for the column. The “To set a column default” on page 5-22
default value is used if you perform an SQL
INSERT for a row but do not provide a value for the
column.

Indexes Page The Indexes page allows you to add and delete indexes. The Indexes
page is explained within the context of the tasks that you perform for
indexes. See “Indexes Tasks” on page 5-11.

Foreign Keys The Foreign Keys page allows you to add and delete foreign keys. The
Page Foreign Keys page is explained within the context of the tasks that
you perform for foreign keys. See “Foreign Keys Tasks” on page 5-11.

SQL View Page The SQL View page displays, and allows you to copy, the SQL
statements used to create or alter the table. The CREATE TABLE
panel displays the SQL with which you could create the same table.
The ALTER TABLE panel reflects any editing changes to an existing
table that you make with Table Editor. When you save the table
changes, the ALTER TABLE panel is cleared and the ALTER
statement(s) becomes part of the CREATE TABLE statement.
The SQL View page is further explained within the context of the
tasks that you can perform. See “SQL View Tasks” on page 5-11.

5-8
 Table Editor Tasks

Table Editor Tasks

This section explains the tasks that you perform with Table Editor.
The tasks are divided into the following categories:

Category Description

General Tasks Orient you to the overall use of Table Editor

Columns Tasks Apply to using the Columns page

Indexes Tasks Apply to using the Indexes page

Foreign Keys Tasks Apply to using the Statistic page

SQL View Tasks Apply to using the SQL View page

Note You cannot save the changes to the structure of a table if

any queries in SQL Editor are holding the table “open.” Close the
SQL Editor holding open the table then save the changes.

General Tasks General tasks apply to the overall use of the tool.

Getting Started
„ “To start Table Editor for an existing table” on page 5-12
„ “To start Table Editor for a new table” on page 5-11
„ “To work with columns” on page 5-12
„ “To work with indexes” on page 5-12
„ “To work with foreign keys” on page 5-12
„ “To view SQL statements applicable to the table” on page 5-13

5-9
Table Editor

Data
„ “To view table data” on page 5-13
„ “To identify tables with changes that have not been saved” on
page 5-13
„ “To save changes for the table being edited” on page 5-14
„ “To save changes for all tables being edited” on page 5-14
„ “To undo changes or to redo changes” on page 5-14

Columns Tasks Column tasks apply to the Columns page.

„ “To insert a column between existing columns” on page 5-15
„ “To insert a column at the end” on page 5-15
„ “To select a column or multiple columns” on page 5-16
„ “To delete a column” on page 5-16
„ “To specify a column name” on page 5-16
„ “To set a column data type” on page 5-17
„ “To set a column size” on page 5-17
„ “To set column precision” on page 5-19
„ “To set a column scale” on page 5-19
„ “To set a column to allow or disallow nulls” on page 5-20
„ “To set case sensitivity for a column” on page 5-20
„ “To set a column collating sequence” on page 5-21
„ “To set a column default” on page 5-22
„ “To set or remove a column as a primary key” on page 5-23

5-10
 Table Editor Tasks

Indexes Tasks Index tasks apply to the Indexes page.

„ “To create an index” on page 5-24
„ “To create a unique index” on page 5-26
„ “To create a partial index” on page 5-28
„ “To modify an existing index” on page 5-30
„ “To delete an index” on page 5-30
„ “To insert an index segment” on page 5-31
„ “To modify an index segment” on page 5-32
„ “To delete an index” on page 5-30
„ “To arrange the order of index segments” on page 5-34
„ “To specify a sort order for an index” on page 5-35
„ “To allow duplicates in an index” on page 5-35
„ “To specify index as modifiable” on page 5-35

Foreign Keys Foreign keys tasks apply to the Foreign Keys page.
Tasks „ “To add a foreign key” on page 5-37
„ “To modify a foreign key” on page 5-39
„ “To delete a foreign key” on page 5-39

SQL View SQL view tasks apply to the SQL View page.
Tasks „ “To copy SQL statements” on page 5-39
„ “To maximize or restore view of SQL statements” on page 5-40

General Tasks

³ To start Table Editor for a new table

1 Start PCC if it is not already running. (See “Starting PCC on
Windows” on page 3-3.)
2 Expand the Engines and Databases nodes in Pervasive PSQL
Explorer.
3 Right-click on the database to which you want to add the new
table.
4 Click New Table and type the name for new table.

5-11
Table Editor

Tip For a list of database object lengths and invalid characters,

see “Identifier Restrictions by Identifier Type” on page 1-3 in
Advanced Operations Guide.

Note that in the same directory, no two files should share the
same file name and differ only in their file name extension. For
example, do not create a table (data file) Invoice.btr and another
one Invoice.mkd in the same directory. This restriction applies
because the database engine uses the file name for various areas
of functionality while ignoring the file name extension. Since
only the file name is used to differentiate files, files that differ
only in their file name extension look identical to the database
engine.
5 Click Finish.

³ To start Table Editor for an existing table

1 Start PCC if it is not already running. (See “Starting PCC on
Windows” on page 3-3.)
2 Expand the Engines and Databases nodes in Pervasive PSQL
Explorer.
3 Right-click on the table that you want to modify then click Edit.

³ To work with columns

1 Perform the steps for “To start Table Editor for an existing table”
or “To start Table Editor for a new table.”
2 Click the Columns page tab.

³ To work with indexes

1 Perform the steps for “To start Table Editor for an existing table”
or “To start Table Editor for a new table.”
2 Click the Indexes page tab.

³ To work with foreign keys

1 Perform the steps for “To start Table Editor for an existing table”
or “To start Table Editor for a new table.”
2 Click the Foreign Keys page tab.

5-12
 Table Editor Tasks

³ To view SQL statements applicable to the table

1 Perform the steps for “To start Table Editor for an existing table”
or “To start Table Editor for a new table.”
2 Click the SQL View page tab.

³ To view table data

1 If the Grid window view is not displayed, click Window Show
View Grid.
2 Perform the steps for “To start Table Editor for an existing table”
or “To start Table Editor for a new table.”
3 By default, the Grid shows all of the data for the table (the result
of a SELECT * FROM table statement).
If the Grid is empty but the table contains data, right-click on
any row in the Grid then click Refresh.
Note that the Grid allows you to directly change database data by
changing the values in the grid cells. See “Grid Tasks” on page 6-
12.

³ To identify tables with changes that have not been

saved
1 Observe the Table Editor tab at the top. The tab contains the
name of the table being created or edited. An asterisk (*)
precedes the name if any modifications have occurred to
columns, indexes, or foreign keys but not yet saved.

5-13
Table Editor

³ To save changes for the table being edited

Note that you cannot undo or redo changes to a table once the table
has been saved.
1 Click File Save or click .

Note You cannot save the changes to the structure of a table if the
table is open in SQL Editor. Close the SQL Editor referencing the
table then save the changes.

³ To save changes for all tables being edited

Note that you cannot undo or redo changes to tables once the tables
have been saved.
1 Click File Save All.

Note You cannot save the changes to the structure of a table if the
table is open in SQL Editor. Close the SQL Editors referencing
the tables then save the changes.

³ To undo changes or to redo changes

1 In the toolbar, click to undo an action; click to redo an
action.
If multiple actions have occurred since the last save, you can
repeatedly click the undo or redo toolbar buttons. When no
more actions are available for undo or redo, the toolbar button
becomes disabled.
Note that you cannot undo or redo changes to a table once the
table has been saved.

5-14
 Table Editor Tasks

Columns Tasks

³ To insert a column between existing columns

1 Ensure that the “Columns” page of Table Editor is active. If
required, perform the steps for “To work with columns” on page
5-12.
2 Right-click on an existing column row above which you want to
insert a new column.
3 Click Insert Column.
The new column appears above the existing column row. The
default name of the inserted column is “columnn,” where “n” is
a number that automatically increments by one. (The first
column you insert is column0, the second column1 and so
forth.)

Tip You can also insert a column by clicking on an existing

column row, then pressing Ctrl+Insert or clicking .
Repeating either action inserts a series of columns in succession.

4 Click File Save or before changing pages within Table

Editor.

³ To insert a column at the end

1 Ensure that the “Columns” page of Table Editor is active. If
required, perform the steps for “To work with columns” on page
5-12.
2 Right-click anywhere on the empty column row below the last
existing column row, then click Add Column.
or
Click the “Column Name” cell on the empty column row below
the last existing column row and start typing a name for the
column.
The default name of the inserted column is “columnn,” where
“n” is a number that automatically increments by one. (The first
column you insert is column0, the second column1 and so
forth.)

5-15
Table Editor

Tip You can also insert a column at the end by clicking or

pressing Ctrl+Insert.

Repeating either action inserts a series of columns in succession.

The insert action automatically adds the new column to the end.

3 Click File Save or before changing pages within Table

Editor.

³ To select a column or multiple columns

1 Ensure that the “Columns” page of Table Editor is active. If
required, perform the steps for “To work with columns” on page
5-12.
2 Click (the column selection icon on the far left of the column
row) for the desired column.
To select multiple columns, press and hold Shift or Ctrl then
click for the desired additional columns.

³ To delete a column
1 Ensure that the “Columns” page of Table Editor is active. If
required, perform the steps for “To work with columns” on page
5-12.
2 Right-click anywhere on the desired column row.
3 Click Drop Column.

Tip You can also delete a column by clicking on an existing

column row, then pressing Ctrl+Delete or clicking .

You can also delete multiple columns by selecting multiple

columns rows. See “To select a column or multiple columns” on
page 5-16.
4 Click File Save or before changing pages within Table
Editor.

5-16
 Table Editor Tasks

³ To specify a column name

1 Ensure that the “Columns” page of Table Editor is active. If
required, perform the steps for “To work with columns” on page
5-12.
2 Click in the Column Name cell for the desired column.
3 Delete the existing column name.
4 Type the name you want.

Tip For a list of database object lengths and invalid characters,

see “Identifier Restrictions by Identifier Type” on page 1-3 in
Advanced Operations Guide.

Also, as a general rule, avoid using reserved words for column

names. See “Reserved Words” on page B-2 on page B-2 in SQL
Engine Reference. See also “Versions of Metadata” on page 2-2 in
SQL Engine Reference.
5 Click File Save or before changing pages within Table
Editor.

³ To set a column data type

The data in your database is converted if you change a column data
type. For a listing of data types, see “Pervasive PSQL Supported Data
Types” on page A-2 in SQL Engine Reference.
Changing a column data type sets the defaults for that type on the
following: size, scale, precision, default, and collate.
1 Ensure that the “Columns” page of Table Editor is active. If
required, perform the steps for “To work with columns” on page
5-12.
2 Click in the Type cell for the desired column.
3 Open the list for data types (click ).
4 Scroll to the data type you want. (You may also type the first
letter of the desired data type to scroll. Repeatedly typing the first
letter scrolls to each data type that begins with that letter.)
5 Click the data type you want.

5-17
Table Editor

6 Click File Save or before changing pages within Table

Editor.

Note Changing a data type on a column that contains a default

value causes the default value to be cleared; reset the value if
necessary.

³ To set a column size

Data in your database is truncated if you change the column to a
smaller size for the following data types:
„ CHAR
„ NUMERIC
„ VARCHAR

1 Ensure that the “Columns” page of Table Editor is active. If

required, perform the steps for “To work with columns” on page
5-12.
2 Click in the Size cell for the desired column.
You can set a size only for applicable data types, such as CHAR.
If size is not applicable, the grid cell is shaded and you will be
unable to edit the Size.
3 Delete the existing size.
4 Type the size you want.
5 Click File Save or before changing pages within Table
Editor.

5-18
 Table Editor Tasks

³ To set column precision

Precision specifies the number of significant digits for floating point
values.
1 Ensure that the “Columns” page of Table Editor is active. If
required, perform the steps for “To work with columns” on page
5-12.
2 Click in the Precision cell for the desired column.
You can set precision only for applicable data types, such as
DECIMAL. If precision is not applicable, the grid cell is shaded
and you will be unable to edit the Precision.
3 Delete the existing value.
4 Type the precision value you want.
5 Click File Save or before changing pages within Table
Editor.

³ To set a column scale

Scale specifies the number of significant digits that are to the right of
the decimal point for floating point values.
1 Ensure that the “Columns” page of Table Editor is active. If
required, perform the steps for “To work with columns” on page
5-12.
2 Click in the Scale cell for the desired column.
You can set a scale value only for applicable data types, such as
NUMERIC. If scale is not applicable, the grid cell is shaded and
you will be unable to edit the Scale.
3 Delete the existing value.
4 Type the scale value you want.
5 Click File Save or before changing pages within Table
Editor.

5-19
Table Editor

³ To set a column to allow or disallow nulls

For additional information about nulls, see “Rebuild Utility
Concepts” on page 14-2 in Advanced Operations Guide, “INSERT”
on page 3-172 in SQL Engine Reference, and “Null Value” on page 4-
17 in the Pervasive PSQL Programmer's Guide, which is part of the
Pervasive PSQL Software Developer’s Kit (SDK).
1 Ensure that the “Columns” page of Table Editor is active. If
required, perform the steps for “To work with columns” on page
5-12.
2 Click the option box in the Null cell for the desired column.
You can allow nulls only for applicable data types. A shaded
square indicates that null values do not apply to the data type.

Option State Meaning

Nulls specified

Nulls allowed but not specified

Nulls do not apply

Also see “Null Values” on page 5-3.

3 Click File Save or before changing pages within Table
Editor.

³ To set case sensitivity for a column

Case sensitivity does not apply if the key uses an alternate collating
sequence (ACS). You cannot specify case sensitivity and use an ACS.
1 Ensure that the “Columns” page of Table Editor is active. If
required, perform the steps for “To work with columns” on page
5-12.
2 Click the option box in the Case cell for the desired column.

5-20
 Table Editor Tasks

You can set a collating sequence only for applicable data types. A
shaded square indicates that case sensitivity does not apply to the
data type.

Option State Meaning

Case insensitive

Case sensitive

Case does not apply

By default, Pervasive PSQL is case sensitive when sorting string

keys. Uppercase letters are sorted before lowercase letters. If you
specify case insensitive, values are sorted without distinguishing
case.
3 Click File Save or before changing pages within Table
Editor.

³ To set a column collating sequence

For additional information about collating sequences, see
“Manipulating Btrieve Data Files with Maintenance” on page 13-1
on page 13-1 in Advanced Operations Guide and “Alternate Collating
Sequences” on page 4-28 in the Pervasive PSQL Programmer's Guide,
which is part of the Pervasive PSQL Software Developer’s Kit (SDK).
If you use an alternate collating sequence (ACS), you cannot specify
case sensitivity. Case sensitivity does not apply if the key uses an ACS.
1 Ensure that the “Columns” page of Table Editor is active. If
required, perform the steps for “To work with columns” on page
5-12.
2 Click in the Collate cell for the desired column.
You can set an alternating collating sequence (ACS) only for
applicable data types. If collating sequence is not applicable, the
grid cell is shaded and you will be unable to edit the Collate cell.
3 Delete the existing value, if present.

5-21
Table Editor

4 Type the path and ACS file name you want.

Pervasive PSQL supplies an ACS file, upper.alt, in the Samples
folder. (See “Where are the Pervasive PSQL files installed?” on
page 7-2 in Getting Started With Pervasive PSQL.) To use this file,
you would type file_path\PSQL\samples\upper.alt.
Upper.alt treats upper and lower case letters the same for sorting.
For example, if a database has values abc, ABC, DEF, and Def,
inserted in that order, the sorting with upper.alt returns as abc,
ABC, DEF, and Def. (The values abc and ABC, and the values
DEF and Def are considered duplicates and are returned in the
order in which they were inserted.) Normal ASCII sorting
sequences upper case letters before lower case, such that the
sorting would return as ABC, DEF, Def, abc.
5 Click File Save or before changing pages within Table
Editor.

³ To set a column default

The default value is used if you perform an SQL INSERT for a row
but do not provide a value for the column.
1 Ensure that the “Columns” page of Table Editor is active. If
required, perform the steps for “To work with columns” on page
5-12.
2 Click in the Default cell for the desired column.
You can set a default only for applicable data types. If a default is
not applicable, the grid cell is shaded and you will be unable to
edit the Default.
3 Delete the existing value, if present.
4 Type the default value you want.

5-22
 Table Editor Tasks

The column default can be a scalar function for certain data

types:

Data Type Scalar Function1

Date • now()
• curdate()

See also “NOW ( )” on page 5-15 and “CURDATE ( )” on

page 5-10, both in SQL Engine Reference.

Time • now()
• curtime()

See also “NOW ( )” on page 5-15 and “CURTIME ( )” on

page 5-10 in SQL Engine Reference.

Timestamp • now()

See also “NOW ( )” on page 5-15 in SQL Engine

Reference.

1
The names are case insensitive. NOW() and now() are equivalent. The
parentheses are required. That is, NOW is invalid but NOW() is valid.

5 Click File Save or before changing pages within Table

Editor.

³ To set or remove a column as a primary key

Note that you cannot set a primary key on a column that allows
NULLs.
1 Ensure that the “Columns” page of Table Editor is active. If
required, perform the steps for “To work with columns” on page
5-12.
2 Click (the column selection icon on the far left of the column
row) for the desired column(s).
To select multiple columns, press and hold Shift or Ctrl then
click for the desired additional columns.
3 Click (the primary key icon).
If the column(s) is not a primary key, the action sets the
column(s) as a primary key.

5-23
Table Editor

If the column, or if any of the columns when multiple columns

are selected, is already a primary key, the action removes the
setting from all columns.
For example, suppose that column 1 is a primary key and you
want columns 1, 2, and 3 to be the primary key. You press and
hold Ctrl then click columns 1, 2, and 3. When you click the
primary key icon, it is removed from column 1 but not added to
columns 2 and 3. If you click the primary key icon again, then
columns 1, 2, and 3 are designated as primary keys.
4 Click File Save or before changing pages within Table
Editor.

Index Tasks

³ To create an index
Only the database engine can add an index to an IDENTITY or
SMALLIDENTITY column. However, you can include an
IDENTITY or SMALLIDENTITY column as part of a multiple-
segment index.
Table Editor permits you to include an IDENTITY or a
SMALLIDENTITY column in the Indexes list if you have not saved
the table. However, the DBMS returns an error when you attempt to
save the table. After you delete the IDENTITY or SMALLIDENTITY
column from the list, you may then save the table.
1 Ensure that the “Indexes” page of Table Editor is active. If
required, perform the steps for “To work with indexes” on page
5-12.
2 Click Add.
The New Index dialog displays.
3 Type the name of the new index and click OK.

Tip For a list of database object lengths and invalid characters,

see “Identifier Restrictions by Identifier Type” on page 1-3 in
Advanced Operations Guide.

5-24
 Table Editor Tasks

The new index appears in the Indexes list and the Index Segment
Details display. Note that the first column is populated into the
Columns list.

Note New indexes are created by default as Normal.

4 In the Columns list, select the Column to designate for the Index
or Index Segment.

Caution Indexes must have at least one Column designated. If

you do not select a Column for the Index, the first column
remains selected.

The default sort order is Ascending. If you need a descending

sort order, select Descending from the Sort Order list for the
Column you want changed.

Note Some data types, such as LONGVARBINARY, cannot be

used for an index. Columns with such data types are not valid
choices.

5 Continue selecting columns from the list until all the segments
are added.
Note that a column can be selected for an index only once. Once
selected, the column is removed from the list of choices because
the column has already been designated in the index.

5-25
Table Editor

6 Click File Save or before changing pages within Table

Editor.
See also “Creating Indexes” on page 12-13 in Pervasive PSQL
Programmer's Guide, which is part of the Pervasive PSQL
Software Developer’s Kit (SDK).

³ To create a unique index

Only the database engine can add an index to an IDENTITY or
SMALLIDENTITY column. However, you can include an
IDENTITY or SMALLIDENTITY column as part of a multiple-
segment index.
Table Editor permits you to include an IDENTITY or a
SMALLIDENTITY column in the Indexes list if you have not saved
the table. However, the DBMS returns an error when you attempt to
save the table. After you delete the IDENTITY or SMALLIDENTITY
column from the list, you may then save the table.
1 Ensure that the “Indexes” page of Table Editor is active. If
required, perform the steps for “To work with indexes” on page
5-12.
2 Click Add.
The New Index dialog displays.
3 Type the name of the new index and click OK.

Tip For a list of database object lengths and invalid characters,

see “Identifier Restrictions by Identifier Type” on page 1-3 in
Advanced Operations Guide.

The new index appears in the Indexes list and the Index Segment
Details display.

Note New indexes are created by default as Normal.

5-26
 Table Editor Tasks

4 Select Unique in the Index Segment Details area to designate the

index as unique.
Selecting Unique disables duplicatibility, restricting duplicates.
Note that the first column is populated into the Columns list.

5 In the Columns list, select the Column to designate for the Index
or Index Segment.

Caution Indexes must have at least one Column designated. If

you do not select a Column for the Index, the first column
remains selected.

The default sort order is Ascending. If you need a descending

sort order, select Descending from the Sort Order list for the
Column you want changed.

Note Some data types, such as LONGVARBINARY, cannot be

used for an index. Columns with such data types are not valid
choices.

6 Continue selecting columns from the list until all the segments
are added.
Note that a column can be selected for an index only once. Once
selected, the column is removed from the list of choices because
the column has already been designated in the index.

5-27
Table Editor

7 Click File Save or before changing pages within Table

Editor.
See also “Creating Indexes” on page 12-13 in Pervasive PSQL
Programmer's Guide, which is part of the Pervasive PSQL
Software Developer’s Kit (SDK).

³ To create a partial index

Only the database engine can add an index to an IDENTITY or
SMALLIDENTITY column. However, you can include an
IDENTITY or SMALLIDENTITY column as part of a multiple-
segment index.
Table Editor permits you to include an IDENTITY or a
SMALLIDENTITY column in the Indexes list if you have not saved
the table. However, the DBMS returns an error when you attempt to
save the table. After you delete the IDENTITY or SMALLIDENTITY
column from the list, you may then save the table.
1 Ensure that the “Indexes” page of Table Editor is active. If
required, perform the steps for “To work with indexes” on page
5-12.
2 Click Add.
The New Index dialog displays.
3 Type the name of the new index and click OK.

Tip For a list of database object lengths and invalid characters,

see “Identifier Restrictions by Identifier Type” on page 1-3 in
Advanced Operations Guide.

The new index appears in the Indexes list and the Index Segment
Details display.

Note New indexes are created by default as Normal.

4 Select Partial in the Index Segment Details area to designate the

index as partial.
Note that the first column is populated into the Columns list.

5-28
 Table Editor Tasks

5 In the Columns list, select the Column to designate for the Index
or Index Segment.

Caution Indexes must have at least one Column designated. If

you do not select a Column for the Index, the first column
remains selected.

The default sort order is Ascending. If you need a descending

sort order, select Descending from the Sort Order list for the
Column you want changed.

Note Partial Indexes are restricted to columns with a data type

of CHAR or VARCHAR and that are designated as the only or
last segment in an Index.

6 Continue selecting columns from the list until all the segments
are added.
Note that a column can be selected for an index only once. Once
selected, the column is removed from the list of choices because
the column has already been designated in the index.
7 Click File Save or before changing pages within Table
Editor.
See also “Creating Indexes” on page 12-13 in Pervasive PSQL
Programmer's Guide, which is part of the Pervasive PSQL
Software Developer’s Kit (SDK).

5-29
Table Editor

³ To modify an existing index

The database engine creates some indexes, such as IDENTITY
column indexes and primary key indexes. These indexes are read-
only and cannot be modified.
Table Editor permits you to include an IDENTITY or a
SMALLIDENTITY column in the Indexes list if you have not saved
the table. However, the DBMS returns an error when you attempt to
save the table. After you delete the IDENTITY or SMALLIDENTITY
column from the list, you may then save the table.
1 Ensure that the “Indexes” page of Table Editor is active. If
required, perform the steps for “To work with indexes” on page
5-12.
2 Click the desired index in the Indexes list.
The Index Segment Details displays.
3 Modify the segment details as desired.
4 Click File Save or before changing pages within Table
Editor.

³ To delete an index
The database engine creates some indexes, such as IDENTITY
column indexes and primary key indexes. These indexes are read-
only and cannot be deleted.
1 Ensure that the “Indexes” page of Table Editor is active. If
required, perform the steps for “To work with indexes” on page
5-12.
2 Click the desired index in the Indexes list.
3 With the Index you want to delete selected, click Delete in the
Indexes list.

4 Click Yes to confirm the deletion.

5-30
 Table Editor Tasks

5 Click File Save or before changing pages within Table

Editor.

³ To insert an index segment

For detailed information about segments, see “Segmentation” on
page 4-13 in the Pervasive PSQL Programmer's Guide, which is part
of the Pervasive PSQL Software Developer’s Kit (SDK).
Only the database engine can add an index to an IDENTITY or a
SMALLIDENTITY column. However, you can include an
IDENTITY or a SMALLIDENTITY column as part of a multiple-
segment index. See also “AUTOINC” on page A-23 in SQL Engine
Reference.
1 Ensure that the “Indexes” page of Table Editor is active. If
required, perform the steps for “To work with indexes” on page
5-12.
2 Click the desired index in the Indexes list.
The Index Segment Details displays and lists the selected Index
Segments.
3 Click in the first empty Columns cell, then open the Columns list
(click ).

4 From the list, click the desired column for the segment.

Note Some data types, such as LONGVARBINARY, cannot be

used for an index. Columns with such data types are not valid
choices.

5-31
Table Editor

The default sort order is Ascending. If you need a descending

sort order, select Descending from the Sort Order list for the
Column you want changed.
5 Continue selecting columns from the list until all the segments
are added.
Note that a column can be selected for an index only once. Once
selected, the column is removed from the list of choices because
the column has already been designated in the index.
6 Click File Save or before changing pages within Table
Editor.

³ To modify an index segment

For detailed information about segments, see “Segmentation” on
page 4-13 in the Pervasive PSQL Programmer's Guide, which is part
of the Pervasive PSQL Software Developer’s Kit (SDK).
Only the database engine can add an index to an IDENTITY or a
SMALLIDENTITY column. However, you can include an
IDENTITY or a SMALLIDENTITY column as part of a multiple-
segment index. See also “AUTOINC” on page A-23 in SQL Engine
Reference.
1 Ensure that the “Indexes” page of Table Editor is active. If
required, perform the steps for “To work with indexes” on page
5-12.
2 Click the desired index in the Indexes list.
The Index Segment Details displays.
3 Click the desired segment in the Columns cell then open the list
of columns (click ).

5-32
 Table Editor Tasks

4 From the Columns list, click the desired column designated as

the index segment.

Note Some data types, such as LONGVARBINARY, cannot be

used for an index. Columns with such data types are not valid
choices.

The default sort order is Ascending. If you need a descending

sort order, select Descending from the Sort Order list for the
Column you want changed.
5 Continue selecting columns from the list until you have
completed all segment modifications.
Note that a column can be selected for an index only once. Once
selected, the column is removed from the list of choices because
the column has already been designated in the index.
6 Click File Save or before changing pages within Table
Editor.

³ To delete an index segment

Note Each index requires a minimum of one segment. To delete

an index that has only one segment, delete the index itself.

1 Ensure that the “Indexes” page of Table Editor is active. If

required, perform the steps for “To work with indexes” on page
5-12.

5-33
Table Editor

2 Click the desired index in the Indexes list.

The Index Segment Details displays, listing all the designated
index segments.
3 Click the desired index segment.
4 With the index segment you want to delete selected, click Delete
in the Index Segment Details Columns list.

5 Click File Save or before changing pages within Table

Editor.

³ To arrange the order of index segments

1 Ensure that the “Indexes” page of Table Editor is active. If
required, perform the steps for “To work with indexes” on page
5-12.
2 Click on the desired index in the Indexes list.
The Index Segment Details displays.
3 Click the index segment you want to reorder.
4 Click Up to move the segment toward the top of the segment
grouping, or Down to move the segment toward the bottom.
5 Click File Save or before changing pages within Table
Editor.

5-34
 Table Editor Tasks

³ To specify a sort order for an index

For detailed information about sort order, see “Sort Order” on page
4-16 in the Pervasive PSQL Programmer's Guide, which is part of the
Pervasive PSQL Software Developer’s Kit (SDK).
1 Ensure that the “Indexes” page of Table Editor is active. If
required, perform the steps for “To work with indexes” on page
5-12.
2 Click on the desired index in the Indexes list.
The Index Segment Details displays.
3 Click in the Sort Columns cell then open the list of sort choices
(click ).
4 From the Sort Order list, click Ascending or Descending.
The default sort order when an index segment is created is
ascending.
5 Click File Save or before changing pages within Table
Editor.

³ To allow duplicates in an index

For detailed information about duplicates, see “Duplicatability” on
page 4-16 in the Pervasive PSQL Programmer's Guide, which is part
of the Pervasive PSQL Software Developer’s Kit (SDK).
1 Ensure that the “Indexes” page of Table Editor is active. If
required, perform the steps for “To work with indexes” on page
5-12.
2 Click the desired index in the Indexes list.
The Index Segment Details displays.
3 Clear the Unique option in the Index Segment Details area by
selecting one of the other options (Partial or Normal).

Note By default, indexes are created as Normal, allowing

duplicates.

4 Click File Save or before changing pages within Table

Editor.

5-35
Table Editor

³ To specify index as modifiable

For detailed information about modifiability, see “Modifiability” on
page 4-16 in the Pervasive PSQL Programmer's Guide, which is part
of the Pervasive PSQL Software Developer’s Kit (SDK).
1 Ensure that the “Indexes” page of Table Editor is active. If
required, perform the steps for “To work with indexes” on page
5-12.
2 Click the desired index in the Indexes list.
The Index Segment Details displays.
3 Click Allow Modifications option.

A check mark in the box indicates that the index value can be
modified. Lack of a check mark indicates that the index value
cannot be modified.

Option State Meaning

Values can be modified

Values cannot be modified

Modifiable does not apply

The default for all SQL data types is that the index column is
modifiable.
4 Click File Save or before changing pages within Table
Editor.

5-36
 Table Editor Tasks

Foreign Keys Tasks

³ To add a foreign key

Note that at least one table in the database must have a primary key
or you cannot add a foreign key.
1 Ensure that the “Foreign Keys” page of Table Editor is active. If
required, perform the steps for “To work with foreign keys” on
page 5-12.
2 Click Add.
3 Type the name that you want for the new foreign key.

Tip For a list of database object lengths and invalid characters,

see “Identifier Restrictions by Identifier Type” on page 1-3 in
Advanced Operations Guide.

4 Click OK.
The new foreign key appears in the Foreign Keys list and the
Foreign Keys Details display.

5 Click for “Select Primary Table” to display the list of tables

permissible as primary tables.

5-37
Table Editor

6 Click the desired table in the list (only tables with a primary key
appear in the list).
The primary field(s) in the table appear in “Primary Table
Fields” column.

7 Match fields in the foreign table with fields in the primary table:
Click the empty cell in the “Foreign Table Fields” column for the
corresponding field in the “Primary Table Fields,” then click
to displays the list of permissible fields.

Note The data type and size of the fields must match. The list of
Foreign Table Fields contains only fields that are the same data
type and size as the primary table field being matched.

8 Click the desired field in the list.

9 Repeat steps 7 and 8 to match each field listed in the “Primary
Table Fields” column with a field in the “Foreign Table Fields”
column.

5-38
 Table Editor Tasks

10 Click the desired referential integrity rule: Delete Restrict or

Delete Cascade.
Pervasive PSQL allows a circular delete cascade on a table that
references itself. Because of this, use delete cascade with caution.
See “Delete Restrict” on page 6-5 and “Delete Cascade” on page
6-5, both in Advanced Operations Guide.
11 Click File Save or before changing pages within Table
Editor.

³ To modify a foreign key

1 Ensure that the “Foreign Keys” page of Table Editor is active. If
required, perform the steps for “To work with foreign keys” on
page 5-12.
2 Click on the desired foreign key in the Foreign Keys list.
3 The Foreign Keys Details displays.
4 As desired, select the primary table, match foreign table fields to
primary table fields, and set the referential integrity rule.
See steps 5 through 10 in “To add a foreign key” on page 5-37.
5 Click File Save or before changing pages within Table
Editor.

³ To delete a foreign key

1 Ensure that the “Foreign Keys” page of Table Editor is active. If
required, perform the steps for “To work with foreign keys” on
page 5-12.
2 Click on the desired foreign key in the Foreign Keys list.
3 Click Delete.
4 Click Yes to confirm the deletion.
5 Click File Save or before changing pages within Table
Editor.

5-39
Table Editor

SQL View Tasks

³ To copy SQL statements

1 Ensure that the “SQL View” page of Table Editor is active. If
required, perform the steps for “To view SQL statements
applicable to the table” on page 5-13.
2 Position the cursor in the desired statement view: CREATE
Statement or ALTER Statement.
3 With the mouse, select the desired text. (Press and hold the right
mouse button then “drag” across the desired lines.)

Tip You can press Ctrl+A to select all of the text.

4 Right-click then click Copy (or press Ctrl+C).

³ To maximize or restore view of SQL statements

1 Ensure that the “SQL View” page of Table Editor is active. If
required, perform the steps for “To view SQL statements
applicable to the table” on page 5-13.
2 For the desired statement view, CREATE Statement or ALTER
Statement, click the icon in the upper right corner of the view:

Icon Action

Maximizes the statement view.

Restores the statement view to its size prior to maximizing.

5-40
 chapter

SQL Editor
6
A Tour of the SQL Editor

The topics in this chapter include:

„ “SQL Editor Concepts” on page 6-2
„ “Working with Common SQL Objects” on page 6-8
„ “SQL Editor Used in SQL View Tab of Table Editor” on page 6-10
„ “SQL Editor Tasks” on page 6-11

6-1
SQL Editor

SQL Editor Concepts

This section contains the following topics:
„ “SQL Editor Concepts” on page 6-2
„ “Working with Common SQL Objects” on page 6-8
„ “SQL Editor Used in SQL View Tab of Table Editor” on page 6-10
„ “SQL Editor Tasks” on page 6-11

Overview SQL Editor is one of the editors within Pervasive PSQL Control
Center (PCC). The editor allows you to run Structured Query
Language (SQL) statements against a Pervasive PSQL database. With
SQL statements, you may retrieve, create, change, or delete data in a
database provided you have the proper database permissions to
perform these actions.
The SQL statements that you may use with SQL Editor are
documented in SQL Engine Reference. See especially “Grammar
Statements” on page 3-2.
Figure 6-1 SQL Editor

6-2
 SQL Editor Concepts

Caution Backup all your data definition files (DDFs) and data
files before you perform functions through SQL Editor. This tool
gives you the ability to modify your database table definitions
and data. You could inadvertently change your files in an
irreversible manner. Full recovery is possible if you have
performed a backup.

Statement Separators
SQL Editor requires a way to differentiate where one statement ends
and another begins. The way to differentiate statements is to place a
statement separator at the end of each statement. SQL Editor accepts
only the pound sign (#) and the semicolon (;) as statement
separators. See “To select an SQL statement separator” on page 6-17.
If you are not using temporary tables, you may use either separator
solely or mix their usage within a set of SQL statements. That is,
some statements can end with a pound sign and others with a
semicolon if you so choose.
Temporary tables begin with “#” or “##.” If you use temporary tables,
the pound sign may not be used as a statement separator. Instead, set
the statement separator to the semicolon.

Restrictions The following actions and SQL statements are not supported in SQL
Editor:
„ Creating a database
„ Use of dynamic parameters (indicated by a question mark)
„ COMMIT and START TRANSACTION

Displaying SQL Editor displays the results of running SQL statements in the
Statement following PCC window views:
Results „ Grid
„ Text
In addition, by default, an Outline window view displays a list of the
SQL statements in SQL Editor, typically with a shorter line length.
For example, you may want the Outline view to show only the first 5
words of each SQL statement in SQL Editor. “To set preferences for
SQL Editor, click SQL Editor.” on page 3-10.

6-3
SQL Editor

Grid Window View

PCC provides a command to execute an individual SQL statement in
SQL Editor so that the results appear in the Grid view. The command
is called Execute in Grid and can be invoked from the SQL menu,
from a toolbar button, or from within the Outline view.

Note The Grid is also used by Table Editor to show table data
when you start Table Editor. That is, when you right-click on a
table then click Edit. See “To view table data” on page 5-13.

Identifying the Grid Window

The Grid window view, or Grid for short, shows the columns and
data in a table. The Grid uses a matrix format, like a spreadsheet, to
show the result of running SQL SELECT statements (statements that
return data).
Figure 6-2 Grid Window View

Modifying Data and Adding Rows

The Grid allows you to directly change database data by changing the
values in the grid cells. You can also add rows to your table with the
Grid. You must have the proper table permissions to affect the
database data.
See “To set preferences for PCC Window Views” on page 3-10, “Grid
Tasks” on page 6-12, and “Assigning Permissions Tasks” on page 3-
47.

6-4
 SQL Editor Concepts

Records Affected and Scrolling

The Grid caches results locally and initially retrieves 100 records. The
Grid displays as many records as its vertical size permits.
As you scroll the vertical scroll bar, more records are retrieved and
made available to the Grid. The number of records retrieved appears
in the lower right corner of the main window.

Once you scroll to the bottom, the rows fetched indicator reports the
total number of records returned by the SQL statement.

Text Window View

PCC provides a command to execute an individual SQL statement in
SQL Editor so that the results appear in the Text view. The command
is called Execute in Text and can be invoked from the SQL menu or
from a toolbar button.
The Text window view is automatically used for the results of any
SQL statement that is not a SELECT statement. For example,
suppose you want to delete some records and have typed a DELETE
statement into SQL Editor. If you select the menu command Execute
in Grid, SQL Editor returns the results to the Text window view, not
to the Grid window view.
A command also exists to execute all statements sequentially in the
SQL Editor. The command is called Execute All SQL Statements and
can be invoked from the SQL menu, from a toolbar button, or from
within the Outline view. Results from this command always display
in the Text view regardless of the statements in SQL Editor.

Identifying the Text Window

The Text window view shows in a text format the result of running
SQL statements. You cannot change the data values in the database
by changing the text, but you can copy the text.
You may use the Text window view for SELECT statements to show
data returned. The data returned appears in a columnar format with
each field represented as an underlined heading. The data appears as
rows below the headings.

6-5
SQL Editor

For how to change the font used by the Text window, see “To set
preferences for Text Output, click Text Output.” on page 3-10.
For PCC running on an operating system set to an English language
locale, the system selects a default font. For non-English locales, PCC
seeks to match the “default font” or “system font” if such can be
found. Otherwise it will select reasonable font.
Figure 6-3 Text Window View

If execution stops because of an error, the Text window view lists the
statement that was last run. Knowing the last statement run can help
you troubleshoot problems.

Scrolling and Positioning

As a convenience, the Text window view automatically scrolls to the
top line of the data returned by the last statement executed. For
example, suppose that you execute the following two statements
sequentially in SQL Editor, each time sending the results to the Text
window view: SELECT * FROM Class and SELECT * FROM Billing.
The Text window view automatically scrolls to the top of the data
returned by SELECT * FROM Billing, the last statement executed.

6-6
 SQL Editor Concepts

Outline Window The Outline window view allows you to view the SQL statements in
View a tree structure. The root node of the tree is the same name as the
name of the SQL Editor session to which the outline corresponds.
Figure 6-4 Outline Window View

The number of words displayed in the Outline window view depends

on your preferences setting. “To set preferences for SQL Editor, click
SQL Editor.” on page 3-10.
You can also execute statements from the Outline window view. The
Outline view allows you to select multiple statements to execute
(with Ctrl+click). For example, if your Outline view shows three
statements as in the figure above, you may choose to execute
statements 1 and 3 but not 2. See “To run SQL statements in Outline
view” on page 6-20.

6-7
SQL Editor

Working with Common SQL Objects

Some SQL objects are dealt with commonly. As a convenience for
you, PCC shows the following objects in Pervasive PSQL Explorer
and provides commands for their creation and editing:
„ Triggers
„ Stored procedures
„ User-defined functions
„ Views
When you use commands to create one of these objects, SQL Editor
provides SQL syntax for that object to help you get started. For
example, if you choose to create a new view, SQL Editor contains the
syntax CREATE VIEW <viewname> AS.

Tip You can hover the mouse cursor on a SQL statement to

obtain a tool tip on the syntax, which also includes an example.

SQL Editor provides the newly created object with a default name of
object_n, where object is the name of the object and n is an integer
that starts with one and increments by one. For example, if you
create a new view, SQL Editor contains a new tab named “View_1.”
After you save the object with a name of your choice, the tab reflects
the saved name.

6-8
 Working with Common SQL Objects

The following table defines the common objects and refers you to
SQL Engine Reference for additional information.
Table 6-1 Description of Common SQL Objects in PCC
Object Description Related Information

Triggers A type of stored procedure that are “CREATE TRIGGER” on page 3-108 in SQL
automatically executed when data in a table is Engine Reference
modified with an INSERT, UPDATE, or
DELETE. “Common SQL Object Tasks” on page 6-12

Stored A collection of one or more SQL statements “CREATE PROCEDURE” on page 3-68 in
procedures that can take and return user-supplied SQL Engine Reference
parameters.
“Common SQL Object Tasks” on page 6-12

User-defined A scalar routine that returns a value. “CREATE FUNCTION” on page 3-53 in SQL
functions Engine Reference

“Common SQL Object Tasks” on page 6-12

Views A database object that stores a query and “CREATE VIEW” on page 3-113 in SQL
behaves like a table. Engine Reference

“Common SQL Object Tasks” on page 6-12

6-9
SQL Editor

SQL Editor Used in SQL View Tab of Table Editor

SQL Editor is also used in the SQL View Page of Table Editor. See
“SQL View Page” on page 5-4.

6-10
 SQL Editor Tasks

SQL Editor Tasks

This section explains the tasks that you perform with SQL Editor.
The tasks are divided into the following categories:

Category Description

General Tasks Orient you to the overall use of SQL Editor

Execution Tasks Apply to the running of SQL statements

Grid Tasks Apply to using the Grid

Text View Tasks Apply to using the Text window

Outline View Tasks Apply to using the Outline window

Common SQL Object Tasks Apply to triggers, stored procedures, user-

defined functions, and views

Note If you use SQL Editor to change the structure of table with
SQL statements, refresh the Pervasive PSQL Explorer to see the
change. Right-click on the Tables node in Pervasive PSQL
Explorer then click Refresh.

General Tasks General tasks orient you to the overall use of SQL Editor.
„ “To start SQL Editor for a new SQL query” on page 6-13
„ “To start SQL Editor by displaying all records in a table” on page
6-14
„ “To set database context for an SQL query” on page 6-14
„ “To identify editor settings for SQL Editor” on page 6-15
„ “To create an SQL query or script” on page 6-16
„ “To open an SQL script” on page 6-16
„ “To type comments into SQL Editor” on page 6-17
„ “To cancel (undo) or restore (redo) typing actions in SQL
Editor” on page 6-18

6-11
SQL Editor

„ “To find text or replace text in SQL Editor” on page 6-18

„ “To select text in SQL Editor” on page 6-19
„ “To perform basic editing functions in SQL Editor” on page 6-19

Execution Execution tasks apply to the running of SQL statements.

Tasks „ “To enable the execution commands and icons for SQL
statements” on page 6-19
„ “To run a single SQL statement in SQL Editor” on page 6-19
„ “To run selected SQL statements in SQL Editor” on page 6-20
„ “To run all SQL statements in SQL Editor” on page 6-20
„ “To run SQL statements in Outline view” on page 6-20

Grid Tasks Grid tasks apply to working with the Grid window.
„ “To change data within the Grid” on page 6-21
„ “To add rows of data to the Grid” on page 6-22
„ “To delete row(s) of data from the Grid” on page 6-23
„ “To enter a date, time, or timestamp data type in the Grid using
scalar functions” on page 6-24
„ “To refresh data in the Grid” on page 6-24
„ “To copy data from the Grid” on page 6-25

Text View Tasks Text view tasks apply to working with the Text window.
„ “To clear results from Text view” on page 6-25
„ “To select and copy text from Text view” on page 6-25

Outline View Outline view tasks apply to working with the Outline window.
Tasks „ “To minimize, maximize, or restore Outline view size” on page
6-26

Common SQL Common SQL Object tasks apply to working with triggers, stored
Object Tasks procedures, user-defined functions, and views.
„ “To create a common SQL object” on page 6-26
„ “To modify a common SQL object” on page 6-27
„ “To delete a common SQL object” on page 6-27

6-12
 SQL Editor Tasks

General Tasks

³ To start SQL Editor for a new SQL query

1 Start PCC if it is not already running. (See “Starting PCC on
Windows” on page 3-3.)
2 Click File New SQL Document or click .
The Select Database dialog box appears.
3 Click the database in the list for which you want the SQL
document to apply, or ensure that the option None is check
marked if the SQL document does not apply to a specific
database.

Note The option None is selected by default if an object other

than a database, or any of the nodes subordinate to a database, is
selected in Pervasive PSQL Explorer.

Note that the commands to execute SQL statements are disabled

if None is specified as the context. See “To set database context
for an SQL query” on page 6-14.

Select the Set selected database as default for this session option
to use the selected database whenever you open a new SQL
Editor tab. If you leave this option unselected, you will be
prompted to select a database each time you open a new SQL
Editor tab.

4 Click OK.
SQL Editor appears as a new window view in PCC. By default,
PCC names the new document SQLDocn, where n is an integer
that starts with 1 and increments by 1. The document name
appears in the tab for SQL Editor.

6-13
SQL Editor

³ To start SQL Editor by displaying all records in a table

1 Start PCC if it is not already running. (See “Starting PCC on
Windows” on page 3-3.)
2 Expand the Engines and Databases nodes in Pervasive PSQL
Explorer.
3 For the desired database, expand the Tables node.
4 Double-click the table for which you want to see all records (or
right-click the table then click Open).
By default, PCC open SQL Editor and executes a SELECT *
FROM statement for the table. Note that the SELECT statement
can fail depending on user and column-level permissions.

³ To set database context for an SQL query

The commands to execute SQL statements are disabled until a
database is specified as the context to which the SQL statement
applies.
1 Start PCC if it is not already running. (See “Starting PCC on
Windows” on page 3-3.)
2 Perform one of the following actions:
a. For a new SQL statement, click File New SQL
Document or click .
The Select Database dialog appears. Click the database in
the list for which you want the SQL document to apply and
click OK.
b. If SQL Editor already contains SQL statements not
associated with a database, click .
The Select Database dialog appears. Click the database in
the list for which you want the SQL document to apply.

6-14
 SQL Editor Tasks

3 Click OK.

Note Select the Set selected database as default for this session
option to use the selected database whenever you open a new
SQL Editor tab. If you leave this option unselected, you will be
prompted to select a database each time you open a new SQL
Editor tab.

To unselect the default database:

Access the Select Database dialog by clicking , and unselect
the Set selected database as default for this session option.
or
Click Windows Preferences then click the General node.
Unselect Do not prompt for new database each time a SQL
document is opened.

The selected database is not maintained across PCC sessions. If

you close and reopen PCC, you will have to select a new default
database context.

³ To identify editor settings for SQL Editor

1 Ensure that the cursor is positioned in SQL Editor.
2 Observe the information blocks along the bottom of the PCC
window.

6-15
SQL Editor

Block Meaning

1 Identifies whether SQL Editor accepts character input

(Writable).

2 Indicates whether the editor is in insert mode or overwrite

mode for character input. The Insert key toggles the mode.
Note that the cursor changes shape for each mode.

3 Indicates the row and column at which the cursor is

positioned. The first value represents the row, the second
the column. In the image above, the cursor is positioned on
the first row at the first character position.

4 Identifies the computer and the database to which the SQL

document applies. The computer name is listed first
followed by the database name. In the image above, the
computer is “tment” and the database is “DEMODATA.”

Note: If None is specified as the database context, then the

text “No Database Selected” appears instead of the name
of the computer and database. The commands to execute
SQL statements are disabled if None is specified. See “To
set database context for an SQL query” on page 6-14.

³ To create an SQL query or script

By default, when you start SQL Editor, you may type in SQL
statements. A script is one or more SQL statements saved as a text
file.
1 Perform the steps for “To start SQL Editor for a new SQL query”
on page 6-13.
2 Type the SQL statements into SQL Editor.
Separate SQL statements with a delimiter. You can use the pound
sign (#) or the semicolon (;).
3 Optionally, click File Save As to save the SQL statements as a
text file.

³ To open an SQL script

A script is one or more SQL statements saved as a text file. You can
execute the statements in SQL Editor after you open a script in the
editor.
1 Click File Open.

6-16
 SQL Editor Tasks

2 Navigate to the location of the text file, select the file, then click
Open.
By default, the Open dialog looks for files in the PVSW\bin
directory with a file name extension of “SQL.”
3 Execute the file. See “To run all SQL statements in SQL Editor”
on page 6-20 and “To run SQL statements in Outline view” on
page 6-20.

³ To select an SQL statement separator

1 On the PCC Window menu, click Preferences. Expand the
Pervasive node if it is not already expanded.
2 Click SQL Editor.
3 Select the desired choices for SQL Statement Separator.

Note Based on the separator option you select, PCC looks for the
selected character(s) and identifies each as the end of a
statement. It sends each identified statement to the database
engine and displays results of that statement before sending the
next statement.
If you use # as a separator in a script but do not select the
# (Pound) option, you will receive an error message when you
run the script.
If you do not select ; (Semicolon) as a separator, but use a
semicolon as a separator in a script anyway, you will not receive
an error message if the statements are properly parsed. This is
because the database engine recognizes semicolons as
separators. However, PCC will not display the results for all the
statements. It will only display results for one statement
(probably the first statement). As far as PCC is concerned, if you
don’t select a semicolon as a separator, statements separated by a
semicolon are a single statement.

6-17
SQL Editor

³ To type comments into SQL Editor

Single-line comments are indicated by double dashes (--) or double
slashes (//). Each comment must be on a separate new line or after
the statement separator on an existing line.
SQL Editor also supports the use of a start/end comment block that
can span multiple lines (/* */).
1 Click at the beginning of the line where you want a comment.
2 Type “--” or “//” followed by your comment text.
The following example shows valid comments.
SELECT * FROM t1#
-- This is a valid comment
// and so is this
SELECT * FROM t2# -- This is valid after the # sign

The following example shows multi-line comments.

SELECT * FROM t1# -- single line comment
/* This is a comment block that spans two lines.
Statements inside this block are ignored */
SELECT * FROM t2#

³ To cancel (undo) or restore (redo) typing actions in

SQL Editor
1 Perform one of the following actions:
a. Click Edit Undo (or press Ctrl+Z) to cancel typing
actions.
b. Click Edit Redo (or press Ctrl+Y) to restore typing
actions.

³ To find text or replace text in SQL Editor

1 Click Edit Find/Replace (or press Ctrl+F).
A dialog appears on which you specify a text string to find or
replace.

6-18
 SQL Editor Tasks

³ To select text in SQL Editor

1 Perform one of the following actions:
a. Click Edit Select All to select all of the contents of SQL
Editor.
b. Press and hold down the left mouse button and drag the
cursor across the text you want to select.

³ To perform basic editing functions in SQL Editor

1 Click Edit then click the function you want: cut, copy, paste, and
so forth.

Statement Execution Tasks

³ To enable the execution commands and icons for SQL

statements
1 Follow the steps for “To set database context for an SQL query”
on page 6-14.

³ To run a single SQL statement in SQL Editor

1 Position the cursor on the statement or select the statement.
2 Perform one of the following actions:
a. Click SQL Execute in Grid or SQL Execute in Text.
b. Press F9 or Shift+F9.
c. Click or .

Note SQL Editor automatically uses the Text window view for
the results of SQL statements that are not SELECT statements.
Only SELECT statements use the Grid window view.

6-19
SQL Editor

³ To run selected SQL statements in SQL Editor

1 Press and hold down the left mouse button and drag the cursor
across the statement that you want to run.
You may select one or more statements.
2 Perform one of the following actions:
a. Click SQL Execute in Text or SQL Execute All SQL
Statements.
b. Press Shift+F9.
c. Click or .

Note SQL Editor automatically uses the Text window view for
the results of SQL statements that are not SELECT statements.
Only SELECT statements use the Grid window view.

³ To run all SQL statements in SQL Editor

1 Click SQL Execute All SQL Statements, press F10, or click
.
Ensure that either no statements are selected or that all
statements are selected. If you select a portion of the statements
in SQL Editor, only the selected portion executes.

³ To run SQL statements in Outline view

1 To execute all statements in Outline view, right-click on the root
node then click Execute All Statements.
To execute one or more statements, click on the desired
statement(s).
Note that you can select multiple statement by using Ctrl+click.
The statements do not have to be contiguous.
2 If multiple statements are selected, right-click on one of the
selected statements, then click Execute Selected Statements.

6-20
 SQL Editor Tasks

3 If a single statement is selected, perform one of the following

actions:
a. Right-click on the statement, then click Execute in Grid or
Execute in Text.
b. Press F9 or Shift+F9.
c. Click or .

Note SQL Editor automatically uses the Text view for the results
of SQL statements that are not SELECT statements. Only
SELECT statements use the Grid.

Grid Tasks

³ To change data within the Grid

1 Click the Grid cell that contains the value you want to change.

Tip By default, the entire contents becomes selected when you

click the cell. Press Delete or Backspace to delete the entire
contents of the cell.

2 Change the data in the cell.

3 Move the cursor outside of the cell (for instance, press Tab or
click outside of the cell).

Caution Moving the cursor from the cell automatically saves the
data changes to physical storage. You cannot explicitly save the
changes made to the cell.

6-21
SQL Editor

³ To add rows of data to the Grid

1 Click on the Grid.
The Add Rows dialog appears. For example, the following image
shows the dialog for the “Billing” table that is part of the sample
database DEMODATA.

2 Click in the Value cell for each Column Name and type the
desired value.
The value must be a data type valid for that column.

Tip You can copy data from Grid cells and paste it into the Value
cells. Click on a Grid cell then right-click. Click Copy. Click on a
Value cell on the Add Rows dialog then right-click. Click Paste.
Also note that Ctrl+C and Ctrl+V provide the copy and paste
actions, respectively.

3 Click Add.
The record is added to the table. Also note that the option
Refresh Grid on Exit becomes enabled.
If you want to add multiple records, you can change values for
specific value cells then click Add. If you want to clear all of the
value cells, click Reset.

6-22
 SQL Editor Tasks

4 Optionally, click Refresh Grid on Exit if you want the table data
refreshed .

When you close the Add Rows dialog, a refresh re-executes the
statement last executed in SQL Editor.
5 Click Close.
If Refresh Grid on Exit is enabled, the Grid displays the record(s)
that you just added (assuming that the last statement executed in
SQL Editor was SELECT * FROM Billing).

³ To delete row(s) of data from the Grid

Caution Deleting a row from the Grid removes that record from
physical storage. No undo feature is available to reclaim the
deleted record.

1 Click any cell within the row (the record) that you want to delete.
You may also select and delete multiple rows. To select multiple
rows, press and hold down the Shift or Ctrl key, then click a cell
in each desired row.
2 Click Edit Delete or click .
3 Click OK to confirm the deletion.

6-23
SQL Editor

³ To enter a date, time, or timestamp data type in the

Grid using scalar functions
1 As a convenience, you can type the following scalar functions for
date, time, and timestamp in Grid cells:

Data Type Scalar Function1 As Typed in Grid Cell

Date • now()
• curdate()

See also “NOW ( )” on page 5-15 and “CURDATE ( )” on

page 5-10, both in SQL Engine Reference.

Time • now()
• curtime()

See also “NOW ( )” on page 5-15 and “CURTIME ( )” on

page 5-10 in SQL Engine Reference.

Timestamp • now()

See also “NOW ( )” on page 5-15 in SQL Engine Reference.

1
The names are case insensitive. NOW() and now() are equivalent. The
parentheses are required. That is, NOW is invalid but NOW() is valid.

Note You can also omit the seconds for a time data type provided
that you include “AM” or “PM.” For example, 10:30 AM is a valid
entry. Time defaults to “AM” if you omit “AM” or “PM.” For
example, 10:30:00 is entered as 10:30:00 AM.

³ To refresh data in the Grid

1 Click on the Grid.
A refresh re-executes the statement last executed in SQL Editor
and sends the results to the Grid.

6-24
 SQL Editor Tasks

³ To copy data from the Grid

1 Perform on of the following actions:
a. To select the data for an individual cell, click in the cell, then
click (or right-click and click Copy).
By default, the entire content of the cell is selected.
b. To select an entire row, right-click on any cell then click
Copy Text or click .
You may also select multiple rows. To select multiple rows,
press and hold down the Shift or Ctrl key, then click a cell
in each desired row.

Note When you copy an entire row or multiple rows, the rows
are pasted in the same layout as they appear in the Text window
view. You can specify the number of characters between the
pasted columns. Click Window then expand the Pervasive node
in the Preferences tree. Click Text Output in the tree and set the
desired value for Number of spaces between columns.

Text Window Tasks

³ To clear results from Text view

1 Click on the Text view.

³ To select and copy text from Text view

1 Perform one of the following actions:
a. Press and hold down the left mouse button and drag the
cursor across the text you want to select.
b. Right-click within the Text view then click Select All.
2 Right-click then click Copy.

6-25
SQL Editor

Outline View Tasks

See also “To run SQL statements in Outline view” on page 6-20.

³ To minimize, maximize, or restore Outline view size

1 Click the desired sizing button:

Button Sizing Action

Minimizes the Outline window

Maximizes the Outline window

Restores the Outline window to its size before it was minimized

Common SQL Objects Tasks

Common SQL objects include triggers, stored procedures, user-
defined functions, and views.

³ To create a common SQL object

1 In PCC Pervasive PSQL Explorer, expand the Engines node and
the registered server nodes to display the available databases.
2 Right-click on the database for which you want the common
SQL object to apply (or right-click on any of the database’s
subordinate nodes).
3 Click New then one of the following depending on the object
that you want to create:
Š Function
Š Stored procedure
Š Trigger
Š View

6-26
 SQL Editor Tasks

A new SQL Editor is opened that contains a default name for the
object on a tab. The name is in the form object_n, where object is
the name of the object and n is an integer that starts with one and
increments by one. For example, if you create a new view, a new
SQL Editor contains a tab named “View_1.” After you save the
object with a name of your choice, the tab reflects the saved
name.
4 Modify the skeletal SQL statement for the common object.

Tip Hover the mouse cursor on the statement to obtain a tool tip
on the syntax, which also includes an example.

5 Click File Save or .

³ To modify a common SQL object

1 In PCC Pervasive PSQL Explorer, click the database in the list for
which you want to modify the common SQL object.
2 Expand the node for the object (function, stored procedures,
user-defined functions, or triggers) that you want to modify.
3 Double-click the object that you want to modify or right-click
the object then click Edit.
A new SQL Editor is opened that contains a tab. The tab name
reflects the name by which you saved the object.

³ To delete a common SQL object

1 In PCC Pervasive PSQL Explorer, click the database in the list for
which you want to delete the common SQL object.
2 Expand the node for the object (function, stored procedures,
user-defined functions, or triggers) that you want to delete.
3 Click the object that you want to delete, then perform one of the
following actions:
a. Right-click, then click Delete.
b. Press Delete.
c. Click on Pervasive PSQL Explorer.
Note that you can select multiple objects for deletion by using
Ctrl+click or Shift+click.

6-27
SQL Editor

6-28
 chapter

Pervasive System Analyzer

(PSA) 7
Usage Information for the Diagnostic Utility PSA

The following are the sections found in this chapter:

„ “PSA Concepts” on page 7-2
„ “PSA GUI Visual Reference” on page 7-6
„ “PSA Tasks” on page 7-8

7-1
Pervasive System Analyzer (PSA)

PSA Concepts
Pervasive System Analyzer (PSA) is a utility that allows you to
perform the following actions:
„ View the Pervasive components on your system with version
information, usage status, size, and location.
„ Identify duplicate components on your system.
„ Test your network communications to verify connectivity.
„ Test the transactional interface to verify connectivity to the
database engine.
„ Test the relational interface to verify connectivity to the database
engine.

View Modules
This option allows you to view all Pervasive components and any
other files you specify. You can add additional components to the
search list. Their versions, usage status, file size, and location is
displayed. Duplicate files are identified so you can resolve any
potential conflicts.
View modules scans a machine for Pervasive components to
determine which ones are loaded into memory.

Test Active Installation

This option allows tests of the network connectivity between a
Pervasive PSQL client and the database engine, and tests the
functionality of the transactional and relational interfaces. If errors
are detected, PSA gives you detailed troubleshooting information to
help you resolve the problem.

Network
The Network Communication tests verify that your client or or
workstation can communicate with network protocols to reach the
machine on which the Pervasive PSQL database engine is installed.
Using Advanced Settings, you can select the protocols to test as well
as the number of stress test messages to send. By default, the network
test connects using any available protocol that is installed on the
system and configured for use in Pervasive PSQL. See “Supported

7-2
 PSA Concepts

Protocols” configuration parameter found on page 4-26 in Advanced

Operations Guide.
The progress bar will complete for all selected tests. The steps
involved in testing network communication are:
1 Verify Available Protocols
2 Verify Network Client Availability
3 Qualify Target Name
4 Resolve Target Location to network address
5 Verify Server Address
6 Verify Server Connection
7 Run Stress Test

Transactional Engine
This test verifies the ability of your client to connect to the Pervasive
PSQL database through the transactional interface (Btrieve).
When you run this test, PSA attempts to perform basic database
operations that are common to most transactional interface
applications. If your machine passes this test, then the following is
verified:
„ The Pervasive PSQL transactional interface is responding
„ Your client interface components are installed correctly
„ The network communication between the client and the
database engine is functioning correctly
„ Transactional interface applications running on your computer
should function correctly

Relational Engine
This test verifies the ability of your client to connect to the Pervasive
PSQL database engine through the relational interface (SQL). When
you run this test, PSA attempts to perform common SQL database
operations. A dialog box displays during the tests to show progress.
If your machine passes this test, then the following is verified:
„ Your Pervasive PSQL relational engine is running
„ Your client interface components are installed correctly

7-3
Pervasive System Analyzer (PSA)

„ The network communication between the client and the

database engine is functioning correctly
„ SQL applications running on your computer should function
correctly

Frequently Listed below are some frequently asked questions about PSA.
Asked „ What is the default log file name?
Questions
„ Can I use a different log file name?
„ What is the local default location for the log file?
„ What is the remote default location for the log file?
„ What kind of information is contained in the log file?
„ What happens to the information in the log file each time the
utility is run?
„ How do I run PSA?
„ When would I want to use PSA?

What is the default log file name?

The default file name for the log file is PSALog.txt.

Can I use a different log file name?

You can rename the file, but the name applies only for that session of
PSA. PSA defaults the name to PSALog.txt the next time you execute
PSA.

What is the local default location for the log file?

The default local location for the log file is under the application data
directory in PSQL\logs.
For default locations of Pervasive PSQL files, see “Where are the
Pervasive PSQL files installed?” on page 7-2 in Getting Started With
Pervasive PSQL.

What is the remote default location for the log file?

The default location for the log file is always the directory where
psawizrd.exe is located on a Windows machine.

7-4
 PSA Concepts

What kind of information is contained in the log file?

The log file records any process performed by PSA and includes the
associated timestamp.

What happens to the information in the log file each time

the utility is run?
New information is appended to the log file each time PSA runs if the
option Append to log file is selected (see Figure 7-1 on page 7-6). If
the option is cleared, the log file contains only information for that
particular execution of PSA.

How do I run PSA?

See “To start PSA” on page 7-8.

When would I want to use PSA?

The following lists the most common situations where you would
want to use PSA:
„ You are encountering network errors and wish to test your
client’s connectivity to a machine running a Pervasive PSQL
database engine.
„ Your Pervasive-based application is not functioning correctly
and you wish to test the functionality of the transactional or
relational interface components to the database engine.
„ You wish to view the Pervasive PSQL components on the system,
loaded in memory, or both.

7-5
Pervasive System Analyzer (PSA)

PSA GUI Visual Reference

The following dialog in PSA provides access to its functionality. Click
on an area of the figure to learn more about the item.
Figure 7-1 PSA Main Dialog

GUI Object Description Related Information

View loaded Displays all current Pervasive PSQL components “View Modules Tasks” on page 7-8
Pervasive modules and version information in a table. Also allows you
to add additional components to the matrix.

Test active Test the Pervasive PSQL installation in three ways: “Test Active Installation Tasks” on
installation network connectivity, functionality of the page 7-10
transactional interface, and functionality of the
relational interface. Select the options that
correspond to the tests you wish to perform.

Test network Test the network connectivity to a machine running “To test your network” on page 7-
the database engine. The network tests display 10
detailed information about any problems
encountered during the test and provide
suggestions on how to remedy the problems.

If you do not have Internet Explorer installed, this

test is not available because the test uses an
embedded HTML component to display results.

Test transactional Tests the functionality of the transactional interface “To test the transactional
engine (Btrieve) to the database engine. interface” on page 7-11

7-6
 PSA GUI Visual Reference

GUI Object Description Related Information

Test relational Tests the functionality of the relational interface “To test the relational interface” on
engine (SQL) to the database engine. page 7-12

Log file Allows you to specify a different log file location “To specify a different location for
than the default. PSA logs detailed information on the PSA log file” on page 7-13
the tests it performs. You can use this log file to
review tests at a later time or to forward them to
Pervasive Technical Support for further review.

The Append to the log file option adds content to

the end of the log file to provide a running history.
If this option is cleared, the log file starts anew and
only information from the current PSA session is
captured.

7-7
Pervasive System Analyzer (PSA)

PSA Tasks

General Tasks
„ “To start PSA” on page 7-8

View Modules Tasks

„ “To select options for View Modules” on page 7-8

Test Active Installation Tasks

„ “To test your network” on page 7-10
„ “To test the transactional interface” on page 7-11
„ “To test the relational interface” on page 7-12

Log Files Tasks

„ “To specify a different location for the PSA log file” on page 7-13
„ “To view the log file at the completion of PSA” on page 7-13

General Tasks ³ To start PSA

1 Click Pervasive System Analyzer in the Pervasive group on the
Start menu, or execute psawizrd.exe from a command prompt.
For default locations of Pervasive PSQL files, see “Where are the
Pervasive PSQL files installed?” on page 7-2 in Getting Started
With Pervasive PSQL.

View Modules ³ To select options for View Modules

Tasks 1 Start PSA and click Next.
2 Click View Loaded Pervasive Modules.

7-8
 PSA Tasks

3 Click Next.
A dialog displays similar to the following figure.
Figure 7-2 View Modules Section of PSA

If In Memory is selected, PSA searches for all Pervasive

components loaded in memory, regardless of whether they are
located in the PATH or other specified locations.
If you want to add components to the search list, do the
following:
a. Click Additional modules (if it is not already selected).
b. Type the file name (without a drive letter or path) in the text
box.
c. Click Add Component .
d. If the component you added is not in the path, add the path
to the searched locations.
If you want to add more paths to the search locations, do the
following:
a. Click Additional locations.
b. Click Add Location .
c. Browse to the location using the directory selector and
select the desired location.
d. Click OK.
e. If you also want all directories below the location to be
searched, click Include subfolders.
4 Click Next.

7-9
Pervasive System Analyzer (PSA)

5 View the grid that shows the components found.

If files of the same name are detected, the multiple occurrences
are marked with an icon on the left side: .

If you see multiple occurrences of a component, you can adjust

the list so that the occurrences sort together. To do this, click the
Module column heading.
Multiple occurrences of a file does not necessarily represent a
problem with your configuration. Their identification can help
you troubleshoot issues with components depending on the
situation. For example, if you see two Pervasive components
both marked with the same version, you may want to check
which is loaded in memory and that the components are located
where you expect.
6 Click Next.
7 Click Finish if you are finished using PSA, or click View Log File
to view the log.

Test Active ³ To test your network

Installation 1 Start PSA and click Next.
Tasks
2 On the Options dialog, click Test active installation (if it is not
already selected).
3 Click Test network communication (if it is not already selected).
4 Click Next.
5 For Target machine, type the machine name or TCP/IP address
of the machine you wish to test. You may also type “localhost”
for the local machine. The machine can be the machine where
you are currently located or a remote machine.

7-10
 PSA Tasks

6 If you want to control how the tests are run, click Advanced
Settings and complete the following steps:
a. By default, PSA uses the first available protocol. You can
force PSA to use one or more protocols by clicking Use Only
These Protocols.
b. Select the protocol options that you want PSA to test. Note
that the NetBIOS protocol is not supported on Pervasive
PSQL Server. The SPX protocol is not supported on
Pervasive PSQL Workgroup.
c. Specify the number of stress test messages to send by typing
a value for test messages. The default is 75. (After
successfully connecting using any protocol, PSA sends
stress test messages to ensure that the connectivity is
functioning correctly. )
d. Click OK to save the changes.
7 Click Next to start the test.
PSA runs a series of tests and displays the results.
If the test succeeds, PSA informs you that all test messages were
successfully transmitted. If the test fails, PSA lists the issues along
with tips on how to resolve them. The tips are also written to the
PSA log file.
8 Click Next.
9 Click Finish if you are finished using PSA, or click View Log File
to view the log.

³ To test the transactional interface

1 Start PSA and click Next.
2 On the Options dialog, click Test active installation (if it is not
already selected).
3 Click Test transactional engine (if it is not already selected).
This test runs a series of transactional operations to simulate
your client requester interacting with the database engine.
4 Click Next.

7-11
Pervasive System Analyzer (PSA)

5 Provide a path name to the samples directory on the machine

running the database engine. The default path should be correct
if the database engine is running on the local machine. You can
type a path, or browse to one if you click .
6 Select the operations you want to perform for the transactional
interface (by default, all are selected):
Š Create Data File (write access required)
Š Read Data File
Š Update Data (write access required)
Š Insert Data (write access required)
7 Click Next.
PSA performs the tests and displays the results. A check mark
indicates a test succeeds and an "x" indicates a test fails.
If all of the tests succeed, your client requester can use the
transactional interface to communicate with the database
engine.
8 Click Next.
9 Click Finish if you are finished using PSA, or click View Log File
to view the log.

³ To test the relational interface

1 Start PSA and click Next.
2 On the Options dialog, click Test active installation (if it is not
already selected).
3 Click Test relational engine (if it is not already selected).
This test runs a series of SQL operations to simulate your client
requester interacting with the database engine.
4 Click Next.
5 For Machine Name, type the name or IP address of the machine
where the engine data source name (DSN) resides, or browse to
the machine (click ).
The name “localhost” is valid if you are testing the local
machine.

7-12
 PSA Tasks

6 For Engine DSN, type the name of the DSN for the data source
you want to test. The default, demodata, uses the DSN for the
sample database installed with the database engine.
7 Select the operations you want to perform for the relational
interface (by default, all are selected):
Š Create Table
Š Read Data
Š Update Data
Š Insert Data
8 Click Next.
PSA performs the tests and displays the results. A check mark
indicates a test succeeds and an "x" indicates a test fails.
If all of the tests succeed, your client requester can use the
relational interface to communicate with the database engine.
9 Click Next.
10 Click Finish if you are finished using PSA, or click View Log File
to view the log.

Log Files Tasks ³ To specify a different location for the PSA log file
1 Start PSA and click Next.
2 In the Log File field, type a path to the PSA log file, or browse to
the desired location (click ).
If you want a log file that contains information only about the
current PSA session, clear the Append to log file option.
You can also specify a different name for the log file, but the
name applies only for that session of PSA. PSA defaults the name
to PSALog.txt the next time you execute PSA.

³ To view the log file at the completion of PSA

Click View Log File to display the PSA log file.
A summary of the tasks PSA completed is listed for you.

7-13
Pervasive System Analyzer (PSA)

7-14
 chapter

Command Line Interface

Utilities 8
Using Pervasive PSQL Command Line Interface Utilities

This chapter discusses command line interface (CLI) utilities

available for Pervasive PSQL.
The chapter contains the following sections:
„ “CLI Utilities Overview” on page 8-2
„ “Command Line Interface Utility Reference” on page 8-5

8-1
Command Line Interface Utilities

CLI Utilities Overview

In addition to providing GUI utilities, Pervasive PSQL provides a
number of command line interface (CLI) utilities that you can use.
In most cases, these utilities duplicate functionality you can perform
with GUI utilities.
For default locations of Pervasive PSQL files, see “Where are the
Pervasive PSQL files installed?” on page 7-2 in Getting Started With
Pervasive PSQL.

Platforms that These utilities are provided in the following installations:

Include CLI „ Windows - Server, Workgroup, and a limited set on the Client
Utilities
„ Linux - Server, and a limited set on the Client
The summary of utilities in the section that follows notes which
utilities are present in a server or client install.

Where to Find Please note the location based on your platform.

CLI Utilities
Windows
In Windows, the utilities are installed to the BIN directory of your
Pervasive PSQL installation. If you installed to the default
installation location, your utilities are located in
file_path\PSQL\bin\. Since the Pervasive PSQL installation places
your install directory in the PATH, these utilities should be available
from any command prompt.

Linux
In Linux, utilities are installed to /usr/local/psql/bin. The user
psql has the necessary environment variables to use the utilities. If
you wish to use utilities from accounts other than psql, follow these
instructions in Getting Started With Pervasive PSQL: “Pervasive
PSQL Account Management on Linux” on page 13-4.

Utilities by The following tables outlines the command line utilities, the
Platform and platform on which they are made available, as well as if a graphical
Engine Type user interface is available for the utility.

8-2
 CLI Utilities Overview

Table 8-1 Available Utilities for Client and Server

Utility Description GUI Available Windows Linux

Server Client Server Client

bcfg Configures Pervasive Pervasive PSQL Control Yes Yes Yes Yes
components Center (see “Configuration
Reference” on page 4-1 in
Advanced Operations
Guide)

bdu Imports data into a No Yes No Yes No

database

bmon Monitors Pervasive PSQL Monitor Utility (see Yes Yes

activity “Monitoring Database
Resources” on page 11-1
in Advanced Operations
Guide)

btadmin Creates and administers No No No Yes No

database user names and
passwords

butil Repairs and manipulates Maintenance Utility (see Yes Yes Yes Yes
data files “Manipulating Btrieve Data
Files with Maintenance” on
page 13-1 in Advanced
Operations Guide)

clilcadm Applies and administers License Administrator (see Yes No Yes No

and user licenses “License Administrator” on
w64clilcadm page 4-1)
and
clilcadm
and
w64clilcadm

dbmaint Creates and administers No No No Yes No

named databases

dsnadd Creates and administers No No No Yes Yes

Engine DSNs on the
server

isql Allows you to run SQL No No No Yes Yes

statements interactively
and test connectivity to a
DSN.

psc Manipulates Pervasive No Yes Yes No No

PSQL services

8-3
Command Line Interface Utilities

Table 8-1 Available Utilities for Client and Server continued

Utility Description GUI Available Windows Linux

Server Client Server Client

psregsvr Register Pervasive No No No Yes Yes

components.

pvdbpass Specifies user names and Pervasive PSQL Control Yes Yes Yes Yes
passwords for secure Center (see “Pervasive
databases PSQL Security” on page 7-
1 in Advanced Operations
Guide)

pvddl Processes SQL Pervasive PSQL Control Yes Yes Yes Yes
statements in a command Center (see “SQL Editor”
file on page 6-1)

pvmdconv Converts V1 metadata to No Yes Yes Yes Yes

V2 metadata

pvnetpass Specifies user names and No Yes Yes Yes Yes

passwords for remote
servers

rbldcli Rebuilds MicroKernel data Yes Yes Yes Yes

files.

8-4
 Command Line Interface Utility Reference

Command Line Interface Utility Reference

This section provides a reference for the following command line
interface utilities:
„ “bcfg” on page 8-6
„ “bdu” on page 8-7
„ “bmon” on page 8-14
„ “btadmin” on page 8-15
„ “butil” on page 8-17
„ “clilcadm and w64clilcadm” on page 8-19
„ “dbmaint” on page 8-20
„ “dsnadd” on page 8-23
„ “isql” on page 8-25
„ “psc” on page 8-26
„ “psregsvr” on page 8-28
„ “pvdbpass” on page 8-29
„ “pvddl” on page 8-31
„ “pvmdconv” on page 8-33
„ “pvnetpass” on page 8-38
„ “rbldcli” on page 8-41
„ “clilcadm and w64clilcadm” on page 8-19

8-5
Command Line Interface Utilities

bcfg
The bcfg utility is documented in Advanced Operations Guide. See
“Configuration Through CLI Utility” on page 4-5.

8-6
 Command Line Interface Utility Reference

bdu

Description The Bulk Data Utility (BDU) is a command line utility that allows
you to load data from a delimited text file into a Pervasive PSQL
table. The table and database must already exist.
The BDU, the table, the database, and the Pervasive PSQL database
engine must all be located on the same machine. The delimited text
file must be locally accessible by the database engine server through
a local drive, mapped drive, mounted folder, or shared folder.
You may use a default delimiter or a user-specified delimiter. The
delimiting character must not be contained in the data itself. The
following tables list the permissible delimiters.
Table 8-2 Delimiters for Columns

Delimiter Indicated By

Tab \t (default)

Any single printable character (control (*, A, t, l, and so forth)

characters are not printable, except
null, tab, new line, and carriage return)

Note Pervasive PSQL does not support the use of NULL

terminator (\0) or double quote (") as column delimiters.

Table 8-3 Delimiters for Rows

Delimiter Indicated By

New line character \n (default)

Carriage return \r

Carriage return line feed (CR LF) \r\n

The BDU supports only the single quote (') and the double quote (")
characters as text qualifiers. The data file may contain column values
enclosed by single quotes or by double quotes. For example, the

8-7
Command Line Interface Utilities

following column values are enclosed by double quotes and

delimited by the TAB character: "Fred"\t"22"\t"2459"\t"Sales"\t.
The BDU treats consecutive column delimiters as NULL values. If
the utility finds consecutive column delimiters, it inserts a NULL
value into the column, provided the column is nullable.
No qualifiers are allowed for a NULL value. The following column
data a NULL value in the second column. Note that qualifiers are not
included for that column: "Fred"\t\t"2459"\t"Sales"\t.

Synopsis bdu {database_name} {table_name} {data_file}

[-e max_errors]
[-r reject_file]
[-f first_row]
[-l last_row]
[-t field_term]
[-n row_term]
[-o output_file]
[{-u login_id} {-p password}]
[-q text_qualifier]
[-h]

Note When loading data with BDU into a secured database for
which the Btrieve Security policy is set to “Mixed,” the supplied
credentials (user name and password) must match those of a
Pervasive PSQL database user account and an operating system
user account.

Options
Table 8-4 Bulk Data Utility Parameters

Parameter Mandatory/ Default Value Description

Optional

database_name Mandatory Database name to connect to the local

Pervasive PSQL engine

table_name Mandatory Name of the table to be populated

8-8
 Command Line Interface Utility Reference

Table 8-4 Bulk Data Utility Parameters continued

Parameter Mandatory/ Default Value Description

Optional

data_file Mandatory Name and location of the delimited text

file

max_errors Optional 0 (zero) The maximum number of errors that the

BDU ignores before exiting.
The BDU exits when the
first error is encountered.

reject_file Optional stderr Name of the file to which to write the

rows that failed load. The specified
directory must exist. However, if the file
does not exist in the specified directory,
it will be created.

first_row Optional Row 1 The first row in the delimited text file
with which the load begins. This
parameter allows you to skip a header
row. For example, if your header row is
row 1, set first_row to 2.

last_row Optional End of the source file Last row in source file (row will be
included in load). The load will stop after
the end row has been loaded

field_term Optional A character, such as a Column delimiter in the source file

comma or tab character

row_term Optional A new line character Row delimiter in the source file

output_file Optional stderr Name of the file to which to write the

information and error messages during
load. The specified directory must exist.
However, if the file does not exist in the
specified directory, it will be created.

login_id Optional User name to connect to the Pervasive

SQL engine.

password Optional Password to connect to the Pervasive

SQL engine

text_qualifier Optional

Notes Configuration Settings

You are not required to change any Pervasive PSQL configuration
settings to use BDU.

8-9
Command Line Interface Utilities

BDU loads data into a table using the accelerated mode. During the
load of data, the MicroKernel does not perform transaction logging.
If you use archival logging, back up your data files again

Error Logging
By default, BDU logs all information and error messages to the
standard error stream (stderr). You may specify a log file to which the
utility writes the information or error messages.
Two types of errors are not logged: critical and recoverable. With
critical errors, BDU exits because it cannot perform error recovery.
For example, a missing delimited data file is a critical error.
With recoverable errors, BDU skips the error and continues
processing. The utility keeps a count of such skipped errors and exits
when it reaches a user-specified threshold. By default, the threshold
is set to zero.

Constraints
The following constraints apply to loading data with BDU.

Constraint Discussion

Any Referential Integrity (RI) error Row is rejected

is considered an RI violation

Any unique or primary key Row is rejected

violations

No value specified for a non-NULL Row is rejected regardless of column’s

column1 default value

No value specified for a nullable NULL inserted regardless of column’s

column1 default value

Table into which data is being BDU returns an error and does not attempt
loaded contains insert triggers to load the table. Drop the insert triggers on
the table then re-run BDU

Table into which data is being BDU does not attempt to load the table
loaded contains CLOB or BLOB
columns

Order of rows BDU treats the delimited data file as

unordered. The original order of rows may
not be preserved.

8-10
 Command Line Interface Utility Reference

Constraint Discussion

Date fields The only supported format is yyyy-mm-dd

Time fields The only supported format is HH:MM:SS

Timestamp fields The only supported format is yyyy-mm-dd

HH:MM:SS.MS

1
BDU is not aware of default values for a column defined during table creation or
update

Best Practices
If possible, run BDU when the database load is minimal or when no
concurrent sessions exist on the table being loaded.
If the table being loaded contains any indexes, drop the indexes
before using DBU. Re-create the indexes after the load is complete.
If the table being loaded contains any columns with check
constraints, drop the check constraints before using BDU. Re-specify
the constraints after the load is complete.

Sample Source File

The following content may be used to create a sample delimited text
file. You may use the file to verify the usage examples. The examples
refer to the sample file as data_file.txt.
Note that, because the following content is comma delimited, you
must specify the -t parameter (-t ,) with BDU. The -t parameter is
required for any delimiter except the TAB character.
pervasiveBDUsample_1,12345,pervasive,101,18446744073709551615
pervasiveBDUsample_2,12346,pervasive,102,18446744073709551614
pervasiveBDUsample_3,12347,pervasive,103,18446744073709551613
pervasiveBDUsample_4,12348,pervasive,104,18446744073709551612
pervasiveBDUsample_5,12349,pervasive,105,18446744073709551611
pervasiveBDUsample_6,12350,pervasive,106,18446744073709551610
pervasiveBDUsample_7,12351,pervasive,107,18446744073709551609
pervasiveBDUsample_8,12352,pervasive,108,18446744073709551608
pervasiveBDUsample_9,12353,pervasive,109,18446744073709551607
pervasiveBDUsample10,12354,pervasive,110,18446744073709551606

Examples The following examples assume that a table named BDU_Table is

part of the Demodata sample database. To add such a table to
Demodata, use the following query:

8-11
Command Line Interface Utilities

CREATE TABLE BDU_Table (Name CHAR(20) NOT NULL CASE,

PhoneNo INTEGER,BuildingName CHAR(25) NOT NULL CASE,
RoomNo UINT NOT NULL,HeadOfDept UBIGINT NOT NULL)

To run BDU with the default options:

bdu demodata BDU_Table C:\data_file.txt

Note The input data must be TAB delimited to use default

options. If the input data is not TAB delimited, you must specify
the delimiter with the -t parameter.

For example, to use the data from “Examples” on page 8-11,

which is comma delimited, you would run BDU as follows:

bdu demodata BDU_Table C:\data_file.txt -t ,

To run the BDU for a database that requires username and password:
bdu demodata BDU_Table C:\data_file.txt -u <username> -
p <password>

To run the BDU with max errors option:

bdu demodata BDU_Table C:\data_file.txt -e <no of errors
user wants to allow>

For instance, for loading to continue until 100 errors have occurred:
bdu demodata BDU_Table C:\data_file.txt -e 100

To run the BDU with a specific column delimiter option:

bdu demodata BDU_Table C:\data_file.txt -t <column
delimiter>

Example:
When the source file contains text in which each row is separated by ,
bdu demodata BDU_Table C:\data_file.txt -t ,

To run the BDU with a specific row delimiter option:

8-12
 Command Line Interface Utility Reference

bdu demodata BDU_Table C:\data_file.txt -n <row

delimiter>

For instance, when the source file contains text in which each row is
separated by \n:
bdu demodata BDU_Table C:\data_file.txt -n \n

To run the BDU with a specific start row option:

bdu demodata BDU_Table C:\data_file.txt -f <line no.
from which user wants loading to begin>

To run the BDU with a specific end row option:

bdu demodata BDU_Table C:\data_file.txt -l <line no. at
which user wants loading to end>

You may combine parameters. To load the first 15 rows from the
source file containing data that is separated by | and is enclosed in ':
bdu demodata BDU_Table C:\data_file.txt -f 1 -l 15 -t |

8-13
Command Line Interface Utilities

bmon
The bmon utility is documented in Advanced Operations Guide. See
“Monitor Command Line Interface” on page 11-21.

8-14
 Command Line Interface Utility Reference

btadmin

Description The btadmin utility is used to create and update the flat file
btpasswd, which stores user names and passwords for authentication
of Pervasive PSQL users. Users given administrator rights can
monitor engine status and configure the engine remotely.

Synopsis btadmin [ -p password] [a+] [a-] [-r] username

Options

-p Specify the password. If this option is not specified, you will be prompted to
enter the password.

a+ Gives administrator rights for this user.

a- Removes administrator rights for this user.

-r Remove user name from btpasswd file.

username
Creates or updates the username in the btpasswd file. If username does
not exist in this file, an entry is added. If it does exist, the password
is changed.

See Also butil(1)

Notes To administer the engine from a remote workstation, you must

supply a user name and password. Upon initial installation of
Pervasive PSQL v10.10, the supplied default is admin with an empty
password.
Use btadmin to add more administrators:
% btadmin [-p password] [a+] username

8-15
Command Line Interface Utilities

This utility creates a record in btpasswd for user username with

password password (if option -p is not used, then you will be asked to
enter a password). If a user already exists, then his password is
changed as specified.
By default a user is created without administration permissions. You
can use the a+ option to give administration rights to the user. You
can remove this right by using a-.
To remove a user record from the password file, enter:
% btadmin -r username

Every time the btpasswd file is changed, the previous version is

backed up to btpasswd-.

8-16
 Command Line Interface Utility Reference

butil

Description The Pervasive PSQL Maintenance Utility, or butil, is a command line

utility that performs command file and data manipulations on a data
file.
The maintenance utility performs the following file and data
manipulations:
„ Starts and stops continuous operations for use in performing
server backups.
„ Recovers changes made to a file between the time of the last
backup and a system failure.
„ Imports and exports ASCII, unformatted, and SDF sequential
data.
„ Copies data between data files.
„ Returns MKDE version information.
Continuous operation is an MKDE feature that enables you to back
up files while they are in use by Pervasive PSQL-based applications.
Two maintenance commands, startbu and endbu, begin and end
continuous operation on a file or set of files.

Synopsis butil
-clone outputFile sourceFile [/O<owner | *>] [/pagecompresson |
/pagecompressoff] [/recordcompresson | /
recordcompressoff] [/UIDuname /PWDpword [/DBdbname]]
-clrowner sourceFile /O<owner | *> [/UIDuname /PWDpword [/
DBdbname]]
@commandFile [commandOutputFile]
-copy sourceFile outputFile
[/O< owner1 | *> [/O<owner2 | *>]] [/UIDuname /PWDpword
[/DBdbname]]
-create outputFile descriptionFile [< Y | N >] [/UIDuname /
PWDpword [/DBdbname]]
-drop sourceFile < keyNumber | SYSKEY >
[/O<owner | *>] [/UIDuname /PWDpword [/DBdbname]]
-endbu < /A | sourceFile | @listFile > [/UIDuname /PWDpword [/
DBdbname]]
-index sourceFile indexFile descriptionFile
[ /O<owner | *>] [/UIDuname /PWDpword [/DBdbname]]
-load unformattedFile outputFile [/O<owner |*>] [/UIDuname /
PWDpword [/DBdbname]]
-recover sourceFile unformattedFile [/O<owner |*>] [/UIDuname /
PWDpword [/DBdbname]]

8-17
Command Line Interface Utilities

-rollfwd <sourceFile | volume | drive | @listFile>

[</L[dumpFile] | /W[dumpFile]> [/T<dataLength>]
[/E<keyLength>] [/H] [/V] [/O<ownerList | owner> | *]]
[/A] [/UIDuname /PWDpword [/DBdbname]]
-save sourceFile unformattedFile
[Y indexFile | N <keyNumber | -1>] [/O<owner1 | *>
[/O<owner2 | *>]] [/UIDuname /PWDpword [/DBdbname]]
-setowner sourceFile /O<owner | *> level [/UIDuname /PWDpword
[/DBdbname]]
-sindex sourceFile <descriptionFile | SYSKEY> [keyNumber] [/O<owner
| *>] [/UIDuname /PWDpword [/DBdbname]]
-startbu <sourceFile | @listFile> [/UIDuname /PWDpword [/
DBdbname]]
-stat <sourceFile> [/O<owner | *>] [/UIDuname /PWDpword [/
DBdbname]]
-ver

Note On Linux distributions, all “/” parameters use the hyphen

(“-”) instead of the slash. For example, the /O parameter for
butil -copy is -O, as in butil -copy -O.

Options Maintenance Utility command options are not case sensitive unless
the option is a filename.
If you run butil without specifying a command option or with an
invalid command option, a usage message is printed. The usage
message indicates that there is an optional /S command line
argument to butil. This argument is ignored under Linux.
For a complete discussion of the utility commands, options, and
examples, see the section “Btrieve Command-Line Maintenance
Utility (butil)” on page 13-38 in Advanced Operations Guide.

See Also syslogd in Linux man pages

Btrieve API Guide, which describes the API for the transactional
interface.

8-18
 Command Line Interface Utility Reference

clilcadm and w64clilcadm

Description The clilcadm utility manages the user count licenses on your engine.
The 64-bit version of this utility is named w64clilcadm.

Note On Linux, this utility can only be run by user accounts

belonging to group pvsw. See Getting Started With Pervasive
PSQL for information on Pervasive PSQL Linux utilities and
user accounts.

Synopsis clilcadm -a key | -h | -i [key] | -r key

w64clilcadm -a key | -h | -i [key] | -r key

Options

-a key Adds a specified license key.

-h Displays help information for the clilcadm utility.

-i [key] Displays information about a specific key. If no key is specified,

information about all installed keys is displayed.

-r key Removes a specified license key.

See Also “License Administrator” on page 4-1 documents License

Administration in detail.

8-19
Command Line Interface Utilities

dbmaint

Description The dbmaint utility manages named databases.

Note This utility can only be run by user accounts belonging to

group pvsw. See Getting Started With Pervasive PSQL for
information on Pervasive PSQL Linux utilities and user
accounts.

Synopsis dbmaint a | d | l | m [-nDbname] [-a] [-b] [-c] [-i] [-e]

[-ldictpath] [-ddatapath] [-ssecuritymode]

add new database name a -nDbname [-b] [-i] [-e]

[-ldictpath] [-ddatapath]

delete database name d -nDbname

list database names l [-a]. The -a option displays the full information
about the dbnames.

modify database name m -nDbname -ssecuritymode

security policy

Options Commands

add, a Add database name

del, d Delete database name

list, l List database names

8-20
 Command Line Interface Utility Reference

Options

-b Create bound database

-c=codepage Set the database code page. Zero specifies the server default
(-c=0).

-i Create database with relational integrity

-e Do not create dictionary files for database

-nDBName Specify database name

-ldictpath Specify dictionary path

-ddatapath Specify datapath

-a Show detail information about dbnames in database list

-ssecuritymode Specify Btrieve security policy for database. Valid choices are:
Classic, Mixed, Database

Examples
To create a database named “TEST” with relational integrity:
% dbmaint a -i -nTEST

Note Unless a datapath is specified, the new database will be in

the default location, $PVSW_ROOT/data. Likewise, if a
dictionary path is not specified, the dictionary will be created in
the default location.

To delete the same database:

% dbmaint d -nTEST

To create a database named “mydbase” with a database code page of

CP932:
% dbmaint a -nmydbase -c=CP932

For the same database, to set the code page to the default operating
system code page:
% dbmaint m -nmydbase -c=0

To see a list of valid code pages (specify an invalid code page and
dbmaint returns a list of valid ones):

8-21
Command Line Interface Utilities

% dbmaint m -nmydbase -c=xzy

Dbmaint returns something similar to the following:

Bad code page "xyz" should be: ASCII, ISO8859_1, CP437,
CP1252, UTF-8, CP1250, CP1251, CP1253, CP1254, CP1255,
CP1256, CP1257, CP1258, CP737, CP775, CP850, CP852,
CP855, CP857, CP858, CP862, CP866, CP932, or EUCJP

To list all database names with full information:

% dbmaint l -a

To modify the security policy of the DefaultDB database to Mixed:

% dbmaint m -nDefaultDB -sMixed

See Also dsnadd(1), butil(1), btadmin(1), syslogd(1), smb.conf(5)

“Data Encoding” on page 10-15 in Getting Started With Pervasive

PSQL.

8-22
 Command Line Interface Utility Reference

dsnadd

Description dsnadd simplifies the setup of a new ODBC data source that uses the
Pervasive ODBC Client Interface driver. It modifies the odbc.ini file
by adding appropriate information about the new data source. For
the latest information on dsnadd, see the man page.

Synopsis To add a data source, execute the following command:

dsnadd -dsn=myDSN -db=DBname
[-desc=DSN_description] [-drv-desc=driver_description]

or
dsnadd -dsn=myDSN -desc=DSN_description
-db DBname -host=psqlhost -sdsn=svDSN

myDSN is a name you want to assign to the new data source.

DSN_description is any string to describe the data source.

psqlhost is the name of the network host where your Pervasive PSQL is
installed.
svDSN is the name of the data source on the Pervasive PSQL host.

Options

-db Name of the database to which the DSN is

associated

-drv-desc Driver description [Pervasive ODBC Client

interface]

-drv-path | -drv [/usr/local/psql/lib:$HOME/lib]

-dsn-desc | -desc DSN description

[[driver_description:]host/DSN]

-dsn-name | -dsn Data Source Name

-help Help about the dsnadd utility

-odbc-ini | -ini ODBC.ini file name (/usr/local/psql/etc/

odbc.ini)

-sdsn Server DSN

-srv-host | -host Server host name

8-23
Command Line Interface Utilities

-srv-port | -port Server port number [1583] (See also “Changing the
Default Communication Ports” on page 10-10 in
Getting Started With Pervasive PSQL.)

-translate=< none | Encoding translation to use for character data. See

auto > “None” on page F-5 and “Automatic” on page F-6,
both in SQL Engine Reference.

Examples To add a Client DSN named localDSN that references an Engine

DSN named remoteDSN on a machine named server12, enter the
following command:
dsnadd -dsn=localDSN -desc=any_text -host=server12
-svr-dsn=remoteDSN

To add a Client DSN named cliacctdb that references an Engine

DSN named srvacctdb3 on a machine named finan_server, and
uses automatic encoding, enter the following command:
dsnadd -dsn=cliacctdb -desc=acct_database_region_3
-host=finan_server -svr-dsn=srvacctdb3
-translate=auto

See Also btadmin(1), dbmaint(1)

8-24
 Command Line Interface Utility Reference

isql

Description isql is an interactive ODBC test utility that you can use to test your
DSNs for their connectivity to databases. For example, to connect to
the DEMODATA database included with Pervasive PSQL, run isql
with the DSN as the first parameter. For example, isql DEMODATA.
The utility puts you in an interactive state with the database. From
that state, you can query the database (such as SELECT * FROM
Department).
To enable security on a database using isql, first connect to the
database as the “Master” user, then use the SET SECURITY
statement in SQL to set the Master user password. For example:
isql DEMODATA Master
SET SECURITY = password

See “SET SECURITY” on page 3-258 in SQL Engine Reference.

To connect to a secured database, pass the user name and password
as the second and third parameters respectively to the isql utility. For
example, to connect to DEMODATA as user “Master” using
password “vforge,” enter isql DEMODATA Master vforge.

Synopsis isql

Options

parameter1 Required. Specifies the data source name (DSN) of the

database to which you want to connect.

parameter2 Required only for a secured database. Specifies the user

name.

parameter3 Required only for a secured database. Specifies the password

for the user.

Examples To connect to an unsecured database named “acctspay:”

isql acctspay

To connect to a secured database named INVENTORY as user

“Master” with a password of “j77b99:”
isql INVENTORY Master j77b99

8-25
Command Line Interface Utilities

psc

Description Psc stands for Pervasive service controller. The utility retrieves and
sets control information about Pervasive PSQL services.
You must have administrator authority to run psc.

Synopsis psc < start | stop | restart | query | getpolicy >

servicename

or
psc setpolicy servicename < automatic | manual | disabled
>

Options A service specifies the name of a program, routine, or process that

performs a specific system function to support other programs,
particularly at a low level (close to the hardware). Servicename
specifies the name given to the service key in the registry. Note that
service key name may differ—and in most cases does differ—from
the service display name.
The options described below are case-insensitive.

start Starts a Pervasive PSQL service running

stop Terminates the running of a Pervasive PSQL service

restart Terminates the running of a Pervasive PSQL service then starts

the service running again

query Specifies whether servicename is running or not

getpolicy Retrives the type of startmode (automatic, manual, or disabled)

associated with servicename

setpolicy Sets the type of startmode (automatic, manual, or disabled)

associated with servicename

automatic The service starts automatically when the operating system

starts

manual The service must be started manually after the operating system
starts

disabled The service is disabled and does not start after the operating
system starts

8-26
 Command Line Interface Utility Reference

Examples
To start the Workgroup Engine service manually:
psc start psqlWGE

To start the Cache Engine service manually:

psc start psqlCE

To stop, then restart the Pervasive PSQL transactional and relational

services:
psc restart psql.all

Note that “psql.all” is a shortcut method available only with the psc
utility. It affects both the “Pervasive.SQL (transactional)” service and
the “Pervasive.SQL (relational)” service, and can be used with the
psc parameters start, stop, or restart.

8-27
Command Line Interface Utilities

psregsvr

Description psregsvr is used to register components in the Pervasive registry.

Synopsis psregsvr [ -s ] [ -u ] { [ -f file ] | filename }

Options

-s Silent. Do not print any status or error messages.

-u Unregister. If not specified, register is assumed.

-f file Specifies a text file with PCOM modules listed one

per line.

filename Specifies a single PCOM module to register.

8-28
 Command Line Interface Utility Reference

pvdbpass

Description pvdbpass allows users to change their passwords for secure databases
without administrator intervention.

Synopsis The utility will prompt for the passwords with this syntax
pvdbpass database username [-server name] [-port number]

This syntax includes the old and new passwords.

pvdbpass database username password newpassword
[-server name] [-port number]

Options

database Database in which the username is defined (this can be

a database name or a server DSN)

username The user whose password will be changed.

password The current password for the user. You must provide the
original password in order to modify it. You can either
provide the password as a parameter or omit it and be
prompted.

newpassword The new password for the user. See “Identifier

Restrictions by Identifier Type” on page 1-3 in Advanced
Operations Guide for password restrictions.

Note: If the new password begins with a non-alphabetic

character, the password must be enclosed in single
quotes. If the existing password begins with a non-
alphabetic character, do not enclose it in single quotes
(see examples).

servername Optional. Server name on which the database is

defined. If you do not specify this option, the local
machine is assumed

port Optional. TCP port on which the SQL engine running on

servername is listening. If you do not specify this option,
the default port 1583 is assumed. See also “Changing
the Default Communication Ports” on page 10-10 in
Getting Started With Pervasive PSQL.

Examples To change the Master user's password and be prompted:

pvdbpass demodata Master

8-29
Command Line Interface Utilities

To change an existing password to one that does not start with an

alphabetic character (use single quotes):
pvdbpass demodata Joe oldpassword '123'

To change a password on a remote server:

pvdbpass demodata Joe oldpass newpass -server finance1

8-30
 Command Line Interface Utility Reference

pvddl

Description pvddl is used to execute a series of SQL statements in a command file.

Synopsis pvddl database commandfile

[-separator character] [-username username] [-password
password] [-server servername] [-port number] [-
stoponfail] [-log logfile]

Options

database Database against which the SQL statements in

commandfile are to be executed (this can be a
database name or a server DSN).

commandfile Text file that contains the SQL statements.

Certain categories of SQL statements, such as
data definition language, are better suited for use
in commandfile. (Contrast this with a data
manipulation statement such as SELECT. A
SELECT statement can be used, but the result
set is not returned to standard output.)

You need a separator character between each

command in your command file. See -separator
character.

-separator character Character used in commandfile to separate SQL

statements. The valid choices are any printable
character. However, ensure that character does
not occur within any of the SQL statements.
Common character choices include the pound
sign (#), semicolon (;), and at sign (@).

-username username Name of a user defined for a database with

security enabled.

-password password Password for the user identified by username

-server servername Name of the server on which the database is

defined. If you do not specify this option, the local
machine is assumed. You may also specify the
IP address of the server.

-port number TCP port number on which the database engine

running on servername is listening. If you do not
specify this option, the default port 1583 is
assumed. (Port 1583 is the default port used for
the relational interface.)

8-31
Command Line Interface Utilities

-stoponfail Stop when the first SQL error is encountered in

commandfile. Pvddl returns an error code of
PS_E_FAIL if an error is encountered (which
equates to -2147467259 decimal). The default
action is for pvddl to continue after an SQL error
is encountered.

-log logfile Write output to a file instead of to standard output

(stdout). Logfile specifies the name of the file to
which output is logged and, optionally, a path to
the file. If path is omitted, logfile is created in the
same directory in which dvddl resides.

See Also SQL Engine Reference for more information about supported SQL
syntax.

8-32
 Command Line Interface Utility Reference

pvmdconv
Pervasive PSQL includes a conversion utility, pvmdconv, to convert
V1 metadata to V2 metadata. This command line utility is located in
the BIN subdirectory under the installation directory.

Synopsis pvmdconv -o <1 | 2> -d path_to_DDFs -n database_name [-

v] [-ddf] [-s server_name] [-i server_login_name] [-
c server_password] [-u database_user_name] [-p
database_password] [-l log_file] [-<h | ?>]

Parameters

-o <1 | 2> Specifies the output format of the metadata. The

choices are 1 or 2, which refer to version 1 (V1) and
version 2 (V2) metadata, respectively.

Note: The current release of pvmdconv does not

support converting DDFs from V2 metadata to V1
metadata.

-d path_to_DDFs Specifies the directory containing the DDFs that

you want to convert. The new DDFs are created in
the same directory.

-n database_name Specifies the name of the Pervasive PSQL

database.

[-v] Specifies to change the metadata version of the

database in dbnames.cfg. For example, if -o=2, the
metadata version of the database is changed to V2
metadata. If the “v” parameter is used, pvmdconv
does not change the metadata version of the
DDFs.

[-ddf] Specifies to change the metadata version of the

DDFs. If this parameter is used, pvmdconv does
not change the metadata version of the database in
dbnames.cfg.

[-s server_name] Specifies the name or IP address of the remote

server where the database resides. This parameter
is required if the pvmdconv utility being executed
resides on one machine but the database resides
on another. This parameter defaults to “localhost,”
so it is not required if pvmdconv and the database
reside on the same machine.

[-i server_login_name] Specifies the name required to log in to the remote

server where the database resides.
Server_login_name is a name administered by the
operating system.

8-33
Command Line Interface Utilities

[-c server_password] Specifies the password for server_login_name.

Server_password is a password administered by
the operating system.

[-u database_user_name] Specifies the name of a user who is authorized to

log on to the database.

[-p database_password] Specifies the password associated with

database_user_name.

[-l log_file] Prints diagnostic messages to a text file. The name

and location of the text file is specified by log_file. If
this parameter is omitted, the utility prints any
diagnostic messages to the screen.

[-<h | ?>] Prints on the screen the usage information for the
utility.

Description Pvmdconv allows you to perform the following actions:

„ Convert only DDFs from one version of metadata to another
version of metadata. The database to which the DDFs belong
remains categorized as is. That is, the metadata property for the
database, which is stored in a special file named dbnames.cfg,
does not change. This action is sometimes referred to as
“migrating” the DDFs.
„ Set the metadata version of a database to V1 metadata or to V2
metadata. The metadata property of a database, which is stored
in a special file named dbnames.cfg, changes. The DDFs for the
database retain their metadata version.
This action requires that the DDFs for each metadata version
must already exist in the location path_to_ddfs. That is, you must
have already converted (migrated) the DDFs from V1 metadata
to V2 metadata.
„ Convert the DDFs and set the metadata property of the database
in dbnames.cfg. That is, combine the first two actions. This is the
default action of pvmdconv.
Having different conversion actions provides more control over how
you can convert metadata. For example, you may choose first to
convert only the DDFs and check for errors. If no errors occur, you
could then update the metadata version in dbnames.cfg.

8-34
 Command Line Interface Utility Reference

Conversion From All of the data from the V1 DDFs is directly copied to the V2 DDFs
V1 to V2 Metadata with the following exceptions:

System Table Action on Field Comments

X$View The value of Xv$Id is copied to Xv$Sequence has auto-increment values for each row.
Xv$Sequence in pvview.ddf.

The value of Xv$Trustee, which is The value is stored as -1 regardless of the security
a new column in V2 metadata, is setting for the database. That is, if the database has
explicitly stored as -1. security enabled or if the databases does not have
security enabled.

If the V1 metadata database has security enabled, an

explicit "GRANT ALL TO PUBLIC" is invoked for all
views when the database is converted to V2 metadata.

X$Proc The value of Xp$Id is copied to Xp$Sequence has auto-increment values for each row.
Xp$Sequence in pvproc.ddf.

The value of Xp$Trustee which is The value is stored as -1 regardless of the security
a new column in V2 metadata, is setting for the database. That is, the value is stored as
explicitly stored as -1. -1 if the database has security enabled or if the
databases does not have security enabled.

If the V1 metadata database has security enabled, an

explicit "GRANT ALL TO PUBLIC" is invoked for all
stored procedures when the database is converted to
V2 metadata.

X$Rights The value of Xr$Table is copied to

Xr$Object in pvrights.ddf.

A default value of 1 is copied to

Xr$Type in pvrights.ddf.

Conversion From The current release of pvmdconv does not support conversion from
V2 to V1 Metadata V2 to V1 metadata.

Examples For default locations of Pervasive PSQL files, see “Where are the
Pervasive PSQL files installed?” on page 7-2 in Getting Started With
Pervasive PSQL.

Default Conversion
To convert the sample database DEMODATA to V2 metadata
(assuming a default installation on a Windows platform):
pvmdconv -o 2 -d file_path\PSQL\Demodata\ -n demodata

This example results in the following:

8-35
Command Line Interface Utilities

„ V2 metadata DDFs are created in the same location as the V1

metadata DDFs (file_path\PSQL\Demodata\).
„ The metadata version of DEMODATA in dbnames.cfg is
changed to V2 metadata.
To perform the same conversion and obtain a log of conversion
diagnostic information:
pvmdconv -o 2 -d file_path\PSQL\Demodata\ -n demodata -l
file_path\PSQL\Demodata\\pvmdconv_log.txt

Convert Only DDFs

To convert only the DDFS for the sample database DEMODATA to
V2 metadata (assuming a default installation on a Windows
platform):
pvmdconv -o 2 -d file_path\PSQL\Demodata\ -n demodata -
DDF

This example results in the following:

„ V2 metadata DDFs are created in the same location as the V1
metadata DDFs (file_path\PSQL\Demodata\).
„ The metadata version of DEMODATA in dbnames.cfg is not
changed.

Change Metadata Version of Database

To change the metadata version of the sample database DEMODATA
to V2 metadata (assuming a default installation on a Windows
platform):
pvmdconv -o 2 -d file_path\PSQL\Demodata\ -n demodata -v

This example results in the following:

„ The metadata version of DEMODATA in dbnames.cfg is
changed to V2 metadata.
„ V2 metadata DDFs are not created.
Note: this example requires that the DEMODATA DDFs exist in
file_path\PSQL\Demodata\ even through the DDFs are not affected
by the conversion.

Perform Conversion on a Remote Server

To convert the sample database DEMODATA to V2 metadata given
the following:

8-36
 Command Line Interface Utility Reference

„ DEMODATA resides on a server named “TESTSERVER”

„ An administrator ID on TESTSERVER is “adminuser” and user
adminuser has a password of “admin99user”
„ Drive “Z” is mapped to drive “C” on TESTSERVER (assuming
TESTSERVER is a Windows platform with a default installation
of Pervasive PSQL).
pvmdconv -o 2 -d z:file_path\PSQL\Demodata\ -n demodata
-s TESTSERVER -i adminuser -c admin99user

This example results in the following:

„ V2 metadata DDFs are created on TESTSERVER in the same
location as the V1 metadata DDFs.
„ The metadata version of DEMODATA in dbnames.cfg on
TESTSERVER is changed to V2 metadata.

8-37
Command Line Interface Utilities

pvnetpass

Description pvnetpass is the Pervasive network password utility. It is a command

line utility used to manage the user IDs and passwords for servers to
which your client connects. When trying to connect to a server, the
client looks up the server name in the registry and uses the user name
and password set for that server.
If your application uses the transactional interface and connects to a
Linux database engine that is configured to use BTPASSWD or PAM
authentication, the application requires a set of credentials to
connect to the database engine. (See “Authentication” on page 13-6
in Getting Started With Pervasive PSQL.) Use pvnetpass to configure
the set(s) of credentials that the application will use. Pvnetpass must
be run on every machine that connects to the database engine,
whether the database engine is local or remote.
If you have a global and a user entry for the same server, the user’s
entry overrides the global. The user name should include the full
user context. For example, in a Windows environment with domain
names, specify the user as DOMAIN\\user. Enter two back slashes for
the user name because the first one is an escape character. For a
Linux environment, use the user account name and the full machine
DNS name. For example, mymachine.mydomain.
The pvnetpass utility can also be used by Windows clients to change
their stored credentials that were saved when using the security login
pop-up dialog. See also “Allow Client-stored Credentials” on page 4-
17 and “Prompt for Client Credentials” on page 4-22, both in
Advanced Operations Guide.

Synopsis pvnetpass [-g] {-a | -r | -m} server [-u user] [-p pwd]
pvnetpass -d

8-38
 Command Line Interface Utility Reference

Options

-a Adds a server entry for a user specified by the -u parameter. If no

user is specified, current user is assumed.

-d Displays the list of configured servers. The configured servers will

display in two groups that are separated by a dashed line. The
ones above the line are global entries and are only viewable by
administrators who are a member of group pvsw. The ones below
the line are the current user’s entries. If you have a global and a
user entry for the same server, the user’s entry overrides the
global.

-g Manipulates default settings for all users. Settings created with -

g can be overridden by individual users.

-m Modifies a server entry for a user specified by the -u parameter. If

no user is specified, current user is assumed.

-p Specifies the password for the user. If not provided, pvnetpass

prompts for a password.

-r Removes a server entry for a user specified by the -u parameter.

If no user is specified, current user is assumed.

server Server, local or remote, to which you want to add a connection

entry. Server can be '*' (include the single quotes) to set the
default server entry information. This default entry is used when
there is no user entry for the server.

-u Specifies the name of the user. If -u is not specified, your current

user name will be used.

See Also “Setting Up Client Access” on page 2-21

Examples From current user to all servers (overrides -g)

pvnetpass -a '*' -p password

From current user to one server 'myserver' (overrides -g)

pvnetpass -a myserver -p password

From all users (-g) to one server 'myserver' using credentials

joe:password
pvnetpass -g -a myserver -u joe -p password

From all users (-g) to all servers ('*'), use default credentials
joe:password
pvnetpass -g -a '*' -u joe -p password

8-39
Command Line Interface Utilities

To add user ‘acctadmin’ with password ‘88sJkE5’ to the local server

named ‘sles2HR’:
pvnetpass -a sles2HR -u acctadmin -p p88sJkE5

To add user ‘bholly’ with password ‘peggysue’ to a remote server

named ‘myserver’:
pvnetpass -a myserver -u bholly -p peggysue

To verify your entry was accepted, use the -d option:

pvnetpass -d

This command results in:

Server: myserver
User: bholly
Password: (not displayed)

To change the password with which you will connect to ‘myserver’

from your Linux client:
pvnetpass -m myserver -u bholly -p newpassword

To remove the entry for server ‘myserver’:

pvnetpass -r myserver

To add the default entry for users trying to connect to server

‘myserver’ when no user-specific entry exists:
pvnetpass -g -a myserver -u admin -p adminpassword

To add the default server entry in the user context (PS_HKEY_USER):

pvnetpass -a ‘*’ -u admin -p adminpassword

To add the default server entry in the machine context

(PS_HKEY_CONFIG):
pvnetpass -g -a ‘*’ -u admin -p adminpassword

To authenticate from a Linux client to a Windows domain server

(myserver) with a domain named “mydomain” and a user named
“user1”:
pvnetpass -a myserver -u mydomain\user1 -p
user1password

8-40
 Command Line Interface Utility Reference

rbldcli

Description rbldcli is used to rebuild MicroKernel data files on your server.

Synopsis rbldcli [ -parameter ] file

rbldcli @command-file

Options For a complete discussion of the rebuild utility, see “Command Line
Parameters” on page 14-18 in Advanced Operations Guide.

See Also Advanced Operations Guide for more information about the Rebuild
utility.

8-41
Command Line Interface Utilities

8-42
 chapter

Basic Troubleshooting
9
How to Identify and Solve Common Problems

This chapter provides information for troubleshooting and resolving

the most commonly-encountered problems.
„ “General Troubleshooting” on page 9-2
„ “Error Messages from PCC” on page 9-9
„ “Frequently Asked Questions” on page 9-13

9-1
Basic Troubleshooting

General Troubleshooting
This section provides some basic troubleshooting procedures to help
you rule out possible causes for situations you may encounter. This
section covers the following topics:
„ “I get Error 1114 when trying to access my data” on page 9-2
„ “I get an error about ServerDSN or DBQ was not found in the
connection string” on page 9-2
„ “I get a message about Engine components’ version is different
than my client components’ version” on page 9-2
„ “I can’t get to my data on the server engine” on page 9-3
„ “PCC runs slowly or hangs when retrieving large record sets” on
page 9-7
„ “PCC crashes when browsing a directory structure using the File
Open dialog or when adding an external tool” on page 9-8

I get Error 1114 when trying to access my data

or

I get an error about ServerDSN or DBQ was not found in

the connection string
PCC can access remote server data sources (DSNs) using
connections without client DSNs. Many desktop applications, such
as Microsoft Excel and Microsoft Access, cannot do this. You must
create a client DSN on your local computer to provide access to data
on the server through the remote server DSN. To create a client DSN,
follow the instructions in “Setting Up Client Access” on page 2-21.
You must first make sure that a server DSN exists on the server you
want to access.

I get a message about Engine components’ version is

different than my client components’ version
When a client requester first connects to an engine, the client
requester compares its internal router version with the value
returned from the engine by a Btrieve Version (26) call. If the client
version is older than the engine, a message dialog box is displayed on
the client system with the message “Engine components’ Version is

9-2
 General Troubleshooting

different from Client’s” along with a suggestion to run Pervasive

System Analyzer (PSA). The same message is also logged in the
client’s PVSW.LOG file.
This message is a warning. The client is not prevented from
connecting to the engine in this situation. However, Pervasive
Software guarantees compatibility between engines and clients only
if the clients are the same version as the database engines. When
prompted by this message, if you choose not to run PSA and archive
your old client components and install a newer client, you can expect
the product to behave unpredictably until the client version is equal
to the engine version.

Note 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.

I can’t get to my data on the server engine

If you cannot get to data on the server engine, your most likely causes
are:
„ The server computer is down or the network has been
interrupted
„ You do not have operating system rights to access the server, or
you are not logged into the correct network
„ The client requester is not enabled

9-3
Basic Troubleshooting

„ The database server engine is not installed or not running

„ The database server is not accepting remote connections
„ The remote database does not have a DSN set up to advertise on
the network
„ The local client does not have a DSN to access the server
„ The client or server network configuration is wrong

³ To determine the actual cause of the failure

Follow the steps below to rule out certain root causes and narrow
down the possible sources of failure.
1 From a Windows client, double-click Network Neighborhood
and see if you can find the server computer that you want to
connect to. If you can see the server, you can rule out that the
server is down or disconnected from the network.
2 Next, try to map a drive to the file server or open a shared file on
the server. If you can successfully connect to the file server and
create a file on the mapped drive, then you can rule out lack of
operating system rights. You can also rule out failure to login to
the correct network. If you’re not logged into a particular
network, you can’t access the servers on that network at all.

Note If you are trying to create a new database on the server, to

use Monitor against the remote server engine, or to configure the
remote server engine, you must have administrative rights on
the server, or be a member of Pervasive_Admin. A simple drive-
mapping or shared-file read will not tell you whether you have
administrative rights. This means you may be able to connect to
the file server, but you still may not be able to connect to the
database engine with Configuration, Monitor, or Create
Database Wizard.

3 The next possibility is that the client requester is disabled.

Start PCC from the Pervasive PSQL group on the Start menu.
Right-click the icon that represents your local client computer,
then click Properties. Click Access and ensure that Use Remote
MicroKernel Engine is selected.
You can now rule out the requester as the source of the problem.

9-4
 General Troubleshooting

4 Next, verify that Pervasive PSQL is installed and running on the

target server.
On Windows, open Services under Administrative Tools. Verify
that Pervasive PSQL Transactional Engine and Pervasive PSQL
Relational Engine have been started. If not, start these services.
On Linux, type the following command at the Linux prompt on
the server where the database engine is installed:
ps -e | egrep ‘mkded’

If the output from the command returns at least one line

containing the text “mkde,” then Pervasive PSQL is running. If
you do not see this line, then you need to be logged into the root
account and start the database engine by entering
/etc/init.d/psql start

You can now be certain that the server engine is installed and
running.
5 The next step is to ensure that the server engine is accepting
remote communication requests.
In PCC, ensure that the remote database engine is configured to
accept remote requests. If you are having difficulty accessing a
Windows 32-bit server engine remotely, then you must check the
setting at the server itself. You must have administrative
permission on the server (or membership in the
Pervasive_Admin group) in order to do so. In PCC, right-click
on the server, then click Properties. Click Access and ensure that
Accept Remote Request is selected.
You can now rule out the possibility the server is not accepting
remote requests.
6 Note: If your application uses pure Btrieve access only, without
ODBC, then skip this step.
If everything checks out so far, but you still cannot get to the data
you want to access, make sure a server DSN has been set up for
your target data. Using PCC, expand the Databases node for that
server and inspect the databases that are present. Make sure one
of the databases represents the data you want to access. If so, then
a server DSN has been created for your data.

9-5
Basic Troubleshooting

If you do not find the data you want to access, but you know it is
on the server, then most likely you need to set up a DSN for the
given data. You must have administrative rights on the server (or
be a member of the Pervasive_Admin group) to do so.
Follow the instructions in “Setting Up ODBC Database Access”
on page 2-15 to set up a DSN for existing data files.
You can now rule out the server DSN as the source of the
problem.
7 Note: If your application uses pure Btrieve access only, without
ODBC, then skip this step.
If you have performed all the steps above and you still cannot get
to your data, the next possibility is lack of a local client DSN for
the remote data.
PCC can access remote server DSNs using connections without
client DSNs. Many desktop applications, such as Microsoft Excel
and Microsoft Access, cannot do this. You must create a client
DSN on your local computer to provide access to the remote
server DSN. To create a client DSN, follow the instructions in
“Setting Up Client Access” on page 2-21. You must first make
sure that a server DSN exists on the server you want to access.
You can now rule out the client DSN as the source of the
problem.
8 The final task to perform is to ensure that your client and server
are communicating on the appropriate network protocols. By
default, Pervasive PSQL ships with all network protocols
enabled, so connection time may be slow as it tries all protocols,
but it should eventually connect. Some application vendors
disable the protocols that are not typically used by their
application(s).
First, determine what protocols ought to be used on your
network. If you have a Linux network or a 100% Microsoft
network, then your preferred protocol is TCP/IP.

9-6
 General Troubleshooting

Once you know what the protocol should be, you should ensure
that your server is using this protocol. You must have
administrative rights on the server operating system (or be a
member of Pervasive_Admin) to perform this task. In PCC,
right-click on the server name then click Properties. Click
Communication Protocols. Ensure that the correct protocol is
listed in the Supported Protocols list and that TCP/IP is selected.
Ensure that your client is using the same protocol. Using PCC,
right-click on Local Client then click Properties. Click
Communication Protocols and ensure that the correct protocol
is selected in the Supported Protocols list.
9 If you have performed all of the above tasks with no success at
accessing your data, refer to “Pervasive PSQL Resources and
Contacts” on page 10-1 for more ways to get help.

PCC runs slowly or hangs when retrieving large record

sets
If this problem occurs, try increasing the amount of memory
available to PCC during start up. The amount of memory you can
specify is limited by the physical memory installed on your machine.
You can specify a minimum and a maximum amount of memory.
For example, to specify a minimum and maximum of 256
megabytes, start PCC with the following command:
pcc.exe -vmargs -Xms256M -Xmx256M

The parameter -vmargs is required if you specify the other

parameters.
The parameter -Xms specifies the minimum amount of memory to
allocate to PCC. The parameter -Xmx specifies the maximum amount
of memory to allocate to PCC. If you specify the -Xms parameter, you
must also specify the -Xmx parameter.
See also the next topic, “PCC crashes when browsing a directory
structure using the File Open dialog or when adding an external
tool.”

9-7
Basic Troubleshooting

PCC crashes when browsing a directory structure using

the File Open dialog or when adding an external tool
This problem results from a conflict between multiple Java Runtime
Environments (JREs) installed on the your machine. If this problem
occurs, try starting PCC by specifying a JRE version equal to or
greater than JRE 1.5.0.
For example, the following command specifies JRE 1.5.0 and
involves an instance of Java without a console window:
pcc.exe -vm "e:\Program Files\Java\jre1.5.0\
bin\javaw.exe"

The -vm parameter is required if you specify the JRE. The full path to
javaw.exe must be enclosed by double quotes if the path contains
spaces.

Tip If your operating system permits shortcuts, you can create a

shortcut to PCC and specify the command in the shortcut.

Note that you can combine the parameters for this command with
those discussed in the previous troubleshooting topic. The -vm
parameter must be specified first. For example, you would start PCC
as follows:
pcc.exe -vm "e:\Program Files\Java\jre1.5.0\
bin\javaw.exe" -vmargs -Xms256M -Xmx256

9-8
 Error Messages from PCC

Error Messages from PCC

You may receive several different messages when attempting to create
or connect to databases in PCC. This section explains the likely
causes for some of the most common error messages:
„ “Can’t retrieve database names. You don’t have access rights for
the operation” on page 9-9
„ “Unable to connect to the specified remote server. Verify that all
of the communication components are loaded on the remote
server and that there are available sessions and try again” on page
9-10
„ “An error was encountered while connecting to the server” on
page 9-11
„ “Unknown configuration properties” on page 9-12

Can’t retrieve database names. You don’t have access

rights for the operation
This error may occur when you are attempting to create a new
database on the server. The most likely cause is that you are logged in
as an operating system user that has neither administrative rights in
the server operating system, nor membership in the
Pervasive_Admin group on the server. Another likely cause is that
you forgot to enter a user name and password.
Solution: Be sure to enter a user name and password for the remote
operating system. You must have administrative rights on the server
or be a member of the Pervasive_Admin group in order to create a
new database on the server. “Granting Administrative Rights for the
Database Engine” on page 2-8 explains how to set up the
Pervasive_Admin group.
For Windows 32-bit platforms, be sure that you are set up as a local
user on the system, not a network user. Network users have a domain
name and a back slash preceding the user name, such as
BOSTON\GILBERT. Be sure that the user who is a member of the
Administrators group or Pervasive_Admin group is a local user.

9-9
Basic Troubleshooting

If you have checked permissions and your user login does in fact
meet one of the criteria above, then you should also check to make
sure that you are logged into the correct network. You can verify
whether you are logged into the correct network by attempting to
read or write to a server that you are certain uses the target operating
system.

Unable to connect to the specified remote server. Verify

that all of the communication components are loaded on
the remote server and that there are available sessions
and try again
You may receive this error when attempting to register a new remote
server in PCC. There are several reasons you may receive this error:
1 You mis-typed the server name. The database client tried to
connect to a server that does not exist.
Solution: Double-check the name of the server, and make sure
you can see it in your Network Neighborhood, spelled exactly
how you entered it.
If you know the server exists but you can’t see it in your Network
Neighborhood, make sure that you are logged into the correct
network. Ask your network administrator for help.
2 The server user count has expired. If you have been using a
temporary license, you will get this message for connection
attempts after the license has expired.
Solution: Run License Administrator from the Pervasive group
on the Start menu to check the status of licenses installed on the
server. In the window that appears, you can see detailed status
information on each license that has been applied to your server.
If your license has expired, purchase a permanent license from
your reseller or from Pervasive Software.
3 There are no available sessions on the server. If you have a heavy
load of users on the server, or if you have configured the server
with a small number of sessions, you may receive this error.

9-10
 Error Messages from PCC

Solution: Run Monitor from the Pervasive group on the Start

menu to check the usage of sessions available on the server. In
Monitor, select Options Connect and connect to the server in
question. Then choose MicroKernel Communications. In the
window that appears, find Total Remote Sessions. If the Peak
value and the Maximum value are the same, then it is likely that
you have run out of sessions.
4 The remote database server is not running.
Solution: Make sure that the remote database engine is running,
or ask your network administrator to do so.
5 The remote database server is not accepting client requests.
Solution: Set the properties to ensure that the remote database
engine is configured to accept remote requests. You must have
administrative permission on the server (or membership in the
Pervasive_Admin group) in order to do so. In PCC, right-click
on the server name in Pervasive PSQL Explorer, then click
Properties. Click Access and ensure that the Accept Remote
Request option is selected.

An error was encountered while connecting to the server

The most likely cause of this error is using the wrong operating
system user name or password in an attempt to connect to the server.
Other possible causes include:
„ The operating system may be expecting the user to change his/
her password on the first logon. This situation occurs if, in the
User Manager, you have selected the User Must Change
Password at Next Logon checkbox.
„ If the user is a member of another group with lesser permissions,
the lesser permissions will override the greater permissions. A
user always has the most restrictive permissions of any group to
which the user belongs.
Solution: Double-check the spelling of the user name and the
password. Make sure the user and password have been set up on the
remote server operating system.
Inspect the user’s account information on the server. Make sure the
operating system is not expecting the user’s password to be changed

9-11
Basic Troubleshooting

at the next logon. Make sure the user is not also a member of a group
that has restricted permissions.
For Windows 32-bit platforms, be sure that the user is set up as a
local user on the system, not a network user. Network users have a
domain name and a back slash preceding the user name, such as
BOSTON\GILBERT. Be sure that the user who is a member of the
Administrators group or Pervasive_Admin group is a local user.

Unknown configuration properties

It is possible, but unlikely, that PCC may retrieve configuration
properties from the database engine that are invalid. Please contact
Pervasive Customer Support to report such error conditions. See
“Pervasive PSQL Resources and Contacts” on page 10-1.

9-12
 Frequently Asked Questions

Frequently Asked Questions

This section answers some of the questions that customers ask most
frequently. A list of the questions is provided below:

Installation
„ Will I lose my data files if I uninstall my existing version of the
product, or install a new version?
„ Why do I not see in PCC Pervasive PSQL Explorer the “plug-in”
product that I just installed or upgraded?
„ What type of client install should I do?
„ How can I be sure what service pack level of client I am running?
„ Is Pervasive PSQL supported on a Terminal Server?
„ Can I install Pervasive PSQL in a Failover environment? or
„ Can I install Pervasive PSQL in a Clustering environment?
„ Can I install Pervasive PSQL in a Load Balancing environment?
„ Can I install Pervasive PSQL on a server running Btrieve v6.x or
earlier?
„ How do I keep my Workgroup Engine from starting up
automatically when I reboot?

PCC
„ How do I start PCC on Linux?

Security
„ When do I login using an operating system user and password,
and when do I login using a database user and password?
„ Why do I get a “log in failed” message when I have a
Pervasive_Admin group defined or I have administrator rights?

User Counts
„ How do I apply a User Count Upgrade?
„ How does the Workgroup engine keep track of how many people
are accessing the data? If people access the data with two engines
at the same time, what happens?

9-13
Basic Troubleshooting

„ Does the Workgroup engine use concurrent or per-seat

licensing?

Networking
„ How do I know which protocol I am using for communication?
I can see other systems in Network Neighborhood but I can’t get
to my data.

Difficulty Accessing Data

„ I upgraded from Btrieve v6.x or earlier to Pervasive PSQL
v10.10. Now I get error messages telling me that a file is
inaccessible when everybody else can get to it. What’s wrong?
„ I have files sitting on the server that are shared and yet Pervasive
PSQL cannot read them. What’s wrong?
„ I am using SQL queries to create a definition for an old table. The
resulting record size is off. Why?
„ I want to convert my data file version from 9 back to file format
version 8, 7, or 6. How do I do this?

ODBC and DDFs

„ How can I tell if I can use ODBC to access my data files?
„ How can a hard-coded filepath in a DDF be changed?
„ What is the best way to ensure that my data dictionaries (DDFs)
are safe?
„ How can I tell whether I have non-standard DDFs?
„ Can I mix and match DDFs from different databases?
„ What happened to DDF Sniffer?
„ I have two similar Btrieve files, and I created a DDF for the first
one. Since they are similar, can I use the same DDF on the second
Btrieve file?
„ I have owner names set on my Btrieve files. After I created a
DSN, I cannot open the files using ODBC. What’s wrong?
„ Is there a client side requester for the SRDE?
„ Is ODBC the only method of access for Pervasive PSQL?
„ Is there a single database file housing all the data, data
definitions, stored procedures, security, table relationships, and
so on as in some other products?

9-14
 Frequently Asked Questions

„ Does the SQL engine (SRDE) have scheduler capabilities to run

stored procedures or other types of scripts designed to access and
affect data?

Upgrading from Btrieve 6.15

„ Is there a tool that replaces Xtrieve?
„ Upgrading and Migration

Upgrading and Migration

„ Where can I find information on migration from earlier product
versions to Pervasive PSQL v10.10? Where can I find migration
and compatibility information?
„ When I create a table using an existing Btrieve file, the wizard
displays fewer columns than there are in the Btrieve file. What’s
wrong?

DEMODATA Sample Database

How do I restore DEMODATA to its installation defaults?
1 Start PCC if it is not already running. (See “Starting PCC on
Windows” on page 3-3.)
2 From the PCC Main menu, click File New SQL Document or
click . (see “To start SQL Editor for a new SQL query” on
page 6-13.)
The Select Database dialog appears.

3 Click DEMODATA in the list then click OK.

SQL Editor appears as a new tab view in PCC.

9-15
Basic Troubleshooting

4 Click File Open.

5 Navigate to the location of the DEMODATA.sql file then click
Open.
For default locations of Pervasive PSQL files, see “Where are the
Pervasive PSQL files installed?” on page 7-2 in Getting Started
With Pervasive PSQL.
6 Click SQL Execute All SQL Statements, press F10, or click
.
DEMODATA.sql deletes the existing tables then re-creates them
using the installation defaults. The restored tables are empty (no
data).
Any new tables that you have created as part of DEMODATA are
not affected.

9-16
 Frequently Asked Questions

7 Use the Bulk Data Utility (BDU) to populate the tables with data
(see “bdu” on page 8-7).
a. Open a command prompt.
b. Go to the "restore" directory for DEMODATA. An "SDF"
file exists for each table in DEMODATA.
c. For each SDF file, use BDU to load the data into the table.
For example, to load the data for the "Billing" table use the
following command. The comma is the field delimiter in
the file.
bdu demodata billing billing.sdf -t ,

Note The "-t ," parameter is required.

The BDU utility returns how many rows of data were

loaded.

Miscellaneous
„ I dumped Btrieve records to a file and now I can’t read the file.
What happened?
„ Does Pervasive PSQL take advantage of multiple processors?
„ How do I run Pervasive PSQL in trace mode?
„ Does garbage collection occur in the data files and indexes? For
example, is space from deleted records recovered or reused?
„ Is database shadowing available, allowing a complete up-to-date
second copy of the database to exist on another drive or
machine?
„ What is the mechanism that allows the database to be backed up
online? What happens if the server goes down in the middle of a
backup with many open transactions?

9-17
Basic Troubleshooting

Installation Frequently asked questions about installation.

Will I lose my data files if I uninstall my existing version of the

product, or install a new version?
When you uninstall Pervasive PSQL or install a new version of
Pervasive PSQL, your data files and DDFs are never affected. Even
when Pervasive System Analyzer archives Pervasive PSQL files, or
even if you have your data files in the same directory as Pervasive
PSQL files, your data files are not affected.

Why do I not see in PCC Pervasive PSQL Explorer the “plug-in”

product that I just installed or upgraded?
See “Situations Requiring That You Clear PCC Cache” on page 3-6.

What type of client install should I do?

If you are not sure, always select complete. This option performs a
standard installation, which makes it easier to troubleshoot if
problems occur.

How can I be sure what service pack level of client I am

running?
If you are using Pervasive PSQL v10.10, start Monitor or
Maintenance, choose Help About from the menu, and check the
Build Level.

Is Pervasive PSQL supported on a Terminal Server?

Support for both the Server and Workgroup engines on Terminal
Server has been available since Pervasive.SQL 2000i, SP 4.
Pervasive.SQL 2000i, SP 3 provided support for the Server engine.
Pervasive.SQL 2000i, SP 2 provided supports only for the client
software.

Can I install Pervasive PSQL in a Failover environment? or

Can I install Pervasive PSQL in a Clustering environment?

Pervasive.SQL 2000i SP3 or later can be installed into a cluster
environment. Earlier versions of Pervasive PSQL are not supported
in a Failover or Clustered environment. Linux clusters are not
supported at this time.

9-18
 Frequently Asked Questions

Can I install Pervasive PSQL in a Load Balancing environment?

That is not supported at this time.

Can I install Pervasive PSQL on a server running Btrieve v6.x or

earlier?
No, you cannot run Pervasive PSQL and Btrieve 6.x on the same
computer at the same time.

How do I keep my Workgroup Engine from starting up

automatically when I reboot?
You must remove it from the Startup group under Start
Programs.
On Windows 32-bit platforms, the contents of this group are located
at:
c:\Documents and Settings\user\start menu\programs\startup
User can be replaced by “All Users” or any user, as appropriate.

PCC frequently asked questions about PCC.

How do I start PCC on Linux?

Certain requirements must be met before you can start PCC on
Linux. See “Starting PCC On Linux” on page 3-4.

Security frequently asked questions about security.

When do I login using an operating system user and password,

and when do I login using a database user and password?
This may seem confusing at first, but in fact there is only one rule:
use a database login only after you have already successfully
connected to the server and are attempting to access a database
directly. Up until this point, you should use an operating system
login.
For example, if you run Monitor or Configuration to work with a
remote server engine, you are prompted for a password. In both
cases, you must supply a user name and password for an operating
system account that has administrative permissions on the remote
system, or an account that is a member of Pervasive_Admin. This
applies also when you are creating a new database.

9-19
Basic Troubleshooting

Once you start to work with the data itself, then you must supply a
database user and password, if prompted. If database security is
turned off, then you would never need a database user name or
password. In this case, you would only need an operating system user
and password to perform administrative tasks, as noted in the
preceding paragraph.

Why do I get a “log in failed” message when I have a

Pervasive_Admin group defined or I have administrator rights?
The settings for the Pervasive PSQL services can affect whether or
not you have permission to log in to the machine where the database
engine is running. The settings apply whether or not you use a
Pervasive_Admin group. If you change the Log on as setting for a
Pervasive PSQL service to This account, you must change the user
rights policy Act as part of the operating system for the account.
Otherwise, remote log in fails.
For example, the Monitoring utility requires that you log in to the
operating system on the machine where the database engine is
running. You will receive a message that log in failed if the account
specified for This account cannot act as part of the operating system.
Note that even the Administrator account requires that you set the
user rights policy for Act as part of the operating system.
See “Services Settings and Log In Authority” on page 2-10 for a
complete discussion and the steps to change the user rights policy.

User Counts frequently asked questions about user counts.

How do I apply a User Count Upgrade?

Refer to the tasks discussed in the chapter “License Administrator”
on page 4-1.

How does the Workgroup engine keep track of how many

people are accessing the data? If people access the data with
two engines at the same time, what happens?
The Workgroup engine keeps track of users just as the Server engine
does. Each license specifies a user count. A user count allows the
specified number of computers to connect to the Pervasive database
engine concurrently. Users are counted by network address. The IP
address is used for TCP/IP; the IPX address is used for SPX/IPX.

9-20
 Frequently Asked Questions

Each workstation that accesses Pervasive PSQL as a client counts as

one user. Multiple applications on a single client computer are
counted as one user, not separate users. Each Terminal Server session
also counts as one user.
Collectively, all applications that access the database engine, use the
same network protocol and address, and run on the same machine
as the database engine count as one user. If one application uses
TCP/IP and another application uses SPX/IPX, two licenses are
counted if both applications run on the same machine. Similarly, if a
machine contains multiple network cards, a user would be counted
for each unique network address being used.
The Pervasive PSQL Workgroup engine includes a trail license. The
license for the Workgroup engine cannot be deleted.
Only one engine is ever permitted to access data files at a time. The
second engine to try to open the files gets locked out, because the
engines open the data files in exclusive mode (non-file sharing) so
that corruption cannot occur.

Does the Workgroup engine use concurrent or per-seat

licensing?
Concurrent. Refer to “User Count” on page 4-3.

9-21
Basic Troubleshooting

Networking frequently asked questions about networking.

How do I know which protocol I am using for communication?

I can see other systems in Network Neighborhood but I can’t
get to my data.
Start Pervasive System Analyzer from Pervasive group in the Start
menu. In the Welcome screen that appears, click Next. In the
following screen, check the box Test Network Communications and
make sure all the other boxes are not checked. Click Next. In the
following screen, cancel the selected protocols that you do not want
to test. Click Browse to select the drive that you have mapped to the
installation directory on the server. You must have a mapped drive;
UNC names are not supported. Click Next to run the network tests.
The results window tells you if there are any significant problems
with your networking.

Difficulty Frequently asked questions about accessing data.

Accessing Data
I upgraded from Btrieve v6.x or earlier to Pervasive PSQL
v10.10. Now I get error messages telling me that a file is
inaccessible when everybody else can get to it. What’s wrong?
Use Pervasive System Analyzer to be sure that all components from
previous versions of Btrieve or Pervasive PSQL have been archived.
Then, make sure your configuration settings are correct. Find the file
pvsw.log and check for error messages indicating a status code 8505
or 8517. These status codes indicate that attempts were made to use
a local Workgroup engine to read the data files. Start PCC (see
“Starting PCC on Windows” on page 3-3 in Pervasive PSQL User's
Guide). Right-click on Local Client then click Properties. Click
Access. Ensure that the option Use Local MicroKernel Engine is not
check marked and that Use Remote MicroKernel Engine is check
marked.

I have files sitting on the server that are shared and yet
Pervasive PSQL cannot read them. What’s wrong?
How are the files shared? Pervasive does not support mapping a drive
letter using Redirected mapping under Microsoft, or using the
hidden Admin share (C$) under Windows 32-bit platforms.
Make sure that users have appropriate operating system login
credentials to access the file server.

9-22
 Frequently Asked Questions

Run Pervasive System Analyzer and choose the Network

Communications Test to be sure that you have proper connectivity.

I am using SQL queries to create a definition for an old table.

The resulting record size is off. Why?
Starting with Pervasive.SQL 2000, fields that allow null values have
an additional byte defined at the start of the field. This byte is the null
indicator byte. You can work around this in one of two ways:
If you are using SQL statements to create a new table definition, enter
the statement SET TRUENULLCREATE=OFF. For the remainder of
your current session, any tables that you create will use the old record
structure without the extra byte for each nullable column.
If you do not wish to use SQL statements, you can get the field sizes
to align properly by creating all columns as not nullable.

I want to convert my data file version from 9 back to file format

version 8, 7, or 6. How do I do this?
If the files you wish to convert are serviced by a remote Server or
Workgroup engine, you must have Administrator permissions on
the remote system in order to perform these tasks. You must also
have a network drive mapped to the remote data files.
In PCC, right-click the server name where the data files are located
then click Properties. Click Compatibility and set Create File
Version to the file version to which you want to convert. Click OK.
Click Yes to restart the engines. These changes result in new files
created to be in the version selected.
Run the Maintenance utility from the Pervasive group on the Start
menu. Within Maintenance, click Options File Information
Editor. Click Load Information and choose the data file that you
want to convert. Click Create and specify the name of the new, empty
data file you want to create with the older version format. Click OK
to create the file. Close the File Information Editor window, but do
not exit Btrieve Maintenance Utility.
From the menu, select Data Copy. Enter the name of the source
data file and the name of the target data file (your newly created file
with the older version file format). Click Execute to copy the records
into the older version file. After the copying has finished, if you need
the new data file to have the same name as it did previously, save your

9-23
Basic Troubleshooting

original data file with a different name, then save your new file using
the original file name.

ODBC and Frequently asked questions about ODBC and dictionary files.
DDFs
How can I tell if I can use ODBC to access my data files?
There are several ways to find out. First, look for .DDF files where the
data files are located. If you see them, then most likely you can access
the database using ODBC. Because it is possible to have DDF files
located in a different directory, you should also use PCC to
determine whether a database has been created for the data files you
want to access. Finally, you can ask your application vendor whether
their application uses ODBC to access the data files.

How can a hard-coded filepath in a DDF be changed?

In PCC, right click on the database to which the table belongs, then
click Properties. Cl ick Directories. Change the value for Dictionary
Location.
It may appear that the path has not changed. To confirm the change,
open the X$File system table and look at the Xf$Loc field for the
given user table. If you cannot see the system tables in PCC, expand
System Objects.
You can also use the ALTER TABLE USING statement in SQL to
change the data file used by a particular table. Refer to SQL Engine
Reference for further information.

What is the best way to ensure that my data dictionaries (DDFs)

are safe?
Always keep a backup copy of your DDFs. Anytime you make
changes to the runtime DDFs, be sure to make a backup copy of the
DDFs before making changes. If you are turning on database security
for the first time, you should make a backup copy of the dictionaries
without security, and a backup copy with security.

How can I tell whether I have non-standard DDFs?

If you can edit your DDFs with a Btrieve utility, it means that you do
not have standard dictionary files. A standard dictionary file does
not permit direct Btrieve access. This lock out is a safety feature that
ensures only the SRDE can write to the dictionary. DDFs are very

9-24
 Frequently Asked Questions

special files that must remain synchronized with each other and with
the data files at all times.
Standard dictionaries do not have case sensitive table names or field
names. That is, the column definitions for column Xf$Name in
file.ddf and column Xe$Name in field.ddf have the Case flag set,
meaning the values are case insensitive.
DDFs are Btrieve files and thus can be opened and viewed (not
updated) using the Function Executor. This is one way to confirm
the contents of file.ddf or field.ddf.
On some non-standard dictionaries, the DDFs file.ddf, field.ddf,
and/or index.ddf do not exist. Such dictionaries do not work with
our products. For example, if you see a file called x$file.ddf, instead
of file.ddf, you can assume your DDFs are non-standard.
Non-standard DDFs are unlikely to work properly with Pervasive
PSQL Control Center or the relational engine.

Can I mix and match DDFs from different databases?

A complete set of DDF files must be considered a unit. No DDF file
from one database may be intermixed with DDFs from a different
database.

What happened to DDF Sniffer?

DDF Sniffer was added to the Pervasive product line with the
acquisition of Smithware in 1998. It is no longer available as a
separate product. Its functionality has since been largely replaced by
the Pervasive PSQL Control Center and DDF Builder.

I have two similar Btrieve files, and I created a DDF for the first
one. Since they are similar, can I use the same DDF on the
second Btrieve file?
The answer depends on how similar the files are. If the two files differ
only in the number of records, you can use the same DDF file. If there
are any differences at all in the number, order, names, or types of
fields or indexes, you cannot use the same DDF. In other words, you
can only use the same DDF if the record structure of the two files is
identical.

9-25
Basic Troubleshooting

I have owner names set on my Btrieve files. After I created a

DSN, I cannot open the files using ODBC. What’s wrong?
If Btrieve files have owner names on them, you must use database
security for ODBC access. Turn on database security in PCC. See “To
turn on security using Pervasive PSQL Explorer” on page 3-40 and
“Owner Names and Security” on page 7-10 in Advanced Operations
Guide.

Caution Do not forget the Master user password. You cannot

turn off security or perform administrative tasks within the
database without it. You may want to make a backup copy of
your DDFs before turning security on, in case you forget the
password.

Next, you must grant the Master user access to the data files that have
owner names defined. You can grant the access by issuing this SQL
statement for each table that has an owner name:
GRANT ALL ON my_table ‘ownername’ TO Master

When you enter the statement, substitute the actual name of your
table and the appropriate owner name for that table, as indicated
above. Remember that each data file corresponds to an ODBC table.
If you don’t know which table corresponds to which data file, see use
PCC to find out. Right-click on the table in PCC then click
Properties. Click Information in the tree. The File Name field shows
you the file that is referenced by that table definition.
If security is important, then you must create users and assign
permissions for all users expected to access the database. You do this
by using the CREATE GROUP and GRANT statements in SQL. You
can also add users and groups with PCC. See “Users and Groups” on
page 7-3 in Advanced Operations Guide.
If security is not important to you, you can avoid creating many users
and assigning privileges by granting access to PUBLIC, which means
anyone on your network can access the data. You can use this
statement:
GRANT ALL ON my_table ‘ownername’ TO PUBLIC

9-26
 Frequently Asked Questions

Is there a client side requester for the SRDE?

There is no DOS requester support for SQL applications, but the
Pervasive PSQL client software for Windows includes ODBC client
components allowing you to connect to a remote SRDE server
engine.

Is ODBC the only method of access for Pervasive PSQL?

Definitely not! In addition to ODBC and the time-tested Btrieve API,
you can also develop applications using our OLE DB provider, our
JDBC driver, our pure Java interface, or our ActiveX controls.

Is there a single database file housing all the data, data

definitions, stored procedures, security, table relationships,
and so on as in some other products?
No. Pervasive PSQL stores data in separate files, one file per
relational table definition. The meta data, such as data definitions,
user/group definitions, and so on, are stored in a set of DDF files,
where each file ends in the extension “.ddf.”

Does the SQL engine (SRDE) have scheduler capabilities to run

stored procedures or other types of scripts designed to access
and affect data?
The SRDE does not have a scheduler.

Upgrading from Frequently asked questions about Btrieve 6.15.

Btrieve 6.15
Is there a tool that replaces Xtrieve?
There is no direct replacement, but you should consider using
Crystal Reports for Btrieve as an excellent upgrade from Xtrieve for
reporting on and querying Btrieve data.

9-27
Basic Troubleshooting

Upgrading and Frequently asked questions about upgrading and migration.

Migration
When I create a table using an existing Btrieve file, the wizard
displays fewer columns than there are in the Btrieve file. What’s
wrong?
Btrieve files contain a limited amount of information about the
structure of the file. The table creation wizard can figure out some
field definitions using the indexes, but after the indexes are
exhausted, data segments may remain that contain more than one
actual field. The wizard has no way of interpreting the contents. You
must use your detailed knowledge of the record structure to split out
these fields and build a table definition that matches all the fields in
the record.
The procedure for this task is provided in Advanced Operations
Guide.

Where can I find information on migration from earlier product

versions to Pervasive PSQL v10.10? Where can I find migration
and compatibility information?
Getting Started With Pervasive PSQL contains an entire chapter that
provides detailed instructions on how to upgrade.
If your application uses Scalable SQL or ODBC, then you should
review the Application Migration Guide available on the web site.

Miscellaneous Frequently asked questions about miscellaneous topics.

I dumped Btrieve records to a file and now I can’t read the file.
What happened?
If you use the Btrieve Maintenance Utility to save/dump the records,
the resulting file contains the binary image of each record. Unless the
record consists entirely of character data, it may not be readable to
the human eye.
The only way that Pervasive PSQL can dump a record in ASCII
readable format, is by reading the DDFs to get a description of the
total contents of the record. Btrieve only has the record length, the
data type of indexes and length of the indexes. Btrieve does not have
information on how to interpret the entire contents of the record.

9-28
 Frequently Asked Questions

Does Pervasive PSQL take advantage of multiple processors?

Pervasive PSQL fully supports symmetric multiprocessing (SMP)
and multiple processors because it is multi-threaded and thread safe.
However, Pervasive PSQL does not take direct advantage of any call
specific for SMP and is not multiprocessor aware.
In an SMP environment, the operating system schedules available
threads on the available processors, including threads for Pervasive
PSQL. Since Pervasive PSQL is multi-threaded and thread safe, SMP
can yield a performance boost for up to four CPUs. No significant
advantage has been shown, however, to bypass the operating system
scheduling and use SMP-specific calls to become SMP aware. This is
because, in most cases, slowness occurs from disk I/O and not from
CPU use.

How do I run Pervasive PSQL in trace mode?

Server
You must have administrator privileges on the machine where the
engine is located that you want to run in debug mode.
1 Using PCC, right-click on the desired Server engine then click
Properties.
2 Click Debugging and set the value for Trace Operation to On.
3 Click OK.
You do not need to restart the engine.
See also “Trace Operation” on page 4-36 in Advanced Operations
Guide.

Note After tracing operations, you should turn off Trace

Operation, making sure to click Edit Apply when finished.
You will notice slower performance if you run Pervasive PSQL in
trace mode.

Windows Client
Run the PSA network connectivity tests to verify network
connectivity. See “Test Active Installation Tasks” on page 7-10. Also
refer to the Knowledge Base, available at the Pervasive Software
website, for information about particular issues.

9-29
Basic Troubleshooting

In addition, client tracing is available for troubleshooting certain

types of low-level problems. Generally, low-level tracing is not
required, so this type of tracing is intended for use by trained
support staff. Your product vendor or Pervasive Software Support
will explain how to conduct low-level client tracing.

Does garbage collection occur in the data files and indexes?

For example, is space from deleted records recovered or
reused?
Yes, space from deleted records is re-used on subsequent inserts.
Space in files is never de-allocated back to disk. If index balancing is
turned on, unused space in index pages is also re-used. See “Rebuild
Utility Concepts” on page 14-2 in Advanced Operations Guide.

Is database shadowing available, allowing a complete up-to-

date second copy of the database to exist on another drive or
machine?
Pervasive PSQL does not contain specific functionality for this, but
many customers have successfully used hardware mirrored drive
arrays and solutions like Vinca’s (now acquired by Legato) Standby
Server to provide this functionality. Pervasive.SQL 2000i SP3 and
later supports Pervasive’s data replication product, Pervasive
DataExchange.

What is the mechanism that allows the database to be backed

up online? What happens if the server goes down in the middle
of a backup with many open transactions?
Continuous Operations allows you to put a set of data files in a
special “safe mode” so that they can be safely backed up while in use.
While data files are in Continuous Operations mode, they are not
modified, and special delta files store the results of any database
operations. After the backup is complete, the data files must be
removed from Continuous Operations mode, at which time the
changes stored in the delta files are rolled into the live files.
If the server goes down while files are in continuous operations
mode, the next time the data file is accessed, the database engine
detects the existing delta file and rolls in the changes at that time.
You can put data files into Continuous Operations mode by using
the BUTIL -STARTBU command or Maintenance utility described
in Advanced Operations Guide.

9-30
 chapter

Pervasive PSQL Resources

and Contacts 10
A Guide to Pervasive PSQL Customer Information Resources

Pervasive Software strives to ensure that your experience with

Pervasive PSQL is successful. This chapter describes the resources
and information available to you as a valued customer of Pervasive
Software.
The following variety of resources can help you get answers to your
questions, troubleshoot problems, and interact with the Pervasive
team as well as with other customers.
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.
The following table lists a variety of resources to help you get answers
to your questions, troubleshoot problems, and interact with the
Pervasive team as well as with other customers.

10-1
Pervasive PSQL Resources and Contacts

Table 10-1 Pervasive Software Resources and Contact Information

Resource Description Contact Information

Pervasive Software Web The site is a great source for everything http://www.pervasive.com
site Pervasive PSQL

Pervasive Resource The Resource Center provides a quick http://www.pervasive.com/

Center and easy way to access Pervasive resources/
resources, such as free trials, data sheets,
white papers, and so forth

FTP Site The FTP site contains downloadable ftp://ftp.pervasive.com/support/

updates and patches to our product
offerings, among other items

Newsgroup The Pervasive PSQL newsgroup is news://comp.databases.btrieve.

managed by the end-user community,
posting and answering questions as they
wish.

Technical Support The Support site contains product support http://www.pervasive.com/support/

assistance and support offerings

Pervasive PSQL The Knowledge Base is a searchable http://www.pervasive.com/support/

Knowledge Base database of information on the products

Pervasive Library The current documentation and technical http://www.pervasive.com/library

papers online

Online Documentation Download the latest versions of Pervasive http://www.pervasive.com/support/

PSQL product manuals technical/online_manuals.asp

The complete suite of online Access installed documentation

documentation can be installed with the from the Pervasive program on the
product Start menu or from the installation
media

Printed Documentation Printed versions of each manual are http://www.pervasive.com/

available for purchase separately, or you ecommerce/Scripts/default.asp
may purchase the entire documentation
set. Send e-mail to
[email protected]

Or telephone 1 800 287 4383.

Telephone Contacts Pervasive Software has offices worldwide http://www.pervasive.com/

to help you company/contact

E-Mail Contacts Pervasive Software welcomes your

comments, suggestions and requests for
assistance via e-mail.

10-2
Thirty-Day Free Note that your purchase of Pervasive products entitles you to 30 days
Technical of free technical support for installation and configuration
Support problems. The free technical support is limited to two support issues
(referred to as “tickets”) during the 30 days.

10-3
Pervasive PSQL Resources and Contacts

10-4
Index
A testing transactional interface 7-11
Bulk Data Utility 8-7
Access conflict 9-20
Bulk Data utility
Access methods 9-27
constraints 8-10
Access rights
error logging 8-10
cannot perform the operation 9-9
examples 8-11
problems due to lack of O/S rights 9-4
BUTIL
Access to database
Linux and 8-17
setting up 2-15
ACS
viewing 3-28 C
Active Directory Cache
create Pervasive_Admin group on domain clearing 3-6
controller 2-11 Case comparisons
Admin share not supported 9-22 in Table Editor 5-7
Administrative rights 2-8 Cell
for Active Directory 2-9 defined 1-7
granting 2-8 Changing file path in DDF 9-24
troubleshooting 9-20 Client
user rights policy 2-11 definition of 1-4
Administrator DSN 2-15
login 2-14 DSN setup 2-22, 2-25
Administrator user installation 9-18
fast user switching 2-37 password utility for use with 8-38
Autostart setting up database access 2-21
keeping Workgroup engine from autostarting 9- testing connectivity to database engine 7-10
19 troubleshooting network protocols 9-6
Available sessions Client DSN
error in PCC if none available 9-10 on Linux workstation 2-25
set up with ODBC Administrator 2-22
B Clilcadm utility 8-19
Clustering 9-18
Backup
Collate
online 9-30
in Table Editor 5-8
Bcfg utility 8-6
Collating sequence
Bdu utility 8-7
setting for column in Table Editor 5-21
Bmon utility 8-14
Column
Bound database
defined 1-6
properties for database 3-20
Column name
Btadmin utility 8-15
in Table Editor 5-7
Btrieve
Columns
and terminology 1-10
allowing index duplicates in Table Editor 5-35
owner names 9-26

Index 1
 arranging order of index segment in Table Editor O/S rights required 9-4
5-34 setting preferences
deleting in Table Editor 5-16 external tools 3-12
deleting index in Table Editor 5-30 general 2-35, 3-9, 6-15
deleting index segment in Table Editor 5-33 Grid 3-9, 3-10
inserting in Table Editor 5-15 SQL Editor 3-10
inserting index segment in Table Editor 5-31 Table Editor 3-10
modifying index in Table Editor 5-30 Text window 3-10
modifying index segment in Table Editor 5-32 window views 3-10
naming in Table Editor 5-17 setting preferences for Data Grid 3-10
selecting in Table Editor 5-16 setting preferences for external tools 3-12
setting case in Table Editor 5-20 Conflict, access 9-20
setting collating sequence in Table Editor 5-21 Connection strings
setting data type in Table Editor 5-17 ’ServerDSN’ or ’DBQ’ not found in 9-2
setting default in Table Editor 5-22 Continuous Operations
setting for nulls in Table Editor 5-20 behavior after server failure 9-30
setting index in Table Editor 5-24 Continuous operations
setting precision in Table Editor 5-19 restriction for files with same name 5-12
setting primary key in Table Editor 5-23 Control Center. See PCC
setting scale in Table Editor 5-19 Convert data files to older file format 9-23
setting size in Table Editor 5-18 Create database 3-25
specifying index as modifiable in Table Editor 5- Create Database Wizard
36 creating a Client DSN 2-21
specifying sort order for index in Table Editor 5- creating an Engine DSN on Windows 2-18
35 CREATE GROUP 9-26
viewing those defined for a table 3-30 CREATE USER 9-26
Columns page
in Table Editor 5-3 D
interface in Table Editor 5-6 Data
Command-line files where stored 9-27
utility to execute SQL statements from 8-31 importing 3-31
utility to rebuild data files from 8-41 location of files for database 3-20
Communication Data compression
testing network connectivity 7-10 viewing 3-28
Configuration Data definitions
bti.ini 2-19 where stored 9-27
database code page 3-18 Data directories for database 3-20
defined 3-50 Data files
engine DSN 2-19 convert to older file format 9-23
object properties in PCC 3-50 not affected by install/uninstall 9-18
PCC connection encoding 3-19 rebuilding with utility 8-41
properties for database 3-17 re-use of space 9-30
properties for database engine 3-16 sharing of DDFs 9-25
properties for services 3-14 Data Grid
properties for table 3-28 setting preferences 3-10
server Data replication 9-30

2 Index
Data source name registering in PCC 3-15
engine DSN 2-19 running as service in PCC 3-13
Data table 3-28 services dependent on 2-2
Data types setting services properties 3-14
Columns page in Table Editor 5-3 setting startup policy 3-14
Database start and stop on Windows 2-3, 2-4
access 2-15, 2-18 starting and stopping on Linux 2-7
access for client workstation 2-21 starting or stopping 3-13
as object in PCC 3-17 starting server 2-2
bound 3-20 stopping 2-2
cannot retrieve names error 9-9 SWT no more handles error on Linux 3-5
code page properties 3-18 unable to connect to error on Linux 3-5
concepts 1-2 Database Management System
creating 3-25 defined 1-3
data directories 3-20 functions of 1-3
defined 1-2, 1-7 Database Workgroup Engine
dictionary location 3-20 start and stop on Windows 2-5
error 7039 when creating 3-25 DataExchange
importing data 8-7 displaying in PCC after installation 3-6
integrity enforced 3-21 displaying in PCC after upgrading 3-6
logging out from in PCC 3-17 Dbmaint utility 2-19, 8-20
mirroring 9-30 DBMS. See Database Management System
PCC connection encoding property 3-19 DBQ not found error 9-2
security 3-38 DDF location for database 3-20
logging in as an administrator 2-14 DDFs
security vs OS security 9-19 changing file path 9-24
set up access for Workstation or Workgroup creating for old data 9-23
engine 2-18 detecting non-standard 9-24
set up access on Linux 2-19 for ODBC access 2-18
set up access on Windows 2-18 keeping safe 9-24
setting properties for 3-17 mixing among databases 9-25
setting up on client 2-21 path viewing 3-28
starting engine 2-2 sharing among data files 9-25
stopping engine 2-2 Default
structures 1-6 object in Table Editor 5-8
structures and terms 1-6 Definitions
test ODBC connection 8-25 client 1-4
testing client connectivity to 7-10 requester 1-4
Database encoding 3-18 Delete
Database engine DSN 2-35
as object in PCC 3-15 Deleted records, re-use of disk space 9-30
java.lang.UnsatisfiedLinkError error on Linux 3- Delimited data
5 loading into a database 8-7
logging in to in PCC 3-16 DEMODATA
logging out from in PCC 3-15 recovering default tables 9-15
reconnecting to in PCC 3-16 restoring to installation defaults 9-15

Index 3
Dependency setting properties for 3-16
of services of database engine 2-2 setting services properties 3-14
Detect non-standard DDFs 9-24 setting startup policy 3-14
Determining starting or stopping 3-13
network protocol in use 9-22 stopping Workgroup under fast user switching 2-
service pack level 9-18 38
Dictionary testing client connectivity to 7-10
location of files for database 3-20 tray icon with fast user switching 2-38
Dictionary path Error 1114 9-2
error 7039 when creating a database 3-25 Error 7039 when creating a database 3-25
viewing 3-28 Error was encountered message 9-11
Disk space Events
re-use of 9-30 scheduling 9-27
Documentation 1-13 Expired licenses
Online help 1-14 hiding 4-15
DSN Export
client 2-15, 2-22 data from table 3-32
Linux client 2-25 files
client DSN needed for many applications 9-6 cannot read file 9-28
concepts 2-15 Export table schema 3-33
engine 2-15, 2-19 External tools
on a Linux server 2-19 adding to PCC 3-12
File DSN not supported 2-15, 2-22
recreating 2-17, 2-35 F
removing 2-35 Failover 9-18
test connection to database 8-25 FAQ. See Frequently asked questions
Dsnadd utility 2-25, 8-23 Fast user switching 2-37
Dump file running Workgroup engine 2-37
cannot read it 9-28 tray icon with 2-38
Duplicate pointers types of users for 2-37
viewing number of 3-28 Field
defined 1-6
E Field.ddf 9-24
Encoding File
database code page 3-18 viewing file name associated with a table 3-30
Engine viewing location of table 3-28
as object in PCC 3-15 File DSN not supported 2-15, 2-22
components File format
different version than client 9-2 converting data to older 9-23
DSN 2-15 File path
DSN setup 2-19 changing in DDF 9-24
logging in to in PCC 3-16 File system security 1-15, 2-29
logging out from in PCC 3-15 File version
reconnecting to in PCC 3-16 viewing 3-28
registering in PCC 3-15 File.ddf 9-24
running as service in PCC 3-13 Files with same name

4 Index
 restriction for 5-12 I
Find non-standard DDFs 9-24
Identifying
Finding
service pack level 9-18
service pack level 9-18
Import Data Wizard
Foreign key
restrictions 3-31
adding in Table Editor 5-37
Importing
deleting in Table Editor 5-39
data 3-31
modifying in Table Editor 5-39
data into a database 8-7
Foreign keys page
data into table 3-31
in Table Editor 5-4
IN DICTIONARY
Freespace threshold
clause in exporting table schema 3-33
viewing 3-28
Increasing user count licenses 9-20
Frequently asked questions 9-13
Index
defined 1-7
G Index balancing
Garbage collection viewing 3-28
on disk 9-30 Index.ddf 9-24
GRANT 9-26 Indexes
Granting allowing duplicates in Table Editor 5-35
administrative rights 2-8 arranging order of segment in Table Editor 5-34
for "this account" 2-10 creating unique 5-26
on Linux 2-13 deleting in Table Editor 5-30
on Windows 2000 2-10 deleting segment in Table Editor 5-33
Grid inserting segment in Table Editor 5-31
adding rows of data 6-22 modifying in Table Editor 5-30
changing data in 6-21 modifying segment in Table Editor 5-32
copying data from 6-25 partial 5-28
deleting rows of data 6-23 setting in Table Editor 5-24
in PCC 3-8 specifying as modifiable in Table Editor 5-36
refreshing data in 6-24 specifying sort order in Table Editor 5-35
setting preferences 3-9, 3-10 viewing number of 3-28
using scalar functions 6-24 viewing those defined for a table 3-30
view in SQL Editor 6-4 Indexes page
Group in Table Editor 5-4
as object in PCC 3-38 Installation
assign user to 3-46 client FAQ 9-18
data files not affected by 9-18
H testing with PSA 7-2
How Interfaces
to apply a user count upgrade 9-20 supported for programming 9-27
to grant a user administrative rights Intigrity enforced
for "this account" 2-10 properties for database 3-21
on Linux 2-13 Isql utility 8-25
on Windows 2000 2-10

Index 5
J administering licenses with License
Administrator 4-1
Java.lang.UnsatisfiedLinkError error on Linux 3-5
and user count 4-2, 4-3
Join
applying a key 4-14, 4-18
defined 1-9
applying user count 4-3
determining total user count 4-17
K displaying a specific license 4-18
Key displaying all applied licenses 4-16, 4-18
system 3-28 for prior releases 4-5
Key only file obtaining user count 4-3
viewing 3-28 platforms 4-2
removing a license 4-15, 4-19
L starting License Administrator 4-11, 4-12
Legacy data License Key Platform 4-2
creating DDFs for 9-23 Licenses for Prior Versions of Pervasive PSQL 4-4
Legacy file format Licensing
convert data files to 9-23 database engine on terminal server 4-4
License Administrator 4-1 workgroup engine 9-21
apply license key 4-14, 4-18 Limited user
CLI syntax 4-8 fast user switching 2-37
CLI tasks 4-18 Linux
command line interface 4-8 client DSNs 2-25
concepts 4-2 directory owner required to create a database 3-
determine total user count 4-17 25
display all applied licenses 4-18 engine DSNs 2-19
display applied license 4-16 naming databases 2-19
display help 4-18, 4-19 PCC
display specific license 4-18 errors trying to start 3-4
graphical user interface 4-5 java.lang.UnsatisfiedLinkError engine error
GUI tasks 4-11 3-5
GUI Visual Reference 4-5 SWT no more handles engine error 3-5
hide expired licenses 4-15 troubleshooting starting 3-4
license key 4-2 unable to connect to database engine error 3-
licenses for prior releases 4-5 5
remove a license 4-15, 4-19 psql force command 2-7
select a computer for license administration 4-12 psql start command 2-7
start as stand-alone application 4-12 psql stop command 2-7
start from PCC 4-11 starting and stopping database engine 2-7
tasks with 4-10 utilities 8-5
user count 4-2, 4-3 btadmin 8-15
applying 4-3 butil 8-17
obtaining 4-3 clilcadm 8-19
License count dbmaint 2-19, 8-20
increasing 9-20 dsnadd 2-25, 8-23
License count. See User count sqlmgr and odbc.ini 2-20
License key to change passwords 8-29

6 Index
 to register components in Pervasive registry use of 9-29
8-28
Load balancing 9-19 N
Load data Naming databases
bulk data utility 8-7 dbmaint utility 2-19
Loading from a Linux server 2-19
database engine 2-2 Network
Local communications
defined 1-8 verifying 9-22
Log protocol
name of PSA log file 7-4 determining 9-22
specifying name for PSA log file 7-13 protocol troubleshooting 9-6
Log file 7-7 setting protocol for connectivity test 7-11
Log on authority for service 2-10 testing connectivity with PSA 7-10
Log on failed Network password utility 8-38
troubleshooting 9-20 Non-standard DDFs
Log out detecting 9-24
from database 3-17 Null
Login in Table Editor 5-7
OS vs DB 9-19 Nulls
and Columns page in Table Editor 5-3
M setting for column in Table Editor 5-20
Map Root not supported 9-22 Number of duplicate pointers
Memory viewing 3-28
increasing amount available to PCC 9-7 Number of indexes
viewing modules loaded in 7-8 viewing 3-28
Metadata Number of unused pages
files where stored 9-27 viewing 3-28
utility to convert 8-33 Number or records
Metadata conversion utility 8-33 viewing 3-28
MicroKernel Database Engine
defined 1-3 O
Microsoft Object properties
Access accessing in PCC 3-8
accessing Pervasive PSQL data using 2-31 ODBC
Excel accessing data 2-29
accessing Pervasive PSQL data using 2-29 concepts 2-15
Migrating 9-28 determining if used 9-24
Mirroring of database 9-30 test utility 8-25
MKDE. See MicroKernel Database Engine ODBC standard 2-15
Monitor ODBC.INI
O/S rights required 9-4 configuration 2-20
Monitoring Online backup 9-30
bmon utility 8-14 Online help 1-14
Multiple Operating system
processors security vs DB security 9-19

Index 7
 troubleshooting access rights 9-4 Outline window 3-9
Outline window overview
in PCC 3-9 Pervasive PSQL Explorer 3-7
Outline window view plug-in
in SQL Editor 6-7 displaying after plug-in installation 3-6
running all SQL statements 6-20 preferences
sizing 6-26 general 2-35, 3-9, 6-15
Owner names window views 3-10
and SQL security 9-26 preferences for external tools 3-12
reconnecting to a server engine 3-16
P registering a remote server engine 3-15
Page size running slowly or hanging 9-7
viewing 3-28 security 3-38
Pages services 3-13
viewing number of unused 3-28 setting connection encoding 3-19
Partial indexes 5-28 setting database code page 3-18
Password setting database engine properties 3-16
troubleshooting wrong 9-11 setting database properties 3-17
utility to change on Linux 8-29 setting table properties 3-28
utility used to manage 8-38 specifying amount of memory to use 9-7
Passwords SQL Editor 3-8
utility used to manage 8-38 stored procedure object 3-37
PCC SWT no more handles error on Linux 3-5
accessing object properties 3-8 Table Editor 3-9
additional utilities 3-11 table object 3-28
clean parameters 3-6 Text window 3-9
clearing cache 3-6 trigger object 3-37
configuration 3-50 troubleshooting starting on Linux 3-4
database engine object 3-15 unable to connect to database engine error on
database engine running as a service 3-13 Linux 3-5
database object 3-17 user object 3-38
DataExchange and other plug-ins user-defined function object 3-37
displaying 3-6 view object 3-37
editor characteristics 3-7 vmargs parameter to increase memory 9-7
editors and window view within 3-6 window view characteristics 3-7
external tools 3-12 window views 3-10
setting preferences 3-12 PCC connection encoding 3-19
general preferences 2-35, 3-9, 6-15 PCC hangs 9-7
Grid 3-8 PCC hangs, See PCC
group object 3-38 PCC running slowly 9-7
increasing memory available to 9-7 Pervasive Control Center hangs, See PCC
java.lang.UnsatisfiedLinkError error on Linux 3- Pervasive PSQL
5 client, defined 2-16
logging in to server engine 3-16 explained 1-2
logging out from database 3-17 need to recreate DSNs 2-17
logging out from server engine 3-15 Server 1-11

8 Index
 server, defined 2-16 determining network 9-22
Workgroup 1-11 setting for PSA connectivity test 7-11
Pervasive PSQL Control Center. See PCC PSA
Pervasive PSQL Explorer log file name 7-4
accessing object properties 3-8 name of wizard executable 7-8
expanding tree objects 3-7 setting protocols for network connectivity test 7-
within PCC 3-7 11
Pervasive PSQL utilities. See Utilities specifying name for log file 7-13
Pervasive registry starting 7-8
utility to register components 8-28 test active installation 7-2
Pervasive Software testing Btrieve application 7-11
how to contact 10-1 testing network connectivity 7-10
Pervasive System Analyzer. See PSA testing relational interface 7-12
Pervasive_Admin security group 2-8 testing SQL application 7-12
use with Active Directory 2-11 testing transactional interface 7-11
Platform for license key 4-2 view modules 7-2
Precision viewing Pervasive modules 7-8
GUI object in Table Editor 5-7 PSA. See Pervasive System Analyzer
Preferences Psc utility 8-26
external tools 3-12 Psql force command 2-7
for Data Grid 3-10 Psql start command 2-7
for SQL Editor 3-10 Psql stop command 2-7
for Table Editor 3-10 Psregsvr 8-28
for Text window 3-10 Pvdbpass utility 8-29
general 3-9 Pvddl utility 8-31
database default for current session 6-15 Pvmdconv utility 8-33
DSN entries 2-35 Pvnetpass utility 8-38
setting for Grid 3-9, 3-10 authenticating to a domain server 8-40
setting in PCC for external tools 3-12 PVSW.LOG
window views 3-10 client and server compatibility 9-3
Primary key
setting for column in Table Editor 5-23 R
Programming interfaces supported 9-27 Rbldcli utility 8-41
Properties Rebuild
accessing in PCC 3-8 data files with utility 8-41
bound database 3-20 Reconnect
data directories location for database 3-20 to database engine in PCC 3-16
dictionary location for database 3-20 Record
integrity enforced for database 3-21 defined 1-6
setting database code page 3-18 length 3-28, 9-23
setting for database 3-17 viewing variable 3-28
setting for database engine 3-16 Recover
setting for services 3-14 default data for DEMODATA sample database 9-
setting for table 3-28 15
setting PCC connection encoding 3-19 Recreating DSNs 2-17, 2-35
Protocol Redirected mapping not supported 9-22

Index 9
Referential constraints exporting table 3-33
listing 3-17 Security 3-38
Register administrative rights 2-8
database engine in PCC 3-15 as object property in PCC 3-38
Registry file system 1-15, 2-29
utility to register components on Linux 8-28 logging in as administrator 2-10, 2-14
Relational OS login vs DB login 9-19
testing interface with PSA 7-12 owner names vs SQL security 9-26
Remote tasks for 3-39
defined 1-8 Separator
Remote database access 2-22 selecting statatement separator 6-17
Removing Server
DSN 2-35 troubleshooting network protocols 9-6
Replication 9-30 ServerDSN not found error 9-2
Requester Service
defined of 1-4 database engine running as 3-13
for SQL Relational Database Engine 9-27 log in authority for "this account" 2-10
troubleshooting client 9-4 setting properties 3-14
Restore setting startup policy for database engine 3-14
DEMODATA sample database to installation starting or stopping database engine 3-13
defaults 9-15 stopping Workgroup engine when using fast user
Restrictions switching 2-38
Import Data Wizard 3-31 Service pack
Rights identifying level 9-18
administrative 2-8 Services
granting administrative psc utility for 8-26
for "this account" 2-10 Set up database access 2-15
on Linux 2-13 Shadowing of database 9-30
on Windows 2000 2-10 Shared files, troubleshooting 9-22
if changed from system account 2-10 Size
Row in Table Editor 5-7
defined 1-6 SMP. See Multiple processors
SQL
S CREATE GROUP 9-26
Sample database CREATE USER 9-26
recreating DEMODATA 9-15 GRANT 9-26
Scalar functions testing relational interface 7-12
DATE in SQL Editor 6-24 utility to execute statements 8-31
TIME in SQL Editor 6-24 SQL Editor 3-8
TIMESTAMP in SQL Editor 6-24 adding rows of data within Grid 6-22
using within SQL Editor Grid 6-24 changing data within Grid 6-21
Scale clearing results in Text window 6-25
GUI object in Table Editor 5-7 copying data from Grid 6-25
Scheduling events 9-27 creating SQL query or script 6-16
Schema creating stored procedures 6-26
defined 1-8 creating triggers 6-26

10 Index
 creating user-defined functions 6-26 creating in SQL Editor 6-16
creating views 6-26 opening in SQL Editor 6-16
deleting rows of data within Grid 6-23 SQL statements
deleting stored procedures 6-27 comments in 6-18
deleting triggers 6-27 copying in Table Editor 5-40
deleting user-defined functions 6-27 creating query or script in SQL Editor 6-16
deleting views 6-27 enabling commands to execute 6-19
enabling SQL execution commands 6-19 finding text in 6-18
finding text 6-18 opening SQL script in SQL Editor 6-16
Grid 6-4 redoing typing in SQL Editor 6-18
identifying setting 6-15 running all in SQL Editor 6-20
modifying stored procedures 6-27 running in SQL Editor Outline window view 6-
modifying triggers 6-27 20
modifying user-defined functions 6-27 running single in SQL Editor 6-19
modifying views 6-27 selecting text in 6-19
opening SQL script 6-16 separators in SQL Editor 6-3
Outline window view 6-7 setting database context in SQL Editor for query
overview 6-2 6-14
redoing an action 6-18 starting SQL Editor 6-13
refreshing data in Grid 6-24 starting SQL Editor by showing all table records
running all SQL statement 6-20 6-14
running all SQL statement in Outline window typing comments in SQL Editor 6-18
view 6-20 undoing typing in SQL Editor 6-18
running single SQL statement 6-19 SQL View
selecting SQL statement separator 6-17 in Table Editor 6-10
selecting text 6-19 SQL view
selecting text in Text window 6-25 in Table Editor 5-4
setting database context for query 6-14 Sqlmgr utility
setting preferences 3-10 odbc.ini 2-20
sizing Outline window view 6-26 Start database engine on Linux 2-7
SQL statement separators 6-3 Start up
starting by showing all table records 6-14 keeping Workgroup engine from autostarting 9-
starting for new query 6-13 19
stored procedures 6-8 Starting
Text window view 6-5 database engine 2-2
triggers 6-8 Startup policy
typing comments in 6-18 for database engine 3-14
undoing an action 6-18 Statement separator
used in SQL View of Table Editor 6-10 selecting 6-17
user-defined functions 6-8 troubleshooting 6-17
using scalar functions within Grid 6-24 Stop database engine on Linux 2-7
views 6-8 Stopping
SQL Relational Database Engine database engine 2-2
defined 1-4 Workgroup engine under fast user switching 2-
SQL requester 9-27 38
SQL script Stored procedure

Index 11
 as object in PCC 3-37 viewing system data key 3-28
creating in SQL Editor 6-26 viewing variable records 3-28
deleting in SQL Editor 6-27 Table columns
in SQL Editor 6-8 viewing 3-30
modifying in SQL Editor 6-27 Table Editor
Structured Query Language adding a foreign key 5-37
utility to execute statements 8-31 allowing index duplicates 5-35
Structures arranging order of index segment 5-34
database 1-6 columns page 5-3
SWT no more handles error on Linux 3-5 columns page interface 5-6
Symmetric Multiprocessing. See Multiple processors copying SQL statement 5-40
System account rights 2-10 creating an index 5-24
System data key deleting a column 5-16
viewing 3-28 deleting a foreign key 5-39
System key deleting an index 5-30
viewing 3-28 deleting an index segment 5-33
System tables 3-28 foreign keys page 5-4
identifying tables with changes pending 5-13
T in PCC 3-9
Table indexes page 5-4
as object in PCC 3-28 inserting an index segment 5-31
creating data for 3-31 inserting columns 5-15
data 3-28 modifying a foreign key 5-39
defined 1-7 modifying an index 5-30
export data 3-32 modifying an index segment 5-32
exporting schema 3-33 naming a column 5-17
import data 3-31 overview 5-2
system 3-28 saving changes for edited table 5-14
viewing saving changes to edited table 5-14
variable record blank truncation 3-28 selecting columns 5-16
viewing alternate collating sequence 3-28 setting a column data type 5-17
viewing data compression 3-28 setting column case 5-20
viewing dictionary path 3-28 setting column collating sequence 5-21
viewing file version 3-28 setting column default 5-22
viewing freespace threshold 3-28 setting column nulls 5-20
viewing index balancing 3-28 setting column precision 5-19
viewing key only file 3-28 setting column primary key 5-23
viewing location of file 3-28 setting column scale 5-19
viewing name 3-28 setting column size 5-18
viewing number of duplicate pointers 3-28 setting preferences 3-10
viewing number of indexes 3-28 specifying index as modifiable 5-36
viewing number of records 3-28 specifying sort order for index 5-35
viewing number of unused pages 3-28 SQL View 6-10
viewing page size 3-28 SQL view 5-4
viewing physical file name associated with 3-30 starting for a new table 5-11
viewing record length 3-28 starting for an existing table 5-12

12 Index
 tasks performed with 5-9 testing interface with PSA 7-11
undoing or redoing changes 5-14 Tray icon
viewing SQL statements applicable to the table 5- with fast user switching 2-38
13 Trigger
viewing table data 5-13 as object in PCC 3-37
work area pages 5-2 creating in SQL Editor 6-26
working with columns 5-12 deleting in SQL Editor 6-27
working with foreign keys 5-12 in SQL Editor 6-8
working with indexes 5-12 modifying in SQL Editor 6-27
Table file location Troubleshooting
viewing 3-28 client DSN not available 9-6
Table indexes disabled client requester 9-4
viewing 3-30 network outage 9-4
Table name no server (engine) DSN available 9-5
viewing 3-28 OS permissions problems 9-4
viewing physical file name associated with 3-30 PCC running slowly or hanging 9-7
Table schema server not accepting requests 9-5
exporting 3-33 server not running 9-5
Tables SQL Statement Separator 6-17
exporting schema 3-33 wrong network protocol settings 9-6
Terminal Server 9-18 Type
database engine licensing 4-4 in Table Editor 5-7
Terminal Server Licensing 4-4
Terminology U
Btrieve usage 1-10 Unable to connect error
client 1-4 troubleshooting 9-10
requester 1-4 Unable to connect to database engine error on Linux
Test active installation 7-6 3-5
Test network 7-6 Unauthorized access
Test relational engine 7-7 to data file with owner name 9-26
Test transactional engine 7-6 Uninstalling
Text window data files not affected 9-18
in PCC 3-9 Unloading
setting preferences 3-10 database engine 2-2
Text window view Unused pages
clearing results in 6-25 viewing number of 3-28
in SQL Editor 6-5 Upgrading 9-28
selecting text in 6-25 user count 9-20
Tools User
adding external to PCC 3-12 as object in PCC 3-38
Trace User count 4-3
run in trace mode 9-29 administering with License Administrator 4-1
Trace mode applying 4-3
running in 9-29 determining total 4-17
Tracing 9-29 how to apply 9-20
Transactional increasing 4-3

Index 13
 license key 4-2, 4-3 Variable record blank truncation
obtaining 4-3 viewing 3-28
troubleshooting expired license 9-10 Variable records
workgroup engine 9-21 viewing 3-28
User name Version
OS vs DB 9-19 new, data files not affected by installing 9-18
troubleshooting wrong 9-11 old, data files not affected by uninstalling 9-18
utility used to manage 8-38 viewing file 3-28
User rights policy View
act as part of the operating system 2-11 as object in PCC 3-37
for "this account" 2-11 creating in SQL Editor 6-26
User switching 2-37 deleting in SQL Editor 6-27
User-defined function in SQL Editor 6-8
as object in PCC 3-37 modifying in SQL Editor 6-27
creating in SQL Editor 6-26 Pervasive modules loaded in memory 7-8
deleting in SQL Editor 6-27 View loaded Pervasive modules 7-6
in SQL Editor 6-8 View modules 7-2
modifying in SQL Editor 6-27 Vmargs
Users PCC parameter to increase memory 9-7
assign to group 3-46
types of for fast user switching 2-37 W
Uses alternate collating sequence W64clilcadm utility 8-19
viewing 3-28 Windows
USING fast user switching 2-37
clause in exporting table schema 3-33 running Workgroup engine with fast user
Utilities switching 2-37
btadmin 8-15 start and stop Database Workgroup Engine 2-5
butil 8-17 types of users for fast user switching 2-37
clilcadm 8-19 XP operating system
dbmaint 2-19, 8-20 tray icon with fast user switching 2-38
dsnadd 2-25, 8-23 Windows services
for Linux 8-5 psc utility 8-26
License Administrator 4-1 Wizard
overview 1-1, 2-1, 9-1 PSA 7-8
psc 8-26 Workgroup engine
sqlmgr database access 2-22
odbc.ini 2-20 keeping from autostarting 9-19
w64clilcadm 8-19 licensing 9-21
simultaneous access 9-20
V stopping under fast user switching 2-38
V1 metadata
conversion utility 8-33 X
V2 metadata Xtrieve
conversion utility 8-33 replacement for 9-27
Value
defined 1-6

14 Index