About This Manual
Who Should Read This Manual
Conventions
Introducing PSQL
Understanding the PSQL Database Management System
What is a Database?
What is a Database Management System?
Components of PSQL
MicroKernel Engine
Relational Engine
Client (also called Requester)
PSQL Control Center
Utilities
Documentation
Key Concepts
Database Structures and Terms
Value
Column or Field
Row or Record
Cell
Table
Index
Database
Schema
Remote
Local
Relational
Join
Unique Benefits of PSQL
Engine Access Methods
Terminology Revisited
Understanding the DBMS Products
PSQL Workgroup
PSQL Server
PSQL Vx Server
Crystal Reports for PSQL
Using PSQL Documentation
Getting Started
What’s New
User’s Guide
Advanced Operations Guide
SQL Engine Reference
Status Codes and Messages
Additional Information
File System Security
Using PSQL
Starting and Stopping the Database Engine
Starting and Stopping the Server Engine on a Windows Server
Services Dependencies
Starting and Stopping the Workgroup Engine on Windows
Starting and Stopping the Database Engine on Linux, macOS, and Raspbian
Linux and Raspbian
macOS
Linux and Raspbian
macOS
Linux and Raspbian
macOS
Verifying That the Database Engine is Running from a Remote PowerShell Session
Starting and Stopping the Database Engine on Windows IoT Core or Nano Server
Granting Administrative Rights for the Database Engine
Tasks Requiring Administrative Rights
How Administrative Rights are Granted
Rights Within an Active Directory Environment
Rights Provided to Non-Administrative Users
Tasks for Granting Administrative Rights
Granting Administrative Rights on a Windows Server
Services Settings and Log In Authority
Default Setting
Logging On as “This Account”
User Rights Policy Tasks
Granting Administrator Rights on Linux and macOS
Logging in as Administrator on Any Platform
Setting Up ODBC Database Access
ODBC Standard
Servers and Clients
Data Source Names
Internal Database Name
Applications Using the MicroKernel Engine
Setting Up Database Access with PCC
Setting Up Database Access on Windows
Setting Up Database Access on a Linux or macOS Server
Setting Up Client Access from a Windows Client
Setting Up a Client DSN on a Linux or macOS Client
Accessing Data on a Remote Engine Using PCC
Accessing Data via ODBC from Other Applications
Before You Begin
Does the Database Have a DSN Available?
Accessing Data Using Microsoft Excel
Accessing Data Using Microsoft Access
Deleting DSNs
Using PSQL Control Center
An Overview of PSQL Control Center
Installing PCC
Starting PCC on Windows
Starting PCC on Linux
Starting PCC on macOS
Situations Requiring That You Clear PCC Cache
Editors and Views within PCC
Editor and View Characteristics
PSQL Explorer
Objects and Their Properties
Right-click Tasks
SQL Editor
Grid
Text
Outline
Table Editor
Preferences
Preferences for PCC Window Views
File Encoding Preferences
Additional Utilities
External Tools
Services on Windows Servers
Services Properties
Database Engines
Database Engine Properties
Capacity Usage Viewer
Monitor
Defragmenter
Databases
Database Properties
Code Page
Database Code Page
PCC Connection Encoding
Directories
Dictionary Location
Data Directories
General
Bound Database
Integrity Enforced
Long Metadata (V2 Metadata)
Relational Constraints
Security
New Database GUI Reference
Creating, Modifying, Deleting, and Repairing PSQL Databases
Tables
Data Tables
System Tables
Table Properties
Managing Schemas
Database Schema Export Options
Table Schema Export Options
IN DICTIONARY
Schema Export and Import Tasks
Common Uses for Exported Database Schema Files
Special Case: Working with Secure Database Schemas
Special Case: Working with Multiple or Variant Record Definitions
Troubleshooting Schema Export and Import Issues
Export Schema Log
Alternate Collating Sequence
Invalid Entries
Overlapping Columns
Btrieve Null Keys
Import Schema Log
SQL Errors
Variant Record Messages
Referential Integrity Constraints
Metadata Version Errors
Schema Validation Log
Offset Mismatches
Data Type Mismatches
Missing Attributes
Missing Indexes
Creating, Importing, and Exporting Data
Creating Data Through PCC
Importing Data with Bulk Data Utility
Importing Data with Import Data Wizard
Restrictions
Exporting Data with Export Data Wizard
Stored Procedures, Triggers, User-Defined Functions, and Views
Groups, Users, and Security
Security Tasks
General Tasks
Btrieve Security Policy Tasks
User and Group Tasks
Assigning Permissions Tasks
Configuring Database Engines and Clients
Dialogs for File Open and File Save
Encoding Choices
Default Encoding
Invalid File Name Characters
File Open Dialog (Open SQL Document)
File Save Dialog (Save SQL Document)
Using the Standard Operating System Dialogs
Wide Character Data Support for Import Data, Export Data, and Export Schema
Import Data Dialog
Export Data Dialog
Export Schema Dialog
License Administration
License Administration Concepts
License Models
Concurrent User License Model
Obtaining a User Count
Capacity-based License Model
Data in Use
Estimating Data in Use
Behavior When Data Use Limit Is Reached
Corrective Action When Data in Use Limit Is Reached
Obtaining an Initial Data in Use Limit
License Enforcement
Authorize a Product
Authorization Access Through a Proxy Server
Windows Proxy Servers
Linux and macOS Proxy Servers
Offline Authorization Without Internet Access
Key Status, or State
Failed Validation and Failed-Validation Period
Repairing a Disabled or Failed Key
Increase User Count or Data in Use
Increasing User Count
Increasing Data in Use Limit
Message Logging
License Administrator Graphical User Interface
GUI Visual Reference
License Administrator Command Line Interface
CLI Syntax
License Administration Tasks
License Administrator
GUI Tasks
CLI Tasks
Alternative Authorization Tasks
Notification Viewer
GUI Tasks
CLI Tasks
Alternative Authorization Tasks
Telephone Authorization
Telephone Deauthorization
Notification Viewer
Table Editor
Table Editor Concepts
Overview
Table Editor Pages
Columns Page
Indexes Page
Foreign Keys Page
SQL View Page
CREATE Statements
ALTER Statements
Data Types
Null Values
Table Editor Graphical User Interface
Columns Page
Indexes Page
Foreign Keys Page
SQL View Page
Table Editor Tasks
General Tasks
Getting Started
Data
Columns Tasks
Indexes Tasks
Foreign Keys Tasks
SQL View Tasks
General Tasks
Columns Tasks
Index Tasks
Foreign Keys Tasks
SQL View Tasks
SQL Editor
SQL Editor Concepts
Overview
Statement Separators
Restrictions
Displaying Statement Results
Grid Window View
Identifying the Grid Window
Modifying Data and Adding Rows
Records Affected and Scrolling
Text Window View
Identifying the Text Window
Scrolling and Positioning
Outline Window View
Working with Common SQL Objects
SQL Editor Used in SQL View Tab of Table Editor
SQL Editor Tasks
General Tasks
Execution Tasks
Grid Tasks
Text View Tasks
Outline View Tasks
Common SQL Object Tasks
General Tasks
Statement Execution Tasks
Grid Tasks
Text Window Tasks
Outline View Tasks
Common SQL Objects Tasks
PSQL System Analyzer (PSA)
PSA Concepts
View Modules
View Modules
Test Active Installation
Network
Transactional Engine
Relational Engine
Frequently Asked Questions
What is the default log file name?
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 tool is run?
How do I run PSA?
When would I want to use PSA?
PSA GUI Visual Reference
PSA Tasks
General Tasks
General Tasks
View Modules Tasks
Test Active Installation Tasks
Log File Tasks
General Tasks
View Modules Tasks
Test Active Installation Tasks
Test at the Network Level
Test at the MicroKernel Level
Test at the Relational Level
Log File Tasks
Command Line Interface Utilities
CLI Utilities Overview
Platforms that Include CLI Utilities
Where to Find CLI Utilities
Windows
Linux, macOS, and Raspbian
Utilities by Platform and Engine Type
Command Line Interface Tool Reference
bcfg
bdu
Description
Synopsis
Parameters
Notes
Configuration Settings
Error Logging
Constraints
Best Practices
Sample Source File
Examples
bmon
btadmin
Description
Synopsis
Options
See Also
Notes
butil
Description
Synopsis
Options
See Also
clilcadm
Description
Synopsis
Options
See Also
clipaadm
Description
Synopsis
Without Parameters
With Parameters in Two Steps
See Also
dbdefrag
dbmaint
Description
Synopsis
Options
Examples
See Also
dsnadd
Description
Synopsis
Options
Examples
Notes
ODBC and Data Source Names (DSNs)
Frequently Asked Questions
ODBC Header Files
See Also
isql
Description
Synopsis
Options
Commands
Notes
Examples
See Also
licgetauth
Description
Synopsis
Options
See Also
psc
Description
Synopsis
Options
Examples
Return Codes
psregedit
Description
Synopsis
Options
psregsvr
Description
Synopsis
Options
pvdbpass
Description
Synopsis
Options
Examples
pvddl
Description
Synopsis
Options
See Also
pvnetpass
Description
Synopsis
Options
See Also
Examples
rbldcli
Description
Synopsis
Options
See Also
Using PSQL Scripts in Macintosh Finder
PSQL Scripts in Finder
Managing Licenses
Managing Engine Services
Basic Troubleshooting
General Troubleshooting
I get Error 1114 when trying to access my data
I get an error about ServerDSN or DBQ was not found in the connection string
I get a message about Engine components’ version is different than my client components’ version
I can’t get to my data on the server engine
PCC runs slowly or hangs when retrieving large record sets
Error Messages from PCC
Can’t retrieve database names. You don’t have access rights for the operation
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
An error was encountered while connecting to the server
Unknown configuration properties
Frequently Asked Questions
Installation
Installation
PCC
Security
User Count, Session Count, Data In Use
Networking
Difficulty Accessing Data
ODBC and DDFs
Upgrading from Btrieve 6.15
Upgrading and Migration
Demodata Sample Database
Miscellaneous
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 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 PSQL supported on a Terminal Server?
Can I install PSQL in a Failover environment? or
Can I install PSQL in a Clustering environment?
Can I install PSQL in a Load Balancing environment?
Can I install 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 or macOS?
Security
When do I log in using an operating system user and password, and when do I log in 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 authorize a User Count Upgrade?
How does a PSQL engine using the concurrent user license model keep track of how many people are accessing the data? If people access the data with two engines at the same time, what happens?
Does the Workgroup engine use concurrent or per-seat licensing?
I am thinking of moving from a PSQL engine with concurrent user licensing to one with capacity-based licensing. How do I determine the appropriate size for my data use license?
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 the current version of PSQL. 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 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 file path 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 nonstandard 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 creating a DSN, why can I not open the files using ODBC?
Is there a client side requester for the Relational Engine?
Is ODBC the only method of access for 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?
Does the Relational Engine have scheduler capabilities to run stored procedures or other types of scripts designed to access and affect data?
Upgrading and 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?
Miscellaneous
I dumped Btrieve records to a file and now I can’t read the file. What happened?
How do I run 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?
About This Manual
Basic Troubleshooting
databaseExplorer:PSQL Explorer%The PSQL Explorer is a tree of objects, such as engines, databases, tables, and users that can be viewed and managed in PCC.
GeneralPrefPage:General Preferences%General Preferences control removal of associated DSN entries and suppression of database prompting for SQL documents.
dataGridPrefPage:Data Grid Preferences%The Data Grid Preferences set the Grid display, including maximum column width, row numbers, and character trimming.
sqlEditorPrefPage:SQL Editor Preferences%The SQL Editor Preferences set SQL statement delimiters and editor characteristics such as number of words and lines to display.
tableEditorPrefPage:Table Editor Preferences%Table Editor Preferences set default colors for the table grid.
dataTextPrefPage:Text Output Preferences%The Data Text Preferences control the Text window display, including font, column width, and SQL script errors.
EncodingPrefPage:File Encoding Preferences%The File Encoding Preferences set the default file encoding to use for Open SQL Document, Close SQL Document, Export Table Schemas, Import Data, and Export Data.
externalToolsNewDialog:To Add External Tools%The External Tools dialog allows you to add software programs to the Tools menu as a convenient way to start them from PCC.
externalToolsPrefPage:External Tools Preferences%External Tools Preferences set the external tools to include with PCC.
servicesPropPage:Services on Windows Servers%Configuration settings for how the transactional and relational interfaces start based on the startup policy for the operating system.
newServerWizard:To Register a Remote Server Engine%PCC can communicate with database engines on remote machines by identifying them here.
dbCodePagePropPage:Database Code Page Properties%The Code Page properties set the code page for a database and the encoding that PCC uses to connect to a database.
dbDirectoriesPropPage:Database Directories Properties%The Directories property page sets the locations for data files and data dictionary files (DDFs).
dbGeneralPropPage:Database General Properties%The General property page sets database binding, enforcement of referential integrity, default metadata version, and encoding.
dbConstraintsPropPage:Database Relational Constraints%The Relational Constraints property page lists relational constraints in effect for the database.
dbSecurityPropPage:Database Security Properties%The Security property page sets security for the database and the security method for the transactional interface.
newDBWizard:New Database GUI Reference%PCC creates new databases based on these settings.
removeDSNDialog:To Delete a Database%When you delete a database, you may also remove the data source name (DSN) associated with it. You can set DSN removal as the default action.
tablePropPage:Table Properties%Read-only information about a table, including general properties, columns information, and indexes information.
exportSchema:Exporting a Schema for a Table or All Tables%Export Schema exports the schema for a specific table or for an entire database.
importData:Importing Data%Import Data reads delimited data from a text file and adds the data to a table based on import settings.
exportData:Exporting Data%Export Data writes data from a table to a delimited text file based on export settings.
newGroupWizard:To Create a New Group%For security, PCC can enforce permissions for groups. Users belonging to a group have group rather than individual permissions.
newUserWizard:To Create a New User%For security, PCC can set permissions for individual users.
groupPermPropPage:To Assign Permissions for a Group%For security, PCC can set group permissions for databases, tables, columns, stored procedures, or views for users who are members of a group.
userPermPropPage:To Assign Permissions for a User%For security, PCC can set individual user permissions for databases, tables, columns, stored procedures, or views for users who are not members of a group.
OpenSQLDoc:Open SQL Document with Selected Encoding%Open SQL Document is an alternative dialog that allows you to change the file encoding during the open action.
license_administrator
licadmin_gui
tableEditorIndexPage:Indexes Page%The Indexes page is a work area in Table Editor for indexes and index segments.
tableEditorForeignKeyPage:Foreign Keys Page%The Foreign Keys page is a work area in Table Editor for foreign keys.
tableEditorColumnPage:Columns Page%The Columns page is a work area in Table Editor for table columns.
newTableWizard:To Start Table Editor for a New Table%PCC can create a new table based on settings chosen in this wizard.
sqlEditor:SQL Editor%SQL Editor is a window in PCC for running Structured Query Language (SQL) statements against a PSQL database.
dataGridView:Data Grid View%The Grid uses a spreadsheet format to show results returned by SQL SELECT statements
sqlOutlineView:SQL Outline View%The Outline window is a view in PCC to manage and run SQL statements in a tree structure.
dataGridAddRowsDialog:To Add Rows of Data to the Grid%The Grid allows you to directly change database data by changing values in existing grid cells or by adding rows to the table.
Welcome_System_Analyzer
System_Analyzer
View_Modules
View_Modules_Grid
Test_Network_Communication
Test_Network_Communication_Adv
Network_Communication_Test_Results
Test_Transactional_Engine
Transactional_Engine_Test_Results
Test_Relational_Engine
Relational_Engine_Test_Results
Completing_System_Analyzer