0% found this document useful (0 votes)

264 views

SQL Engine Reference

Pervasive SQL_Engine_Reference

Uploaded by

Indra Anggara

Available Formats

Download as PDF, TXT or read online on Scribd

0% found this document useful (0 votes)

264 views

SQL Engine Reference

Pervasive SQL_Engine_Reference

Uploaded by

Indra Anggara

Available Formats

Download as PDF, TXT or read online on Scribd

You are on page 1/ 608

Pervasive PSQL Summit v10

SQL Engine Reference

Using SQL with Pervasive PSQL

Pervasive Software Inc.

12365 Riata Trace Parkway
Building B
Austin, TX 78727 USA

Telephone: 512 231 6000 or 800 287 4383

Fax: 512 231 6010
Email: info@pervasive.com
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 2007 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
(pharvey@codebydesign.com), modified and extended by Nick Gorham (nick@easysoft.com), 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 (nick@easysoft.com).
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.

SQL Engine Reference

September 2007
100-004378-001

Contents
About This Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Who Should Read this Manual
Manual Organization . . . . . .
Conventions . . . . . . . . . . .
For More Information . . . . .

.
.
.
.

xvii
.
.
.
.

SQL Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

xviii
xix
xxi
xxii

1-1

An Overview of the Structured Query Language (SQL)

Data Definition Statements . . . . . . . . . . . . . . . . . . .
Creating, Modifying, and Deleting Tables . . . . . . . .
Creating and Deleting Views . . . . . . . . . . . . . . .
Creating and Deleting Indexes . . . . . . . . . . . . . .
Creating and Deleting Triggers . . . . . . . . . . . . . .
Creating and Deleting Stored Procedures . . . . . . . .
Creating and Deleting User-Defined Functions (UDF) .
Data Manipulation Statements . . . . . . . . . . . . . . . . .
Retrieving Data . . . . . . . . . . . . . . . . . . . . . . .
Modifying Data. . . . . . . . . . . . . . . . . . . . . . .
Defining Transactions . . . . . . . . . . . . . . . . . . .
Creating and Deleting Views . . . . . . . . . . . . . . .
Executing Stored Procedures . . . . . . . . . . . . . . .
Executing System Stored Procedures . . . . . . . . . . .
Executing Triggers . . . . . . . . . . . . . . . . . . . . .
Data Control Statements . . . . . . . . . . . . . . . . . . . . .
Enabling and Disabling Security . . . . . . . . . . . . .
Creating and Deleting Users and Groups . . . . . . . .
Granting and Revoking Rights . . . . . . . . . . . . . .

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

ODBC Engine Reference. . . . . . . . . . . . . . . . . . . . . . . .

1-3
1-3
1-4
1-4
1-4
1-4
1-5
1-7
1-7
1-8
1-8
1-9
1-9
1-9
1-9
1-10
1-10
1-11
1-11

2-1

Limits, Connection Strings, and ODBC Support

Versions of Metadata . . . . . . . . . . . . . . . .
Relational Interface Limits . . . . . . . . .
Fully Qualified Object Names . . . . . . . .
Data Source Name Connection String Keywords
ODBC Support . . . . . . . . . . . . . . . . . . .
ODBC Interface Support . . . . . . . . . .
ODBC API Support . . . . . . . . . . . . .
Exceptions to ODBC API Support . . . . .
ODBC Attribute Support . . . . . . . . . .
ODBC Descriptor Field Support . . . . . .

.
.
.
.
.
.
.
.
.
.

2-2
2-2
2-6
2-7
2-9
2-9
2-9
2-12
2-14
2-15

iii

Contents

SQL Grammar Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Delimited Identifiers in SQL Statements . . . . . . . . . . . . . . . . . . . . . .

2-17
2-19

SQL Syntax Reference . . . . . . . . . . . . . . . . . . . . . . . . .

3-1

A Reference to Pervasive PSQL Supported Syntax

Grammar Statements . . . . . . . .
ADD . . . . . . . . . . . . . .
ALL . . . . . . . . . . . . . . .
ALTER (rename) . . . . . . .
ALTER GROUP . . . . . . . .
ALTER TABLE . . . . . . . .
ALTER USER . . . . . . . . .
ANY . . . . . . . . . . . . . .
AS. . . . . . . . . . . . . . . .
BEGIN [ATOMIC] . . . . . .
CALL . . . . . . . . . . . . . .
CASCADE . . . . . . . . . . .
CASE (expression) . . . . . .
CASE (string) . . . . . . . . .
CLOSE . . . . . . . . . . . . .
COALESCE . . . . . . . . . .
COMMIT . . . . . . . . . . .
CREATE DATABASE . . . .
CREATE FUNCTION . . . .
CREATE GROUP . . . . . . .
CREATE INDEX . . . . . . .
CREATE PROCEDURE . . .
CREATE TABLE . . . . . . .
CREATE (temporary) TABLE
CREATE TRIGGER . . . . .
CREATE USER . . . . . . . .
CREATE VIEW . . . . . . . .
DECLARE . . . . . . . . . . .
DECLARE CURSOR . . . . .
DEFAULT . . . . . . . . . . .
DELETE (positioned) . . . .
DELETE . . . . . . . . . . . .
DISTINCT . . . . . . . . . . .
DROP DATABASE . . . . . .
DROP FUNCTION . . . . . .
DROP GROUP . . . . . . . .
DROP INDEX . . . . . . . .
DROP PROCEDURE . . . . .
DROP TABLE . . . . . . . . .
DROP TRIGGER . . . . . . .
iv

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

3-2
3-3
3-4
3-5
3-8
3-10
3-26
3-28
3-29
3-31
3-32
3-33
3-34
3-39
3-40
3-41
3-44
3-46
3-51
3-58
3-59
3-66
3-80
3-93
3-103
3-106
3-108
3-113
3-114
3-116
3-123
3-125
3-128
3-129
3-131
3-132
3-133
3-135
3-136
3-137

Contents

DROP USER . . . . . . . . . . . . . . .
DROP VIEW . . . . . . . . . . . . . . .
END . . . . . . . . . . . . . . . . . . . .
EXECUTE . . . . . . . . . . . . . . . .
EXISTS . . . . . . . . . . . . . . . . . .
FETCH . . . . . . . . . . . . . . . . . .
FOREIGN KEY . . . . . . . . . . . . . .
GRANT . . . . . . . . . . . . . . . . . .
GROUP BY . . . . . . . . . . . . . . . .
HAVING . . . . . . . . . . . . . . . . .
IF . . . . . . . . . . . . . . . . . . . . .
IN . . . . . . . . . . . . . . . . . . . . .
INSERT . . . . . . . . . . . . . . . . . .
JOIN . . . . . . . . . . . . . . . . . . .
LEAVE . . . . . . . . . . . . . . . . . .
LIKE . . . . . . . . . . . . . . . . . . . .
LOOP . . . . . . . . . . . . . . . . . . .
NOT . . . . . . . . . . . . . . . . . . . .
OPEN . . . . . . . . . . . . . . . . . . .
PARTIAL . . . . . . . . . . . . . . . . .
PRIMARY KEY. . . . . . . . . . . . . .
PRINT. . . . . . . . . . . . . . . . . . .
PUBLIC . . . . . . . . . . . . . . . . . .
RELEASE SAVEPOINT . . . . . . . . .
RESTRICT . . . . . . . . . . . . . . . .
REVOKE . . . . . . . . . . . . . . . . .
ROLLBACK . . . . . . . . . . . . . . .
SAVEPOINT . . . . . . . . . . . . . . .
SELECT (with into) . . . . . . . . . . .
SELECT . . . . . . . . . . . . . . . . .
SET ANSI_PADDING . . . . . . . . .
SET CACHED_PROCEDURES . . . .
SET DECIMALSEPARATORCOMMA
SET DEFAULTCOLLATE . . . . . . .
SET OWNER . . . . . . . . . . . . . .
SET PASSWORD . . . . . . . . . . . .
SET PROCEDURES_CACHE . . . . .
SET ROWCOUNT . . . . . . . . . . .
SET SECURITY . . . . . . . . . . . . .
SET TIME ZONE . . . . . . . . . . . .
SET TRUEBITCREATE . . . . . . . . .
SET TRUENULLCREATE . . . . . . .
SET . . . . . . . . . . . . . . . . . . . .
SIGNAL . . . . . . . . . . . . . . . . .
SQLSTATE . . . . . . . . . . . . . . . .

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

3-138
3-139
3-140
3-141
3-143
3-145
3-147
3-149
3-160
3-162
3-163
3-165
3-166
3-173
3-180
3-181
3-183
3-184
3-185
3-186
3-187
3-189
3-190
3-191
3-193
3-194
3-197
3-199
3-201
3-202
3-228
3-231
3-235
3-237
3-240
3-242
3-245
3-249
3-250
3-252
3-258
3-259
3-260
3-261
3-263

Contents

START TRANSACTION . . . .
UNION. . . . . . . . . . . . . .
UNIQUE . . . . . . . . . . . . .
UPDATE . . . . . . . . . . . .
UPDATE (positioned) . . . . .
USER . . . . . . . . . . . . . . .
WHILE . . . . . . . . . . . . . .
Grammar Element Definitions
Global Variables . . . . . . . . . . . .
Other Characteristics . . . . . . . . .
Temporary Files . . . . . . . . .
Working with Literal Values . .
Working with NULL Values . .
Working with Binary Data . . .
Creating Indexes. . . . . . . . .
Closing an Open Table . . . . .
Concurrency . . . . . . . . . . .
Comma as Decimal Separator .
OEM to ANSI Support . . . . .

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

3-264
3-266
3-268
3-269
3-277
3-279
3-280
3-281
3-290
3-294
3-294
3-296
3-298
3-298
3-299
3-299
3-300
3-300
3-304

Bitwise Operators . . . . . . . . . . . . . . . . . . . . . . . . . . .

4-1

A Reference to Pervasive PSQL Bitwise Operators

Overview . . . . . . . . .
Bitwise AND (&) . . . . .
Syntax . . . . . . .
Values Returned . .
Examples . . . . . .
Bitwise NOT (~) . . . . .
Syntax . . . . . . .
Values Returned . .
Examples . . . . . .
Bitwise OR (|) . . . . . .
Syntax . . . . . . .
Values Returned . .
Examples . . . . . .
Bitwise Exclusive OR (^)
Syntax . . . . . . .
Values Returned . .
Examples . . . . . .
Truth Table . . . . . . . .

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

4-2
4-3
4-3
4-3
4-3
4-5
4-5
4-5
4-5
4-6
4-6
4-6
4-6
4-8
4-8
4-8
4-8
4-9

Contents

Scalar Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5-1

A Reference to Pervasive PSQL Scalar Functions

String Functions. . . . . . . . . . . . . . . . . . .
Examples . . . . . . . . . . . . . . . . . . .
Numeric Functions . . . . . . . . . . . . . . . . .
Examples . . . . . . . . . . . . . . . . . . .
Time and Date Functions . . . . . . . . . . . . .
Inserting Time and Date Function Values .
Examples . . . . . . . . . . . . . . . . . . .
System Functions . . . . . . . . . . . . . . . . . .
Examples . . . . . . . . . . . . . . . . . . .
Logical Functions . . . . . . . . . . . . . . . . . .
Examples . . . . . . . . . . . . . . . . . . .
Conversion Functions . . . . . . . . . . . . . . .
Examples . . . . . . . . . . . . . . . . . . .

.
.
.
.
.
.
.
.
.
.
.
.
.

System Stored Procedures . . . . . . . . . . . . . . . . . . . . . .

5-2
5-4
5-6
5-8
5-9
5-9
5-14
5-16
5-16
5-17
5-17
5-20
5-21

6-1

A Reference to Pervasive PSQL System Stored Procedures

Pervasive PSQL System Stored Procedures .
psp_columns . . . . . . . . . . . . . .
psp_column_attributes . . . . . . . .
psp_column_rights. . . . . . . . . . .
psp_fkeys . . . . . . . . . . . . . . . .
psp_groups . . . . . . . . . . . . . . .
psp_help_sp . . . . . . . . . . . . . .
psp_help_trigger . . . . . . . . . . . .
psp_help_udf . . . . . . . . . . . . . .
psp_help_view . . . . . . . . . . . . .
psp_indexes. . . . . . . . . . . . . . .
psp_pkeys . . . . . . . . . . . . . . . .
psp_procedure_rights . . . . . . . . .
psp_rename. . . . . . . . . . . . . . .
psp_stored_procedures . . . . . . . .
psp_tables. . . . . . . . . . . . . . . .
psp_table_rights . . . . . . . . . . . .
psp_triggers. . . . . . . . . . . . . . .
psp_udfs . . . . . . . . . . . . . . . .
psp_users . . . . . . . . . . . . . . . .
psp_view_rights . . . . . . . . . . . .
psp_views . . . . . . . . . . . . . . . .

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

6-2
6-3
6-6
6-9
6-13
6-15
6-17
6-19
6-21
6-23
6-25
6-28
6-29
6-32
6-33
6-36
6-39
6-41
6-43
6-45
6-47
6-50

vii

Contents

Performance Reference . . . . . . . . . . . . . . . . . . . . . . . .

7-1

An Examination of the Performance Features in the Database Engine

Restriction Analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7-2
Modified CNF Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7-2
Restrictions that Cannot be Converted . . . . . . . . . . . . . . . . . . . . . . .
7-2
Conditions Under Which Conversion is Avoided . . . . . . . . . . . . . . . . .
7-2
Restriction Optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7-4
Single Predicate Optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7-4
Closed Range Optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7-5
Modified Disjunct Optimization. . . . . . . . . . . . . . . . . . . . . . . . . . .
7-5
Conjunct Optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7-5
Disjunctive Normal Form Optimization . . . . . . . . . . . . . . . . . . . . . .
7-6
Modified Conjunctive Normal Form Optimization . . . . . . . . . . . . . . . .
7-7
Closing Open Ended Ranges through Modified CNF Optimization . . . . . . .
7-7
Single Join Condition Optimization . . . . . . . . . . . . . . . . . . . . . . . . .
7-8
Conjunct with Join Conditions Optimization . . . . . . . . . . . . . . . . . . .
7-9
Modified Conjunctive Normal Form with Join Conditions Optimization . . . .
7-9
Closing Join Condition Open Ended Ranges through Modified CNF Optimization 7-10
Multi-Index Modified Disjunct Optimization . . . . . . . . . . . . . . . . . . . 7-10
Push-Down Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-11
Efficient Use of Indexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-12
DISTINCT in Aggregate Functions . . . . . . . . . . . . . . . . . . . . . . . . . 7-12
DISTINCT Preceding Selection-list . . . . . . . . . . . . . . . . . . . . . . . . . 7-12
Relaxed Index Segment Order Sensitivity . . . . . . . . . . . . . . . . . . . . . . 7-12
Relaxed Segment Ascending Attribute Sensitivity . . . . . . . . . . . . . . . . . 7-13
Search Update Optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-14
Temporary Table Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-15
Row Pre-fetch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-16
Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-18

Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

A-1

Pervasive PSQL Supported Data Types

Pervasive PSQL Supported Data Types. . . . . . . . . . . . . . . .
Data Type Ranges . . . . . . . . . . . . . . . . . . . . . . . .
Operator Precedence . . . . . . . . . . . . . . . . . . . . . .
Data Type Precedence. . . . . . . . . . . . . . . . . . . . . .
Precision and Scale of Decimal Data Types . . . . . . . . . .
Truncation . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Notes on Data Types . . . . . . . . . . . . . . . . . . . . . . . . . .
CHAR, VARCHAR, and LONGVARCHAR . . . . . . . . .
BINARY and LONGVARBINARY . . . . . . . . . . . . . . .
Limitations on LONGVARCHAR and LONGVARBINARY

viii

.
.
.
.
.
.
.
.
.
.

A-2
A-5
A-6
A-8
A-9
A-10
A-11
A-11
A-11
A-12

Contents

DATETIME. . . . . . . . .
UNIQUEIDENTIFIER. . .
Representation of Infinity .
Legacy Data Types . . . . . . . .
Btrieve Key Data Types . . . . . .

.
.
.
.
.

. A-13
. A-17
. A-19
. A-20
. A-21

SQL Reserved Words . . . . . . . . . . . . . . . . . . . . . . . . .

B-1

Supported Pervasive PSQL Reserved Words

Reserved Words . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Words to Avoid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

System Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

B-2
B-7

C-1

Pervasive PSQL System Tables Reference

Overview. . . . . . . . . . . . . . .
System Tables Structure . . . . . .
V1 Metadata System Tables .
V2 Metadata System Tables .

.
.
.
.

. C-2
. C-4
. C-4
. C-19

SQL Access for COBOL Applications . . . . . . . . . . . . . . . .

D-1

Providing SQL Access for COBOL Applications

Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . .
SQL Statements. . . . . . . . . . . . . . . . . . . . . . . . .
Components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using SQL Access . . . . . . . . . . . . . . . . . . . . . . . . . . .
Step 1: Modify the Sample XML Templates . . . . . . . . .
Step 2: Copy the Data File Specified in the XML Template .
Step 3: Run the Schema Executor Utility . . . . . . . . . . .
Step 4: Optionally, Deploy the System Tables . . . . . . . .
Example of How to Execute a Sample XML File . . . . . . . . . .
Additional Notes . . . . . . . . . . . . . . . . . . . . . . . .

.
.
.
.
.
.
.
.
.
.
.

. D-2
. D-2
. D-3
. D-4
. D-6
. D-6
. D-6
. D-6
. D-12
. D-13
. D-13

Query Plan Viewer . . . . . . . . . . . . . . . . . . . . . . . . . . .

E-1

A Utility To Help You Optimize Queries

Query Plan Settings . . . . . . . . . . . . . . . . . . . . . . .
Graphical User Interface . . . . . . . . . . . . . . . . . . . .
Query Pane . . . . . . . . . . . . . . . . . . . . . . . .
Plan Pane . . . . . . . . . . . . . . . . . . . . . . . . .
Query Plan Viewer Tasks . . . . . . . . . . . . . . . . . . . .
Examining Query Plans and Evaluating Query Performance
Creating Example Query Plans for Comparison. . . .
Viewing the Example Query Plans . . . . . . . . . . .

.
.
.
.
.
.
.
.

E-2
E-3
E-3
E-3
E-7
E-9
E-9
E-10

Figures
3-1

COALESCE Supported Combinations and Resultant Data Types . . . . . . . . . 3-42

Tables
1-1
1-2
1-3
1-4
1-5
1-6
1-7
1-8
1-9
1-10
1-11
1-12
1-13
1-14
1-15
1-16
1-17
1-18

SQL Statement Types and Related Tasks . . . . . . . . . . . .

Data Definition StatementsTables . . . . . . . . . . . . . .
Data Definition StatementsViews . . . . . . . . . . . . . .
Data Definition StatementsIndexes . . . . . . . . . . . . .
Data Definition StatementsTriggers . . . . . . . . . . . . .
Data Definition StatementsTrigger Control. . . . . . . . .
Data Definition StatementsStored Procedure . . . . . . .
Data Definition StatementsStored Procedure Control . . .
Data Definition StatementsUser-Defined Function . . . .
Data Manipulation StatementsRetrieving Data . . . . . . .
Data Manipulation StatementsRetrieving Data Options . .
Data Manipulation StatementsModifying Data. . . . . . .
Data Manipulation StatementsViews . . . . . . . . . . . .
Data Manipulation Statements- Stored Procedures . . . . . .
Data Manipulation StatementsSystem Stored Procedures .
Data Control StatementsSecurity . . . . . . . . . . . . . .
Data Control StatementsGroups and Users . . . . . . . . .
Data Control StatementsRights . . . . . . . . . . . . . . .

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

1-1
1-3
1-4
1-4
1-4
1-4
1-5
1-5
1-6
1-7
1-8
1-8
1-9
1-9
1-9
1-10
1-11
1-11

2-1
2-2
2-3
2-4
2-5
2-6
2-7
2-8

Limits/Conditions of Pervasive PSQL Features . . .

Valid Connection Strings for Client DSNs . . . . . .
Valid Connection Strings for Engine DSNs . . . . .
Interface-supported ODBC API Functions . . . . .
Exceptions to ODBC Statement Attribute Support .
Exceptions to ODBC Connection Attribute Support
Exceptions to ODBC Descriptor Support . . . . . .
SQL Grammar Support . . . . . . . . . . . . . . . .

.
.
.
.
.
.
.
.

2-3
2-7
2-8
2-9
2-14
2-15
2-16
2-17

3-1
3-2
3-3
3-4
3-5
3-6
3-7
3-8
3-9
3-10
3-11
3-12

Supported Input Parameters and Returned Data Types . . . . . . . . . . .

Data Types Prohibited in Stored Procedures and Triggers . . . . . . . . . .
Characteristics of Temporary Tables . . . . . . . . . . . . . . . . . . . . . .
Allowed DEFAULT Expression Data Types . . . . . . . . . . . . . . . . . .
Date and Time Scalar Functions as Default Values . . . . . . . . . . . . . .
Permissions Applicable To Object Type . . . . . . . . . . . . . . . . . . . .
Permissions Granted with ALL Key Word by Object Type . . . . . . . . . .
Characteristics of Trusted and Non-trusted Views and Stored Procedures .
Default Values and Nullable Columns . . . . . . . . . . . . . . . . . . . . .
Emp Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Dept Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Addr Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

.
.
.
.
.
.
.
.
.
.
.
.

3-52
3-70
3-95
3-117
3-122
3-151
3-152
3-155
3-167
3-175
3-175
3-175

.
.
.
.
.
.
.
.

Tables

3-13
3-14
3-15
3-16
3-17
3-18
3-19
3-20
3-21
3-22
3-23
3-24
3-25
3-26
3-27

Loc Table. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Two-way Left Outer Join . . . . . . . . . . . . . . . . . . . .
Three-way Radiating Left Outer Join . . . . . . . . . . . . .
Three-way Chaining Left Outer Join . . . . . . . . . . . . .
Three-way Radiating Left Outer Join, Less Optimized . . . .
Special Characters . . . . . . . . . . . . . . . . . . . . . . . .
Permissions Removed with ALL Key Word by Object Type .
Addr Table . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Loc Table. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SELECT Statement with Cartesian JOIN . . . . . . . . . . .
Effect of TOP Clause on Cursor Types . . . . . . . . . . . .
Time/Date Functions with SET TIME ZONE Default . . . .
Time/Date Functions with SET TIME ZONE Specified . . .
Local to UTC Conversion Examples . . . . . . . . . . . . . .
Timestamp Data Type Examples. . . . . . . . . . . . . . . .

4-1

Truth Table for Bitwise Operations . . . . . . . . . . . . . . . . . . . . . . . . . . 4-9

5-1
5-2
5-3
5-4
5-5
5-6

String Functions . . . . . .
Numeric Functions . . . .
Time and Date Functions.
System Functions . . . . .
Logical Functions . . . . .
Conversion Functions. . .

.
.
.
.
.
.

. 5-2
. 5-6
. 5-9
. 5-16
. 5-17
. 5-21

6-1
6-2
6-3
6-4
6-5
6-6
6-7
6-8
6-9
6-10
6-11
6-12
6-13
6-14
6-15
6-16
6-17
6-18
6-19
6-20

Pervasive PSQL System Stored Procedures .

psp_columns Arguments . . . . . . . . . . .
psp_columns Returned Result Set . . . . . .
psp_column_attributes Arguments . . . . .
psp_column_attributes Returned Result Set
psp_column_rights Arguments . . . . . . .
psp_column_rights Returned Result Set . .
psp_fkeys Arguments . . . . . . . . . . . . .
psp_fkeys Returned Result Set . . . . . . . .
psp_groups Arguments . . . . . . . . . . . .
psp_groups Returned Result Set . . . . . . .
psp_help_sp - Arguments . . . . . . . . . .
psp_help_sp - Returned Result Set. . . . . .
psp_help_trigger - Arguments . . . . . . . .
psp_help_trigger - Returned Result Set . . .
psp_help_udf - Arguments . . . . . . . . . .
psp_help_udf - Returned Result Set . . . . .
psp_help_view - Arguments . . . . . . . . .
psp_help_view - Returned Result Set . . . .
psp_indexes Arguments . . . . . . . . . . .

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

. 6-2
. 6-3
. 6-3
. 6-7
. 6-7
. 6-10
. 6-10
. 6-13
. 6-14
. 6-16
. 6-16
. 6-17
. 6-18
. 6-20
. 6-20
. 6-21
. 6-22
. 6-24
. 6-24
. 6-25

xii

.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

. 3-175
. 3-176
. 3-177
. 3-178
. 3-179
. 3-181
. 3-195
. 3-221
. 3-221
. 3-222
. 3-223
. 3-253
. 3-253
. 3-254
. 3-254

Tables

6-21
6-22
6-23
6-24
6-25
6-26
6-27
6-28
6-29
6-30
6-31
6-32
6-33
6-34
6-35
6-36
6-37
6-38
6-39
6-40
6-41
6-42

psp_indexes Returned Result Set . . . . . . .

psp_pkeys Arguments . . . . . . . . . . . . .
psp_pkeys Returned Result Set . . . . . . . .
psp_procedure_rights Arguments . . . . . .
psp_procedure_rights Returned Result Set .
psp_rename Arguments . . . . . . . . . . . .
psp_stored_procedures Arguments. . . . . .
psp_stored_procedures Returned Result Set.
psp_tables Arguments . . . . . . . . . . . .
psp_tables Returned Result Set . . . . . . .
psp_table_rights Arguments . . . . . . . . .
psp_table_rights Returned Result Set. . . . .
psp_triggers Arguments . . . . . . . . . . . .
psp_triggers Returned Result Set . . . . . . .
psp_udfs Arguments . . . . . . . . . . . . . .
psp_udfs Returned Result Set . . . . . . . . .
psp_users Arguments . . . . . . . . . . . . .
psp_users Returned Result Set . . . . . . . .
psp_view_rights Arguments. . . . . . . . . .
psp_view_rights Returned Result Set . . . . .
psp_views Arguments . . . . . . . . . . . . .
psp_views Returned Result Set . . . . . . . .

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

6-26
6-28
6-28
6-30
6-30
6-32
6-33
6-34
6-36
6-37
6-39
6-40
6-42
6-42
6-44
6-44
6-45
6-46
6-47
6-48
6-50
6-50

A-1
A-2
A-3
A-4
A-5
A-6
A-7
A-8
A-9
A-10
A-11
A-12
A-13
A-14
A-15
A-16

Pervasive PSQL Data Types and Equivalent ODBC Data Types . . .

Pervasive PSQL Data Type Ranges . . . . . . . . . . . . . . . . . . .
Calculation of Precision and Scale for DECIMAL Operation . . . .
DATETIME Components and Valid Values . . . . . . . . . . . . . .
Millisecond Rounding . . . . . . . . . . . . . . . . . . . . . . . . . .
Operands Involving DATE, DATETIME, TIME, and TIMESTAMP
Permitted CONVERT Operations . . . . . . . . . . . . . . . . . . .
Permitted CAST Operations . . . . . . . . . . . . . . . . . . . . . .
Infinity Representation . . . . . . . . . . . . . . . . . . . . . . . . .
Data Types Used to Replace Legacy Data Types . . . . . . . . . . . .
Btrieve Key Data Types and Type Codes . . . . . . . . . . . . . . . .
INTEGER Key Type . . . . . . . . . . . . . . . . . . . . . . . . . . .
Comparison of Shifted and Unshifted Sign Values for NUMERICS .
Specifying the DBCobolNumeric Setting for Different Platforms . .
Sign Values for NUMERICSA. . . . . . . . . . . . . . . . . . . . . .
TIMESTAMP Components . . . . . . . . . . . . . . . . . . . . . . .

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

A-2
A-5
A-10
A-13
A-14
A-14
A-16
A-17
A-19
A-20
A-21
A-30
A-31
A-32
A-33
A-35

B-1

Words to Avoid as User-Defined Names. . . . . . . . . . . . . . . . . . . . . . . B-7

C-1
C-2
C-3

System Tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-3

X$Attrib System Table Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . C-4
X$Attrib System Table Index Definitions . . . . . . . . . . . . . . . . . . . . . . C-5

xiii

Tables

C-4
C-5
C-6
C-7
C-8
C-9
C-10
C-11
C-12
C-13
C-14
C-15
C-16
C-17
C-18
C-19
C-20
C-21
C-22
C-23
C-24
C-25
C-26
C-27
C-28
C-29
C-30
C-31
C-32
C-33
C-34
C-35
C-36
C-37
C-38
C-39
C-40
C-41
C-42
C-43
C-44
C-45
C-46
C-47
C-48

xiv

X$Depend System Table Structure. . . . . . . . . . . . . . .

X$Depend System Table Index Definitions . . . . . . . . . .
X$Field System Table Structure . . . . . . . . . . . . . . . .
X$Field System Table Index Definitions . . . . . . . . . . .
X$File System Table Structure . . . . . . . . . . . . . . . . .
X$File System Table Index Definitions . . . . . . . . . . . .
X$Index System Table Structure . . . . . . . . . . . . . . . .
X$Index System Table Index Definitions . . . . . . . . . . .
X$Index System Table Index Definitions . . . . . . . . . . .
X$Proc System Table Structure . . . . . . . . . . . . . . . .
X$Proc System Table Index Definitions . . . . . . . . . . . .
X$Relate System Table Structure. . . . . . . . . . . . . . . .
X$Relate System Table Index Definitions . . . . . . . . . . .
X$Rights System Table Structure . . . . . . . . . . . . . . .
Xr$Rights System Table Bit Position Definitions . . . . . . .
X$Rights System Table Index Definitions . . . . . . . . . . .
X$Trigger System Table Structure . . . . . . . . . . . . . . .
X$Trigger System Table Index Definitions . . . . . . . . . .
X$User System Table Structure . . . . . . . . . . . . . . . .
Xu$Flags System Table Bit Position Definitions . . . . . . .
X$User System Table Index Definitions . . . . . . . . . . . .
X$View System Table Structure . . . . . . . . . . . . . . . .
X$View System Table Index Definitions . . . . . . . . . . .
X$Attrib System Table Structure for V2 Metadata . . . . . .
X$Attrib System Table Index Definitions for V2 Metadata .
X$Depend System Table Structure for V2 Metadata . . . . .
X$Depend System Table Index Definitions for V2 Metadata
X$Field System Table Structure for V2 Metadata. . . . . . .
X$Field System Table Index Definitions for V2 Metadata . .
X$File System Table Structure for V2 Metadata . . . . . . .
X$File System Table Index Definitions for V2 Metadata. . .
X$Index System Table Structure for V2 Metadata . . . . . .
Xi$Flags Bit Positions for V2 Metadata . . . . . . . . . . . .
X$Index System Table Index Definitions for V2 Metadata .
X$Proc System Table Structure for V2 Metadata . . . . . . .
X$Proc System Table Index Definitions for V2 Metadata . .
X$Relate System Table Structure for V2 Metadata . . . . . .
X$Relate System Table Index Definitions for V2 Metadata .
X$Rights System Table Structure for V2 Metadata . . . . . .
Xr$Rights Bit Positions for V2 Metadata . . . . . . . . . . .
X$Rights System Table Index Definitions for V2 Metadata .
X$Trigger System Table Structure for V2 Metadata . . . . .
X$Trigger System Table Index Definitions for V2 Metadata
X$User System Table Structure for V2 Metadata . . . . . . .
Xu$Flags Bit Positions for V2 Metadata . . . . . . . . . . . .

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

. C-5
. C-5
. C-6
. C-8
. C-8
. C-9
. C-9
. C-9
. C-10
. C-11
. C-12
. C-12
. C-13
. C-13
. C-14
. C-14
. C-15
. C-15
. C-16
. C-17
. C-17
. C-18
. C-18
. C-19
. C-19
. C-20
. C-20
. C-21
. C-23
. C-23
. C-24
. C-24
. C-25
. C-26
. C-27
. C-28
. C-28
. C-29
. C-29
. C-30
. C-31
. C-32
. C-33
. C-33
. C-34

Tables

C-49
C-50
C-51

X$User System Table Index Definitions for V2 Metadata . . . . . . . . . . . . . C-34

X$View System Table Structure for V2 Metadata . . . . . . . . . . . . . . . . . . C-35
X$View System Table Index Definitions . . . . . . . . . . . . . . . . . . . . . . . C-36

D-1
D-2
D-3
D-4

Use of SQL Statements With COBOL Data Constructs . . . . . . . . . .

Components Installed to Provide SQL Access for COBOL Applications
Options for Schema Executor Utility . . . . . . . . . . . . . . . . . . . .
Possible Error Codes in a CobolSchemaExec Log File . . . . . . . . . .

E-1
E-2

Query Plan SQL Statements for Settings . . . . . . . . . . . . . . . . . . . . . . . E-2

Plan Pane Nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-4

.
.
.
.

D-3
D-4
D-8
D-11

Tables

xvi

About This Manual

This manual contains the reference material you need for
understanding the language functionality and limitations of
Pervasive PSQL v10.

xvii

Who Should Read this Manual

This manual provides information for using Pervasive PSQL v10.
This manual assumes you have a general understanding of ODBC
architecture and ODBC driver components, and have access to the
Microsoft ODBC Software Development Kit.
This document also assumes you have a working understanding of
modern database principles and terminology, the C language, and
your development environment (compiler and linker).
Pervasive Software would appreciate your comments and
suggestions about this manual. As a user of our documentation, you
are in a unique position to provide ideas that can have a direct
impact on future releases of this and other manuals. If you have
comments or suggestions for the product documentation, post your
request at http://www.pervasive.com/devtalk.

xviii

Manual Organization
This reference includes the following chapters:

Chapter 1 SQL Overview

This chapter describes the types of SQL statements you can
create using Pervasive PSQL.

Chapter 2 ODBC Engine Reference

This chapter describes Pervasive PSQL capabilities,
characteristics, and conformance to the SQL grammar and
ODBC API standards.

Chapter 3 SQL Syntax Reference

This chapter describes the SQL grammar and syntax supported
by Pervasive PSQL.

Chapter 4Bitwise Operators

This chapter describes the bitwise operators used to manipulate
the bits of one or more operands.

Chapter 5Scalar Functions

This chapter describes the various functions that operate on a
single value and then return a single value.

Chapter 6System Stored Procedures

This chapter describes the procedures that help you accomplish
administrative and informative tasks that are not covered by the
Data Definition Language.

Chapter 7 Performance Reference

This chapter explains in detail the optimizations used in the
database engine and how to best take advantage of them in your
SQL statements.

xix

Appendix A Data Types

This appendix contains tables of supported Data Types.

Appendix B SQL Reserved Words

This appendix contains the list of supported SQL Keywords.

Appendix C System Tables

This appendix describes the system tables that comprise the
relational data dictionary.

Appendix D SQL Access for COBOL Applications

This appendix describes the relational interface support for
COBOL OCCURS constructs, partial REDEFINES, and variable
record layouts.

Appendix E Query Plan Viewer

This appendix describes the graphical utility with which you can
view query plans selected by the database engine, and optimize
your queries.

The manual also contains an index.

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

Commands and reserved words typically appear in uppercase

letters. Unless the manual states otherwise, you can enter
these items using uppercase, lowercase, or both. For
example, you can type MYPROG, myprog, or MYprog.

[ ]

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.

An asterisk is used as a wildcard symbol to indicate a series

of APIs with the same prefix.

Note Unless otherwise noted, all references in this book to the

Pervasive PSQL product refer to the current version, Pervasive

PSQL v10.

xxi

For More Information

For complete information on the ODBC specification, see the
Microsoft ODBC Programmers Reference.

xxii

chapter

SQL Overview
An Overview of the Structured Query Language (SQL)

Structured Query Language (SQL) is a database language consisting

of English-like statements you can use to perform database
operations. Both the American National Standards Institute (ANSI)
and IBM have defined standards for SQL. (The IBM standard is the
Systems Application Architecture [SAA].) The Pervasive PSQL
product implements most of the features of both ANSI SQL and IBM
SAA SQL and provides additional extensions that neither standard
specifies.
Pervasive PSQL allows you to create different types of SQL
statements. The following table lists the types of SQL statements you
can create and the tasks you can accomplish using each type of
statement:
Table 1-1 SQL Statement Types and Related Tasks
SQL Statement Type

Tasks

Data Definition

Create, modify, and delete tables.

Create and delete views.
Create and delete indexes.
Create and delete stored SQL procedures.
Create and delete triggers.
Create and delete user-defined functions.

Data Manipulation

Retrieve, insert, update, and delete data in tables.

Define transactions.
Define and delete views.
Execute stored SQL procedures.
Execute triggers.

Data Control

Enable and disable security for a dictionary.

Create and delete users.
Add and drop users from groups.
Change user passwords.
Grant and revoke table access rights.

1-1

SQL Overview

The rest of this chapter briefly describes the SQL statements used in
each statement category. For detailed information about each
statement, refer to SQL Syntax Reference on page 3-1.
The following are the statement category overview sections found in
this chapter:

1-2

Data Definition Statements on page 1-3

Data Manipulation Statements on page 1-7
Data Control Statements on page 1-10

Data Definition Statements

Data definition statements let you specify the characteristics of your
database. When you execute data definition statements, Pervasive
PSQL stores the description of your database in a data dictionary.
You must define your database in the dictionary before you can store
or retrieve information.
Pervasive PSQL allows you to construct data definition statements to
do the following:

Create, modify, and delete tables.

Create and delete views.
Create and delete indexes.
Create and delete triggers.
Create and delete stored procedures.
Create and delete user-defined functions.

The following sections briefly describe the SQL statements

associated with each of these tasks. For general information about
defining the characteristics of your database, refer to the Pervasive
PSQL Programmer's Guide, available in the Pervasive PSQL Software
Developer Kit (SDK).

Creating,
You can create, modify, and delete tables from a database by
Modifying, and constructing SQL using the following statements:
Deleting Tables Table 1-2 Data Definition StatementsTables
CREATE
TABLE

Defines a table and optionally creates the corresponding data

file.

ALTER TABLE

Changes a table definition. With an ALTER TABLE statement,

you can perform such actions as add a column to the table
definition, remove a column from the table definition, change a
columns data type or length (or other characteristics), and add
or remove a primary key or a foreign key and associate the table
definition with an different data file.

DROP TABLE

Deletes a table from the data dictionary and optionally deletes

the associated data file from the disk.

1-3

SQL Overview

Creating and
Deleting Views

You can create and delete views from a database by constructing SQL
using the following statements:
Table 1-3 Data Definition StatementsViews

Creating and
Deleting
Indexes

Creating and
Deleting
Triggers

CREATE VIEW

Defines a new view.

DROP VIEW

Deletes a view.

You can create and delete indexes from a database by constructing

SQL using the following statements:
Table 1-4 Data Definition StatementsIndexes
CREATE INDEX

Defines a new index (a named index) for an existing table.

DROP INDEX

Deletes a named index.

You can create and delete triggers from a database by constructing

SQL using the following statements:
Table 1-5 Data Definition StatementsTriggers
CREATE TRIGGER

Defines a trigger for an existing table.

DROP TRIGGER

Deletes a trigger.

Pervasive PSQL provides additional SQL control statements, which

you can only use in the body of a trigger. You can use the following
statements in triggers:
Table 1-6 Data Definition StatementsTrigger Control
BEFORE

Defines the trigger execution before the INSERT,

UPDATE, or DELETE operation.

AFTER

Defines the trigger execution after the INSERT, UPDATE,

or DELETE operation.

Creating and
A stored procedure consists of statements you can precompile and
Deleting Stored save in the dictionary. To create and delete stored procedures,
construct statements using the following:
Procedures

1-4

Data Definition Statements

Table 1-7 Data Definition StatementsStored Procedure

CREATE
PROCEDURE

Stores a new procedure in the data dictionary.

DROP
PROCEDURE

Deletes a stored procedure from the data dictionary.

Pervasive PSQL provides additional SQL control statements, which

you can only use in the body of a stored procedure. You can use the
following statements in stored procedures:
Table 1-8 Data Definition StatementsStored Procedure Control

Creating and
Deleting UserDefined
Functions
(UDF)

IF...THEN...ELSE

Provides conditional execution based on the truth value of

a condition.

LEAVE

Continues execution by leaving a block or loop statement.

LOOP

Repeats the execution of a block of statements.

WHILE

Repeats the execution of a block of statements while a

specified condition is true.

In addition to the built-in functions, Pervasive PSQL allows you to

create your own user-defined functions (UDF) and use them in
Pervasive PSQL statements.
A user-defined function is a database object that encapsulates one or
more Pervasive PSQL statements that can be reused. A user-defined
function takes zero or more input arguments and evaluates a return
value, which is a scalar value.
User-defined functions are always defined within the context of a
database. Successful execution of this statement results in the storing
of the UDF definition in the specific database. Once stored, the UDF
can be modified, invoked, and deleted.
Pervasive PSQL supports scalar user-defined functions.

1-5

SQL Overview

A scalar user-defined function returns a single value of the data type

specified in the RETURNS clause of the Pervasive PSQL statement.
A scalar UDF can contain multiple Pervasive PSQL statements. You
can specify any data type value for the returned data except text,
ntext, image, cursor, or timestamp.
To create and delete user-defined functions, construct statements
using the following:
Table 1-9 Data Definition StatementsUser-Defined Function

1-6

CREATE
FUNCTION

Creates a scalar user-defined function in the database.

DROP
FUNCTION

Deletes a scalar user-defined function from the database.

Data Manipulation Statements

Data manipulation statements let you access and modify the
contents of your database. Pervasive PSQL allows you to construct
data manipulation statements to do the following:

Retrieve data from tables.

Modify data in tables.
Define transactions.
Create and delete views.
Execute stored procedures.
Execute triggers.

The following sections briefly describe the SQL statements

associated with each of these tasks.

Retrieving Data All statements you use to retrieve information from a database are
based on the SELECT statement.
Table 1-10 Data Manipulation StatementsRetrieving Data
SELECT

Retrieves data from one or more tables in the database.

When you create a SELECT statement, you can use various clauses to
specify different options. (See the entry for the SELECT statement in
ODBC Engine Reference on page 2-1 for detailed information
about each type of clause.) The types of clauses you use in a SELECT
statement are as follows:

1-7

SQL Overview

Table 1-11 Data Manipulation StatementsRetrieving Data Options

FROM

Specifies the tables or views from which to retrieve data.

WHERE

Defines search criteria that qualify the data a SELECT statement

retrieves.

GROUP
BY

Combines sets of rows according to the criteria you specify and

allows you to determine aggregate values for one or more columns in
a group.

HAVING

Allows you to limit a view by specifying criteria that the aggregate

values of a group must meet.

ORDER
BY

Determines the order in which Pervasive PSQL returns selected

rows.

In addition, you can use the UNION keyword to obtain a single

result table from multiple SELECT queries.

Modifying Data

You can add, change, or delete data from tables and views by issuing
statements such as the following:
Table 1-12 Data Manipulation StatementsModifying Data
INSERT

Adds rows to one or more tables or a view.

UPDATE

Changes data in a table or a view.

DELETE

Deletes rows from a table or a view.

When you create a DELETE or UPDATE statement, you can use a

WHERE clause to define search criteria that restrict the data upon
which the statement acts.

Defining
Transactions

To update the data in a database, you can issue SQL statements

individually or you can define transactions (logical units of related
statements). By defining transactions, you can ensure that either all
the statements in a unit of work are executed successfully or none are
executed. You can use transactions to group statements to ensure the
logical integrity of your database.
Pervasive PSQL supports the ODBC API SQLTransact. See the
Microsoft ODBC Programmers Reference for more information.

1-8

Data Manipulation Statements

Creating and
Deleting Views

You can create and delete views by constructing SQL using the
following statements:
Table 1-13 Data Manipulation StatementsViews

Executing
Stored
Procedures

CREATE VIEW

Defines a database view and stores the definition in the

dictionary.

DROP VIEW

Deletes a view from the data dictionary.

A stored procedure consists of statements that you can precompile

and save in the dictionary. To execute stored procedures, construct
statements using the following:
Table 1-14 Data Manipulation Statements- Stored Procedures
CALL or
EXEC[UTE]

Executing
System Stored
Procedures

Recalls a previously compiled procedure and executes it.

A system stored procedure helps you accomplish those

administrative and informative tasks that are not covered by the Data
Definition Language. The system stored procedures have a psp_
prefix. To execute stored procedures, construct statements using the
following:
Table 1-15 Data Manipulation StatementsSystem Stored Procedures
CALL or
EXEC[UTE]

Recalls a system stored procedure and executes it.

For more details, see System Stored Procedures on page 6-1.

Executing
Triggers

A trigger consists of statements you can precompile and save in the

dictionary. Triggers are executed automatically by the engine when
the specified conditions occur.

1-9

SQL Overview

Data Control Statements

Data control statements let you define security for your database.
When you create a dictionary, no security is defined for it until you
explicitly enable security for that dictionary. Pervasive PSQL allows
you to construct data control statements to do the following:

Enable and disable security.

Create and delete users and groups.
Add and drop users from groups and change user passwords.
Grant and revoke rights.
Note If you have a Btrieve owner name set on a file that is a table

in a secure database, the Master user of the database must use the
owner name in any GRANT statement to grant privileges on the
given table to any user, including the Master user.
The following sections briefly describe the SQL statements
associated with each of these tasks.

Enabling and
Disabling
Security

You can enable or disable security for a database by issuing

statements using the following statement:
Table 1-16 Data Control StatementsSecurity
SET
SECURITY

1-10

Enables or disables security for the database and sets the Master
password.

Data Control Statements

Creating and
Deleting Users
and Groups

Granting and
Revoking
Rights

You can create or delete users and user groups for the database by
constructing SQL using the following statements:
Table 1-17 Data Control StatementsGroups and Users
ALTER USER

Rename a user or change a users password.

CREATE USER

Creates a new user with or without a password or

membership in a group.

DROP USER

Delete a user.

ALTER GROUP

Adds users to a group. Drops users from a group.

CREATE GROUP

Creates a new group of users.

DROP GROUP

Deletes a group of users.

GRANT LOGIN TO

Creates users and passwords, or adds users to groups.

REVOKE LOGIN
FROM

Removes a user from the dictionary.

You can assign or remove rights from users or groups by issuing

statements using the following:
Table 1-18 Data Control StatementsRights
GRANT (access rights)

Grants a specific type of rights to a user or a group.

The rights you can grant with a GRANT (access
rights) statement are All, Insert, Delete, Alter, Select,
Update, and References.

GRANT CREATETAB TO

Grants the right to create tables to a user or a group.

REVOKE (access rights)

Revokes access rights from a user or a group.

REVOKE CREATETAB
FROM

Revokes the right to create tables from a user or a

group.

1-11

SQL Overview

1-12

chapter

ODBC Engine Reference

Limits, Connection Strings, and ODBC Support

This chapter contains information regarding the limits and support

of the Pervasive PSQL v10 ODBC interface:

Versions of Metadata on page 2-2

Data Source Name Connection String Keywords on page 2-7
ODBC Support on page 2-9
SQL Grammar Support on page 2-17

For detailed information on the ODBC API, SQL grammar, and

scalar functions, refer to the Microsoft ODBC Programmers
Reference.

2-1

ODBC Engine Reference

Versions of Metadata
The relational interface in Pervasive PSQL v10 supports two versions
of metadata, referred to as version 1 (V1) and version 2 (V2).
Metadata version is a property of the database that you specify when
you create a database. V1 metadata is the default. When you create a
database, you must specify V2 metadata if you want that version.
Metadata version applies to all data dictionary files (DDFs) within
that database. A single database cannot use some DDFs with V1
metadata and others with V2 metadata. DDFs from the two versions
cannot interact.
The database engine can, however, concurrently access multiple
databases and each database can use either V1 metadata or V2
metadata.
All databases created with Pervasive PSQL versions prior to Pervasive
PSQL v10 use V1 metadata. Databases created with Pervasive PSQL
v10 or later may use either metadata version depending on the
database settings.
Comparison of Metadata Versions
Version 2 metadata allows for many identifier names to be up to 128
bytes long. Refer to Limits/Conditions of Pervasive PSQL Features
on page 2-3 on page 2-3 for additional information. In addition, V2
metadata allows for permissions on views and stored procedures. See
Permissions on Views and Stored Procedures on page 3-153.
The data dictionary files (DDFs) for V2 metadata are named
differently than for V1. In many cases, the V2 DDFs contain
additional fields and changes to existing fields. See System Tables
on page C-1.
Conversion Utility
Pervasive PSQL includes a conversion utility, pvmdconv, to convert
V1 metadata to V2 metadata. See pvmdconv on page 8-40 in
Pervasive PSQL User's Guide.

Relational
The following table shows the limits or conditions that apply to
Interface Limits features of the relational interface.
2-2

Versions of Metadata

A Pervasive PSQL database may contain four billion objects in any

valid combination. The objects are persisted in the data dictionary
files.
See also Naming Conventions on page 12-6 in Pervasive PSQL
Programmer's Guide, which is part of the Pervasive PSQL Software
Developers Kit (SDK).
Table 2-1 Limits/Conditions of Pervasive PSQL Features
Pervasive PSQL Feature

Limit or Condition

Metadata
V1

Arguments in a parameter list for a

stored procedure

300

CHAR column size

8,000 bytes1

Character string literal

A character in the string may be any ANSI character

between 1 and 255 decimal.

Columns in a table

1,536

Columns allowed in a trigger or stored

procedure

300

Column name2

20 bytes

128 bytes
Column size

2 GB

Correlation name

limited by memory

Cursor name

18 bytes

Database name2

20 bytes

Database sessions

limited by memory

Data file path name

64 bytes (the maximum length of the data file path

name is a combination of Xf$Loc path and the data file
path)

250 bytes (the maximum length of the data file path

name is a combination of Xf$Loc path and the data file
path)

2-3

ODBC Engine Reference

Table 2-1 Limits/Conditions of Pervasive PSQL Features continued

Pervasive PSQL Feature

Limit or Condition

Metadata
V1

Function (user-defined) name2

30 bytes

128 bytes
Group name2

30 bytes

128 bytes
Index name2

20 bytes

128 bytes
Key name2

20 bytes

128 bytes
Label name

limited by memory

Number of ANDed predicates

300

Number of database objects

65,536

2 billion
Parameter name

126 bytes

Password2

8 bytes

128 bytes
Procedure name2

30 bytes

128 bytes
Referential integrity (RI) constraint
name

20 bytes

128 bytes
Representation of single quote

Two consecutive single quotes ()

Result name

limited by memory

2-4

Versions of Metadata

Table 2-1 Limits/Conditions of Pervasive PSQL Features continued

Pervasive PSQL Feature

Limit or Condition

Metadata
V1

Savepoint name

limited by memory

SELECT list columns in a query

1,600

Size of a single term (quoted literal

string) in an SQL statement

14,997, excluding null terminator and quotations

(15,000 total)

SQL statement length

64 KB

SQL statements per session

limited by memory

Stored procedure size

64 KB

Table name2

20 bytes

128 bytes
Table rows

2 billion

Joined tables per query

limited by memory

Trigger name2

20 bytes

128 bytes
User name2

30 bytes

128 bytes
VARCHAR column size

8,000 bytes1

Variable name

limited by memory

View name2

20 bytes

128 bytes

The maximum size of a CHAR or VARCHAR column that may be fully indexed is 255 bytes

See also Identifier Restrictions by Identifier Type on page 1-3 in Advanced Operations Guide.

2-5

ODBC Engine Reference

Fully Qualified
Object Names

A fully qualified object name combines the name of the database and
the object using dot notation. For example, if you have a view named
myview in database mydbase, the fully qualified object name is
mydbase.myview.
Fully qualified object names need to be unique within a database. For
example, suppose in database mydbase, you name a table acctpay
and a user-defined function (or any other object) acctpay. The fully
qualified name is mydbase.acctpay, in which case Pervasive PSQL
does not know to which object the name refers.

2-6

Data Source Name Connection String Keywords

A connection string used to connect to a DSN may include any
number of driver-defined keywords. Using these keywords, the
driver has enough information to connect to the data source. The
driver (for example, the Pervasive ODBC Engine Interface or
Pervasive ODBC Client Interface) defines which keywords are
required to connect to the data source.
Connection strings serve the same purpose in Pervasive PSQL v10 as
they did in previous versions. They are used to identify which data
source to connect to. The difference now lies in the driver-defined
keywords listed in the connection string. Pervasive.SQL 7 used a
different set of keywords to identify a data source.
Listed below are the keywords used in Pervasive PSQL v10
connection strings.
Table 2-2 Valid Connection Strings for Client DSNs
DSN

Name of the data source as returned by

SQLDataSources or the data sources dialog box of
SQLDriverConnect.

DRIVER

The description of the driver as returned by SQLDrivers

function. For a Client DSN, it is "Pervasive ODBC Client
Interface".

ServerName

The address of the server or host name and the port

number where the data resides. See also Changing
the Default Communication Ports on page 10-10 in
Getting Started With Pervasive PSQL.

ServerDSN

The name of an Engine data source referenced by this

DSN.

TransportHint

Specifies the transport protocols to check for the

ServerName. The list of transport protocols is specified
in the order in which they should be searched.

PWD

The password corresponding to the user ID.

ArrayFetchOn

Enable array fetching. Array fetching is used to improve

performance of data fetching between the client and
the server. The default setting is to enable array
fetching.

2-7

ODBC Engine Reference

Table 2-2 Valid Connection Strings for Client DSNs continued

ArrayBufferSize

Size of the array buffer. Values between 1 and 64KB

are acceptable. The default setting is 8KB.

UID

A user login ID.

Table 2-3 Valid Connection Strings for Engine DSNs

2-8

DSN

Name of the data source as returned by

SQLDataSources or the data sources dialog box of
SQLDriverConnect.

DRIVER

The description of the driver as returned by SQLDrivers

function. For an Engine DSN, it is "Pervasive ODBC
Engine Interface".

DBQ

A database name.

UID

A user login ID.

PWD

The password corresponding to the user ID.

ODBC Support

ODBC Support
ODBC Interface The relational interface supports the ODBC v3.51 specifications for
Core, Level 1, and Level 2 interface support levels.
Support
Exceptions to ODBC Interface Support
Core Level

SQL_BEST_ROWID
The relational interface uses unique indexes as the optimal set of
columns that identifies a row in the table.
When a new row is inserted into a table that includes an IDENTITY
column, the relational interface does not return the value assigned to
the IDENTITY column. You may determine the value for an
IDENTITY column through the use of the @@IDENTITY variable.
See @@IDENTITY on page 3-290.
Level 2

SQL_ROWVER
See SQL_BEST_ROWID above.
SQL_ATTR_LOGIN_TIMEOUT
Not supported

ODBC API
Support

The following table lists the ODBC API functions supported by the
relational interface and the ODBC support level.
Table 2-4 Interface-supported ODBC API Functions
ODBC Function

ODBC Support Level

SQLAllocHandle

Core

SQLBindCol

Core

SQLBindParameter

Core

SQLBrowseConnect

Level 1

SQLBulkOperations

Level 1

SQLCancel

Core

2-9

ODBC Engine Reference

Table 2-4 Interface-supported ODBC API Functions continued

2-10

ODBC Function

ODBC Support Level

SQLCloseCursor

Core

SQLColAttribute

Core

SQLColumnPrivileges

Level 2

SQLColumns

Core

SQLConnect

Core

SQLCopyDesc

Core

SQLDataSources

Core

SQLDescribeCol

Core

SQLDescribeParam

Level 2

SQLDisconnect

Core

SQLDriverConnect

Core

SQLDrivers

Core

SQLEndTran

Core

SQLExecDirect

Core

SQLExecute

Core

SQLExtendedFetch

Core

SQLFetch

Core

SQLFetchScroll

Core

SQLForeignKeys

Level 2

SQLFreeHandle

Core

SQLFreeStmt

Core

SQLGetConnectAttr

Core

SQLGetCursorName

Core

SQLGetData

Core

SQLGetDescField

Core

ODBC Support

Table 2-4 Interface-supported ODBC API Functions continued

ODBC Function

ODBC Support Level

SQLGetDescRec

Core

SQLGetDiagField

Core

SQLGetDiagRec

Core

SQLGetEnvAttr

Core

SQLGetFunctions

Core

SQLGetInfo

Core

SQLGetStmtAttr

Core

SQLGetTypeInfo

Core

SQLMoreResults

Level 1

SQLNativeSql

Core

SQLNumParams

Core

SQLNumResultCols

Core

SQLParamData

Core

SQLPrepare

Core

SQLPrimaryKeys

Level 1

SQLProcedureColumns

Level 1

SQLProcedures

Level 1

SQLPutData

Core

SQLRowCount

Core

SQLSetConnectAttr

Core

SQLSetCursorName

Core

SQLSetDescField

Core

SQLSetDescRec

Core

SQLSetEnvAttr

Core

SQLSetPos

Level 1

2-11

ODBC Engine Reference

Table 2-4 Interface-supported ODBC API Functions continued

Exceptions to
ODBC API
Support

ODBC Function

ODBC Support Level

SQLSetStmtAttr

Core

SQLStatistics

Core

SQLTablePrivileges

Level 2

SQLTables

Core

The following section contains details on the exceptions to ODBC

API support.
SQLGetTypeInfo
SQLGetTypeInfo generates a list of native data type names
(type_name) specified by the relational interface. For example,
SQL_CHAR is mapped to CHARACTER. Use the names which are
returned from this function for the data type names for columns in
a CREATE TABLE or ALTER TABLE statement or for parameters
for procedures or declared variables in procedures and triggers.

See also Pervasive PSQL Data Types and Equivalent ODBC Data
Types on page A-2 for a list of supported ODBC data types.
SQLSpecialColumns
The relational interface uses unique indexes as the optimal set of
columns that uniquely identifies a row in the table. When a new row
is inserted, the relational interface does not return the values for
IDENTITY columns. You may determine the value for an
IDENTITY column through the use of the @@IDENTITY variable.
See @@IDENTITY on page 3-290.
SQLGetData
If your application calls SQLGetData to return data into an
SQL_C_NUMERIC structure, the ODBC standard specifies that the
SQL_DESC_SCALE field is set to zero and the
SQL_DESC_PRECISION field uses the driver-defined precision.
Pervasive PSQL use the values for scale and driver-defined precision
as defined in the metadata. Consider the following example, in
which scale is set to two.

2-12

ODBC Support
CREATE TABLE testnum (col1 NUMERIC(10,2))
INSERT INTO testnum VALUES (10.34)
SELECT * FROM testnum

The SELECT statement returns 10.34, not 10.00.

SQLGetInfo
The relational interface returns identical values for SQL_DRIVER_VER
and SQL_DBMS_VER. This version value is returned in the following
format:
aa.bb.cccc ddd

This value can be interpreted as four components as explained in the

following table:
Part

Value

Description

Major version

The major version of the Pervasive PSQL database

engine.

Minor version

The minor version of the Pervasive PSQL database

engine, which is typically updated in a service pack.

cccc

Build number

The build further specifies the release by marking

the time at which Pervasive Software generated the
release.

ddd

Point build

A minor update to the build. The build number and

point build uniquely identify a product release
created at a specific time.

2-13

ODBC Engine Reference

The following table summarizes the expected format of other values

typically returned by SQLGetInfo. The values are examples only.
Item

Example Value

SQL_DRIVER_NAME

W3ODBCCI.DLL

SQL_DRIVER_VER

10.00.0147 012

SQL_DRIVER_ODBC_VER

03.51

SQL_DBMS_NAME

Pervasive.SQL

SQL_DBMS_VER

10.00.0147 012

SQL_ODBC_VER

03.52.0000

SQL_ODBC_API_CONFORMANCE

SQL_OAC_LEVEL2

SQL_ODBC_INTERFACE_CONFORMANCE

SQL_OIC_LEVEL2

ODBC Attribute The relational interface provides ODBC v3.51 attribute support,
with the following exceptions.
Support
Exceptions to ODBC Attribute Support
Statement Attribute Support

The following table lists the exceptions to ODBC statement attribute

support:
Table 2-5 Exceptions to ODBC Statement Attribute Support

2-14

fOption (numerical value)

Comments

SQL_ATTR_QUERY_TIMEOUT (0)

Supported through SQLSetStmtAttr

and SQLSetConnectAttr. Applies only
to SQLExecDirect, SQLExecute,
SQLFetch, and SQLExtendedFetch.
Does not apply to DDL statements.

SQL_ATTR_METADATA_ID (10014)

The default value is SQL_FALSE.

Pervasive ODBC Driver does not allow
setting this attribute's value to
SQL_TRUE.

ODBC Support

Table 2-5 Exceptions to ODBC Statement Attribute Support continued

fOption (numerical value)

Comments

SQL_ATTR_ENABLE_AUTO_IPD (15)

The default value is SQL_TRUE.

Pervasive ODBC Driver does not allow
setting this attribute value to
SQL_FALSE.

SQL_ATTR_PARAM_BIND_TYPE (18)

Only
SQL_PARAM_BIND_BY_COLUMN is
supported.

Connection Attribute Support

The following table lists the exceptions to ODBC Connection

Attribute support:
Table 2-6 Exceptions to ODBC Connection Attribute Support

ODBC
Descriptor
Field Support

fOption

Comments

SQL_ATTR_AUTO_IPD

The default value is SQL_TRUE. The

Pervasive ODBC Driver does not
allow setting this attribute value to
SQL_FALSE.

SQL_ATTR_METADATA_ID

The default value is SQL_FALSE. The

Pervasive ODBC Driver does not
allow setting this attribute's value to
SQL_TRUE

SQL_ATTR_CONNECTION_TIMEOUT

The default value is 0. No other value

is supported.

The relational interface provides ODBC v3.51 descriptor field

support, with the following exceptions.

2-15

ODBC Engine Reference

Exceptions to ODBC Descriptor Support

The following table lists the exceptions to ODBC descriptor field
support:
Table 2-7 Exceptions to ODBC Descriptor Support

2-16

fOption

Comments

SQL_DESC_BIND_TYPE

For application parameter descriptors (APDs), only

SQL_BIND_BY_COLUMN is supported.

SQL_DESC_ROWVER

See Exceptions to ODBC Interface Support on

page 2-9.

SQL Grammar Support

The ODBC v2.5 specification provides three levels of SQL grammar
support: Minimum, Core, and Extended. Each higher level provides
more fully-implemented data definition and data manipulation
language support. The relational interface fully supports the
minimum SQL grammar, as well as many core and extended
grammar statements. The relational interface support for SQL
grammar is summarized in the following table.
Table 2-8 SQL Grammar Support
SQL Grammar Statement

Minimum

Core

Extended

ALTER TABLE

CREATE GROUP

CREATE INDEX
CREATE PROCEDURE

CREATE TABLE

CREATE TRIGGER

CREATE VIEW
DELETE (positional)

DELETE (searched)

DROP GROUP

DROP INDEX

DROP PROCEDURE
DROP TABLE

DROP TRIGGER
DROP VIEW

GRANT

2-17

ODBC Engine Reference

Table 2-8 SQL Grammar Support continued

SQL Grammar Statement
INSERT

Minimum

Core

Extended

JOIN LEFT OUTER (Select)

REVOKE
SELECT (with into)

- approximate-numeric-literal

- between-predicate

- correlation-name

- date arithmetic

- date-literal

- exact-numeric-literal

- extended predicates
- in-predicate

- set-function

- time-literal

- timestamp-literal

Subqueries

2-18

UNION

SET SECURITY

UPDATE (positional)

UPDATE (searched)

SQL Grammar Support

Delimited
Identifiers in
SQL
Statements

Column names and table names can occur as delimited identifiers if

they contain non-ODBC standard characters. If an identifier is a
keyword, it must delimited.
The delimiter character for identifiers is the double-quote.
Examples
SELECT "last-name" FROM "non-standard-tbl"

The hyphen is a non-ODBC standard character.

SELECT "password" FROM my_pword_tbl

Password is a keyword in the SET PASSWORD statement.

2-19

ODBC Engine Reference

2-20

chapter

SQL Syntax Reference

A Reference to Pervasive PSQL Supported Syntax

This chapter details the SQL grammar supported by Pervasive PSQL:

Grammar Statements on page 3-2

Global Variables on page 3-290
Other Characteristics on page 3-294

For detailed information on the ODBC API, ODBC SQL grammar,

and scalar functions, refer to the Microsoft ODBC Programmers
Reference.

3-1

SQL Syntax Reference

Grammar Statements
The following pages describe the complete grammar for all
supported SQL grammar elements.
Note You can use the SQL Editor provided with Pervasive PSQL

Control Center to test most of the SQL examples. Exceptions are

noted in the discussion of the grammar elements. For more
information about SQL Editor, see the chapter SQL Editor in
Pervasive PSQL User's Guide.

3-2

Grammar Statements

ADD
Remarks

Use the ADD clause within the ALTER TABLE statement to specify
one or more column definitions, column constraints, or table
constraints to be added.

See Also

ALTER TABLE on page 3-10

FOREIGN KEY on page 3-147
PRIMARY KEY on page 3-187

3-3

SQL Syntax Reference

ALL
Remarks

When you specify the ALL keyword before a subquery, Pervasive

PSQL v10 performs the subquery and uses the result to evaluate the
condition in the outer query. If all the rows the subquery returns
meet the outer query's condition for a particular row, Pervasive
PSQL v10 includes that row in the final result table of the statement.
Generally, you can use the EXISTS or NOT EXISTS keyword instead
of the ALL keyword.

Examples

The following SELECT statement compares the ID column from the

Person table to the ID columns in the result table of the subquery:
SELECT p.ID, p.Last_Name
FROM Person p
WHERE p.ID <> ALL
(SELECT f.ID FROM Faculty f WHERE f.Dept_Name =
'Chemistry')

If the ID value from Person does not equal any of the ID values in the
subquery result table, Pervasive PSQL includes the row from Person
in the final result table of the statement.
See Also

SELECT (with into) on page 3-201

SELECT on page 3-202
UNION on page 3-266

3-4

Grammar Statements

ALTER (rename)
The ALTER (rename) statement allows you to change the name of
indexes, user-defined functions, stored procedures, tables, triggers,
or views.
Syntax

ALTER object-type RENAME qualified-object-name TO new-object-name

object-type ::= INDEX

| database-name.object-name
| table-name.object-name
| object-name
database-name, table-name, object-name, new-object-name ::= user-defined name

Remarks

You cannot rename the following objects if they were created with a
version of Pervasive PSQL prior to Pervasive PSQL v9:

stored procedures
triggers
views.

In releases prior to Pervasive PSQL v9, the system table index on the
name of these objects was created as not modifiable. The indexes for
these objects are modifiable with release Pervasive PSQL v9 or
greater.
You can use database-name to qualify any object-type. However, if it
is used to qualify an INDEX or TRIGGER object, you must also
include table-name. You can use table-name to qualify only the
objects INDEX and TRIGGER.
The ALTER statement can rename an object in a database whether or
not ODBC is currently connected to that database. You must use
database-name to qualify object-type if the object resides in a

3-5

SQL Syntax Reference

database to which your session is not currently connected. The

renamed object occurs in the same database as database-name.
If you omit database-name as a qualifier, the database to which your
session is currently connected is used to identify and rename the
objects.
Note that new-object-name never uses a database name as a qualifier.
The context of the new name always matches the context of the
original name.
Note The database engine does not check dependencies for

renamed objects. If you rename an object, ensure that all other

objects with a dependency on the previous (changed from)
name are revised appropriately. For example, suppose that a
trigger refers a table named t1. If you rename table t1 to t5, the
trigger contains invalid SQL that will not execute correctly.
You can also use the psp_rename system stored procedure to rename
objects.
Examples

The following statement alters the name of index suplid to

vendor_id in the database to which your session is currently
connected. The index applies to table region5.
ALTER INDEX RENAME region5.suplid TO vendor_id

The following statement alters the name of the user-defined function

calbrned to caloriesburned in database foodforlife.
ALTER FUNCTION RENAME foodforlife.calbrned TO
caloriesburned

The following statement alters the name of stored procedure

checkstatus to eligibility in database international.
ALTER PROCEDURE RENAME international.checkstatus TO
eligibility

The following statement alters the name of table payouts to accts_

payable in the database to which your session is currently
connected.
ALTER TABLE RENAME payouts TO accts_payable

The following statement alters the name of trigger testtrig3 to

new_customer in table domestic and database electronics.

3-6

Grammar Statements
ALTER TRIGGER RENAME electronics.domestic.testtrig3 TO
new_customer

The following statement alters the name of view suplrcds to

vendor_codes in the database to which your session is currently
connected.
ALTER VIEW RENAME suplrcds TO vendor_codes

See Also

CREATE FUNCTION on page 3-51

CREATE PROCEDURE on page 3-66
CREATE TABLE on page 3-80
CREATE TRIGGER on page 3-103
CREATE VIEW on page 3-108
psp_rename on page 6-32

3-7

SQL Syntax Reference

ALTER GROUP
The ALTER GROUP statement adds or removes a user account from
a group.
Syntax

ALTER GROUP group-name

<ADD USER user-name [ ,

user-name

]...

| DROP USER user-name [ , user-name ]...>

Remarks

This function is an extension to SQL grammar as documented in the

Microsoft ODBC Programmers Reference.
Only the Master user can execute this statement.
This statement must be used with one of the available keywords.
A user account cannot be added to a group if the group is not already
created in the database. To create users and add them to groups
simultaneously, see GRANT on page 3-149.
Dropping a user account from a group does not remove the group
from the database.
User accounts cannot belong to multiple groups simultaneously. A
user account cannot be added to a group if it is currently a member
of another group. Such a user account must first be dropped from its
current group and then added to another group.
A user name must be enclosed in double quotes if it contains spaces
or other non-alphanumeric characters.
For further general information about users and groups, see Master
User on page 7-2 on page 7-2 and Users and Groups on page 7-3
on page 7-3 in Advanced Operations Guide, and Assigning
Permissions Tasks on page 3-44 in Pervasive PSQL User's Guide.

Examples

The following examples show how to add a user account to a group:

ALTER GROUP developers ADD USER pgranger

The existing user account pgranger is added to the existing group

developers.

ALTER GROUP developers ADD USER polly granger

The user account polly granger (containing non-alphanumeric

characters) is added to the group developers.

3-8

Grammar Statements

ALTER GROUP developers ADD USER polly granger, bflat

The user accounts polly granger (containing non-alphanumeric

characters) and bflat are added to the group developers.

The following examples show how to drop a user account from a

group.
ALTER GROUP developers DROP USER pgranger

The user account pgranger is removed from the group developers.

ALTER GROUP developers DROP USER polly granger

The user account polly granger (with a name containing nonalphanumeric characters) is removed from the group developers.

ALTER GROUP developers DROP USER polly granger, bflat

The user accounts polly granger (containing non-alphanumeric

characters) and bflat are removed from the group developers.
See Also

ALTER USER on page 3-26

CREATE GROUP on page 3-58
CREATE USER on page 3-106
DROP GROUP on page 3-132
GRANT on page 3-149
REVOKE on page 3-194
SET SECURITY on page 3-250

3-9

SQL Syntax Reference

ALTER TABLE
The ALTER TABLE statement modifies a table definition.
Syntax

ALTER TABLE table-name [ IN DICTIONARY ]

[ USING 'path_name'] [ WITH REPLACE ] alter-options
table-name ::= user-defined name
path_name ::=

a simple file name or relative path and file name

alter-options ::= alter-option-list1 | alter-option-list2

alter-option-list1 ::= alter-option |(alter-option [, alter-option ]...)
alter-option ::= ADD [ COLUMN ] column-definition

| ADD table-constraint-definition
| ALTER [ COLUMN ] column-definition
| DROP [ COLUMN ] column-name
| DROP CONSTRAINT constraint-name
| DROP PRIMARY KEY
| MODIFY [ COLUMN ] column-definition
alter-option-list2 ::= PSQL_MOVE [ COLUMN ] column-name TO [ [ PSQL_
PHYSICAL ] PSQL_POSITION ] new-column-position | RENAME
COLUMN column-name TO new-column-name
column-definition ::= column-name data-type [ DEFAULT default-value-expression
] [ column-constraint [ column-constraint ]... [CASE (string) |
COLLATE collation-name ]
column-name ::= user-defined name
new-column-position ::=

new ordinal position (a positive integer value). The

value must be greater than zero and less than or equal to the total
number of columns in the table.

new-column-name ::= user-defined name

data-type ::= data-type-name [ (precision [ , scale ] ) ]
precision ::=
scale ::=

integer

default-value-expression ::= default-value-expression + default-value-expression

3-10

Grammar Statements
| default-value-expression - default-value-expression
| default-value-expression * default-value-expression
| default-value-expression / default-value-expression
| default-value-expression & default-value-expression
| default-value-expression | default-value-expression
| default-value-expression ^ default-value-expression
| ( default-value-expression )
| -default-value-expression
| +default-value-expression
| ~default-value-expression
| ?
| literal
| scalar-function
| { fn scalar-function }
| USER
| NULL
default-literal ::= 'string'

| number
| { d 'date-literal' }
| { t 'time-literal' }
| { ts 'timestamp-literal' }
default-scalar-function ::= USER ( )

| UNIQUE

3-11

SQL Syntax Reference

| PRIMARY KEY
| REFERENCES table-name [ ( column-name ) ] [ referential-actions ]
referential-actions ::= referential-update-action [ referential-delete-action ]

| referential-delete-action [ referential-update-action ]
referential-update-action ::= ON UPDATE RESTRICT
referential-delete-action ::= ON DELETE CASCADE

| ON DELETE RESTRICT
collation-name ::= 'string' | user-defined-name
table-constraint-definition ::= [ CONSTRAINT constraint-name ] table-constraint
table-constraint ::= UNIQUE (column-name [ , column-name ]... )

| PRIMARY KEY ( column-name [ , column-name ]... )

| FOREIGN KEY ( column-name [ , column-name ] )
REFERENCES table-name
[ ( column-name [ , column-name ]... ) ]
[ referential-actions ]

Remarks

Refer to CREATE TABLE for information pertaining to primary and

foreign keys and referential integrity.
ALTER TABLE requires an exclusive lock on a table. If the same table
is being held open with another statement, ALTER TABLE fails and
returns status code 88. Ensure that you execute all data definition
statements before executing data manipulation statements. For an
example showing this, see PSQL_MOVE on page 3-18.
IN DICTIONARY

The purpose of using this keyword is to notify the database engine

that you wish to make modifications to the DDFs, while leaving the
underlying physical data unchanged. IN DICTIONARY is a very
powerful and advanced feature. It should only be used by system
administrators or when absolutely necessary. Normally, Pervasive
PSQL keeps DDFs and data files totally synchronized, but this
feature allows users the flexibility to force table dictionary definitions
to match an existing data file. This can be useful when you want to
create a definition in the dictionary to match an existing data file, or

3-12

Grammar Statements

when you want to use a USING clause to change the data file path
name for a table.
You cannot use this keyword on a bound database.
IN DICTIONARY is allowed on CREATE and DROP TABLE, in
addition to ALTER TABLE. IN DICTIONARY affects dictionary
entries only, no matter what CREATE/ALTER options are specified.
Since Pervasive PSQL allows multiple options (any combination of
ADD, DROP, ADD CONSTRAINT, and so on), IN DICTIONARY is
honored under all circumstances to guarantee only the DDFs are
affected by the schema changes.
The error Table not found results if you query a detached table or
a table that does not exist. If you determine that a table exists but you
receive the Table not found error, the error resulted because the
data file could not be opened. This indicates a detached table. (Tables
that exist in the DDFs only (the data file does not exist) are called
detached entries. These tables are inaccessible via queries or other
operations that attempt to open the physical underlying file.)
You may verify whether a table really exists by using SQLTables or
directly querying the Xf$Name column of X$File:
SELECT * FROM X$File WHERE Xf$Name = 'table_name'

The SELECT statement returns the Xf$Loc value, which is the name
of the physical file for the table. Combine the name with a data path
defined for the database to get the complete path to the file.
It is possible for a detached table to cause confusion, so the IN
DICTIONARY feature must be used with extreme care. It is crucial
that it should be used to force table definitions to match physical
files, not to detach them. Consider the following examples, assuming
that the file test123.btr does not exist. (USING is explained below, in
the next subtopic.)
CREATE TABLE t1 USING 't1.btr' (c1 INT)
ALTER TABLE t1 IN DICTIONARY USING 'test123.btr'

Or, combining both statements:

CREATE TABLE t1 IN DICTIONARY USING 'test123.btr' (c1
INT)

If you then attempt to SELECT from t1, you receive an error that the
table was not found. Confusion can arise, because you just created
the tablehow can it not be found? Likewise, if you attempt to
DROP the table without specifying IN DICTIONARY, you receive

3-13

SQL Syntax Reference

the same error. These errors are generated because there is no data
file associated with the table.
Whenever you create a relational index definition for an existing
Btrieve data file (for example, by issuing an ALTER TABLE statement
to add a column definition of type IDENTITY), Pervasive PSQL
automatically checks the Btrieve indexes defined on the file to
determine whether an existing Btrieve index offers the set of
parameters requested by the relational index definition. If an existing
Btrieve index matches the new definition being created, then an
association is created between the relational index definition and the
existing Btrieve index. If there is no match, then Pervasive PSQL
creates a new index definition and, if IN DICTIONARY is not
specified, a new index in the data file.
USING

The USING keyword allows you to associate a CREATE TABLE or

ALTER TABLE action with a particular data file.
Because Pervasive PSQL requires a Named Database to connect, the
path_name provided must always be a simple file name or relative
path and file name. Paths are always relative to the first Data Path
specified for the Named Database to which you are connected.
The path/file name passed is partially validated when SQLPrepare is
called. The following rules must be followed when specifying the
path name:

3-14

The text must be enclosed in single quotes, as shown in the

grammar definition.
Text must be 1 to 64 characters in length for V1 metadata and 1
to 250 characters for V2 metadata, and is stored in Xf$Loc in
X$File. The entry is stored exactly as typed (trailing spaces are
truncated and ignored).
The path must be a simple, relative path. Paths that reference a
server or volume are not allowed.
Relative paths containing a period (. - current directory) ,
double-period (.. - parent directory), slash \, or any
combination of the three are allowed. The path must contain a
file name representing the SQL table name (path_name cannot end
in a slash \ or a directory name). When you create a file with
CREATE or ALTER TABLE, all file names, including those

Grammar Statements

specified with relative paths, are relative to the first Data Path as
defined in the Named Database configuration. (If you use IN
DICTIONARY, the file name does not have to relative to the first
data location.)
Root-based relative paths are also allowed. For example,
assuming that the first data path is D:\mydata\DEMODATA,
Pervasive PSQL interprets the path name in the following
statement as D:\TEMP\TEST123.BTR.
CREATE TABLE t1 USING '\temp\test123.btr' (c1 int)

Slash (\) characters in relative paths may be specified either

LINUX style (/) or in the customary back slash notation (\),
depending on your preference. You may use a mixture of the two
types, if desired. This is a convenience feature since you may
know the directory structure scheme, but not necessarily know
(or care) what type of server you are connected to. The path is
stored in X$File exactly as typed. Pervasive PSQL engine
converts the slash characters to the appropriate platform type
when utilizing the path to open the file. Also, since data files
share binary compatibility between all supported platforms, this
means that as long as the directory structure is the same between
platforms (and path-based file names are specified as relative
paths), the database files and DDFs can be moved from one
platform to another with no modifications. This makes for a
much simpler cross-platform deployment with a standardized
database schema.
If specifying a relative path, the directory structure in the USING
clause must first exist. Pervasive PSQL does not create directories
to satisfy the path specified in the USING clause.

Include a USING clause to specify the physical location and name of

an existing data file to associate with an existing table. A USING
clause also allows you to create a new data file at a particular location
using an existing dictionary definition. (The string supplied in the
USING clause is stored in the Xf$Loc column of the dictionary file
X$File.) The original data file must be available when you create the
new file since some of the file information must be obtained from the
original.
In the DEMODATA sample database, the Person table is associated
with the file PERSON.MKD. If you create a new file named
PERSON2.MKD, the statement in the following example changes

3-15

SQL Syntax Reference

the dictionary definition of the Person table so that the table is

associated with the new file.
ALTER TABLE Person IN DICTIONARY USING 'person2.mkd'

You must use either a simple file name or a relative path in the
USING clause. If you specify a relative path, Pervasive PSQL
interprets it relative to the first data file path associated with the
database name.
The USING clause can be specified in addition to any other standard
ALTER TABLE option. This means columns can be manipulated in
the same statement that specifies the USING path.
If you specify a data file name that differs from the data file name
currently used to store the table data and you do not specify IN
DICTIONARY, Pervasive PSQL creates the new file and copies all of
the data from the existing file into the new file. For example, suppose
person.mkd is the current data file that holds the data for table
Person. You then alter table Person using data file person2.mkd, as
shown in the statement above. The contents of person.mkd are
copied into person2.mkd. Person2.mkd then becomes the data file
associated with table Person and database operations affect
person2.mkd. Person.mkd is not deleted, but it is not associated with
the database any more.
The reason for copying the data is because Pervasive PSQL allows all
other ALTER TABLE options at the same time as USING. The new
data file created needs to be fully populated with the existing tables
data. The file structure is not simply copied, but instead the entire
contents are moved over, similar to a Btrieve BUTIL -CREATE and
BUTIL -COPY. This can be helpful for rebuilding an SQL table, or
compressing a file that once contained a large number of records but
now contains only a few.
Note ALTER TABLE USING copies the contents of the existing

data file into the newly specified data file, leaving the old data file
intact but unlinked.
WITH REPLACE

Whenever WITH REPLACE is specified with the USING keyword,

Pervasive PSQL automatically overwrites any existing file name with

3-16

Grammar Statements

the specified file name. The existing file is always overwritten as long
as the operating system allows it.
WITH REPLACE affects only the data file, it never affects the DDFs.
The following rules apply when using WITH REPLACE:

WITH REPLACE can only be used with USING.

When used with IN DICTIONARY, WITH REPLACE is ignored
because IN DICTIONARY specifies that only the DDFs are
affected.
Note No data is lost or discarded if WITH REPLACE is used with

ALTER TABLE. The newly created data file, even if overwriting

an existing file, still contains all data from the previous file. You
cannot lose data by issuing an ALTER TABLE command.
Include WITH REPLACE in a USING clause to instruct Pervasive
PSQL to replace an existing file (the file must reside at the location
you specified in the USING clause). If you include WITH REPLACE,
Pervasive PSQL creates a new file and copies all the data from the
existing file into it. If you do not include WITH REPLACE and a file
exists at the specified location, Pervasive PSQL returns a status code
and does not create the new file. The status code is error -4940.
MODIFY COLUMN and ALTER COLUMN
The ability to modify the nullability or data type 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 primary or foreigh key column,
you can do so by dropping the constraint, changing the data type of
the column, and re-adding the constraint. Keep in mind that you
must ensure that all associated key columns remain synchronized.
For example, if you have a primary key in table T1 that is referenced
by foreign keys in tables T2 and T3, you must first drop the foreign
keys. Then you can drop the primary key. Then you need to change

3-17

SQL Syntax Reference

all three columns to the same data type. Finally, you must re-add the
primary key and then the foreign keys.
The ANSI standard includes the ALTER keyword. Pervasive PSQL
allows both keywords (ALTER and MODIFY) in the ALTER TABLE
statement (the keyword COLUMN is optional):
ALTER
ALTER
ALTER
ALTER

TABLE
TABLE
TABLE
TABLE

t1
t1
t1
t1

MODIFY c1 INTEGER
ALTER c1 INTEGER
MODIFY COLUMN c1 INTEGER
ALTER COLUMN c1 INTEGER

Pervasive PSQL allows altering a column to a smaller length if the

actual data does not overflow the new, smaller length of the column.
This behavior is similar to that of Microsoft SQL Server.
You can add, drop, or modify multiple columns on a single ALTER
TABLE statement. Although it simplifies operations, this behavior is
not considered ANSI-compliant. The following is a sample multicolumn ALTER statement.
ALTER TABLE t1 (ALTER c2 INT, ADD D1 CHAR(20), DROP C4,
ALTER C5 LONGVARCHAR, ADD D2 LONGVARCHAR NOT NULL)

You can convert all legacy data types (Pervasive.SQL v7 or earlier) to

data types that are natively supported by Pervasive PSQL v10. If you
wish to convert new data types backwards to legacy data types,
contact Pervasive Support.
To add a LONGVARCHAR/LONGVARBINARY column to a legacy
table that contains a NOTE/LVAR column, the NOTE/LVAR column
first has to be converted to a LONGVARCHAR or
LONGVARBINARY column. After converting the NOTE/LVAR
column to LONGVARCHAR/LONGVARBINARY, you can add more
LONGVARCHAR/LONGVARBINARY columns to the table. Note
that the legacy engine does not work with this new table because the
legacy engine can work with only one variable length column per
table.
PSQL_MOVE

The PSQL_MOVE syntax allows you to keep the columns of a table

at desired ordinal positions. You may change the ordinal position of

3-18

Grammar Statements

existing columns or for a new column after adding it. You can move
a column logically and physically.
Type of Move

Result

Logical

Columns are rearranged when listed in a result set, but the

physical order of the columns in the table does not change. For
example, you can rearrange how the columns are listed in a
result set with a query such as SELECT * FROM table-name. A
logical move affects only queries that list the columns, such as
SELECT * FROM from table-name.

Physical

A column is physically relocated from its current position to a

new position in the file. A physical move affects the data file of
the table. To move a column physically, you must specify the
PSQL_PHYSICAL keyword. If the PSQL_PHYSICAL keyword
is omitted, a logical move occurs by default.
Note that only column offsets in the DDFs are changed if IN
DICTIONARY is used in the ALTER TABLE statement. Columns
in the data file are not physically moved because IN
DICTIONARY overrides the MOVE . . . PSQL_PHYSICAL
syntax for the data file.

Note Once you move columns logically, that order becomes the

default order for listing columns in result sets. For instance, if

you move columns physically after moving them logically, the
logical order is used for queries such as SELECT * FROM from
table-name. Logical column changes are stored in X$Attrib.
The PSQL_MOVE keyword must specify a column location greater
than zero but less than the total number of columns. For example,
assume that table t1 has only two columns, col1 and col2. Both of the
following statement return an error:
ALTER TABLE t1 PSQL_MOVE col1 to 0
ALTER TABLE t1 PSQL_MOVE col1 to 3

The first statement attempts to move the column to position zero.

The second statements attempts to move the column to position
three, which is a number greater than the total number of columns
(two).
ALTER TABLE requires an exclusive lock on a table. If the same table
is being help open by another statement, ALTER TABLE fails and

3-19

SQL Syntax Reference

returns status code 88. Ensure that you execute all data definition
statements before executing data manipulation statements.
For example, the following stored procedure fails and returns status
code 88 because the INSERT statement has table t1 open, which
prevents the ALTER TABLE statement from obtaining an exclusive
lock.
CREATE PROCEDURE proc1() AS
BEGIN
CREATE TABLE t1(c1 INT,c2 INT,c3 INT);
INSERT INTO t1 VALUES (123,345,678);
ALTER TABLE t1 PSQL_MOVE c3 to 1;
END;

A way to resolve this is to execute the statements pertaining first to

the table creation and data insertion, then call the procedure:
CREATE TABLE t1(c1 INT,c2 INT,c3 INT);
INSERT INTO t1 VALUES (123,345,678);
CALL proc1;
CREATE PROCEDURE proc1() AS
BEGIN
ALTER TABLE t1 PSQL_MOVE c3 to 1;
END;

RENAME COLUMN

Rename column allows you to change the name of a column to a new

name. You cannot rename a column to the name of an existing
column in the same table.
Renaming a column can invalidate objects that reference the
previous name. For example, a trigger might reference column c1 in
table t1. Renaming c1 to c5 results in the trigger being unable to
execute successfully.
You can also use the psp_rename system stored procedure to rename
columns.
Note The database engine does not check dependencies for

renamed columns. If you rename a column, ensure that all

objects with a dependency on the previous (changed from)
name are revised appropriately.

3-20

Grammar Statements

ON DELETE CASCADE

See Delete Rule on page 3-84 for CREATE TABLE.

Examples

The following statement adds the Emergency_Phone column to the

Person table
ALTER TABLE person ADD Emergency_Phone NUMERIC(10,0)

The following statement adds two integer columns col1 and col2 to
the Class table.
ALTER TABLE class(ADD col1 INT, ADD col2 INT)

To drop a column from a table definition, specify the name of the

column in a DROP clause. The following statement drops the
emergency phone column from the Person table.
ALTER TABLE person DROP Emergency_Phone

The following statement drops col1 and col2 from the Class table.
ALTER TABLE class(DROP col1, DROP col2)

The following statement drops the constraint c1 in the Faculty table.

ALTER TABLE Faculty(DROP CONSTRAINT c1)

This example adds an integer column col3 and drops column col2 to
the Class table
ALTER TABLE class(ADD col3 INT, DROP col2 )

The following example creates a primary key named c1 on the ID

field in the Faculty table. Note that you cannot create a primary key
on a Nullable column. Doing so generates the error, Nullable
columns are not allowed in primary keys.
ALTER TABLE Faculty(ADD CONSTRAINT c1 PRIMARY KEY(ID))

The following example creates a primary key using the default key
name PK_ID on the Faculty table.
ALTER TABLE Faculty(ADD PRIMARY KEY(ID))

The following example adds the constraint UNIQUE to the columns

col1 and col2. The combined value of col1 and col2 in any row is

3-21

SQL Syntax Reference

unique within the table. Neither column is required to be unique

individually.
ALTER TABLE Class(ADD UNIQUE(col1,col2))

The following example drops the primary key in the Faculty table.
Because a table can have only one primary key, you cannot add a
primary key to a table that already has a primary key defined. To
change the primary key of a table, delete the existing key then add the
new primary key.
ALTER TABLE Faculty(DROP PRIMARY KEY)

Before you can drop a primary key from a parent table, you must
drop any corresponding foreign keys from dependent tables.

The following example adds a new foreign key to the Class table. The
Faculty_ID column is defined as a column that does not include
NULL values. You cannot create a foreign key on a Nullable column.
ALTER TABLE Class ADD CONSTRAINT Teacher FOREIGN KEY
(Faculty_ID) REFERENCES Faculty (ID) ON DELETE RESTRICT

In this example, the restrict rule for deletions prevents someone

from removing a faculty member from the database without first
either changing or deleting all of that facultys classes. Also note that
the column listed in the REFERENCES clause (ID) is optional.
Columns listed in the REFERENCES clause can be included, if you
choose, to improve clarity of the statement. The only column(s) that
can be referenced in the REFERENCES clause is the primary key(s)
of the referenced table.
The following statement shows how to drop the foreign key added in
this example. Pervasive PSQL drops the foreign key from the
dependent table and eliminates the referential constraints between
the dependent table and the parent table.
ALTER TABLE Class DROP CONSTRAINT Teacher

The following example adds a foreign key to the Class table without
using the CONSTRAINT clause. In this case, a foreign key constraint
is generated internally to reference the primary key (ID) of Faculty.
The column listed in the REFERENCES clause is optional. Columns
listed in the REFERENCES clause can be included, if you choose, to

3-22

Grammar Statements

improve clarity of the statement. The only column(s) that can be

referenced in the REFERENCES clause is the primary key(s) of the
referenced table.
ALTER TABLE Class ADD FOREIGN KEY (Faculty_ID)
REFERENCES Faculty (ID) ON DELETE RESTRICT

This creates foreign key FK_Faculty_ID. To drop the foreign key,

specify the CONSTRAINT keyword:
ALTER TABLE Class DROP CONSTRAINT FK_Faculty_ID

The following example illustrates multiple adding and dropping of

constraints and columns in a table. This statement drops column
salary, adds a column col1 of type integer, and drops constraint c1 in
the Faculty table.
ALTER TABLE Faculty(DROP salary, ADD col1 INT, DROP
CONSTRAINT c1)

The following examples illustrate altering the data type of multiple

columns.
ALTER TABLE t1 (ALTER c2 INT, ADD D1 CHAR(20), DROP C4,
ALTER C5 LONGVARCHAR, ADD D2 LONGVARCHAR NOT NULL)
ALTER TABLE t2 (ALTER c1 CHAR(50), DROP CONSTRAINT MY_
KEY, DROP PRIMARY KEY, ADD MYCOLUMN INT)

The following examples illustrate how the column default and

alternate collating sequence can be set or dropped with the ALTER or
MODIFY column options.
CREATE TABLE t1 (c1 INT DEFAULT 10, c2 CHAR(10))
ALTER TABLE t1 ALTER c1 INT DEFAULT 20

resets column c1 default to 20

ALTER TABLE t1 ALTER c1 INT

drops column c1 default

ALTER TABLE t1 ALTER c2 CHAR(10)
COLLATE 'file_path\upper.alt'

sets alternate collating sequence on column c2

ALTER TABLE t1 ALTER c2 CHAR(10)

3-23

SQL Syntax Reference

drops alternate collating sequence on column c2

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 ordered, 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.

The following statement logically moves column Registrar_ID from

its current position to the second position when the columns are
listed in a results set.
ALTER TABLE Billing PSQL_MOVE Registrar_ID TO 2

The following statement moves columns Amount_Owed and

Amount_Paid from their current positions to the second and third
positions, respectively, when the columns are listed in a result set.
ALTER TABLE Billing ( PSQL_MOVE Amount_Owed TO 2, PSQL_
MOVE Amount_Paid TO 3 )

The following statement physically moves column Registrar_ID

from its current position to the second column in the data file. This
causes the data file to be rebuilt to reflect the change.
ALTER TABLE Billing PSQL_MOVE Registrar_ID TO PSQL_
PHYSICAL 2

The following statement physically moves columns Amount_Owed

and Amount_Paid from their current positions to the second and
third column positions, respectively, in the data file.
ALTER TABLE Billing ( PSQL_MOVE Amount_Owed TO PSQL_
PHYSICAL 2, PSQL_MOVE Amount_Paid TO PSQL_PHYSICAL 3
)

Assume that table t1 contains columns c1 and col2. The following

statement renames column c1 to c2.
ALTER TABLE t1 RENAME COLUMN c1 TO c2

3-24

Grammar Statements

Assume that table t1 contains columns c1 and col2. The following

statement returns an error (duplicate column name) because it
attempts to rename a column (col2) to the name of an existing
column (c1).
ALTER TABLE t1 (RENAME COLUMN c1 TO c2, RENAME COLUMN
col2 TO c1)

Instead, you must issue two separate ALTER statements. The first to
rename c1 to c2; the second to rename col2 to c1.
ALTER TABLE t1 (RENAME COLUMN c1 TO c2)
ALTER TABLE t1 (RENAME COLUMN col2 TO c1)

See Also

CREATE TABLE on page 3-80

DROP TABLE on page 3-136
CREATE INDEX on page 3-59
SET DEFAULTCOLLATE on page 3-237

3-25

SQL Syntax Reference

ALTER USER
The ALTER USER statement changes the name or password of a user
account.
Syntax

ALTER USER user-name < RENAME TO new-user-name | WITH PASSWORD

user-password >

Remarks

This function is an extension to SQL grammar as documented in the

Microsoft ODBC Programmer's Reference.
Only the Master user can rename a user. Other users can change their
passwords with the WITH PASSORD clause or by using SET
PASSWORD. See SET PASSWORD on page 3-242.
Security must be turned on to perform this statement.
This statement must be used with either the RENAME TO option or
the WITH PASSWORD keywords.
New-user-name must be unique in the database.
User-name and password must be enclosed in double quotes if they
contain spaces or other non-alphanumeric characters. See Users
and Groups on page 3-152 for more information on created users.

Note For information on password restrictions, see Table 1-

1:Identifier Restrictions by Identifier Type on page 1-3 and

Database Security on page 7-2 in Advanced Operations Guide.
For further general information about users and groups, see
Master User on page 7-2 on page 7-2 and Users and Groups
on page 7-3 in Advanced Operations Guide, and Assigning
Permissions Tasks on page 3-44 in Pervasive PSQL User's Guide.

Examples

The following examples show how to rename a user account.

ALTER USER pgranger RENAME TO grangerp

The name of the account pgranger is changed to grangerp.

ALTER USER pgranger RENAME TO polly granger

The name of the account pgranger is changed to polly granger

containing non-alphanumeric characters.

3-26

Grammar Statements

The following examples show how to change the password for a user
account.
ALTER USER pgranger WITH PASSWORD Prvsve1

The password for user account pgranger is changed to Prvsve1 (casesensitive).

ALTER USER pgranger WITH PASSWORD Nonalfa$

The password for user account pgranger is changed to Nonalfa$

(case-sensitive) containing non-alphanumeric characters.
See Also

ALTER (rename) on page 3-5

CREATE GROUP on page 3-58
CREATE USER on page 3-106
DROP USER on page 3-138
GRANT on page 3-149
SET PASSWORD on page 3-242

3-27

SQL Syntax Reference

ANY
Remarks

The ANY keyword works similarly to the ALL keyword except that
Pervasive PSQL v10 includes the compared row in the result table if
the condition is true for any row in the subquery result table.

Examples

The following statement compares the ID column from Person to the

ID columns in the result table of the subquery. If the ID value from
Person is equal to any of the ID values in the subquery result table,
Pervasive PSQL includes the row from Person in the result table of
the SELECT statement.
SELECT p.ID, p.Last_Name
FROM Person p
WHERE p.ID = ANY
(SELECT f.ID FROM Faculty f WHERE f.Dept_Name =
'Chemistry')

See Also

3-28

SELECT on page 3-202

Grammar Statements

AS
Remarks

Include an AS clause to assign a name to a select term or to a table

name. You can use this name elsewhere in the statement to reference
the select term. The name is often referred to as an alias.
When you use the AS clause on a non-aggregate column, you can
reference the name in WHERE, ORDER BY, GROUP BY, and
HAVING clauses. When you use the AS clause on an aggregate
column, you can reference the name only in an ORDER BY clause.
The name you define must be unique in the SELECT list.
Column aliases are returned as the column name in an
SQLDescribeCol ODBC call. Computed columns, including group
aggregates, that do not have a column alias specified are assigned a
system-generated column name such as EXPR-1, EXPR-2, and so
forth.

Examples

The AS clause in the following statement instructs Pervasive PSQL to

assign the name Total to the select term SUM (Amount_Paid) and
order the results by the total for each student:
SELECT Student_ID, SUM (Amount_Paid) AS Total
FROM Billing
GROUP BY Student_ID
ORDER BY Total

The keyword AS is optional when used for table aliases as in this next
example. When you use the AS clause on a table name in a FROM
clause, you can reference the name in a WHERE, ORDER BY,
GROUP BY, and HAVING clause.
SELECT DISTINCT c.Name, p.First_Name, c.Faculty_Id
FROM Person AS p, class AS c
WHERE p.Id = c.Faculty_Id
ORDER BY c.Faculty_Id

You can rewrite this query without using the AS clause in the FROM
clause as follows.
SELECT DISTINCT c.Name, p.First_Name, c.Faculty_Id
FROM Person p, class c
WHERE p.Id = c.Faculty_Id
ORDER BY c.Faculty_Id

3-29

SQL Syntax Reference

Once you establish a table alias, do not intermix the table name and
its alias in a WHERE clause. The following does not work:
SELECT DISTINCT c.Name, p.First_Name, c.Faculty_Id
FROM Person p, class c
WHERE Person.Id = c.Faculty_Id
ORDER BY c.Faculty_Id

See Also

3-30

SELECT on page 3-202

Grammar Statements

BEGIN [ATOMIC]
Remarks

It is often convenient to group individual statements so that they can

be treated as a single unit. The BEGIN and END statements are used
in compound statements to group the statements into a unit. You can
use a compound statement only in the body of a stored procedure, a
user-defined function, or in a trigger declaration.
ATOMIC specifies that the set of statements within the unit either all
succeed or all fail. If one condition within the BEGIN ATOMIC . . .
END unit is not met, no records are affected. If the condition should
affect more than one row, all rows (or none) are affected. For any
record to be affected, all the conditions within a BEGIN
ATOMIC . . . END unit must return true.

Examples

In the following example, two UPDATEs are grouped as an ATOMIC

unit. The Perm_State column in the Person table is updated only if
all of the other conditions are true. That is, a record for Bill Andrew
exists with 'TX' as the Perm_State, and a record for Yvette Lopez
exists with 'OR' as the Perm_State. If any of these conditions are not
true, neither record is updated. Assume the BEGIN . . . END unit is
within a procedure.
BEGIN ATOMIC
UPDATE Person SET Perm_State = 'MA' WHERE Perm_State
= 'TX' AND First_Name = 'Bill' AND Last_Name =
'Andrew';
UPDATE Person SET Perm_State = 'WA' WHERE Perm_State
= 'OR' AND First_Name = 'Yvette' AND Last_Name =
'Lopez';
END

See Also

END on page 3-140

CREATE PROCEDURE on page 3-66
CREATE TRIGGER on page 3-103

3-31

SQL Syntax Reference

CALL
Remarks

Use the CALL statement to invoke a stored procedure. The stored

procedure may be a user-defined one or a system stored procedure.

Examples

The following example calls a user-defined procedure without

parameters:
CALL NoParms() or CALL NoParms

The following examples call a user-defined procedure with

parameters:
CALL Parms(vParm1, vParm2)
CALL CheckMax(N.Class_ID)

The following statement lists the column information for all

columns in the Dept table by calling a system stored procedure.
CALL psp_columns(Demodata,Dept)

See Also

CREATE PROCEDURE on page 3-66

CREATE TRIGGER on page 3-103
EXECUTE on page 3-141
System Stored Procedures on page 6-1

3-32

Grammar Statements

CASCADE
Remarks

If you specify CASCADE when creating a Foreign Key, Pervasive

PSQL uses the DELETE CASCADE rule. When a user deletes a row
in the parent table, Pervasive PSQL deletes the corresponding rows
in the dependent table.
Use caution with delete cascade. Pervasive PSQL allows a circular
delete cascade on a table that references itself. See examples in
Delete Cascade on page 6-5 in Advanced Operations Guide.

See Also

ALTER TABLE on page 3-10

CREATE TABLE on page 3-80

3-33

SQL Syntax Reference

CASE (expression)
A CASE expression returns a value. CASE expression has two
formats:

Simple When/Then. This format compares a value expression to

a set of value expressions to determine a result. The value
expressions are evaluated in their order listed. If a value
expression evaluates to TRUE, CASE returns the value
expression for the THEN clause.
Searched When/Then. This format evaluates a set of Boolean
expressions to determine a result. The Boolean expressions are
evaluated in their order listed. If a Boolean expression evaluates
to TRUE, CASE returns the expression for the THEN clause.

Both formats support an optional ELSE argument. If no ELSE clause

is used, then ELSE NULL is implied.
Syntax

Simple When/Then:
CASE case_value_expression
WHEN when_expression THEN then_expression [...]
[ ELSE else_expression ]
END

Searched When/Then:
CASE
WHEN search_expression THEN then_expression [...]
[ ELSE else_expression ]
END

Arguments

case_value_expression

The expression evaluated by the simple When/Then CASE format.

when_expression

The expression to which case_value_expression is compared. The

data types of case_value_expression and each when_expression must
be the same or must be an implicit conversion.
then_expression

The expression returned when case_value_expression equals when_

expression evaluates to TRUE.
else_expression

3-34

Grammar Statements

The expression returned if no comparison operation evaluates to

TRUE. If this argument is omitted and no comparison operation
evaluates to TRUE, CASE returns NULL.
search_expression

The Boolean expression evaluated by the searched CASE format.

Search_expression may be any valid Boolean expression.
Remarks

A CASE expression must be used within a SELECT statement. The

SELECT statement may be within a stored procedure or within a
view.

Examples

The following statement uses the simple When/Then format to

report the prerequisites for the art courses listed in the Course table.
SELECT name 'Course ID', description 'Course Title',
CASE name
WHEN 'Art 101' THEN 'None'
WHEN 'Art 102' THEN 'Art 101 or instructor
approval'
WHEN 'Art 203' THEN 'Art 102'
WHEN 'Art 204' THEN 'Art 203'
WHEN 'Art 305' THEN 'Art 101'
WHEN 'Art 406' THEN 'None'
WHEN 'Art 407' THEN 'Art 305'
END
AS 'Prerequisites' FROM Course WHERE Dept_Name = 'Art'
ORDER BY name

The query returns the following:

Course ID

Course Title

Prerequisites

Art 101

Drawing I

None

Art 102

Drawing II

Art 101 or instructor approval

Art 203

Drawing III

Art 102

Art 204

Drawing IV

Art 203

Art 305

Sculpture

Art 101

3-35

SQL Syntax Reference

Art 406

Modern Art

None

Art 407

Baroque Art

Art 305

The previous statement can be changed to include an ELSE clause:

SELECT name 'Course ID', description 'Course Title',
CASE name
WHEN 'Art 101' THEN 'None'
WHEN 'Art 102' THEN 'Art 101 or instructor
approval'
WHEN 'Art 203' THEN 'Art 102'
WHEN 'Art 204' THEN 'Art 203'
WHEN 'Art 305' THEN 'Art 101'
ELSE 'Curriculum plan for Art History majors'
END
AS 'Prerequisites' FROM Course WHERE Dept_Name = 'Art'
ORDER BY name

The query now returns the following:

Course ID

Course Title

Prerequisites

Art 101

Drawing I

None

Art 102

Drawing II

Art 101 or instructor approval

Art 203

Drawing III

Art 102

Art 204

Drawing IV

Art 203

Art 305

Sculpture

Art 101

Art 406

Modern Art

Curriculum plan for Art History majors

Art 407

Baroque Art

Curriculum plan for Art History majors

The following statement uses the searched When/Then format to

report the funding program for which a person may be eligible.
SELECT last_name, first_name,
CASE

3-36

Grammar Statements
WHEN scholarship = 1 THEN 'Scholastic'
WHEN citizenship <> 'United States' THEN 'Foreign
Study'
WHEN (date_of_birth >= '1960-01-01' AND date_of_
birth <= '1970-01-01') THEN 'AJ-44 Funds'
ELSE 'NONE'
END
AS 'Funding Program' FROM Person ORDER BY last_name

Here is a partial listing of what the query returns:

Last_Name

First_Name

Funding Program

Abad

Alicia

NONE

Abaecherli

David

Foreign Study

Abebe

Marta

Foreign Study

Abel

James

AJ-44 Funds

Abgoon

Bahram

Foreign Study

Abken

Richard

NONE

Abu

Austin

Foreign Study

Abuali

Ibrahim

AJ-44 Funds

Acabbo

Joseph

NONE

Acar

Dennis

Foreign Study

The following example show how a CASE expression may be used

within a stored procedure.
CREATE PROCEDURE pcasetest () RETURNS (d1 CHAR(10), d2
CHAR(10));
BEGIN
SELECT c1, CASE WHEN c1 = 1 THEN c4
WHEN c1 = 2 THEN c5
ELSE
CASE WHEN c2 = 100.22 THEN c4
WHEN c2 = 101.22 THEN c5 END END
FROM tcasetest;

3-37

SQL Syntax Reference

END
CALL pcasetest

The following example show how a CASE expression may be used

within a view.
CREATE VIEW vcasetest (vc1, vc2) AS
SELECT c1, CASE WHEN c1 = 1 THEN c4
WHEN c1 = 2 THEN c5
ELSE
CASE WHEN c2 = 100.22 THEN c4
WHEN c2 = 101.22 THEN c5 END END
FROM TCASEWHEN
SELECT * FROM vcasetest

See Also

COALESCE on page 3-41

SELECT on page 3-202

3-38

Grammar Statements

CASE (string)
Remarks

The CASE keyword causes Pervasive PSQL to ignore case when

evaluating restriction clauses involving a string column. CASE can
be specified as a column attribute in a CREATE TABLE or ALTER
TABLE statement, or in an ORDER BY clause of a SELECT
statement.
For example, suppose you have a column called Name that is defined
with the CASE attribute. If you insert two rows with Name = Smith
and Name = SMITH, a query with a restriction specifying Name =
smith correctly returns both rows.
Note CASE (string) does not support multiple-byte character

strings. The keyword assumes that the string data is single-byte

ASCII. The string functions do support multiple-byte character
strings. See String Functions on page 5-2.

Examples

The following example shows how you add a column to the Student
table with the CASE keyword.
ALTER TABLE Student ADD Name char(64) CASE

The following example shows how to use CASE in an ORDER BY

clause of a SELECT statement.
SELECT Id, Last_Name+', '+First_Name AS Whole_Name,
Phone FROM Person ORDER BY Whole_Name CASE

See Also

ALTER TABLE on page 3-10

CREATE TABLE on page 3-80
SELECT on page 3-202

3-39

SQL Syntax Reference

CLOSE
Remarks

The CLOSE statement closes an open SQL cursor.

The cursor that the cursor name specifies must be open.
This statement is allowed only inside of a stored procedure, userdefined functions, or a trigger. Cursors and variables are only
allowed inside of stored procedures, user-defined functions, and
triggers.

Syntax

CLOSE cursor-name
cursor-name ::= user-defined-name

Examples

The following example closes the cursor BTUCursor.

CLOSE BTUCursor;

CREATE PROCEDURE MyProc(OUT :CourseName CHAR(7)) AS

BEGIN
DECLARE cursor1 CURSOR
FOR SELECT Degree, Residency, Cost_Per_Credit
FROM Tuition ORDER BY ID;
OPEN cursor1;
FETCH NEXT FROM cursor1 INTO :CourseName;
CLOSE cursor1;
END

See Also

OPEN on page 3-185

CREATE PROCEDURE on page 3-66
CREATE TRIGGER on page 3-103

3-40

Grammar Statements

COALESCE
The COALESCE scalar function takes two or more arguments and
returns the first nonnull argument, starting from the left in the
expression list.
Syntax

COALESCE ( expression, expression[,...])

Arguments

expression

Is any valid expression

Returned Value
Types

The COALESCE function returns the value of one of the expressions

in the list. For a detailed list of returned data types, see Supported
Combination Types and Result Data Types on page 3-42.

Restrictions

The function takes a minimum of two arguments.

Valid:
COALESCE(10, 20)

Invalid:
COALESCE()

Note An invalid instance results in a parse-time error:

COALESCE must have at least 2 arguments.

The expression list must contain at least one non-null argument.
Valid:
COALESCE (NULL, NULL, 20)

Invalid:
COALESCE (NULL, NULL, NULL)

3-41

SQL Syntax Reference

Note An invalid instance results in a parse-time error:

All arguments of COALESCE cannot be the NULL function

The function does not support some of the data type combinations
in the expression list.
For example, COALESCE cannot have BINARY and VARCHAR
types as arguments as neither of them can be implicitly converted to
the other.
Supported
Combination
Types and Result
Data Types

3-42

The following figure details the various supported combination

types and also helps you identify the resultant data type for various
combinations in a COALESCE function.
Figure 3-1 COALESCE Supported Combinations and Resultant Data Types

Grammar Statements

Chart Element

Description
Types can be used directly in COALESCE function. The result type is that of operand 2.
Types can be used directly in COALESCE function. The result type is that of operand 1.

blank cell

Types are not compatible. The operands cannot be used directly in COALESE. An explicit
CONVERT is required.

Result type is SQL_DOUBLE

Result type is SIM_BCD

Result type is SQL_INTEGER

Result type is SQL_SMALLINT

Using any of the unsupported type combinations (those left blank in

the chart) in COALESCE function results in a parse-time error:
ODBC Error: SQLSTATE = 01S01, Native error code = 0
Error in row
Error in assignment
Expression evaluation error
Examples

SELECT COALESE(NULL,10 + 2,15,NULL)

10+2 is treated as a SMALLINT and ResultType (SQL_SMALLINT,

SQL_SMALLINT) is SQL_SMALLINT. Hence, the result type is
SQL_SMALLINT.
The first parameter is null. The second expression evaluates to 12,
which is not null and can be converted to result type SQL_
SMALLINT. Therefore, the return value of this example is 12.

SELECT COALESCE(10, 'abc' + 'def')

Ten is treated as a SMALLINT and ResultType (SQL_SMALLINT,

SQL_VARCHAR) is SQL_SMALLINT. Hence, the result type is
SQL_SMALLINT.
The first parameter is 10, which can be converted to result type SQL_
SMALLINT. Therefore, the return value of this example is 10.

3-43

SQL Syntax Reference

COMMIT
The COMMIT statement signals the end of a logical transaction and
converts temporary data into permanent data.
Syntax

COMMIT [ ]

Remarks

COMMIT (and START TRANSACTION) is supported only within

stored procedures. You cannot use COMMIT or START
TRANSACTION within the SQL Editor. (SQL Editor sets
AUTOCOMMIT to on.)
Any committed statements within a stored procedure are controlled
by the outermost transaction of the calling ODBC application. This
means that, depending on the AUTOCOMMIT mode specified on
SQLSetConnectOption, calling the stored procedure externally from
an ODBC application performs one of two actions. It either commits
automatically (AUTOCOMMIT on, the default) or waits for you to
call SQLTransact with SQL_COMMIT or SQL_ROLLBACK (when
AUTOCOMMIT is set to off).
You may execute multiple START TRANSACTION statements to
start nested transactions, but the outermost COMMIT controls
whether any nested committed blocks are committed or rolled back.
For example, if transactions are nested five levels, then five
COMMIT statements are needed to commit all of the transactions.
COMMIT does not release any lock until the outermost transaction
is committed.
COMMIT and COMMIT WORK perform the same functionality.

Examples

The following example, within a stored procedure, begins a

3-44

Grammar Statements
WHERE E.Student_ID = B.Student_ID);
COMMIT WORK;
START TRANSACTION;
UPDATE Billing B
SET Amount_Paid = 0
WHERE Student_ID IN
(SELECT DISTINCT E.Student_ID
FROM Enrolls E, Billing B
WHERE E.Student_ID = B.Student_ID);
COMMIT WORK;

CREATE PROCEDURE UpdateBilling( ) AS

BEGIN
START TRANSACTION;
UPDATE Billing SET Amount_Owed =
Amount_Owed + Amount_Owed;
UPDATE Billing set Amount_Owed = Amount_Owed + 100
WHERE Student_ID = 10;
COMMIT;
END;

See Also

CREATE PROCEDURE on page 3-66

ROLLBACK on page 3-197
START TRANSACTION on page 3-264

3-45

SQL Syntax Reference

CREATE DATABASE
The CREATE DATABASE statement creates a new database. Any user
logged in to a database can issue the statement. (The user must also
have permissions at the operating system to create files in the
specified location.)
Syntax

CREATE DATABASE [ IF NOT EXISTS ] database-name DICTIONARY_

PATH 'dict-path-name' [ DATA_PATH 'data-path-name' ] [ ; 'datapath-name' ]... ] [ NO_REFERENTIAL_INTEGRITY ] [ BOUND
] [ REUSE_DDF ] [ DBSEC_AUTHENTICATION ] [ DBSEC_
AUTHORIZATION ] [ V1_METADATA | V2_METADATA ]
database-name ::= user-defined-name
dict-path-name ::= user-defined-path
data-path-name ::= user-defined-path

Remarks

CREATE DATABASE creates only a database, not an associated data

source name (DSN). You need to create an engine DSN separately if
you want one. See To set up an Engine DSN using ODBC
Administrator on page 2-19 in Pervasive PSQL User's Guide.
The CREATE DATABASE statement cannot be used to create the first
database on a server. The reason is that a user must log on to a
database before issuing the CREATE DATABASE statement.
Therefore, at least one database must already exist.
The CREATE DATABASE statement cannot be used in a stored
procedure or in a user-defined function.
Database Name and IF NOT EXISTS Clause
Database-name specifies a name for the new database. The database
names must be unique within a server and conform to the rules for
identifiers. See Identifier Restrictions by Identifier Type on page 13 in Advanced Operations Guide.
An error occurs if the database exists and you omit the IF NOT
EXISTS clause (status code 2303). No error returns if you include the
IF NOT EXISTS clause.

3-46

Grammar Statements

Dictionary Path
Dict-path-name specifies where the dictionary files (DDFs) reside on
physical storage. The data files are also placed in this same location
when you use the CREATE TABLE on page 3-80 statement or create
tables using Pervasive PSQL Control Center (PCC). See Dictionary
Location on page 3-21 in Pervasive PSQL User's Guide.
Data Path
Data-path-name specifies a possible location of the data files for the
database (see Note below). You can specify multiple path names by
delimiting them with a semicolon.
Data-path-name can be any path that is valid from the database
engine's point of view, not from the calling application's perspective.
The location specified must already exist. The CREATE DATABASE
statement does not create directories.
Omit data-path-name if you want to use the same location for the
data files as for the dictionary files. You may also specify the same
location by passing an empty string for data-path-name. For
example, specifying DATA_PATH '' indicates an empty string for the
data path.
Note If you create tables using the CREATE TABLE statement or

with PCC, the data files are placed in the first dict-path-name
specified. If no dict-path-names are specified, data files are
created in the dict-path-name location.
Data-path-name is useful if you are creating tables through the
Distributed Tuning Interface (DTI). The DTI function
PvAddTable allows you to specify where you want the data files
located. See PvAddTable() on page 2-21 in the SDK book
Distributed Tuning Interface Guide.

Referential Integrity
By default, the database engine enforces referential integrity. If you
specify the NO_REFERENTIAL_INTEGRITY clause, then any
triggers and referential integrity defined in the database are not
enforced.

3-47

SQL Syntax Reference

See Setting Up Referential Integrity on page 6-1 and Interactions

Between Btrieve and Relational Constraints on page 6-11.
BOUND
If BOUND is specified, the DDFs are bound to the database. A
bound database associates a database name with a single set of DDFs,
which refer to only one set of data files. The DDFs are bound whether
they already existed or are created through the execution of the
CREATE DATABASE statement.
If DDFs are bound, you cannot use those DDFs for more than one
database, nor can you refer to the data files by more than one set of
DDFs.
If BOUND is not specified then the DDFs are not bound to a
database.
See Bound Database versus Integrity Enforced on page 6-13 in
Advanced Operations Guide.
Dictionary Files
The REUSE_DDF keyword associates any existing DDFs with the
database. The existing DDFs must in the dict-path-name location.
If REUSE_DDF is omitted, new DDFs are created unless DDFs
already exists in the dict-path-name location. If DDFs exists in the
dict-path-name location, they are associated with the database
instead of new DDFs being created.
Security
The database engine supports three security models for the
transactional interface:

3-48

Classic. A user who successfully logs into the computer has

access to the database contents at whatever level of file system
rights the user has been assigned to the data file. File system
rights are assigned through the operating system.
Database. Database user accounts are unrelated to operating
system user accounts. A users access rights to the data are
governed by user permissions set up in the database.

Grammar Statements

Mixed. This policy has aspects of both of the other policies. Users
log in using their operating system user names and passwords,
but a users access rights to the data are governed by user
permissions set up in the database.

See the chapter Pervasive PSQL Security on page 7-1 in Advanced

Operations Guide for a complete discussion of security.
The DBSEC_AUTHENTICATION and DBSEC_
AUTHORIZATION keywords set the security policy for the
database:
Keyword Included or Omitted in Statement

Security Model

DBSEC_AUTHENTICATION

DBSEC_AUTHORIZATION

Classic

omitted

included

omitted

included

Database

Mixed

Metadata Version
The relational interface supports two versions of metadata, referred
to as version 1 (V1) and version 2 (V2). Metadata version applies to
all data dictionary files (DDFs) within that database. V1 metadata is
the default.
Among other features, V2 metadata allows for many identifier names
to be up to 128 bytes long and for permissions on views and stored
procedures. See Versions of Metadata on page 2-2 for a complete
discussion.
You may include or omit the V1_METADATA keyword to specify V1
metadata. You must include the V2_METADATA keyword to specify
V2 metatadata.
See also Versions of Metadata on page 2-2.
Examples

The following example creates a database named inventorydb and

specifies its location for DDFs on drive D: in the folder mydbfiles\
ddf_location. New DDFs are created because none exist in d:\
mydbfiles\ddf_location. The data files are placed in the same
location as the DDFs. The database uses V1 metadata.

3-49

SQL Syntax Reference

CREATE DATABASE inventorydb DICTIONARY_PATH 'D:\
mydbfiles\ddf_location'

The following example creates a database named HRUSBenefits if

it does not already exist, and specifies its location for DDFs on drive
C: in the folder HRDatabases\US. Possible locations for the data
files include the C: drive in a directory called HRDatabases\US\
DataFiles and the E: drive in a directory called Backups\
HRUSData (see Note under Data Path). Existing DDFs are used if
they exist in the DICTIONARY_PATH. The database uses V1
metadata.
CREATE DATABASE IF NOT EXISTS HRUSBenefits DICTIONARY_
PATH 'C:\HRDatabases\US' DATA_PATH 'C:\HRDatabases\
US\DataFiles ; E:\Backups\HRUSData' REUSE_DDF

The following example creates a database named EastEurope,

specifies its location for DDFs on drive C: in the folder Europe\
DbaseFiles, creates new DDFs and binds them to the database, sets
the security policy to mixed, and uses V2 metadata.
CREATE DATABASE EastEurope DICTIONARY_PATH 'C:\Europe\
DbaseFiles' BOUND DBSEC_AUTHORIZATION V2_METADATA

See Also

3-50

DROP DATABASE on page 3-129

Grammar Statements

CREATE FUNCTION
The CREATE FUNCTION statement creates a scalar user-defined
function (UDF) in the database. You can invoke the user-defined
functions from a query.
Syntax

CREATE FUNCTION function-name ( [ [ IN ]

{ :parameter_name scalar_parameter_data_type } [...] ] )
RETURNS scalar_return_data_type
[AS]
BEGIN
body_of_function

RETURN scalar_expression
END;

Arguments

function_name

Name of the scalar UDF. UDF names must conform to the rules for
identifiers and must be unique within the database and to its owner.
parameter_name

A parameter in the scalar UDF. A maximum of 300 parameters is

allowed. The value must be supplied when the function is invoked.
scalar_parameter_data_type

The data type for the specified parameter name.

scalar_return_data_type

The return value of a scalar UDF. Only scalar types are supported.
body_of_function

The statements that compose the scalar function.

scalar_expression

Specifies the scalar value that the scalar function returns.

Remarks

You must have the CREATE FUNCTION permission in the database

in which you wish to create a scalar UDF.
Each fully qualified UDF name (database-name.function-name)
must be unique within a database. The UDF name cannot be the
same as that of a built-in function or any other UDF in the same
database.

3-51

SQL Syntax Reference

Restrictions

You cannot use the CREATE DATABASE or the DROP DATABASE

statement in a user-defined function. The table actions CREATE,
ALTER, UPDATE, DELETE, and INSERT are not permitted within a
user-defined function.
Only scalar input parameters are supported. No OUTPUT and
INOUT parameters are allowed. By default, all parameters are input.
You need not specify the IN keyword.

Limits

Observe the following limitations when you create user-defined

functions.
Attribute

Limit

Number of parameters

300

Size of the UDF body

64 KB

Maximum length of a UDF name

See Table 1-1, Identifier Restrictions

by Identifier Type, in Advanced
Operations Guide

Maximum length of a UDF variable name

128 characters

Supported Scalar Input Parameters and Returned Data Types

The following are the supported data types for input scalar
parameters and returned values in Pervasive PSQL.
Table 3-1 Supported Input Parameters and Returned Data Types

3-52

BIGINT

BINARY

BIT

BLOB

CHAR

CHARACTER

CLOB

CURRENCY

DATE

DEC

DECIMAL

DOUBLE

DOUBLE PRECISION

FLOAT

IDENTITY

INT

INTEGER

LONG

LONG VARBINARY

LONG VARCHAR

LONGVARBINARY

LONGVARCHAR

NUMERIC

REAL

SMALLIDENTITY

SMALLINT

Grammar Statements

Table 3-1 Supported Input Parameters and Returned Data Types continued
SMALLINT

SPT_BINARY

SPT_BIT

SPT_CHAR

SPT_DATE

SPT_DECIMAL

SPT_DOUBLE

SPT_INTEGER

SPT_LONGVARBIN

SPT_LONGVARCHAR

SPT_NUMERIC

SPT_REAL

SPT_SMALLINT

SPT_TIME

SPT_TIMESTAMP

SPT_TINYINT

SPT_VARBINARY

SPT_VARCHAR

TIME

TIMESTAMP

TINYINT

UBIGINT

UINT

UINTEGER

UNIQUEIDENTIFIER

USMALLINT

UTINYINT

VARBINARY

VARCHAR

Examples

The following example creates a function that calculates the area of a

rectangular box whose details are stored in the Box table:
CREATE FUNCTION CalculateBoxArea(:boxName char(20))
RETURNS REAL
AS
BEGIN
DECLARE :len REAL;
DECLARE :breadth REAL;
SELECT len, breadth INTO :len, :breadth FROM box
WHERE name = :boxName;
RETURN(:len * :breadth);
END;

The following example creates a function that compares two integers

and returns the smaller of the two:
CREATE FUNCTION GetSmallest(:A integer, :B Integer)
RETURNS Integer
AS
BEGIN

3-53

SQL Syntax Reference

DECLARE :smallest INTEGER
IF (:A < :B ) THEN
SET :smallest = :A;
ELSE
SET :smallest = :B;
END IF;
RETURN :smallest;
END;

The following example creates a function that calculates simple

interest using the formula SI = PTR/100, where P is the Principle, T
is the period, and R is the rate of interest.
CREATE FUNCTION CalculateInterest(IN :principle float,
IN :period real, IN :rate double)
RETURNS DOUBLE
AS
BEGIN
DECLARE :interest DOUBLE;
SET :interest = ((:principle * :period * :rate) /
100);
RETURN (:interest);
END;

Invoking a Scalar User-Defined Function

You can invoke a user-defined function wherever scalar expressions

are supported, by specifying the function name followed by a
comma-separated list of arguments. The list of arguments is
enclosed in parentheses.
A UDF can be invoked with or without a database qualifier prefix.
When a database qualifier is not prefixed, the UDF is executed from
the current database context. If a database qualifier is prefixed, the
UDF is executed in the context of the specified database. (In the
examples below, some use a database qualifier prefix and some do
not.)
Limits

3-54

Parameter names cannot be specified in the arguments, when

invoking a function.

Grammar Statements

The argument values for all parameters (also known as actual

parameters) must be in the same sequence in which the parameters
are defined in the CREATE FUNCTION statement (also known as
formal parameters).
Examples

UDF in Procedures
CREATE PROCEDURE procTestUdfInvoke() AS
begin
DECLARE :a integer;
SET :a = 99 + (222 + Demodata.GetSmallest(10, 9)) +
10;
PRINT :a;
end;
CALL procTestUdfInvoke()

The following example is similar to the previous one, except that the
database qualifier is omitted.
create procedure procTestUdfInvoke2() as
begin
declare :a integer;
set :a = 99 + (222 + GetSmallest(10, 9)) +10;
print :a;
end;
call procTestUdfInvoke2

UDF in SELECT list

SELECT GetSmallest(100,99)

UDF in WHERE clause

SELECT name FROM class WHERE id <= GetSmallest(10,20)

UDF within UDF

CREATE FUNCTION funcTestUdfInvoke() RETURNS integer AS
begin
DECLARE :a integer;

3-55

SQL Syntax Reference

SET :a = 99 + (222 - Demodata.GetSmallest(10, 9));
RETURN :a;
END;

UDF in INSERT statement

CREATE TABLE t1(col1 integer, col2 integer, col3 float)
INSERT INTO t1 VALUES (GetSmallest(10,20), 20 , 2.0)
INSERT INTO t1 (SELECT * FROM t1 WHERE col1 =
getSmallest(10,20))

UDF in UPDATE statement

UPDATE t1 SET col2 = Demodata.GetSmallest(2,10) WHERE
col1 = 2
UPDATE t1 SET col1 = 3 WHERE col2 =
Demodata.GetSmallest(10, 5)

UDF in GROUP BY statement

SELECT col2 FROM t1 GROUP BY getSmallest(10,2), col2

UDF in ORDER BY statement

SELECT col2 FROM t1 ORDER BY Demodata.getSmallest(10,2),
col2

Recursive UDF
CREATE FUNCTION factorial(IN :n integer) RETURNS double
AS BEGIN
DECLARE :fact double;
IF (:n <= 0) THEN
SET :fact = 1;
else
SET :fact = (:n * Demodata.factorial(:n - 1));
END IF;
RETURN :fact;
END;

3-56

Grammar Statements

SELECT Demodata.factorial(20) can be used to get the factorial

value of 20.

UDF with default values

CREATE FUNCTION testUdfDefault(:z integer = 10) RETURNS
integer AS
begin
RETURN :z-1;
end;

SELECT Demodata.testUdfDefault(). This function takes the default

value specified in case the value of the parameter is not given.

IUDF with dynamic parameters

SELECT name FROM class WHERE id <= GetSmallest(?,?)

IUDF as an expression
SELECT 10 + Demodata.Getsmallest(10,20) + 15

UDF used as parameters

SELECT demodata.calculateinterest
(10+demodata.getsmallest(3000, 2000),
demodata.factorial(2), demodata.testUdfDefault(3))

See Also

DECLARE on page 3-113

DROP FUNCTION on page 3-131

3-57

SQL Syntax Reference

CREATE GROUP
The CREATE GROUP statement creates one or more security
groups.
Syntax

CREATE GROUP group-name [ , group-name ]...

group-name

Remarks

::= user-defined-name

Only the Master user can perform this statement.

Security must be turned on to perform this statement.

Examples

The following example creates a group named pervasive.

CREATE GROUP pervasive

The next example uses a list to create several groups at once.

CREATE GROUP pervasive_dev, pervasive_marketing

See Also

ALTER USER on page 3-26

CREATE USER on page 3-106
DROP GROUP on page 3-132
GRANT on page 3-149
SET SECURITY on page 3-250
REVOKE on page 3-194

3-58

Grammar Statements

CREATE INDEX
Use the CREATE INDEX statement to create a named index for a
specified table.
Syntax

CREATE [ UNIQUE | PARTIAL ] [ NOT MODIFIABLE ] INDEX indexname [ IN DICTIONARY ] ON table-name [ index-definition ]
index-name

::= user-defined-name

table-name

::= user-defined-name

index-definition

]... )

::= ( index-segment-definition [ , index-segment-definition

index-segment-definition

Remarks

::= column-name [ ASC | DESC ]

The maximum column size for VARCHAR and CHAR columns is

255 bytes. VARCHAR columns differ from CHAR columns in that
either the length byte (Btrieve lstring) or a zero terminating byte
(Btrieve zstring) are reserved, reducing the effective storage by 1
byte. In other words, you can fit 255 useful characters in a
CHAR(255) type, but only 254 useful characters in a VARCHAR,
after you reserve a byte for the size or null terminator.
Whenever you create a relational index definition for an existing data
file (through the use of CREATE INDEX or CREATE INDEX IN
DICTIONARY), Pervasive PSQL automatically checks the Btrieve
indexes defined on the file to determine whether an existing Btrieve
index offers the set of parameters requested by the relational index
definition. If an existing Btrieve index matches the new definition
being created, then an association is created between the relational
index definition and the existing Btrieve index. If there is no match,
then Pervasive PSQL create a new index definition and, if IN
DICTIONARY is not specified, a new index in the data file.

3-59

SQL Syntax Reference

Index Segments
The number of index segments that you may use depends on the
files page size.
Page Size (bytes)

Maximum Key Segments byFile Version

8.x and prior

512

9.0

9.5
rounded up2

1,024

1,536

rounded up2

2,048

2,560

rounded up2

3,072

rounded up2

3,584

rounded up2

4,096

119

1193

8,192

n/a1

119

1193

16,384

n/a1

1193

n/a stands for not applicable

2rounded

up means that the page size is rounded up to the next size

supported by the file version. For example, 512 is rounded up to 1,024,
2,560 is rounded up to 4,096, and so forth.

3The

maximum number of index segments that can be used with the

relational interface is 119. For the transactional interface, the maximum
number is 204 for a page size of 4,096, and 420 for page sizes 8,192 and
16,384.

Note that nullable columns must also be considered. For example,

in a data files with 4096 byte page size you are limited to 119 index
segments per file. Because each indexed nullable column with true
null support requires an index consisting of 2 segments, you cannot
have more than 59 indexed nullable columns in a table (or indexed
nullable true null fields in a Btrieve file). This limit is smaller for
smaller page sizes.
Any file created with file version set to 7.x or later, and
TRUENULLCREATE set to the default value of On, has true null
support. Files created using an earlier file format, or with

3-60

Grammar Statements

Pervasive.SQL 7, or with TRUENULLCREATE set to Off, do not have

true null support and do not have this limitation.
A UNIQUE segment key guarantees that the combination of the
segments for a particular row are unique in the file. It does not
guarantee or require that each individual segment is unique.
Note All data types can be indexed except for the following:
BIT
LONGVARBINARY
LONGVARCHAR
BLOB
CLOB

See also status code 6008: Too Many Segments on page 1-139 in
Status Codes and Messages.
PARTIAL

Use the PARTIAL keyword with a CREATE INDEX statement to

create an index on a column, or group of columns, totalling more
than 255 bytes.
Partial indexes are created using a prefix of a wide column, or by
combining multiple small columns, so that searches using a prefix of
the wide column will execute faster. Therefore, queries using
WHERE clause restrictions, for example 'WHERE column_name
LIKE 'prefix%' would execute faster using the partial index as
opposed to not using any index.
If you include the PARTIAL keyword with a CREATE INDEX
statement, and the index column(s) width and overhead do not
equal or exceed 255 bytes, the PARTIAL keyword is ignored and a
normal index is created instead.
Note Width refers to the actual size of the column, and overhead

refers to NULL indicators, string lengths, and the like.

Limitations

The following limitations apply when using PARTIAL:

3-61

SQL Syntax Reference

Partial indexes may only be added to columns with the data type
of CHAR or VARCHAR.
Partial index columns should always be the last column in the
index definition, or should be the only column in the index
definition.
When the the partial index column is the only column in the
index, the column size can be up to 8000 bytes, but the user-data
index segment will be of size 255 bytes minus any overhead
segments.

Partial indexes are not used by the engine while executing

queries with strict equality or collation operations, such as
ORDER BY, GROUP BY or JOINs involving the partial column.
Partial indexes are used only while matching WHERE clause
restrictions of the following form:
WHERE col

WHERE col

LIKE 'literal%'

'literal'

WHERE col

LIKE ?

where the literal or actual parameter value can be of any length.

It could be shorter or wider than the number of bytes indexed in
the partial index column. Partial indexes won't be used if a LIKE
clause is not of the form 'prefix%'.
If the WHERE clauses match the constraints listed previously, partial
indexes will be used while creating the execution plan.
Note If a partially indexed column length is altered using ALTER

TABLE such that the new length fits in 255 bytes of the index or
when the new length overshoots 255 bytes, it is the responsibility
of the user to drop the index and recreate it according to his/her
requirements.

Examples

The following example creates a table named Part_tbl with columns

PartID, PartName, SerialNo and Description, using the specified
data types and sizes.
CREATE TABLE part_tbl (partid INT, partname CHAR(50),
serialno VARCHAR(200), description CHAR(300));

3-62

Grammar Statements

Next, the example creates a partial index named idx_01 using the
Description column.
CREATE PARTIAL INDEX idx_01 on part_tbl (description);

Although the Description column used in the index is 300 bytes,

using the PARTIAL keyword enables the index to only use the first
255 bytes (including overhead) as the prefix.

The following example creates a partial index named idx_02 for the
same table in the previous example. Instead, this example uses the
PartId, SerialNo, and Description columns collectively for the index.
CREATE PARTIAL INDEX idx_02 on part_tbl (partid,
serialno, description);

The following table details the index columns so that you may
understand how the wide column is allocated in the index.

Column Name

Data Type

Size

PartID

Integer

SerialNo

Varchar

200

Description

Char

300

Overhead

Size in Index
4

Total Index Size

201
50
255

IN DICTIONARY

The purpose of using this keyword is to notify Pervasive PSQL that

you wish to make modifications to the DDFs, while leaving the
underlying physical data unchanged.
You cannot use this keyword on a bound database.
IN DICTIONARY is a very powerful and advanced feature. It should
only be used by system administrators or when absolutely necessary.
Normally, Pervasive PSQL keeps DDFs and data files perfectly
synchronized, but this feature allows users the flexibility to force outof-sync table dictionary definitions to match an existing data file.
This can be useful when you want to create a definition in the
dictionary to match an existing data file.

3-63

SQL Syntax Reference

Caution Modifying a DDF without performing parallel

modifications to the underlying data file can cause serious

problems.
If you have created a disjointed index, one that exists only in the DDF
and not in the data file, and you attempt to drop the index without
using IN DICTIONARY, you may encounter Status Code 6 (invalid
key number). This error occurs because the database engine
attempts to delete the index from the data file, and it is unable to do
so because no such index exists in the data file.
You cannot control the number assigned to a Btrieve index (key) if
you create the index through SQL. If you use SQL to create indexes
on a Btrieve file that has no indexes defined, the first index created is
index #0, the second is index #1, and so forth.
If the Btrieve file already has one or more indexes defined, adding an
index through SQL causes Pervasive PSQL to check the Btrieve
indexes for one that has the required attributes. A description of the
new index is inserted into INDEX.DDF. If Pervasive PSQL can match
an existing Btrieve index, the inserted description includes the index
number of the existing index and no new Btrieve index is generated
on the data file.
If Pervasive PSQL cannot match an existing Btrieve index, the
smallest unused index number is specified in the description. The
description of the new index is inserted into INDEX.DDF. If IN
DICTIONARY is not specified, then a Btrieve index is created on the
data file using the index number specified in the description.
Since you cannot specify which index number is used to create new
indexes in INDEX.DDF, finding out the index number is a manual
process. First, issue the command BUTIL -STAT on the underlying
Btrieve file to get a listing of the Btrieve indexes. Then you can query
X$Index to see which SQL index number(s) will be used next.
SELECT X$Index.* from X$Index
WHERE Xi$file in
(SELECT Xf$Id FROM X$File
WHERE Xf$Name = 'tablename')

Substitute the name of your database table for tablename.

3-64

Grammar Statements

The following example creates an index named Dept based on Dept_

name in the Faculty table.
CREATE INDEX Dept on Faculty(Dept_Name)

The following example creates a non-modifiable segmented index in

the Person table.
CREATE NOT MODIFIABLE INDEX X_Person on Person(ID, Last_
Name)

The following examples create a detached table, one with no

associated data file, then add and drop an index from the table
definition. Again, this index is a disjointed index because there is no
underlying Btrieve index associated with it.
CREATE TABLE t1 IN DICTIONARY (c1 int, c2 int)
CREATE INDEX idx_1 IN DICTIONARY on t1(c1)
DROP INDEX t1.idx_1 IN DICTIONARY

See Also

DROP INDEX on page 3-133

3-65

SQL Syntax Reference

CREATE PROCEDURE
The CREATE PROCEDURE statement creates a new stored
procedure. Stored procedures are SQL statements that are predefined and saved in the database dictionary.
Syntax

CREATE PROCEDURE procedure-name

( [ parameter [, parameter ]... ] )

[ RETURNS ( result [ , result ]... ) ] see Remarks

[ WITH DEFAULT HANDLER | WITH EXECUTE AS MASTER |
WITH DEFAULT HANDLER , EXECUTE AS MASTER | WITH
EXECUTE AS MASTER, DEFAULT HANDLER]
as-or-semicolon
proc-stmt
procedure-name
parameter
expr

::= user-defined-name

::= parameter-type-name data-type [ DEFAULT proc-expr | = proc]

| SQLSTATE

parameter-type-name ::= parameter-name

| parameter-type parameter-name
| parameter-name parameter-type
parameter-type
parameter-name

::= IN | OUT | INOUT | IN_OUT

::= :user-defined-name

::= same as normal expression but does not allow IF expression,

or ODBC-style scalar functions

proc-expr

result

::= user-defined-name data-type

as-or-semicolon
proc-stmt
stmt

::= AS | ;

::= [ label-name : ] BEGIN [ATOMIC] [ proc-stmt [ ; proc]... ] END [ label-name ]

| CALL procedure-name ( proc-expr [ , proc-expr ]... )

3-66

Grammar Statements

| delete-statement
| FETCH [ fetch-orientation [ FROM ] ]cursor-name [ INTO variablename

[ , variable-name ] ]

| IF proc-search-condition THEN proc-stmt [ ; proc-stmt ]... [ ELSE

::= commit-statement

| rollback-statement

3-67

SQL Syntax Reference

| release-statement
commit-statement

::= see COMMIT statement

::= see ROLLBACK statement

rollback-statement
release-statement

::= see RELEASE SAVEPOINT statement

create-table-statement ::=

see CREATE TABLE statement

alter-table-statement ::=

see ALTER TABLE statement

drop-table-statement ::=

see DROP TABLE statement

create-index-statement ::=

see CREATE INDEX statement

drop-index-statement ::=

see DROP INDEX statement

create-view-statement ::=

see CREATE VIEW statement

drop-view-statement ::=
grant-statement ::=
revoke-statement ::=
set-statement ::=
label-name
cursor-name

see DROP VIEW statement

see GRANT statement

see REVOKE statement

see SET DECIMALSEPARATORCOMMA statement

::= user-defined-name
::= user-defined-name

variable-name

::= user-defined-name

::= same as normal search-condition, but does not

allow any expression that includes a subquery.

proc-search-condition

fetch-orientation
sqlstate-value

Remarks

::= | NEXT

::= 'string'

To execute stored procedures, use the CALL or EXECUTE statement.

Note that, in a procedure, the name of a variable and the name of a
parameter must begin with a colon (:), both in the definition and use
of the variable or parameter.
The RETURNS clause is required if the stored procedure returns a
result set or a scalar value.
The WITH DEFAULT HANDLER clause, when present, causes the
procedure to continue execution when an error occurs. The default
behavior (without this clause) is to abort the procedure with
SQLSTATE set to the error state generated by the statement.

3-68

Grammar Statements

The use of a StmtLabel at the beginning (and optionally at the end)

of an IF statement is an extension to ANSI SQL 3.
The PRINT statement applies only to Windows-based platforms. It
is ignored on other operating system platforms.
In SQL Editor, the only way to test a stored procedure by using
variable parameters is to call the stored procedure from another
stored procedure. This technique is shown in the example for pdate
(CREATE PROCEDURE pdate();).
You may use variables as SELECT items only within stored
procedures. This technique is shown in the example for varsub1
(CREATE PROCEDURE varsub1 ();).
You cannot use the CREATE DATABASE or the DROP DATABASE
statement in a stored procedure.
Trusted and Non-Trusted Stored Procedures

A trusted stored procedure includes the WITH EXECUTE AS

MASTER clause. See Trusted and Non-trusted Objects on page 3154.
Memory Caching
By default, the database engine creates a memory cache in which to
store multiple stored procedures for the duration of the SQL session.
Once a stored procedure is executed, its compiled version is then
retained in the memory cache. Typically, caching results in improved
performance for each subsequent call to a cached procedure. The
cache provides no performance improvement the first time that a
stored procedure is executed since the procedure has not yet been
loaded into memory.
Two SET statements apply to the memory cache:

SET CACHED_PROCEDURES on page 3-231 specifies the

number of procedures to cache. The default is 50.
SET PROCEDURES_CACHE on page 3-245 specifies the
amount of memory for the cache. The default is 5 MB.

Note that excessive memory swapping, or thrashing, could occur

depending on the cache settings and the SQL being executed by your
application. Thrashing can cause a decrease in performance.

3-69

SQL Syntax Reference

Caching Exclusions

A stored procedure is not cached, regardless of the cache setting(s),

for any of the following:

Data Type
Restrictions

The stored procedure references a local or a global temporary

table. A local temporary table has a name that begins with the
pound sign (#). A global temporary table has a name that begins
with two pound signs (##). See CREATE (temporary) TABLE
on page 3-93.
The stored procedure contains any data definition language
(DDL) statements. See Data Definition Statements on page 13.
The stored procedure contains an EXEC[UTE] statement used
to execute a character string, or an expression that returns a
character string. For example: EXEC ('SELECT Student_ID
FROM ' + :myinputvar).

The following data types cannot be passed as parameters or declared

as variables in a stored procedure or trigger:
Table 3-2 Data Types Prohibited in Stored Procedures and Triggers

Limits

Examples

BFLOAT4

BFLOAT8

MONEY

NUMERIC

NUMERICSA

NUMERICSTS

The following limitations must be observed when creating stored

procedures:
Attribute

Limit

Number of columns allowed in a trigger or stored procedure

300

Number of arguments in a parameter list for a stored procedure

300

Size of a stored procedure

64 KB

The following example creates stored procedure Enrollstudent,

which inserts a record into the Enrolls table, given the Student ID
and the Class ID.
CREATE PROCEDURE Enrollstudent(IN :Stud_id INTEGER, IN
:Class_Id INTEGER, IN :GPA REAL);

3-70

Grammar Statements
BEGIN
INSERT INTO Enrolls VALUES(:Stud_id, :Class_id,
:GPA);
END;

Use the following statement to call the stored procedure.

CALL Enrollstudent(1023456781, 146, 3.2)

Use the following statement to retrieve the newly inserted record.

SELECT * FROM Enrolls WHERE Student_id = 1023456781

The CALL and SELECT statements, respectively, call the procedure

by passing arguments, then display the row that was added.

The following procedure reads the Class table, using the classId
parameter passed in by the caller and validates that the course
enrollment is not already at its limit.
CREATE PROCEDURE Checkmax(in :classid integer);
Begin
DECLARE :numenrolled integer;
DECLARE :maxenrolled integer;
SELECT COUNT(*) INTO :numenrolled FROM Enrolls WHERE
class_ID = :classid;
SELECT Max_size INTO :maxenrolled FROM Class WHERE id
= :classid;
IF (:numenrolled > :maxenrolled) THEN
PRINT Enrollment Failed. Number of students
enrolled reached maximum allowed for this
class ;
ELSE
PRINT Enrollment Possible. Number of students
enrolled has not reached maximum allowed for
this class;
END IF;
END;
CALL Checkmax(101)

Note that COUNT(expression) counts all non-NULL values for an

expression across a predicate. COUNT(*) counts all values,
including NULL values.

3-71

SQL Syntax Reference

The following is an example of using the OUT parameter when

creating stored procedures. Calling this procedure returns the
number of students into the variable :outval that satisfies the
WHERE clause.
CREATE PROCEDURE PROCOUT (out :outval INTEGER)
AS BEGIN
SELECT COUNT(*) INTO :outval FROM Enrolls WHERE Class_Id
= 101;
END;

The following is an example of using the INOUT parameter when

creating stored procedures. Calling this procedure requires an
INPUT parameter :IOVAL and returns the value of the output in the
variable :IOVAL. The procedure sets the value of this variable based
on the input and the IF condition.
CREATE PROCEDURE ProcIODate (INOUT :ioval DATE)
AS BEGIN
IF :ioval = '1982-03-03'
THEN
SET :ioval ='1982-05-05';
ELSE
SET :ioval = '1982-03-03';
END IF;
END;

You cannot call the above procedure using a literal value (as in call
prociodate(1982-03-03)), because it requires an output
parameter. You must first bind the parameter using ODBC calls, or
you can test the procedure by creating another procedure to call it, as
shown here:
CREATE PROCEDURE pdate();
BEGIN
DECLARE :a DATE;
CALL prociodate(:a);
PRINT :a;
END
CALL pdate

3-72

Grammar Statements

The following example illustrates using the RETURNS clause in a

procedure. This sample returns all of the data from the Class table
where the Start Date is equal to the date passed in on the CALL
statement.
CREATE PROCEDURE DateReturnProc(IN :pdate DATE)
RETURNS(
ID INTEGER,
Name CHAR(7),
Section CHAR(3),
Max_Size USMALLINT,
Start_Date DATE,
Start_Time TIME,
Finish_Time TIME,
Building_Name CHAR(25),
Room_Number UINTEGER,
Faculty_ID UBIGINT
);
BEGIN
SELECT ID, Name, Section, Max_Size, Start_Date,
Start_Time, Finish_Time, Building_Name, Room_
Number, Faculty_ID FROM class WHERE Start_Date
= :pdate;
END;
CALL DateReturnProc('2001-06-05')

Note that the user-defined names in the RETURNS clause do not

have to be named identically to the column names that appear in the
selection list, as this example shows.

The following procedure returns data from the Class table where the
Start Date is equal to the date passed in on the CALL statement.
CREATE PROCEDURE DateReturnProc (IN :pdate date, IN
:flag) AS
BEGIN
IF (:flag = 1) THEN
SELECT ID, Name, Room_Number FROM Class
WHERE start_date = :pdate;

3-73

SQL Syntax Reference

ELSE
SELECT Name FROM Class WHERE start_date =
:pdate;
END IF;
END;
CALL DateReturnProc('2001-06-05', 1)

The following example shows the use of the WHERE CURRENT OF

clause, which applies to positioned deletes.
CREATE PROCEDURE MyProc(IN :CourseName CHAR(7)) AS
BEGIN
DECLARE c1 CURSOR FOR SELECT name FROM course
WHERE name = :CourseName FOR UPDATE;
OPEN c1;
FETCH NEXT FROM c1 INTO :CourseName;
DELETE WHERE CURRENT OF c1;
CLOSE c1;
END;
CALL MyProc('HIS 305')

(Note that if you use a SELECT inside of a WHERE clause of a

DELETE, it is a searched DELETE not a positioned DELETE.)

The following example shows the use of a variable (:i) as a SELECT

item. The example assumes that table1 does not already exist. All
records in the person table with an ID greater than 950000000 are
selected, then inserted into col2 of table1. Col1 contains the value 0,
1, 2, 3, or 4 as defined by the WHILE loop.
CREATE TABLE table1 (col1 CHAR(10), col2 BIGINT);
CREATE PROCEDURE varsub1 ();
BEGIN
DECLARE :i INT;
SET :i = 0;
WHILE :i < 5 DO
BEGIN
INSERT INTO table1 (col1, col2) SELECT :i , A.ID
FROM PERSON A WHERE A.ID > 950000000;

3-74

Grammar Statements
SET :i = :i + 1;
END;
END WHILE;
END
CALL varsub1
SELECT * FROM table1
-- returns 110 rows

The following is an example of using ATOMIC, which groups a set of

statements so that either all succeed or all fail. ATOMIC can be used
only within the body of a stored procedure or trigger.
The first procedure does not specify ATOMIC, the second does.
CREATE TABLE t1 (c1 INTEGER)
CREATE UNIQUE INDEX t1i1 ON t1 (c1)
CREATE PROCEDURE p1 ();
BEGIN
INSERT INTO t1 VALUES (1);
INSERT INTO t1 VALUES (1);
END;
CREATE PROCEDURE p2 ();
BEGIN ATOMIC
INSERT INTO t1 VALUES (2);
INSERT INTO t1 VALUES (2);
END;
CALL p1()
CALL p2()
SELECT * FROM t1

Both procedures return an error because they attempt to insert

duplicate values into a unique index.
The result is that t1 contains only one record because the first
INSERT statement in procedure p1 succeeds even though the second
fails. Likewise, the first INSERT statement in procedure p2 succeeds
but the second fails. However, since ATOMIC is in procedure p2, all
of the work done inside procedure p2 is rolled back when the error is
encountered.

3-75

SQL Syntax Reference

This example uses a stored procedure to create two tables and insert
one row of default values into each. It then turns on security and
grants permissions to user user1.
CREATE PROCEDURE p1 ();
BEGIN
CREATE TABLE t1 (c1 INT DEFAULT 10, c2 INT DEFAULT
100);
CREATE TABLE t2 (c1 INT DEFAULT 1 , c2 INT DEFAULT 2);
INSERT INTO t1 DEFAULT VALUES;
INSERT INTO t2 DEFAULT VALUES;
SET SECURITY = larry;
END;
CALL p1
SELECT * FROM t1
-- returns 10, 100

SELECT * FROM t2
-- returns 1, 2

This example uses a stored procedure to revoke privileges from user

user1, drop the two tables created in Example A, and turn off database
security.
CREATE PROCEDURE p3 ();
BEGIN
REVOKE ALL ON t1 FROM user1;
REVOKE ALL ON t2 FROM user1;
DROP TABLE t1;
DROP TABLE t2;
SET SECURITY = NULL;
END;
CALL p3
SELECT * FROM t1
-- returns an error, table not found

SELECT * FROM t2
-- returns an error, table not found

3-76

Grammar Statements

The following example shows how to loop through a cursor.

CREATE TABLE atable (c1 INT, c2 INT)
INSERT INTO atable VALUES (1,1)
INSERT INTO atable VALUES (1,2)
INSERT INTO atable VALUES (2,2)
INSERT INTO atable VALUES (2,3)
INSERT INTO atable VALUES (3,3)
INSERT INTO atable VALUES (3,4)
CREATE PROCEDURE pp ();
BEGIN
DECLARE :i INTEGER;
DECLARE c1Bulk CURSOR FOR SELECT c1 FROM atable ORDER
BY c1 FOR UPDATE;
OPEN c1Bulk;
BulkLinesLoop:
LOOP
FETCH NEXT FROM c1Bulk INTO :i;
IF SQLSTATE = '02000' THEN
LEAVE BulkLinesLoop;
END IF;
UPDATE SET c1 = 10 WHERE CURRENT OF c1Bulk;
END LOOP;
CLOSE c1Bulk;
END
CALL pp
--Succeeds
SELECT * FROM atable
--Returns 6 rows

This example creates a trusted stored procedure named InParam.

User Master then grants User1 EXECUTE and ALTER permissions to
InParam. This example assumes that table t99 exists and contains
two columns of type INTEGER.
CREATE PROCEDURE InParam(IN :inparam1 INTEGER, IN
:inparam2 INTEGER)
WITH DEFAULT HANDLER, EXECUTE AS 'Master' AS
BEGIN
INSERT INTO t99 VALUES(:inparam1 , :inparam2);
END;
GRANT ALL ON PROCEDURE InParam TO User1

3-77

SQL Syntax Reference

Using Stored
Procedures

As an example, CALL foo(a, b, c) executes the stored procedure foo

with parameters a, b, and c. Any of the parameters may be a dynamic
parameter (?), which is necessary for retrieving the values of output
and inout parameters. For example: {CALL foo (?, ?, TX)}. The
curly braces are optional in your source code.
This is how stored procedures work in the current version of
Pervasive PSQL.

General Stored
Procedure Engine
Limitations

You should be aware of the following limitations before using stored

procedures.

3-78

Triggers (CREATE TRIGGER, DROP TRIGGER) are supported

as a form of stored procedure. This support includes tracking
dependencies that the trigger has on tables, and procedures, in
the database. You cannot use CREATE PROCEDURE or
CREATE TRIGGER in the body of a stored procedure or a
trigger.
CONTAINS, NOT CONTAINS, BEGINS WITH are not
supported.
LOOP: post conditional loops are not supported
(REPEAT...UNTIL).
ELSEIF: The conditional format uses IF ... THEN ... ELSE. There
is no ELSEIF support.

There is no qualifier support in CREATE PROCEDURE or

CREATE TRIGGER.
Maximum length of a stored procedure variable name is 128
characters.
See Table 1-1, Identifier Restrictions by Identifier Type, in
Advanced Operations Guide for the maximum length of a stored
procedure name.
Only partial syntactical validation occurs at CREATE
PROCEDURE or CREATE TRIGGER time. Column names are
not validated until run time.
There is currently no support for using subqueries everywhere
expressions are used. For example, set :arg = SELECT
MIN(sal) FROM emp is not supported. However, you could
rewrite this query as SELECT min(sal) INTO :arg FROM emp.
Only the default error handler is supported.

Grammar Statements

Limits to SQL
Variables and
Parameters

Limits to Cursors

Limits when using

Long Data

Variable names must be preceded with a colon (:). This allows

the stored procedure parser to differentiate between variables
and column names.
Variable names are case insensitive.
No session variables are supported. Variables are local to the
procedure.
Positioned UPDATE does not accept a table name.
Global cursors are not supported.
When you pass long data as arguments to an imbedded
procedure, (that is, a procedure calling another procedure), the
data is truncated to 65500 bytes.
Long data arguments to and from procedures are limited to a
total of 2 MB.

Internally long data may be copied between cursors with no limit on

data length. If a long data column is fetched from one statement and
inserted into another, no limit is imposed. If, however, more than
one destination is required for a single long data variable, only the
first destination table receives multiple calls to PutData. The
remaining columns are truncated to the first 65500 bytes. This is a
limitation of the ODBC GetData mechanism.
See Also

DROP PROCEDURE on page 3-135

SET CACHED_PROCEDURES on page 3-231
SET PROCEDURES_CACHE on page 3-245
Trusted and Non-trusted Objects on page 3-154

3-79

SQL Syntax Reference

CREATE TABLE
The CREATE TABLE statement creates a new table in a database.
CREATE TABLE contains functionality that goes beyond minimal or
core SQL conformance. CREATE TABLE supports Referential
Integrity features. Pervasive PSQL conforms closely to SQL 92 with
the exception of ColIDList support.
You can also create temporary tables with the CREATE TABLE
statement. See CREATE (temporary) TABLE on page 3-93.
Syntax

CREATE TABLE table-name [ option ] [ IN DICTIONARY ]

[ USING 'path_name'] [ WITH REPLACE ]
( table-element [ , table-element ]... )
table-name ::= user-defined-name
option ::= DCOMPRESS | PCOMPRESS | PAGESIZE = size | LINKDUP
= number
number ::= user-defined value

(sets the number of pointers to reserve for the

addition of linked duplicates index keys)

table-element ::= column-definition | table-constraint-definition

column-definition ::= column-name data-type [ DEFAULT default-value-expression
] [ column-constraint [ column-constraint ]... [CASE (string) |
COLLATE collation-name ]
column-name ::= user-defined-name
data-type ::= data-type-name [ (precision [ , scale ] ) ]
precision ::=
scale ::=

integer

default-value-expression ::= default-value-expression + default-value-expression

3-80

Grammar Statements
| -default-value-expression
| +default-value-expression
| ~default-value-expression
| ?
| literal
| scalar-function
| { fn scalar-function }
| USER
| NULL
literal ::= 'string'

| number
| { d 'date-literal' }
| { t 'time-literal' }
| { ts 'timestamp-literal' }
scalar-function ::= see Scalar Functions on page 5-1
column-constraint ::= [ CONSTRAINT constraint-name ] col-constraint
constraint-name ::= user-defined-name
col-constraint ::= NOT NULL

| UNIQUE
| PRIMARY KEY
| REFERENCES table-name [ ( column-name ) ] [ referential-actions ]
table-constraint-definition ::= [ CONSTRAINT constraint-name ] table-constraint
table-constraint ::=

UNIQUE ( column-name [ , column-name ]... )

| PRIMARY KEY ( column-name [ , column-name ]... )

| FOREIGN KEY ( column-name [ , column-name ] )
REFERENCES table-name [ ( column-name [ , column-name ]... )
] [ referential-actions ]
referential-actions ::= referential-update-action [ referential-delete-action ]

| referential-delete-action [ referential-update-action ]
referential-update-action ::= ON UPDATE RESTRICT
referential-delete-action ::= ON DELETE CASCADE

| ON DELETE RESTRICT

3-81

SQL Syntax Reference

collation-name ::= 'string' | user-defined-name

Remarks

Indexes must be created with the CREATE INDEX statement.

Foreign key constraint names must be unique in the dictionary. All
other constraint names must be unique within the table in which
they reside and must not have the same name as a column.
If the primary key name is omitted, the name of the first column in
the key, prefixed by PK_ is used as the name of the constraint.
If a reference column is not listed, the reference becomes, by default,
the primary key of the table referenced. If a PK is unavailable, a Key
not found error returns. You can avoid this situation by
enumerating the target column.
If the foreign key name is omitted, the name of the first column in
the key, prefixed by FK_ is used as the name of the constraint. This
is different behavior from previous versions of Pervasive PSQL.
If the UNIQUE key constraint name is omitted, the name of the first
column in the constraint, prefixed by UK_ is used as the name of
the constraint.
If the NOT NULL key name is omitted, the name of the first column
in the key, prefixed by NN_ is used as the name of the constraint.
The maximum length of a constraint name is 20 characters.
Pervasive PSQL uses the left most 20 characters of the name after the
prefix, if any, has been prepended.
A foreign key may reference the primary key of the same table
(known as a self-referencing key).
If CREATE TABLE succeeds, the data file name for the created table
is xxx.mkd, where xxx is the specified table name. If the table already
exists, it is not replaced, and error -1303, Table already exists is
signalled. The user must drop the table before replacing it.
Limitations on Record Size

The total size of the fixed-length portion of any data record may not
exceed 65535 bytes. The fixed-length portion of any data record is
made up of the following:

3-82

all the columns that have a fixed sized (all columns except for
LONGVARCHAR and LONGVARBINARY)

Grammar Statements

one byte for each column that allows null values

8 bytes for each variable-length column (column of type
LONGVARCHAR or LONGVARBINARY).

If you attempt to create a table that exceeds this limit, or if you

attempt modifications that would cause a table to exceed the limit,
Pervasive PSQL returns Status Code -3016, The maximum fixedlength rowsize for the table has been exceeded.
To determine the size in bytes of the fixed-length portion of a record
before you attempt to create a new table, you can use the following
calculation:
(sum of the fixed-length column sizes in bytes) + (number of
nullable columns) + ( 8 * number of variable-length columns) =
record size in bytes
If you want to determine the size of the fixed-length portion of the
record for an existing data file, you can use the BUTIL -STAT
command to display a report that includes this information.
Example
Assume you have a table with the following columns defined:
Type

Number of Columns of This Type

Nullable?

VARCHAR(216)

Yes

VARCHAR(213)

All columns

CHAR(42)

1494

All columns

Each VARCHAR has two extra bytes reserved for it. One bite for the
preceding NULL indicator and one trailing byte because VARCHAR
is implemented as a ZSTRING. Each CHAR has a preceding byte
reserved for the NULL indicator.
Therefore, the record size is 1 x 218 + 5 x 215 + 1494 x 43 = 65535
bytes
In this example, you could not add another column of any length
without exceeding the fixed-length limit.
Delete Rule

You can include an ON DELETE clause to define the delete rule

Pervasive PSQL enforces for an attempt to delete the parent row to

3-83

SQL Syntax Reference

which a foreign key value refers. The delete rules you can choose are
as follows:

If you specify CASCADE, Pervasive PSQL uses the delete cascade

rule. When a user deletes a row in the parent table, the database
engine deletes the corresponding row in the dependent table.
If you specify RESTRICT, Pervasive PSQL enforces the delete
restrict rule. A user cannot delete a row in the parent table if a
foreign key value refers to it.

If you do not specify a delete rule, Pervasive PSQL applies the restrict
rule by default.
Use caution with delete cascade. Pervasive PSQL allows a circular
delete cascade on a table that references itself. See examples in
Delete Cascade on page 6-5 in Advanced Operations Guide.
Update Rule

Pervasive PSQL enforces the update restrict rule. This rule prevents
the addition of a row containing a foreign key value if the parent
table does not contain the corresponding primary key value. This
rule is enforced whether or not you use the optional ON UPDATE
clause, which allows you to specify the update rule explicitly.
IN DICTIONARY

See the discussion of IN DICTIONARY forALTER TABLE on page

3-10.
USING

The USING keyword allows you to associate a CREATE TABLE or

ALTER TABLE action with a particular data file.
Because Pervasive PSQL requires a Named Database to connect, the
path_name provided must always be a simple file name or relative path
and file name. Paths are always relative to the first Data Path specified
for the Named Database to which you are connected.
The path/file name passed is partially validated when SQLPrepare is
called. The following rules must be followed when specifying the
path name:

3-84

The text must be enclosed in single quotes, as shown in the

grammar definition.

Grammar Statements

Text must be 1 to 64 characters in length, such that the entry as

specified fits in Xf$Loc in X$File. The entry is stored in Xf$Loc
exactly as typed (trailing spaces are truncated and ignored).
The path must be a simple, relative path. Paths that reference a
server or volume are not allowed.
Relative paths containing a period (. - current directory),
double-period (.. - parent directory), slash \, or any
combination of the three are allowed. The path must contain a
file name representing the SQL table name (path_name cannot end
in a slash \ or a directory name). All file names, including those
specified with relative paths, are relative to the first Data Path as
defined in the Named Database configuration.
Root-based relative paths are also allowed. For example,
assuming that the first data path is D:\mydata\DEMODATA,
Pervasive PSQL interprets the path name in the following
statement as D:\TEMP\TEST123.BTR.
CREATE TABLE t1 USING '\temp\test123.btr' (c1 int)

Slash (\) characters in relative paths may be specified either

Include a USING clause to specify the physical location of the data

file associated with the table. This is necessary when you are creating
a table definition for an existing data file, or when you want to
specify explicitly the name or physical location of a new data file.

3-85

SQL Syntax Reference

If you do not include a USING clause, Pervasive PSQL generates a

unique file name (based on the table name with the extension
.MKD) and creates the data file in the first directory specified in the
data file path associated with the database name.
If the USING clause points to an existing data file, Pervasive PSQL
creates the table in the DDFs and returns SQL_SUCCESS_WITH_
INFO. The informational message returned indicates that the
dictionary entry now points to an existing data file. If you want
CREATE TABLE to return only SQL_SUCCESS, specify IN
DICTIONARY on the CREATE statement. If WITH REPLACE is
specified (see below), then any existing data file with the same name
is destroyed and overwritten with a newly created file.
Note Pervasive PSQL returns a successful status code if you

specify an existing data file.

Whenever you create a relational index definition for an existing data
file (for example, by issuing a CREATE TABLE USING statement
with a column definition of type IDENTITY), Pervasive PSQL
automatically checks the Btrieve indexes defined on the file to
determine whether an existing Btrieve index offers the set of
parameters requested by the relational index definition. If an existing
Btrieve index matches the new definition being created, then an
association is created between the relational index definition and the
existing Btrieve index. If there is no match, then Pervasive PSQL
creates a new index definition and, if IN DICTIONARY is not
specified, a new index in the data file.
WITH REPLACE

Whenever WITH REPLACE is specified with the USING keyword,

Pervasive PSQL automatically overwrites any existing file name with
the specified file name. The existing file is always overwritten as long
as the operating system allows it.
WITH REPLACE affects only the data file, it never affects the DDFs.
The following rules apply when using WITH REPLACE:

3-86

WITH REPLACE can only be used with USING.

Grammar Statements

When used with IN DICTIONARY, WITH REPLACE is ignored

because IN DICTIONARY specifies that only the DDFs are
affected.

If you include WITH REPLACE in your CREATE TABLE statement,

Pervasive PSQL creates a new data file to replace the existing file (if
the file exists at the location you specified in the USING clause).
Pervasive PSQL discards any data stored in the original file with the
same name. If you do not include WITH REPLACE and a file exists
at the specified location, Pervasive PSQL returns a status code and
does not create a new file.
WITH REPLACE affects only the data file; it does not affect the table
definition in the dictionary.
Note No data is lost or discarded if WITH REPLACE is used with

ALTER TABLE. The newly created data file, even if overwriting

an existing file, still contains all data from the previous file. You
cannot lose data by issuing an ALTER TABLE command.
DCOMPRESS

The DCOMPRESS option specifies that the data file for the specified
table should use record compression to reduce the file size on disk.
The following example creates a table with record compression and
page size 1024 bytes:
CREATE TABLE t1 DCOMPRESS PAGESIZE=1024 (c1 INT DEFAULT
10, c2 CHAR(10) DEFAULT 'abc')

PCOMPRESS

The PCOMPRESS option specifies that the data file for the specified
table should use page compression. The following example creates a
table with page compression and page size 1024 bytes:
CREATE TABLE t1 PCOMPRESS PAGESIZE=1024 (c1 INT DEFAULT
10, c2 CHAR(10) DEFAULT 'abc')

PAGESIZE

The PAGESIZE option specifies that the data file for the specified
table should use pages of size bytes. The value of size can be any of the
following depending on file version:

3-87

SQL Syntax Reference

512 4096 for file versions prior to 9.0 (a multiple of 512 bytes
up to 4096).
512, 1024, 1536, 2048, 2560, 3072, 3584, 4096, or 8192 for file
version 9.0.
1024, 2048, 4096, 8192, or 16384 for file versions 9.5 and newer.

The following example creates a table with file compression and page
size 8192 bytes, specifying creation of the particular data file
identified by the relative path, ..\data1.mkd:
CREATE TABLE t1 DCOMPRESS PAGESIZE=8192
USING ..\data1.mkd (c1 INT DEFAULT 10, c2 CHAR(10)
DEFAULT 'abc')

LINKDUP

Multiple records may carry the same duplicated value for index keys.
The two methods to keep track of the records with duplicate key
values are called linked duplicates (linkdup) and repeating
duplicates. (For a detailed discussion of both methods, see Methods
for Handling Duplicate Keys on page 13-14 in Advanced Operations
Guide.)
The following conditions apply to the use of the LINKDUP keyword.

3-88

If the LINKDUP keyword is not specified, a CREATE INDEX

statement uses the repeating duplicates method
If the LINKDUP keyword is specified, the following applies:

a CREATE INDEX statement uses the linked duplicates

method up to the value specified for the number of pointers

once the value specified for the number of pointers is

reached, a CREATE INDEX statement uses the repeating
duplicates method

if the value specified for the number of pointers has been

reached and a linked-duplicate index is dropped, a CREATE
INDEX statement uses the linked duplicates method for the
next key

a CREATE INDEX statement cannot create a repeatingduplicate key if pointers are still reserved for linkedduplicate keys.
The ALTER TABLE statement does not support the LINKDUP
option.

Grammar Statements

Examples

The following example creates a table named Billing with columns

Student_ID, Transaction_Number, Log, Amount_Owed, Amount_
Paid, Registrar_ID and Comments, using the specified data types.
CREATE TABLE Billing
(Student_ID UBIGINT,
Transaction_Number USMALLINT,
Log TIMESTAMP,
Amount_Owed DECIMAL(6,2),
Amount_Paid DECIMAL(6,2),
Registrar_ID DECIMAL(10,0),
Comments LONGVARCHAR)

The following example creates a table named Faculty in the database

with columns ID, Dept_Name, Designation, Salary, Building_Name,
Room_Number, Rsch_Grant_Amount, and a primary key based on
column ID.
CREATE TABLE Faculty
(ID

UBIGINT,

Dept_Name

CHAR(20) CASE,

Designation

CHAR(10) CASE,

Salary

CURRENCY,

Building_Name

CHAR(25) CASE,

Room_Number

UINTEGER,

Rsch_Grant_Amount
PRIMARY KEY (ID))

DOUBLE,

The following example is similar to the one just discussed, except the
ID column, which is the primary key, is designated as UNIQUE.
CREATE TABLE organizations
(ID UBIGINT UNIQUE,
Name LONGVARCHAR,
Advisor CHAR(30),
Number_of_people INTEGER,
Date_started DATE,
Time_started TIME,
Date_modified TIMESTAMP,
Total_funds DOUBLE,

3-89

SQL Syntax Reference

Budget DECIMAL(2,2),
Avg_funds REAL,
President VARCHAR(20) CASE,
Number_of_executives SMALLINT,
Number_of_meetings TINYINT,
Office UTINYINT,
Active BIT,
PRIMARY KEY(ID))

In the next example, assume that you need a table called

StudentAddress to contain students addresses. You need to alter the
Student tables id column to be a primary key and then create a
StudentAddress table. (The Student table is part of the DEMODATA
sample database.) Four ways are shown how to create the
StudentAddress table.
First, make the id column of table Student a primary key.
ALTER TABLE Student ADD PRIMARY KEY (id)

This next statement creates a StudentAddress table to have a foreign

key referencing the id column of table Student with the DELETE
CASCADE rule. This means that whenever a row is deleted from the
Student table (Student is the parent table in this case), all rows in the
StudentAddress table with that same id are also deleted.
CREATE TABLE StudentAddress (id UBIGINT REFERENCES
Student (id) ON DELETE CASCADE, addr CHAR(128))

This next statement creates a StudentAddress table to have a foreign

key referencing the id column of table Student with the DELETE
RESTRICT rule. This means that whenever a row is deleted from the
Student table and there are rows in the StudentAddress table with
that same id, an error occurs. You need to explicitly delete all the
rows in StudentAddress with that id before the row in the Student
table, the parent table, can be deleted.
CREATE TABLE StudentAddress (id UBIGINT REFERENCES
Student (id) ON DELETE RESTRICT, addr CHAR(128))

This next statement creates a StudentAddress table to have a foreign

key referencing the id column of table Student with the UPDATE
RESTRICT rule. This means that if a row is added to the
StudentAddress table that has an id that does not occur in the
Student table, an error occurs. In other words, you must have a

3-90

Grammar Statements

parent row before you can have foreign keys referring to that row.
This is the default behavior of Pervasive PSQL. Moreover, Pervasive
PSQL does not support any other UPDATE rules. Thus, whether this
rule is stated explicitly or not makes no difference.
CREATE TABLE StudentAddress (id UBIGINT REFERENCES
Student (id) ON UPDATE RESTRICT, addr CHAR(128))

This next statement creates a StudentAddress table to have a foreign

key referencing the id column of table Student with the DELETE
RESTRICT and UPDATE RESTRICT rules. The Pervasive PSQL
parser accepts this syntax with RI rules. However, as stated above, the
UPDATE RESTRICT rule is redundant since Pervasive PSQL does
not behave any other way with respect to UPDATE rules.
CREATE TABLE StudentAddress (id UBIGINT REFERENCES
Student (id) ON DELETE RESTRICT, addr CHAR(128))

This next example shows how to use an alternate collating sequence

(ACS) when you create a table. The ACS file used is the sample one
provided with Pervasive PSQL.
CREATE TABLE t5 (c1 CHAR(20) COLLATE 'file_path\
upper.alt')

The following example creates a table, t1, and reserves the number of
pointers to use for linked duplicate keys to four. The CREATE
INDEX statements create index keys for the table.
DROP table t1
CREATE table t1 LINKDUP=4 (c1 int, c2 int, c3 int)
CREATE
CREATE
CREATE
CREATE
CREATE

INDEX link_1
INDEX link_2
UNIQUE INDEX
INDEX link_4
INDEX link_5

on t1(c1,c2)
on t1(c1,c3)
link_3 on t1(c3)
on t1(c1)
on t1(c2)

3-91

SQL Syntax Reference

CREATE INDEX link_6 on t1(c2,c3)

The results of the CREATE INDEX statements are the following:

Linked duplicate keys: link_1, link_2, link_4, link_5

Repeating duplicate keys: link_6 (because the number of
pointers to use for linked duplicate keys reached the specified
value, four)

DROP INDEX link_2

CREATE INDEX link_7 on t1(c3,c1)

These two statements result in the following:

See Also

Linked duplicate keys: link_1, link_4, link_5, link_7 (because the

DROP INDEX statement reduced the number of pointers to use
for linked duplicate keys to three, which allowed link_7 to
become the fourth linked duplicates index key)
Repeating duplicate keys: link_6

ALTER TABLE on page 3-10

DROP TABLE on page 3-136
CREATE INDEX on page 3-59
SET DEFAULTCOLLATE on page 3-237

3-92

Grammar Statements

CREATE (temporary) TABLE

You can also use the CREATE TABLE statement to create a
temporary table. The CREATE TABLE syntax for temporary tables is
more restrictive than for permanent tables. For this reason, and
because of other characteristics, temporary tables are discussed in
their own section.
Syntax

CREATE TABLE <# | ##>table-name (table-element [ , table-element ]... )

table-name ::= user-defined-name
table-element ::= column-definition | table-constraint-definition
column-definition ::= column-name data-type [ DEFAULT default-value-expression
] [ column-constraint [ column-constraint ]... [CASE (string) |
COLLATE collation-name ]
column-name ::= user-defined-name
data-type ::= data-type-name [ (precision [ , scale ] ) ]
precision ::=
scale ::=

integer

default-value-expression ::= default-value-expression + default-value-expression

| default-value-expression - default-value-expression
| default-value-expression * default-value-expression
| default-value-expression / default-value-expression
| default-value-expression & default-value-expression
| default-value-expression | default-value-expression
| default-value-expression ^ default-value-expression
| ( default-value-expression )
| -default-value-expression
| +default-value-expression
| ~default-value-expression
| ?
| literal
| scalar-function
| { fn scalar-function }
| USER
| NULL

3-93

SQL Syntax Reference

literal ::= 'string'

| number
| { d 'date-literal' }
| { t 'time-literal' }
| { ts 'timestamp-literal' }
scalar-function ::=

see Scalar Functions on page 5-1

column-constraint ::= [ CONSTRAINT constraint-name ] col-constraint

constraint-name ::= user-defined-name
col-constraint ::= NOT NULL

| UNIQUE
| PRIMARY KEY
| REFERENCES table-name [ ( column-name ) ] [ referential-actions ]
table-constraint-definition ::= [ CONSTRAINT constraint-name ] table-constraint
table-constraint ::=

UNIQUE ( column-name [ , column-name ]... )

| PRIMARY KEY ( column-name [ , column-name ]... )

REFERENCES table-name [ ( column-name [ , column-name ]... ) ]
[ referential-actions ]
referential-actions ::= referential-update-action [ referential-delete-action ]

| referential-delete-action [ referential-update-action ]
referential-update-action ::= ON UPDATE RESTRICT
referential-delete-action ::= ON DELETE CASCADE

| ON DELETE RESTRICT
collation-name ::= 'string' | user-defined-name

Remarks

A temporary table is used for intermediate results or working

storage. Unlike in permanent tables, data in a temporary table is
destroyed at some point during the SQL session or at the end of the
SQL session. The data is not saved in the database.
Temporary tables are useful to narrow down intermediate results by
continuing to operate on intermediate tables. Complex data
operations are often easier if split into a sequence of simpler steps,

3-94

Grammar Statements

which each step operating on the table result of a previous step. A

temporary table is a base table. That is, the data it contains is its own.
Contrast this with a view, which is an indirect representation of data
in other tables.
Pervasive PSQL supports two types of temporary tables:

Local
Global

Both types can be used within a stored procedure.

The following table summarizes characteristics of temporary tables
contrasted with where the table is created or used. Characteristics
can vary depending on whether the table is created or used within or
outside of a stored procedure. Additional remarks are discussed as
footnotes at the end of the table.
Except for permissible length of the temporary table name, the
characteristics are the same for both V1 and V2 metadata.
Table 3-3 Characteristics of Temporary Tables
Table Characteristic

Local Temporary Table

Global Temporary
Table

Outside
of SP1

Within SP

Outside
of SP

Within SP

First character of table name must be # (see also

Compatibility With Previous Releases below)

yes

First character of table name must be ## (see also

Compatibility With Previous Releases below)

yes

Context of table same as database in which table is

created

yes

Two or more sessions can create table with same name2

yes

For V1 metadata, see Identifier Restrictions by Identifier

Type in Advanced Operations Guide for the maximum
length of a table name (the length includes #, ##,
underscores, and ID)

yes3

yes4

yes3

yes4

For V2 metadata, see Identifier Restrictions by Identifier

Type in Advanced Operations Guide for the maximum
length of a table name (the length includes #, ##,
underscores, and ID)

yes3

yes4

yes3

yes4

Table in another database can be accessed by

qualifying table name with other database name

yes

3-95

SQL Syntax Reference

Table 3-3 Characteristics of Temporary Tables continued

Table Characteristic

Local Temporary Table

Global Temporary
Table

Outside
of SP1

Within SP

Outside
of SP

Within SP

SELECT, INSERT, UPDATE, and DELETE statements

permitted on table

yes

ALTER TABLE and DROP TABLE statements permitted

on table

yes

Can create view on table

Can create user-defined function on table

Can create trigger on table

Can grant or revoke permissions on table

FOREIGN KEY constraint allowed with CREATE TABLE

statement5

SELECT INTO statement can populate table with data

yes

SELECT INTO statement can create table6

yes

Table created in one SQL session can be accessed by

other SQL sessions

yes

Table created in procedure can be accessed outside of

that procedure

not
applicable

not
applicabl
e

yes

Table created in topmost procedure can be accessed by

nested procedures

not
applicable

not
applicabl
e

CREATE TABLE statement in a recursive stored

procedure returns table name error on recursive call

not
applicable

yes7

not
applicabl
e

yes9

Table dropped when explicitly dropped

yes

Table dropped at end of session in which table created

yes

yes8

yes

Table dropped at end of procedure in which table

created

not
applicable

yes

not
applicabl
e

3-96

Grammar Statements

Table 3-3 Characteristics of Temporary Tables continued

Table Characteristic

Table dropped at end of transaction in another session

1SP

Local Temporary Table

Global Temporary
Table

Outside
of SP1

Within SP

Outside
of SP

Within SP

not
applicable

yes

stands for stored procedure

2The

database engine automatically appends the name of the stored procedure and a session-specific ID to
the user-defined name to ensure a unique table name. This functionality is transparent to the user.
3The

total length of the table name includes # or ##, plus an underscore, plus a session ID. The session ID
can be 8, 9, or 10 bytes depending on the operating system. See Identifier Restrictions by Identifier Type in
Advanced Operations Guide.

4The

total length of the table name includes # or ##. plus an underscore, plus the name of the stored
procedure, plus an underscore, plus a session ID. The session ID can be 8, 9, or 10 bytes depending on the
operating system. See Identifier Restrictions by Identifier Type in Advanced Operations Guide.
5Constraint
6A
7

returns a warning but table is created.

table can be created and populated with data with a single SELECT INTO statement.

The table name already exists from the first execution of the stored procedure.

8If

end of session occurs before the execution of the procedure ends.

Compatibility With Previous Releases

Releases of Pervasive PSQL prior to Pervasive PSQL v9 Service Pack
2 permitted the naming of permanent tables starting with # or
##. Permanent tables starting with # or ## cannot be used with
Pervasive PSQL v9 Service Pack 2 or later releases. Tables starting
with # or ## are temporary tables and are created in the
TEMPDB database.
A table not found error is returned if you attempt to access a
permanent table starting with # or ## that was created with a
version of Pervasive PSQL prior to Pervasive PSQL v10.
See also Statement Separators on page 6-3 in Pervasive PSQL User's
Guide.
TEMPDB Database
The installation of Pervasive PSQL creates a system database named
TEMPDB. TEMPDB holds all temporary tables. Never delete the

3-97

SQL Syntax Reference

TEMPDB database. If you remove it, you will be unable to create

temporary tables.
TEMPDB is created in the install directory of the Pervasive PSQL
product. See Where are the Pervasive PSQL v10 files installed? on
page 7-2 in Getting Started With Pervasive PSQL.
If you prefer, after installation, you may change the location of the
dictionary files and data files for TEMPDB. See Database
Properties on page 3-20 in Pervasive PSQL User's Guide.
Caution TEMPDB is a system database for exclusive use by the

database engine. Do not use TEMPDB as a repository of your

permanent tables, views, stored procedures, and so forth.

Table Names of Local Temporary Tables

The database engine automatically appends information to the
names of local temporary tables to differentiate between temporary
tables created across multiple sessions. The length of the appended
information varies depending on the operating system.
The name of a local temporary table can be at least 10 bytes provided
the number of stored procedures that create local temporary tables
does not exceed 1,296. The 10 bytes include the # character. The
1,296 limit applies to stored procedures within the same session.
The maximum name length is 20 bytes, including the # character,
the table name, and the appended information.
Transactions
A global temporary table can be explicitly dropped or is
automatically dropped when the session in which the table was
created ends. If a session other than the one that created the table
uses the table in a transaction, the table is dropped when the
transaction completes.
SELECT INTO
You can create a temporary table and populate it with data by using
a single SELECT INTO statement. For example, SELECT * INTO
#mytmptbl FROM Billing creates a local temporary table named

3-98

Grammar Statements

#mytmptbl (provided #mytmptbl does not already exist). The

temporary table contains the same data as the Billing table in the
DEMODATA sample database.
If the SELECT INTO statement is executed a second time with the
same temporary table name, an error returns because the temporary
table already exists.
The SELECT INTO statement can create a temporary table from two
or more tables. However, the column names must be unique in each
of the tables from which the temporary table is created or an error
returns.
The error can be avoided if you qualify the column names with the
table names and provide an alias for each column. For example,
suppose that table t1 and t2 both contain columns col1 and col2. The
following statement returns an error: SELECT t1.co1, t1.col2,
t2.col1, t2.col2 INTO #mytmptbl FROM t1, t2. Instead, use a
statement such as this: SELECT t1.co1 c1, t1.col2 c2, t2.col1
c3, t2.col2 c4 INTO #mytmptbl FROM t1, t2.
Restrictions

A local temporary table created within a stored procedure is

inside the scope of the stored procedure. The local temporary
table is destroyed after the stored procedure executes.
The UNION and UNION ALL keywords are not permitted with
a SELECT INTO statement.
Only one temporary table can receive the results of the SELECT
INTO statement. You cannot SELECT data into multiple
temporary table with a single SELECT INTO statement.

Caching of Stored Procedures

Any stored procedure that references a local or a global temporary
table is not cached, regardless of the cache setting(s). See SET
CACHED_PROCEDURES on page 3-231 and SET
PROCEDURES_CACHE on page 3-245.
Examples

The following example creates a local temporary table named #b_

temp and populates it with the data from the Billing table in the
DEMODATA sample database.
SELECT * INTO #b_temp FROM Billing

3-99

SQL Syntax Reference

The following example creates a global temporary table named

##tenurefac with columns ID, Dept_Name, Building_Name, Room_
Number, and a primary key based on column ID.
CREATE TABLE ##tenurefac
(ID

UBIGINT,

Dept_Name

CHAR(20) CASE,

Building_Name

CHAR(25) CASE,

Room_Number

UINTEGER,

PRIMARY KEY (ID))

The following example alters temporary table ##tenurefac and adds

the column Research_Grant_Amt.
ALTER TABLE ##tenurefac ADD Research_Grant_Amt DOUBLE

The following example drops temporary table ##tenurefac.

DROP TABLE ##tenurefac

The following example creates two temporary tables within a stored

procedure, populates them with data, then assigns values to
variables. The values are selected from the temporary tables.
Note SELECT INTO is permitted within a stored procedure if

used to assigned values to variables.

CREATE PROCEDURE p11 ()
AS BEGIN
DECLARE :val1_int INTEGER;
DECLARE :val2_char VARCHAR(20);
CREATE TABLE #t11 (col1 INT, col2 VARCHAR(20));
CREATE TABLE #t12 (col1 INT, col2 VARCHAR(20));
INSERT INTO #t11 VALUES (1,'t1 col2 text');
INSERT INTO #t12 VALUES (2,'t2 col2 text');
SELECT col1 INTO :val1_int FROM #t11 WHERE col1 = 1;
SELECT col2 INTO :val2_char FROM #t12 WHERE col1 = 2;

3-100

Grammar Statements
PRINT :val1_int;
PRINT :val2_char;
COMMIT;
END;
CALL P11 ()

The following example creates global temporary table ##enroll_

student_global_temp_tbl then creates stored procedure
Enrollstudent. When called, the procedure inserts a record into
##enroll_student_global_temp_tbl, given the Student ID, Class ID,
and a grade point average (GPA). A SELECT selects all records in the
temporary table and displays the result. The length of the name for
the global temporary table is permissible only for V2 metadata.
CREATE TABLE ##enroll_student_global_temp_tbl (student_
id INTEGER, class_id INTEGER, GPA REAL);
CREATE PROCEDURE Enrollstudent(in :Stud_id integer, in
:Class_Id integer, IN :GPA REAL);
BEGIN
INSERT INTO ##enroll_student_global_temp_tbl
VALUES(:Stud_id, :Class_id, :GPA);
END;
CALL Enrollstudent(1023456781, 146, 3.2)
SELECT * FROM ##enroll_student_global_temp_tbl

The following example creates two temporary tables within a stored

procedure, populates them with data, then assigns values to
variables. The values are selected from the temporary tables.
CREATE PROCEDURE "p11" ()
AS BEGIN
DECLARE :val1_int INTEGER;
DECLARE :val2_char VARCHAR(20);
CREATE TABLE #t11 (col1 INT, col2 VARCHAR(20));
CREATE TABLE #t12 (col1 INT, col2 VARCHAR(20));
INSERT INTO #t11 VALUES (1,'t1 col2 text');
INSERT INTO #t12 VALUES (2,'t2 col2 text');
SELECT col1 INTO :val1_int FROM #t11 WHERE col1 = 1;
SELECT col2 INTO :val2_char FROM #t12 WHERE col1 = 2;

3-101

SQL Syntax Reference

PRINT :val1_int;
PRINT :val2_char;
COMMIT;
END;
CALL P11()

See Also

ALTER TABLE on page 3-10

DROP TABLE on page 3-136
SELECT (with into) on page 3-201

3-102

Grammar Statements

CREATE TRIGGER
The CREATE TRIGGER statement creates a new trigger in a
database. Triggers are a type of stored procedure that are
automatically executed when data in a table is modified with an
INSERT, UPDATE, or DELETE.
Unlike a regular stored procedure, a trigger cannot be executed
directly nor can it have parameters. Triggers do not return a result set
nor can they be defined on views.
Syntax

CREATE TRIGGER trigger-name before-or-after ins-upd-del ON table-name

[ ORDER number ]
[ REFERENCING referencing-alias ] FOR EACH ROW
[ WHEN proc-search-condition ] proc-stmt
trigger-name ::= user-defined-name
before-or-after ::= BEFORE | AFTER
ins-upd-del ::= INSERT | UPDATE | DELETE
referencing-alias ::= OLD [ AS ] correlation-name [ NEW [ AS ] correlationname ]

| NEW [ AS ] correlation-name [ OLD [ AS ] correlation-name ]

correlation-name ::= user-defined-name

Remarks

This function is an extension to SQL grammar as documented in the

Microsoft ODBC Programmers Reference and implements a subset of
the SQL 3/PSM (Persistent Stored Modules) specification.
Note In a trigger, the name of a variable must begin with a colon

(:).
OLD (OLD correlation-name) and NEW (NEW correlation-name) can be
used inside triggers, not in a regular stored procedure.
In a DELETE or UPDATE trigger, OLD or a OLD correlation-name
must be prepended to a column name to reference a column in the
row of data prior to the update or delete operation.

3-103

SQL Syntax Reference

In an INSERT or UPDATE trigger, NEW or a NEW correlation-name

must be prepended to a column name to reference a column in the
row about to be inserted or updated.
Trigger names must be unique in the dictionary.
Triggers are executed either before or after an UPDATE, INSERT, or
DELETE statement is executed, depending on the type of trigger.
Note CREATE TRIGGER statements are subject to the same

length and other limitations as CREATE PROCEDURE. For

more information, see Limits on page 3-70 and Data Type
Restrictions on page 3-70.

Examples

The following example creates a trigger that records any new values
inserted into the Tuition table into TuitionIDTable.
CREATE TABLE Tuitionidtable (PRIMARY KEY(id), id
UBIGINT)
CREATE TRIGGER InsTrig
BEFORE INSERT ON Tuition
REFERENCING NEW AS Indata
FOR EACH ROW
INSERT INTO Tuitionidtable VALUES(Indata.ID);

An INSERT on Tuition calls the trigger.

The following example shows how to keep two tables, A and B,

synchronized with triggers. Both tables have the same structure.
CREATE TABLE A (col1 INTEGER, col2 CHAR(10))
CREATE TABLE B (col1 INTEGER, col2 CHAR(10))
CREATE TRIGGER MyInsert
AFTER INSERT ON A FOR EACH ROW
INSERT INTO B VALUES (NEW.col1, NEW.col2);
CREATE TRIGGER MyDelete
AFTER DELETE ON A FOR EACH ROW
DELETE FROM B WHERE B.col1 = OLD.col1 AND B.col2 =
OLD.col2;
CREATE TRIGGER MyUpdate

3-104

Grammar Statements
AFTER UPDATE ON A FOR EACH ROW
UPDATE B SET col1 = NEW.col1, col2 = NEW.col2 WHERE
B.col1 = OLD.col1 AND B.col2 = OLD.col2;

Note that OLD and NEW in the example keep the tables
synchronized only if table A is altered with non-positional SQL
statements. If the ODBC SQLSetPos API or a positioned update or
delete is used, then the tables stay synchronized only if table A does
not contain any duplicate records. An SQL statement cannot be
constructed to alter one record but leave another duplicate record
unaltered.
See Also

DROP TRIGGER on page 3-137

3-105

SQL Syntax Reference

CREATE USER
The CREATE USER statement creates a new user account in a
database.
This function can be used to create a user account in a database with
a password, without a password, or as member of a group.
Syntax

CREATE USER user-name [ WITH PASSWORD user-password ][ IN GROUP

referencing-alias ]

Remarks

This function is an extension to SQL grammar as documented in the

Microsoft ODBC Programmers Reference.
Note This statement creates a user with the same rights as those
of a user created using the Pervasive PSQL Control Center
(PCC). For example, the created user is not restricted by default
from creating a database even if the user is not logged in as
Master.

Only the Master user can execute this statement.

Security must be turned on to perform this statement.
User-name and user-password here only refer to Pervasive PSQL
databases and are not related to user names and passwords set at the
operating system level. Pervasive PSQL user names, groups, and
passwords can also be configured through the Pervasive PSQL
Control Center (PCC).
User name must be unique in the dictionary.
The user name and password must be enclosed in double quotes if
they contain spaces or other non-alphanumeric characters.
If you create a user as the member of a group, you must set up the
group before creating the user.
For further general information about users and groups, see Master
User on page 7-2 and Users and Groups on page 7-3 in Advanced
Operations Guide.
Examples

3-106

The following examples show how to create a new user account

without any login privileges and without a membership in any
group.

Grammar Statements
CREATE USER pgranger

The new user name is pgranger. The users password is NULL and the
user account is not a member of any group.
CREATE USER polly granger

The new user name is polly granger with non-alphanumeric

characters. The users password is NULL and the user account is not
a member of any group.

The following examples show how to create a new user account with
login privileges that is not a member of any group.
CREATE USER pgranger WITH PASSWORD Prvsve1

The new user name is pgranger. The users password is Prsve1 (casesensitive).
CREATE USER pgranger WITH PASSWORD Nonalfa$

The new user name is pgranger. The users password is Nonalfa$

(case-sensitive) with non-alphanumeric characters.

The following example shows how create a new user as a member of

a group without login privileges.
CREATE USER pgranger IN GROUP developers

The new user name is pgranger. The new user account is a assigned
to the group developers.

The following example shows how create a new user as a member of

a group with login privileges.
CREATE USER pgranger WITH PASSWORD Prvsve1 IN GROUP
developers

The new user name is pgranger. The new user account is assigned to
the group developers and has the case-sensitive password Prvsve1.
The order of this syntax (CREATE USER..WITH PASSWORD...IN
GROUP) is absolutely necessary.
See Also

ALTER USER on page 3-26

DROP USER on page 3-138
GRANT on page 3-149

3-107

SQL Syntax Reference

CREATE VIEW
The CREATE VIEW statement defines a stored view, or virtual table.
Syntax

CREATE VIEW view-name [ ( column-name [ , column-name ]...) ] [

WITH EXECUTE AS MASTER ] AS query-specification [ ORDER BY
order-by-expression [ , order-by-expression ]... ]
view-name ::= user-defined-name
column-name ::= user-defined-name
order-by-expression ::= expression [ CASE (string) | COLLATE collationname ] [ ASC | DESC ] (see SELECT syntax on page 3-

202)

Remarks

A view is a database object that stores a query and behaves like a

table. A view contains a set of columns and rows. Data accessed
through a view is stored in one or more tables; the tables are
referenced by SELECT statements. Data returned by a view is
produced dynamically every time the view is referenced.
See Table 1-1, Identifier Restrictions by Identifier Type, in
Advanced Operations Guide for the maximum length of a view name.
The maximum number of columns in a view is 256. View definitions
have a 64 KB limit.
Pervasive PSQL supports grouped views. A grouped view is one that
contains any of the following in the SELECT list:

DISTINCT
GROUP BY
ORDER BY
Scalar Functions
Scalar subquery
TOP
UNION

Grouped views may be used in a subquery provided the subquery is

an expression. A subquery connected with the operators IN, EXISTS,
ALL, or ANY is not considered an expression.
View definitions cannot contain procedures.

3-108

Grammar Statements

ORDER BY

The ORDER BY clause is functionally the same as the one described

for the SELECT statement. See SELECT on page 3-202. Note the
following, which are some of the key points:

Aliases may appear in the ORDER BY clause.

Scalar subqueries may appear in the ORDER BY clause.
ORDER BY clauses are not allowed in a subquery clause.
A view can contain a SELECT statement that includes both TOP
and an ORDER BY clause. If so, the database engine generates a
temporary table and populates it with the querys entire result
set. The rows in the temporary table are ordered as specified by
the ORDER BY clause and the TOP number of rows in the
ordered result set are returned.
Views that contain a TOP clause can be joined with other tables
or views.
The use of a TOP clause is recommended in views that include
an ORDER BY clause.

Trusted and Non-Trusted Views

A trusted view includes the WITH EXECUTE AS MASTER clause.

See Trusted and Non-trusted Objects on page 3-154.
Examples

The following statement creates a non-trusted view named vw_

Person, which creates a phone list of all the people enrolled in a
university. This view lists the last names, first names and telephone
numbers with a heading for each column. The Person table is part of
the DEMODATA sample database.
CREATE VIEW vw_Person (lastn,firstn,phone) AS SELECT
Last_Name, First_Name,Phone FROM Person

In a subsequent query on the view, you may use the column headings
in your SELECT statement:
SELECT lastn, firstn FROM vw_Person

The user executing the view must have SELECT permissions on the
Person table.

The following example creates a similar view, but a trusted one.

3-109

SQL Syntax Reference

CREATE VIEW vw_trusted_Person (lastn,firstn,phone) WITH
EXECUTE AS MASTER AS SELECT Last_Name, First_
Name,Phone FROM Person

Now assume that you grant user user1 SELECT permissions on

vw_Person. User1 can use the column headings in a SELECT
statement:
SELECT lastn, firstn FROM vw_trusted_Person

User1 is not required to have SELECT permissions on the Person

table because the permissions were granted to the trusted view.

The following statement creates a view named vw_Person, which

creates a phone list of all the people enrolled in a university. This
view lists the last names, first names and telephone numbers with a
heading for each column. The Person table is part of the
DEMODATA sample database.
CREATE VIEW vw_Person (lastn, firstn, telphone) AS
SELECT Last_Name, First_Name, Phone FROM Person

In a subsequent query on the view, you may use the column headings
in your SELECT statement, as shown in the next example.
SELECT lastn, firstn FROM vw_Person

The example above can be changed to include an ORDER BY clause.

CREATE VIEW vw_Person_ordby (lastn, firstn, telphone) AS
SELECT Last_Name, First_Name, Phone FROM Person ORDER BY
phone

The view returns the following (for brevity, not all records are
shown).
Last_Name
=========
Vqyles
Qulizada
Ragadio
Luckey
Sokell
Gyduska
Happy
Nix

3-110

First_Name
==========
Rex
Ahmad
Ernest
Anthony
Chester
Michael
Anthony
Anna

Phone
==========
2105551871
2105552233
2105554654
2105557628
2105559149
5125550001
5125550004
5125550006

Grammar Statements

The following example creates a view that returns the grade point
average (GPA) of students in descending order, and, for each GPA
ordering, lists the students by last name descending.
CREATE VIEW vw_gpa AS SELECT Last_Name,Left(First_
Name,1) AS First_Initial,Cumulative_GPA AS GPA FROM
Person LEFT OUTER JOIN Student ON Person.ID=Student.ID
ORDER BY Cumulative_GPA DESC, Last_Name

The view returns the following (for brevity, not all records are
shown).
Last_Name
=========================
Abuali
Adachi
Badia
Rowan
Ujazdowski
Wotanowski
Gnat
Titus
Mugaas
Pabalan

First_Initial
===============
I
K
S
A
T
H
M
A
M
R

GPA
======
4.000
4.000
4.000
4.000
4.000
4.000
3.998
3.998
3.995
3.995

The following example creates a view that returns the top 10 records
from the Person table, ordered by ID.
CREATE VIEW vw_top10 AS SELECT TOP 10 * FROM person ORDER
BY id;

The view returns the following (for brevity, not all columns are
shown).
ID
=========
100062607
100285859
100371731
100592056
100647633
100822381
101042707
101135758
101369010
101581226

First_Name
==========
Janis
Lisa
Robert
Andrew
Robert
Roosevelt
Avram
Ismail
Bruno
Robert

Last_Name
==========
Nipart
Tumbleson
Mazza
Sugar
Reagen
Bora
Japadjief
Badad
Ippolite
Obici

10 rows were affected.

3-111

SQL Syntax Reference

The following example creates a view to demonstrate that ORDER

BY can be used with UNION.
CREATE VIEW vw_union_ordby_desc AS SELECT first_name
FROM person UNION SELECT last_name FROM PERSON ORDER
BY first_name DESC

The view returns the following (for brevity, not all records are
shown).
First_Name
===========
Zyrowski
Zynda
Zydanowicz
Yzaguirre
Yyounce
Xystros
Xyois
Xu
Wyont
Wynalda
Wykes

See Also

DROP VIEW on page 3-139

SELECT on page 3-202
SET ROWCOUNT on page 3-249
Trusted and Non-trusted Objects on page 3-154

3-112

Grammar Statements

DECLARE
Remarks

Use the DECLARE statement to define an SQL variable.

This statement is allowed only inside of a stored procedure, a userdefined function, or a trigger.
The name of a variable must begin with a colon (:), both in the
definition and use of the variable or parameter. A variable must be
declared before it can be set to a value with SET.
Use a separate DECLARE statement for each variable (you cannot
declare multiple variables with a single statement). Specify a value or
values for data types that require a size, precision, or scale, such as
CHAR, DECIMAL, NUMERIC, and VARCHAR.

Examples

The following examples show how to declare variables, including

ones that require a value for size, precision, or scale.
DECLARE :SaleItem CHAR(15);
DECLARE :CruiseLine CHAR(25) DEFAULT 'Open Seas Tours'
DECLARE :UnitWeight DECIMAL(10,3);
DECLARE :Titration NUMERIC(12,3);
DECLARE :ReasonForReturn VARCHAR(200);
DECLARE :Counter INTEGER = 0;
DECLARE :CurrentCapacity INTEGER = 9;
DECLARE :Cust_ID UNIQUEIDENTIFIER = NEWID()
DECLARE :ISO_ID UNIQUEIDENTIFIER = '1129619D-772C-AAABB221-00FF00FF0099'

See Also

CREATE FUNCTION on page 3-51

CREATE PROCEDURE on page 3-66
CREATE TRIGGER on page 3-103
SET on page 3-260

3-113

SQL Syntax Reference

DECLARE CURSOR
The DECLARE CURSOR statement defines an SQL cursor.
Syntax

DECLARE cursor-name CURSOR FOR select-statement [ FOR UPDATE | FOR

READ ONLY ]
cursor-name ::= user-defined-name

Remarks

The DECLARE statement is only allowed inside of a stored

procedure or a trigger, since cursors and variables are only allowed
inside of stored procedures and triggers.
The default behavior for cursors is read-only. Therefore, you must
use FOR UPDATE to explicitly designate an update (write or delete).

Examples

The following example creates a cursor that selects values from the
Degree, Residency, and Cost_Per_Credit columns in the Tuition
table and orders them by ID number.
DECLARE BTUCursor CURSOR
FOR SELECT Degree, Residency, Cost_Per_Credit
FROM Tuition
ORDER BY ID;

The following example uses FOR UPDATE to ensure a delete.

CREATE PROCEDURE MyProc(IN :CourseName CHAR(7)) AS
BEGIN
DECLARE c1 CURSOR FOR SELECT name FROM course
WHERE name = :CourseName FOR UPDATE;
OPEN c1;
FETCH NEXT FROM c1 INTO :CourseName;
DELETE WHERE CURRENT OF c1;
CLOSE c1;
END;
CALL MyProc('HIS 305')

3-114

Grammar Statements

DECLARE cursor1 CURSOR

FOR SELECT Degree, Residency, Cost_Per_Credit
FROM Tuition ORDER BY ID
FOR UPDATE;

See Also

CREATE PROCEDURE on page 3-66

The following example shows how to loop through a cursor. on
page 3-77
CREATE TRIGGER on page 3-103

3-115

SQL Syntax Reference

DEFAULT
You may use the DEFAULT keyword in the following contexts:

Column definition of CREATE TABLE statement

Column definition of ALTER TABLE statement
VALUES clause of INSERT statement
VALUES clause of UPDATE statement

The default value (literal or expression) that you specify in a

CREATE TABLE or ALTER TABLE statement must meet the
following criteria:

be consistent with the data type of the column

conform to any other constraint imposed on the column, such
as range, length, and so forth.

Also, in INSERT and UPDATE statements, you do not have to specify

values for columns that have a DEFAULT value defined. In such a
case, Pervasive PSQL computes the DEFAULT expression and uses
the result value as the value of the column.
Syntax

See the syntax for the following statements:

3-116

ALTER TABLE on page 3-10

CREATE TABLE on page 3-80
INSERT on page 3-166
UPDATE on page 3-269

Grammar Statements

Remarks

You can specify expressions as DEFAULT values for columns of all

data types as shown in the following table.
Table 3-4 Allowed DEFAULT Expression Data Types
Relational Data Type

Allowed DEFAULT Expression Types

(ODBC data types)

BFLOAT4, BFLOAT8

SQL_BIGINT

BIGINT, UBIGINT

SQL_BIT

BIT

SQL_CHAR

CURRENCY

SQL_DECIMAL

DECIMAL

SQL_DOUBLE

DOUBLE

SQL_FLOAT

IDENTITY1

SQL_INTEGER

INTEGER, UINTEGER

SQL_LONGVARCHAR

NUMERIC

SQL_NUMERIC

NUMERICSA

SQL_REAL

NUMERICSTS

SQL_SMALLINT

REAL

SQL_TINYINT

SMALLIDENTITY1

SQL_VARCHAR

SMALLINT, USMALLINT

TINYINT, UTINYINT

BINARY

SQL_BIGINT

LONGVARBINARY

SQL_BINARY

SQL_BIT

SQL_CHAR

SQL_GUID

SQL_INTEGER

SQL_LONGVARBINARY

SQL_LONGVARCHAR

SQL_SMALLINT

SQL_TINYINT

SQL_VARCHAR

3-117

SQL Syntax Reference

Table 3-4 Allowed DEFAULT Expression Data Types continued

Relational Data Type

Allowed DEFAULT Expression Types

(ODBC data types)

CHAR

SQL_BIGINT

LONGVARCHAR

SQL_BIT

VARCHAR

SQL_CHAR

SQL_DATE

SQL_DECIMAL

SQL_DOUBLE

SQL_FLOAT

SQL_GUID

SQL_INTEGER

SQL_LONGVARCHAR

SQL_NUMERIC

SQL_REAL

SQL_SMALLINT

SQL_TIME

SQL_TIMESTAMP

SQL_TINYINT

SQL_VARCHAR

SQL_CHAR

SQL_LONGVARCHAR

SQL_VARCHAR

SQL_GUID

SQL_CHAR

SQL_DATE

SQL_LONGVARCHAR

SQL_TIMESTAMP

SQL_VARCHAR

UNIQUEIDENTIFIER

DATE

If the data type of expression is

TIMESTAMP, only the date part is
extracted and used.

3-118

Grammar Statements

Table 3-4 Allowed DEFAULT Expression Data Types continued

Relational Data Type

Allowed DEFAULT Expression Types

(ODBC data types)

TIME

SQL_CHAR

SQL_LONGVARCHAR

SQL_TIME

SQL_TIMESTAMP

SQL_VARCHAR

If the data type of expression is

TIMESTAMP, only the time part is
extracted and used.
TIMESTAMP

SQL_CHAR

SQL_DATE

SQL_LONGVARCHAR

SQL_TIMESTAMP

SQL_VARCHAR

If the data type of expression is

DATE, the time part is set to
'00:00:00'.
1

In a CREATE TABLE statement or an ALTER TABLE statement, you may set a

default value of zero (default 0 or default '0') for an IDENTITY or a
SMALLIDENTITY data type. No other default value is permissible.

Examples

The following statement creates a table named Tab1. The default

value of the col1 column is the DATE part of timestamp returned by
NOW ().
CREATE TABLE Tab1
(
col1 DATE DEFAULT NOW()
)

The following statement creates a table named Tab5. The default

value of the col5 column is 200.
CREATE TABLE Tab5
(
col5 INT DEFAULT 200
)

3-119

SQL Syntax Reference

The following statement creates a table named Tab8. The default

value of the col8 column is the timestamp at the time of the INSERT
or UPDATE.
CREATE TABLE Tab8
(
col8 TIMESTAMP DEFAULT CURRENT_TIMESTAMP
)

The following statement creates a table named Tab6. The default

value of the col6 column is the name of user, after executing an
INSERT or UPDATE statement. Using a default user name is
practical only when security is enabled. Otherwise, USER is always
NULL.
CREATE TABLE Tab6
(
col6 VARCHAR(20) DEFAULT USER
)

The following statement shows an invalid example. The statement

results in a parse-time error because SQL_TIME is not an allowed
data type for a DATE column.
CREATE TABLE Tab
(
col DATE DEFAULT CURTIME()
)

The following statement shows an invalid example. The statement

results in a parse-time error. Although '3.1' is convertible to a
number, it is not a valid integer.
CREATE TABLE Tab
(
col SMALLINT DEFAULT '3.1'
)

The following statement shows an invalid example. The CREATE

TABLE statement succeeds but the INSERT statement fails because 60000 is outside of the range supported by SMALLINT.
CREATE TABLE Tab

3-120

Grammar Statements
(
col SMALLINT DEFAULT 3 * -20000
)
INSERT INTO Tab values(DEFAULT)

The following statements show valid examples of setting a default

value of zero for an IDENTITY and a SMALLIDENTITY data type.
CREAT TABLE t1 ( c1 IDENTITY DEFAULT '0' )
ALTER TABLE t1 ALTER c1 SMALLIDENTITY DEFAULT 0

The following statements show invalid examples of setting a default

value for an IDENTITY and a SMALLIDENTITY data type.
CREATE TABLE t1 ( c1 IDENTITY DEFAULT 3 )
ALTER TABLE t1 ALTER c1 SMALLIDENTITY DEFAULT 1

Expressions as
Default Values for
Date or Time
Columns

Defaults specify the values that are used in a column if you do not
specify a value for the column when inserting a row.
To assign an expression as a default on a column, define a default
value using the DEFAULT keyword in the CREATE TABLE
statement. For more details on creating a table, see CREATE
TABLE on page 3-80.
In addition to literals and NULL values, Pervasive PSQL also allows
you to specify date and time scalar functions and expressions as
default values for columns of the appropriate data types.
CURRENT_USER() is allowed as a default value for string columns
CHAR and VARCHAR.

3-121

SQL Syntax Reference

The following table lists the specific date and time scalar functions
that you can invoke to provide the default value for a column of the
appropriate data type:
Table 3-5 Date and Time Scalar Functions as Default Values
Function

Default for

CURRENT_DATE( )

Date columns only

CURDATE( )

Date columns only

CURRENT_TIME( )

Time columns only

CURTIME( )

Time columns only

CURRENT_TIMESTAMP( )

Timestamp or date-time columns

NOW( )

Timestamp or date-time columns

When you specify a scalar function as the default value for a column
in INSERT and UPDATE statements, Pervasive PSQL invokes the
specified scalar function to set the value of such a column to the
result of the function call.
See Also

ALTER TABLE on page 3-10

CREATE TABLE on page 3-80
INSERT on page 3-166
UPDATE on page 3-269

3-122

Grammar Statements

DELETE (positioned)
Use the positioned DELETE statement to remove the current row of
a view associated with an SQL cursor.
Syntax

DELETE WHERE CURRENT OF cursor-name

cursor-name ::= user-defined-name

Remarks

This statement is allowed in stored procedures, triggers, and at the

session level.
Note Even though positioned DELETE is allowed at the session
level, the DECLARE CURSOR statement is not. Use the
SQLGetCursorName() API to obtain the cursor name of the
active result set.

Examples

The following sequence of statements provide the setting for the

positioned DELETE statement. The required statements for the
positioned DELETE statement are DECLARE CURSOR, OPEN
CURSOR, and FETCH FROM cursorname.
The Modern European History class has been dropped from the
schedule, so this example deletes the row for Modern European
History (HIS 305) from the Course table in the sample database:
CREATE PROCEDURE DropClass();
DECLARE :CourseName CHAR(7);
DECLARE c1 CURSOR
FOR SELECT name
FROM COURSE
WHERE name = :CourseName;
BEGIN
SET :CourseName = 'HIS 305';
OPEN c1;
FETCH NEXT FROM c1 INTO :CourseName;
DELETE WHERE CURRENT OF c1;
END;

3-123

SQL Syntax Reference

See Also

CREATE PROCEDURE on page 3-66

CREATE TRIGGER on page 3-103

3-124

Grammar Statements

DELETE
This statement deletes specified rows from a database table or view.
Syntax

DELETE [ FROM ] < table-name | view-name > [ alias-name ]

[ FROM table-reference [, table-reference ] ...
[ WHERE search-condition ]
table-name ::= user-defined-name
view-name ::= user-defined-name
alias-name ::= user-defined-name

(Alias-name is not allowed if a second

FROM clause is used. See FROM Clause on page 3-126.)

table-reference ::= { OJ outer-join-definition }

| [db-name.]table-name [ [ AS ] alias-name ]
| [db-name.]view-name [ [ AS ] alias-name ]
| join-definition
| ( join-definition )
| ( table-subquery )[ AS ] alias-name [ (column-name [ , column-name
]... ) ]
outer-join-definition ::= table-reference outer-join-type JOIN table-reference ON searchcondition
outer-join-type ::= LEFT [ OUTER ] | RIGHT [ OUTER ] | FULL [

OUTER ]
search-condition ::= search-condition AND search-condition

| search-condition OR search-condition
| NOT search-condition
| ( search-condition )
| predicate
db-name ::= user-defined-name
view-name ::= user-defined-name
join-definition ::= table-reference [ join-type ] JOIN table-reference ON searchcondition

| table-reference CROSS JOIN table-reference

| outer-join-definition

3-125

SQL Syntax Reference

join-type ::= INNER | LEFT [ OUTER ] | RIGHT [ OUTER ] | FULL

[ OUTER ]
table-subquery ::= query-specification [ [ UNION [ ALL ]
query-specification ]... ]

Remarks

INSERT, UPDATE, and DELETE statements behave in an atomic

manner. That is, if an insert, update, or delete of more than one row
fails, then all insertions, updates, or deletes of previous rows by the
same statement are rolled back.
FROM Clause
Some confusion may arise pertaining to the second optional FROM
clause and references to the table whose rows are being deleted
(referred to as the delete table). If the delete table occurs in the
second FROM clause, then one of the occurrences is the same
instance of the table whose rows are being deleted.
For example, in the statement DELETE t1 FROM t1, t2 WHERE
t1.c1 = t2.c1, the t1 immediately after DELETE is the same
instance of table t1 as the t1 after FROM. Therefore, the statement is
identical to DELETE t1 FROM t2 WHERE t1.c1 = t2.c1.
If the delete table occurs in the second FROM clause multiple times,
one occurrence must be identified as the same instance as the delete
table. The second FROM clause reference that is identified as the
same instance as the delete table is the one that does not have a
specified alias.
Therefore, the statement DELETE t1 FROM t1 a, t1 b WHERE a.c1
= b.c1 is invalid because both instances of t1 in the second FROM
clause contain an alias. The following version is valid: DELETE t1
FROM t1, t1 b WHERE t1.c1 = b.c1.
The following conditions apply to the second FROM clause:

If the DELETE statement contains an optional second FROM

clause, the table reference prior to the FROM clause cannot have
an alias specified. For example, DELETE t1 a FROM t2 WHERE
a.c1 = t2.c1 returns the following error:
SQL_ERROR (-1)
SQLSTATE of 37000

3-126

Grammar Statements
[Pervasive][ODBC Client Interface][LNA][Pervasive]
[ODBC Engine Interface]Table alias not allowed in
UPDATE/DELETE statement with optional FROM.

A valid version of the statement is DELETE t1 FROM t2 WHERE

t1.c1 = t2.c1 or DELETE t1 FROM t1 a, t2 WHERE a.c1 =
t2.c1.

If more than one reference to the delete table appears in the

second FROM clause, then only one of the references can have a
specified alias. For example, DELETE t1 FROM t1 a, t1 b
WHERE a.c1 = b.c1 returns the following error:
SQL_ERROR (-1)
SQLSTATE of 37000
[Pervasive][ODBC Client Interface][LNA][Pervasive]
[ODBC Engine Interface] The table t1 is
ambiguous.

In the erroneous statement, assume that you want table t1

with alias a to be the same instance of the delete table. A valid
version of the statement is DELETE t1 FROM t1, t1 b WHERE
t1.c1 = b.c1.

Examples

The second FROM clause is supported in a DELETE statement

only at the session level. The FROM clause is not supported if the
DELETE statement occurs within a stored procedure.

The following statement deletes the row for first name Ellen from the
person table in the sample database.
DELETE FROM person WHERE First_Name = 'Ellen'

The following statement deletes the row for Modern European

History (HIS 305) from the course table in the sample database:
DELETE FROM Course WHERE Name = 'HIS 305'

3-127

SQL Syntax Reference

DISTINCT
Remarks

Include the DISTINCT keyword in your SELECT statement to direct

Pervasive PSQL to remove duplicate values from the result. By using
DISTINCT, you can retrieve all unique rows that match the SELECT
statement's specifications.
The following rules apply to using the DISTINCT keyword:

You can use DISTINCT in any statement that includes

subqueries.
The DISTINCT keyword is ignored if the selection list contains
an aggregate; the aggregate guarantees that no duplicate rows
result.

The following usage of DISTINCT is not allowed:

SELECT DISTINCT column1, DISTINCT column2

Examples

The following statement retrieves all the unique courses taught by

Professor Beir (who has a Faculty ID of 111191115):
SELECT DISTINCT c.Name
FROM Course c, class cl
WHERE c.name = cl.name AND cl.faculty_id =
'111191115'

See Also

3-128

SELECT on page 3-202

Grammar Statements

DROP DATABASE
The DROP DATABASE statement deletes a database. Only the
Master user can issue the statement.
Syntax

DROP DATABASE database-name [ DELETE FILES ]

database-name ::= user-defined-name

Remarks

As Master user, you must be logged on to a database to issue the

statement. The DROP DATABASE statement can be used to drop any
database, including the one to which you are currently logged on,
provided the security setting permits deletion. See Secured
Databasesbelow.
DROP DATABASE cannot be used to delete system databases such as
defaultdb and tempdb. The statement can be used to delete the last
remaining user-defined database if you choose, security permitting.
The DROP DATABASE statement cannot be used in a stored
procedure or in a user-defined function.
Secured Databases
You cannot delete a database secured with the database
transactional security model. See Available Models for the
Transactional Interface on page 7-5 in Advanced Operations Guide.
You can delete a database secured with any of the following ways:

The classic transactional security model

The mixed transactional security model
Relational security (Master password) in combination with
classic or mixed transactional models

See Security Models and Concepts on page 7-4 in Advanced

Operations Guide.
DELETE FILES
The DELETE FILES clause specifies to delete the data dictionary files
(DDFs). Data files are not deleted.
If DELETE FILES is omitted, the DDFs remain on physical storage,
but the database name is deleted from dbnames.cfg. (Once the name
is removed from dbnames.cfg, the database no longer exists to the

3-129

SQL Syntax Reference

database engine.) Retaining the DDFs allows you to re-create the

database should you so choose.
Note that the DDFs must not be in use to delete them. If you have
Pervasive PSQL Control Center open, for example, a file is locked
error returns if you use the DELETE FILES clause. Having PCC open
causes the DDFs to be in use, which prevents their deletion.
Examples

The following example deletes a database named inventorydb

from dbnames.cfg, but retains the databases DDFs (and data files)
on physical storage.
DROP DATABASE inventorydb

The following example deletes a database named HRUSBenefits

and its DDFs. Data files for HRUSBenefits are retained.
DROP DATABASE HRUSBenefits DELETE FILES

See Also

3-130

CREATE DATABASE on page 3-46

Grammar Statements

DROP FUNCTION
The DROP FUNCTION statement removes an existing user-defined
function (UDF) from the database.
Note An error message appears if you attempt to delete a UDF

that does not exist.

Syntax

DROP FUNCTION { function_name }

function_name ::=

Examples

Name of the user-defined function to be removed.

The following statement drops UDF fn_MyFunc from the database.

DROP FUNCTION fn_MyFunc

See Also

CREATE FUNCTION on page 3-51

3-131

SQL Syntax Reference

DROP GROUP
This statement removes one or more groups in a secured database.
Syntax

DROP GROUP group-name [ , group-name ]...

Remarks

Only the Master user can perform this statement. Separate multiple
group names with a comma. A group must be empty to be dropped.
Security must be turned on to perform this statement.

Examples

The following example drops the group pervasive.

DROP GROUP pervasive

The following example uses a list to drop groups.

DROP GROUP pervasive_dev, pervasive_marketing

See Also

ALTER GROUP on page 3-8

CREATE GROUP on page 3-58

3-132

Grammar Statements

DROP INDEX
This statement drops a specific index from a designated table.
Syntax

DROP INDEX [ table-name . ] index-name [ IN DICTIONARY ]

table-name ::= user-defined-name
index-name ::= user-defined-name

Remarks

IN DICTIONARY is a very powerful and advanced feature. It should

only be used by system administrators or when absolutely necessary.
The IN DICTIONARY keyword allows you to drop an index from a
DDF without removing the index from the underlying data file.
Normally, Pervasive PSQL keeps DDFs and data files perfectly
synchronized, but this feature allows users the flexibility to force outof-sync table dictionary definitions to match an existing data file.
This can be useful when you want to create a definition in the
dictionary to match an existing data file.
Caution Modifying a DDF without performing parallel

modifications to the underlying data file can cause serious

problems.
For more information on this feature, see the discussion under IN
DICTIONARY on page 3-12.
Partial Indexes

When dropping partial indexes, the PARTIAL modifier is not

required.
Examples

The following statement drops the named index from the Faculty
table.
DROP INDEX Faculty.Dept

3-133

SQL Syntax Reference

The following examples create a detached table, one with no

associated data file, then add and drop an index from the table
definition. The index is a detached index because there is no
underlying Btrieve index associated with it.
CREATE TABLE t1 IN DICTIONARY (c1 int, c2 int)
CREATE INDEX idx_1 IN DICTIONARY on t1(c1)
DROP INDEX t1.idx_1 IN DICTIONARY

See Also

3-134

CREATE INDEX on page 3-59

Grammar Statements

DROP PROCEDURE
This statement removes one or more stored procedures from the
current database.
Syntax

DROP PROCEDURE procedure-name

Examples

The following statement drops the stored procedure myproc from

the dictionary:
DROP PROCEDURE myproc

See Also

CREATE PROCEDURE on page 3-66

3-135

SQL Syntax Reference

DROP TABLE
This statement removes a table from a designated database.
Syntax

DROP TABLE table-name [ IN DICTIONARY ]

table-name ::= user-defined-name for the table that you want to remove.

IN DICTIONARY

See the discussion of IN DICTIONARY forALTER TABLE on page

3-10.
Remarks

CASCADE and RESTRICT are not supported.

If any triggers depend on the table, the table is not dropped.
If a transaction is in progress and refers to the table, then an error is
signalled and the table is not dropped.
The drop of table fails if other tables depend on the table to be
dropped.
If a primary key exists, it is dropped. The user need not drop the
primary key before dropping the table. If the primary key of the table
is referenced by a constraint belonging to another table, then the
table is not dropped and an error is signalled.
If the table has any foreign keys, then those foreign keys are dropped.
If the table has any other constraints (for example, NOT NULL,
CHECK, UNIQUE, or NOT MODIFIABLE), then those constraints
are dropped when the table is dropped.

Examples

The following statement drops the class table definition from the
dictionary.
DROP TABLE Class

See Also

ALTER TABLE on page 3-10

CREATE TABLE on page 3-80

3-136

Grammar Statements

DROP TRIGGER
This statement removes a trigger from the current database.
Syntax

DROP TRIGGER trigger-name

Examples

The following example drops the trigger named InsTrig.

DROP TRIGGER InsTrig

See Also

CREATE TRIGGER on page 3-103

3-137

SQL Syntax Reference

DROP USER
The DROP USER statement removes an existing user account(s)
from a database.
Syntax

DROP USER user-name [ , user-name ]...

Remarks

This function is an extension to SQL grammar as documented in the

Microsoft ODBC Programmers Reference.
Only the Master user can execute this statement.
Security must be turned on to perform this statement.
Separate multiple user names with a comma.
The user name must be enclosed in double quotes if it contains
spaces or other non-alphanumeric characters.
Dropping a user account does not delete the tables, views, or other
database objects created by the user.
For further general information about users and groups, see Master
User on page 7-2 and Users and Groups on page 7-3 in Advanced
Operations Guide.

Examples

The following example removes the user account pgranger.

DROP USER pgranger

The following example removes multiple user accounts.

DROP USER pgranger, lester pelling

See Also

ALTER USER on page 3-26

CREATE USER on page 3-106

3-138

Grammar Statements

DROP VIEW
This statement removes a specified view from the database.
Syntax

DROP VIEW view-name

view-name ::= user-defined name

Remarks

[CASCADE | RESTRICT] is not supported.

Examples

The following statement drops the vw_person view definition from

the dictionary.
DROP VIEW vw_person

See Also

CREATE VIEW on page 3-108

3-139

SQL Syntax Reference

END
Remarks

3-140

See the discussion for BEGIN [ATOMIC] on page 3-31.

Grammar Statements

EXECUTE
The EXECUTE statement has two uses:

Syntax

To invoke a user-defined procedure or a system stored

procedure. You may use EXECUTE in place of the CALL
statement
To execute a character string, or an expression that returns a
character string, within a stored procedure.

To invoke a stored procedure:

EXEC[UTE] stored-procedure [ ( [ procedure-parameter [ , procedure-parameter
]... ] ) ]
stored-procedure

::= the name of a stored procedure

procedure-parameter

::= the input parameter(s) required by the stored

procedure
Within a user-defined stored procedure:
EXEC[UTE] ( string [ + string ]... )
string ::=

a string, string variable, or an expression that returns a character

string
Examples

The following example executes a procedure without parameters:

EXEC NoParms() or CALL NoParms

The following examples execute a procedure with parameters:

EXEC Parms(vParm1, vParm2)
EXECUTE CheckMax(N.Class_ID)

3-141

SQL Syntax Reference

The following procedure selects the student ID from the Billing

table.
CREATE PROCEDURE tmpProc(IN :vTable CHAR(25)) RETURNS
(sID INTEGER) AS
BEGIN
EXEC ('SELECT Student_ID FROM ' + :vtable);
END;
EXECUTE tmpProc(Billing)

See Also

CALL on page 3-32

CREATE PROCEDURE on page 3-66
System Stored Procedures on page 6-1

3-142

Grammar Statements

EXISTS
The EXISTS keyword tests whether rows exist in the result of a
subquery. True is returned if the subquery contains any rows.
Syntax

EXISTS ( subquery )

Remarks

For every row the outer query evaluates, Pervasive PSQL tests for the
existence of a related row from the subquery. Pervasive PSQL
includes in the statement's result table each row from the outer query
that corresponds to a related row from the subquery.
You may use EXISTS for a subquery within a stored procedure.
However, the subquery SELECT statement within the stored
procedure may not contain a COMPUTE clause or the INTO
keyword.
In most cases, a subquery with EXISTS can be rewritten to use IN.
Pervasive PSQL can process the query more efficiently if the query
uses IN.

Examples

The following statement returns a list containing only persons who

have a 4.0 grade point average:
SELECT * FROM Person p WHERE EXISTS
(SELECT * FROM Enrolls e WHERE e.Student_ID = p.id
AND Grade = 4.0)

This statement can be rewritten to use IN:

SELECT * FROM Person p WHERE p.id IN
(SELECT e.Student_ID FROM Enrolls WHERE Grade = 4.0)

3-143

SQL Syntax Reference

The following procedure selects the ID from the Person table using a
value as an input parameter. The first EXEC of the procedure returns
Exists returned true. The second EXEC returns Exists returned
false.
CREATE PROCEDURE ex1(IN :vID INTEGER) AS
BEGIN
IF EXISTS ('SELECT id FROM person WHERE id < :vID)
THEN PRINT 'Exists returned true';
ELSE PRINT 'Exists returned false';
ENDIF;
END;
EXEC ex1(222222222)
EXEC ex1(1)

See Also

3-144

SELECT on page 3-202

Grammar Statements

FETCH
Remarks

A FETCH statement positions an SQL cursor on a specified row of a

table and retrieves values from that row by placing them into the
variables in a target list.
You may choose not to use the NEXT and FROM keywords while
fetching data from any cursor.
Note Pervasive PSQL supports only the forward-only cursor. So,

you will not be able to control the flow of the cursor records even
by omitting NEXT FROM.

Syntax

FETCH [ [NEXT] FROM ]cursor-name INTO variable-name

cursor-name ::= user-defined-name

Examples

The FETCH statement in this example retrieves values from cursor

c1 into the CourseName variable. The Positioned UPDATE
statement in this example updates the row for Modern European
History (HIS 305) in the Course table in the DEMODATA sample
database:
CREATE PROCEDURE UpdateClass();
BEGIN
DECLARE :CourseName CHAR(7);
DECLARE :OldName CHAR(7);
DECLARE c1 CURSOR FOR SELECT name FROM course WHERE
name = :CourseName;
OPEN c1;
SET :CourseName = 'HIS 305';
FETCH NEXT FROM c1 INTO :OldName;
UPDATE SET name = 'HIS 306' WHERE CURRENT OF c1;
END;

3-145

SQL Syntax Reference

CREATE PROCEDURE MyProc(OUT :CourseName CHAR(7)) AS

BEGIN
DECLARE cursor1 CURSOR
FOR SELECT Degree, Residency, Cost_Per_Credit
FROM Tuition ORDER BY ID;
OPEN cursor1;
FETCH NEXT FROM cursor1 INTO :CourseName;
CLOSE cursor1;
END

See Also

3-146

CREATE PROCEDURE on page 3-66

Grammar Statements

FOREIGN KEY
Remarks

Include the FOREIGN KEY keywords in the ADD clause to add a

foreign key to a table definition.
Note You must be logged in to the database using a database

name before you can add a foreign key or conduct any other
referential integrity (RI) operation. Also, when security is
enabled, you must have the Reference right on the table to which
the foreign key refers before you can add the key.
Include a FOREIGN KEY clause in your CREATE TABLE statement
to define a foreign key on a dependent table. In addition to specifying
a list of columns for the key, you can define a name for the key.
The columns in the foreign key column may be nullable. However,
ensure that pseudo-null columns do not exist in an index that does
not index pseudo-null values.
The foreign key name must be unique in the dictionary. If you omit
the foreign key name, Pervasive PSQL uses the name of the first
column in the key as the foreign key name. This can cause a duplicate
foreign key name error if your dictionary already contains a foreign
key with that name.
When you specify a foreign key, Pervasive PSQL creates an index on
the columns that make up the key. This index has the same attributes
as the index on the corresponding primary key except that it allows
duplicate values. To assign other attributes to the index, create it
explicitly using a CREATE INDEX statement. Then, define the
foreign key with an ALTER TABLE statement. When you create the
index, ensure that it does not allow null values and that its case and
collating sequence attributes match those of the index on the
corresponding primary key column.
The columns in a foreign key must be the same data types and
lengths and in the same order as the referenced columns in the
primary key. The only exception is that you can use an integer
column in the foreign key to refer to an IDENTITY or
SMALLIDENTITY column in the primary key. In this case, the two
columns must be the same length.

3-147

SQL Syntax Reference

Pervasive PSQL checks for anomalies in the foreign keys before it

creates the table. If it finds conditions that violate previously defined
referential integrity (RI) constraints, it generates a status code and
does not create the table.
When you define a foreign key, you must include a REFERENCES
clause indicating the name of the table that contains the
corresponding primary key. The primary key in the parent table
must already be defined. In addition, if security is enabled on the
database, you must have the Reference right on the table that
contains the primary key.
You cannot create a self-referencing foreign key with the CREATE
TABLE statement. Use an ALTER TABLE statement to create a
foreign key that references the primary key in the same table.
Also, you cannot create a primary key and a foreign key on the same
set of columns in a single statement. Therefore, if the primary key of
the table you are creating is also a foreign key on another table, you
must use an ALTER TABLE statement to create the foreign key.
Examples

The following statement adds a new foreign key to the Class table.
(The Faculty column is defined as an index that does not include null
values.)
ALTER TABLE Class ADD CONSTRAINT Teacher FOREIGN KEY
(Faculty_ID)
REFERENCES Faculty ON DELETE RESTRICT

In this example, the restrict rule for deletions prevents someone

from removing a faculty member from the database without first
either changing or deleting all of that faculty's classes.
See Also

ALTER TABLE on page 3-10

CREATE TABLE on page 3-80

3-148

Grammar Statements

GRANT
The GRANT statement creates new user IDs and gives permissions
to specific users in a secured database.
Syntax

GRANT CREATETAB | CREATEVIEW | CREATESP TO public-or-user-orgroup-name [ , user-or-group-name ]...

GRANT LOGIN TO user-password [ , user-password ]... [ IN GROUP groupname ]
GRANT permission ON < * | [ TABLE ] table-name [ owner-name ] |
VIEW view-name | PROCEDURE stored_procedure-name >
TO user-or-group-name [ , user-or-group-name ]...
* ::= all of the objects (that is, all tables, views and
stored procedures)
permission ::=

|
|
|
|
|
|
|

ALL

ALTER [ ( table-column-name [ , table-column-name ]... ) ]

DELETE [ ( table-column-name [ , table-column-name ]... ) ]
INSERT [ ( table-column-name [ , table-column-name ]... ) ]
REFERENCES [ (table-column-name [ , table-column-name ]...)]
SELECT [ ( table-column-name [ , table-column-name ]... ) ]
UPDATE [ ( table-column-name [ , table-column-name ]... ) ]
EXECUTE

table-name ::= user-defined table-name

owner-name ::= user-defined owner name
view-name ::= user-defined view-name
stored-procedure-name ::= user-defined stored_procedure-name
user-password ::= user-name [ : ] password
public-or-user-or-group-name ::= PUBLIC | user-or-group-name
user-or-group-name ::= user-name | group-name
user-name ::= user-defined user name
table-column-name ::= user-defined column name (tables only)

3-149

SQL Syntax Reference

Remarks

CREATETAB, CREATESP, CREATEVIEW, and LOGIN TO

arguments are extensions to the core SQL grammar. You can use the
GRANT statement to grant privileges for CREATE TABLE, CREATE
VIEW, and CREATE PROCEDURE, and to create a user account
with password as a member of an already created group.
The following table shows the syntax for a given action:
To GRANT Privileges For This Action

Use This Syntax With GRANT

CREATE TABLE

CREATETAB

CREATE VIEW

CREATEVIEW

CREATE PROCEDURE

CREATESP

LOGIN AS GROUP MEMBER

Note that CREATETAB, CREATEVIEW, and CREATESP must be

explicitly granted. These permissions are not included as part of a
GRANT ALL statement.
GRANT LOGIN TO

GRANT LOGIN TO creates a user and allows that user to access the
secured database. You must specify a user name and user password
to create a user. Optionally, you may specify the group to which you
want the user to belong. The group must already exist. You cannot
create a group with the GRANT LOGIN statement.
Constraints
The following constraints apply to permissions:

3-150

By Object Type
ALL Key Word

Grammar Statements

By Object Type
Table 3-6 Permissions Applicable To Object Type
Permission
CREATETAB

Table1

CREATEVIEW

CREATESP
ALTER2

DELETE

INSERT

REFERENCES

SELECT

UPDATE

EXECUTE3

Stored Procedure

1Columns

can be specified only for tables. Permissions for a view can be

granted to the entire view, not to individual columns within the view.
2To drop a table, view, or stored procedure, a user must have ALTER permission
on that object. Trused views and stored procedures can be dropped only by the
Master user.

The EXECUTE permission applies only to stored procedures. Note that a

stored procedure can be executed with either the CALL statement or the
EXECUTE statement. The stored procedure can be a trusted type or a nontrusted type. See Trusted and Non-trusted Objects on page 3-154.

3-151

SQL Syntax Reference

ALL Key Word

Table 3-7 Permissions Granted with ALL Key Word by Object Type
Permission Included
by ALL

Table

View

ALTER1

DELETE

INSERT

REFERENCES

SELECT

UPDATE

Stored Procedure

EXECUTE

To drop a table, view, or stored procedure, a user must have ALTER permission
on that object. Trused views and stored procedures can be dropped only by the
Master user.

For example, if you were to issue GRANT ALL ON * to User1, User1

would have all permissions listed in the table above.
If you were to issue GRANT ALL ON VIEW myview1 TO User2,
User2 would have ALTER, DELETE, INSERT, UPDATE, and
SELECT permissions on myview1.
Users and Groups

Relational security is based on the existence of a default user named

Master who has full access to the database when security is turned
on. When you turn security on, you will be required to specify a
password for the Master user.
Security must be turned on to perform this statement.
The Master user can create groups and other users using the GRANT
LOGIN TO, CREATE USER or CREATE GROUP commands and
define data access permissions for these groups and users.
If you want to grant the same permissions to all users, you can grant
them to the PUBLIC group. All users inherit the default permissions
assigned to the PUBLIC group.

3-152

Grammar Statements

Note If you wish to use groups, you must set up the groups

before creating users.

User name and password must be enclosed in double quotes if they
contain spaces or other non-alphanumeric characters.
For further information about users and groups, see Master User
on page 7-2 and Users and Groups on page 7-3 in Advanced
Operations Guide.
Owner Name

An owner name is a password required to gain access to a Btrieve file.

There is no relation between an owner name and any system user
name or database user name. You should think of an owner name as
a simple file password.
If you have a Btrieve owner name set on a file that is a table in a secure
ODBC database, the Master user of the ODBC database must use the
owner name in any GRANT statement to grant privileges on the
given table to any user, including the Master user.
After the GRANT statement containing the owner name has been
issued for a given user, that user can access the specified table by
logging into the database, without specifying the owner name each
time.
If a user tries to access a table through ODBC that has a Btrieve
owner name, the access will not be allowed unless the Master user
has granted privileges on the table to the user, with the correct owner
name in the GRANT statement.
If a table has an owner name with the Read-Only attribute, the
Master user automatically has SELECT rights on this table without
specifically granting himself/herself the SELECT rights with the
owner name.
Permissions on Views and Stored Procedures
Views and stored procedures can be trusted or non-trusted,
depending on how you want to handle the permissions for the
objects referenced by the view or stored procedure.

3-153

SQL Syntax Reference

Trusted and Non-trusted Objects

Views and stored procedures reference objects, such as tables, other

views or other stored procedures. Granting permissions on every
referenced object could become highly time consuming depending
on the number of objects and users. A simpler approach for many
situations is the concept of a trusted view or stored procedure.
A trusted view or stored procedure is one that can be executed
without having to explicitly set permissions for each referenced
object. For example, if trusted view myview1 references tables t1
and t2, the Master user can grant a user permissions on myview1
without having to grant the user permissions on t1 and t2.
A non-trusted view or stored procedure is one that cannot be
executed without having to explicitly set permissions for each
referenced object.

3-154

Grammar Statements

See the following table for a comparison of the characteristics

between trusted and non-trusted objects.
Table 3-8 Characteristics of Trusted and Non-trusted Views and Stored Procedures
Object

Characteristic

Notes

Trusted view or
trusted stored
procedure

Requires V2 metadata

See Versions of Metadata on page 22.

Requires WITH EXECUTE AS MASTER

clause in CREATE statement

See CREATE VIEW on page 3-108

and CREATE PROCEDURE on page
3-66.

Only Master user can create the object

See Master User on page 7-2 in

Advanced Operations Guide.

Only Master user can delete the object

See DROP VIEW on page 3-139 and

DROP PROCEDURE on page 3-135

Master user must grant object permissions

to other users

By default, only the Master user can

access trusted views or stored
procedures and must grant users
permissions to them.

GRANT and REVOKE statements

applicable to object

Object can exist in a secured or in a nonsecured database

See Security Models and Concepts

on page 7-4 in Advanced Operations
Guide.

Changing a trusted object to a non-trusted

one (or vice versa) requires deletion then
re-creation of object8

The ALTER statement for a view or

stored procedure cannot be used to
add or remove the trusted
characteristic of the object. If you need
to change a trusted object to a nontrusted one, you must first delete the
object then re-create it without the
WITH EXECUTE AS MASTER
clause. Similarly, if you need to change
a non-trusted object to a trusted one,
you must first delete the object then recreate it with the WITH EXECUTE AS
MASTER clause.

3-155

SQL Syntax Reference

Table 3-8 Characteristics of Trusted and Non-trusted Views and Stored Procedures continued
Object

Characteristic

Notes

Non-trusted view or
non-trusted stored
procedures

Any user can create the object

User must be granted CREATEVIEW

or CREATESP permission. See
Remarks on page 3-150.

Any user can delete the object

User must be granted ALTER

permission on the view or stored
procedure. See GRANT on page 3149.

ALTER permission required to delete the

object

ALTER permission is also required to

delete a table. Note that, by default,
only the Master user can delete trusted
objects. Users (other than Master) who
did not create the view or stored
procedure must be granted ALTER
permissions to delete the view or
stored procedure.

All users, by default, have all permissions

to the object

For V2 metadata, if a non-secured

database contains non-trusted objects,
all permissions for the non-trusted
objects are automatically granted to
PUBLIC if security is enabled on the
database.

User executing the view or stored

procedure needs permissions on the
objects referenced by the view or stored
procedure

The user must also have permissions

on the top-most object. That is, on the
view or stored procedure that
references the other objects.

GRANT and REVOKE statements

applicable to object

See GRANT on page 3-149 and

REVOKE on page 3-194.

Object can exist in a secured or in a nonsecured database

See Security Models and Concepts

on page 7-4 in Advanced Operations
Guide.

Changing a trusted object to a non-trusted

one (or vice versa) requires deletion then
re-creation of object

Same as above for trusted view or

trusted stored procedure.

Examples

A GRANT ALL statement grants the INSERT, UPDATE, ALTER,

SELECT, DELETE and REFERENCES rights to the specified user or
group. In addition, the user or group is granted the CREATE TABLE
right for the dictionary. The following statement grants all these
privileges to user dannyd for table Class.
GRANT ALL ON Class TO dannyd

3-156

Grammar Statements

The following statement grants the ALTER privilege to user debieq

for table Class.
GRANT ALTER ON Class TO debieq

The following statement gives INSERT privileges to keithv and miked

for table Class.
GRANT INSERT ON Class TO keithv, miked

The following statement grants INSERT privileges on two columns,

First_name and Last_name, in the Person table to users keithv and
brendanb
GRANT INSERT(First_name,last_name) ON Person to
keithv,brendanb

The following statement grants CREATE TABLE rights to users

aideenw and punitas
GRANT CREATETAB TO aideenw, punitas

The following GRANT LOGIN TO statement grants login rights to a

user named ravi and specifying his password as password.
GRANT LOGIN TO ravi:password

Note If the a user account that is granted login rights using the

GRANT LOGIN TO statement does not currently exist, then it is

created.
The user name and password here only refer to Pervasive PSQL
databases and are not related to user names and passwords set at the
operating system level. Pervasive PSQL user names, groups, and
passwords can also be set through the Pervasive PSQL Control
Center (PCC).
The following example grants login rights to users named dannyd
and travisk and specifies their passwords as password and 1234567
respectively.
GRANT LOGIN TO dannyd:password,travisk:1234567

3-157

SQL Syntax Reference

If there are spaces in a name you may use double quotes as in the
following example. This statement grants login rights to user named
Jerry Gentry and Punita and specifies their password as sun and
moon respectively
GRANT LOGIN TO "Jerry Gentry":sun, Punita:moon

The following example grants the login rights to a user named Jerry
Gentry with password 123456 and a user named travisk with
password abcdef. It also adds them to the group pervasive_dev
GRANT LOGIN TO "Jerry Gentry":123456, travisk:abcdef IN
GROUP pervasive_dev

To grant privileges on a table that has a Btrieve owner name, the

Master user has to supply the correct owner name in the GRANT
statement.
The following example grants the SELECT rights to the Master user
on table T1 that has a Btrieve owner name of abcd.
GRANT SELECT ON t1 'abcd' TO Master

The Master user has all rights on a table that does not have an owner
name. You can set an owner name on a table with the Maintenance
utility. The Btrieve owner name is case sensitive.

After the Master user performs the following set of SQL statements,
the user "jsmith" has SELECT access to all tables in the current
database. The user also has DELETE access to tab1 and UPDATE
access to tab2.
GRANT DELETE ON tab1 TO jsmith
GRANT SELECT ON * TO jsmith
GRANT UPDATE ON tab2 TO jsmith

If the following statement is performed later by any user with

CREATE TABLE privileges, the user "jsmith" will have SELECT
access to the newly created table.
CREATE TABLE tab3 (col1 INT)

GRANT CREATETAB TO user1

GRANT CREATESP TO user1

3-158

Grammar Statements

The following example grants EXECUTE permissions on stored

procedure cal_rtrn_rate to all users.
GRANT EXECUTE ON PROCEDURE cal_rtrn_rate TO PUBLIC

The following example shows how members of the group

Accounting can update only the salary column in the employee table
(employee is part of the DEMODATA sample database).
Assume that the following stored procedure exists:
CREATE PROCEDURE employee_proc_upd(in :EmpID integer, in
:Salary money) WITh EXECUTE AS 'Master';
BEGIN
UPDATE employee SET Salary = :Salary WHERE EmployeeID
= :Empid;
END
GRANT EXECUTE ON PROCEDURE employee_proc_upd TO
Accounting

Note that users belonging to group Accounting cannot update other

columns in the Employee table because permissions were granted
only for the stored procedure and the stored procedure updates only
the salary column.
See Also

CREATE GROUP on page 3-58

CREATE PROCEDURE on page 3-66
CREATE VIEW on page 3-108
DROP GROUP on page 3-132
REVOKE on page 3-194
SET SECURITY on page 3-250
System Stored Procedures on page 6-1

3-159

SQL Syntax Reference

GROUP BY
Remarks

In addition to the GROUP BY syntax in a SELECT statement,

Pervasive PSQL supports an extended GROUP BY syntax that can
include vendor strings.
A GROUP BY query returns a result set which contains one row of
the select list for every group encountered. (See the Microsoft ODBC
Programmers Reference for the syntax of a select list.)
The use of aliases is allowed within the GROUP BY clause. The alias
must differ from any column names within the table.

Examples

The following example uses the course table to produce a list of

unique departments:
SELECT Dept_Name FROM Course GROUP BY Dept_Name

This same example could use an alias, in this case dn, to produce
the same result:
SELECT Dept_Name dn FROM Course GROUP BY dn

In the next example, the result set contains a list of unique

departments and the number of courses in each department:
SELECT Dept_Name, COUNT(*) FROM Course GROUP BY Dept_
Name

Note that COUNT(expression) counts all non-NULL values for an

expression across a predicate. COUNT(*) counts all values,
including NULL values.

The rows operated on by the set function are those rows remaining
after the WHERE search condition is applied. In this example, only
those rows in the faculty table that have Salary > 80000 are counted:
SELECT COUNT(*) FROM Faculty WHERE Salary > 80000 GROUP
BY Dept_Name

3-160

Grammar Statements

The following example shows an extended GROUP BY that includes

vendor strings in an escape sequence. The Microsoft Web site
provides additional information about escape sequences and vendor
strings: http://msdn.microsoft.com/library/default.asp?url=/library/enus/odbc/htm/odbcescape_sequences_in_odbc.asp.
SELECT(--(*vendor(Microsoft), product(ODBC) fn
left(at1.col2, 1) *)--) FROM at1 GROUP BY (-(*vendor(Microsoft), product(ODBC) fn left(at1.col2, 1)
*)--) ORDER BY (--(*vendor(Microsoft), product(ODBC) fn
left(at1.col2, 1) *)--) DESC

See Also

SELECT on page 3-202

3-161

SQL Syntax Reference

HAVING
Remarks

Use a HAVING clause in conjunction with a GROUP BY clause

within SELECT statements to limit your view to groups whose
aggregate values meet specific criteria.
The expressions in a HAVING clause may contain constants, set
functions or an exact replica of one of the expressions in the GROUP
BY expression list.
The Pervasive PSQL database engine does not support HAVING
without GROUP BY.
The use of aliases is allowed within the HAVING clause. The alias
must differ from any column names within the table.

Examples

The following example returns department names where the count

of course names is greater than 5.
SELECT Dept_Name, COUNT(*) FROM Course GROUP BY Dept_
Name HAVING COUNT(*) > 5

This same example could use aliases, in this case dn and ct, to
produce the same result:
SELECT Dept_Name dn, COUNT(*) ct FROM Course GROUP BY dn
HAVING ct > 5

Note that COUNT(expression) counts all non-NULL values for an

expression across a predicate. COUNT(*) counts all values,
including NULL values.

The next example returns department name that matches

Accounting and has a number of courses greater than 5.
SELECT Dept_Name, COUNT(*) FROM Course GROUP BY Dept_
Name HAVING COUNT(*) > 5 AND Dept_Name = 'Accounting'

See Also

3-162

SELECT on page 3-202

Grammar Statements

IF
Remarks

IF statements provide conditional execution based on the value of a

condition. The IF . . . THEN . . . ELSE . . . END IF construct controls
flow based on which of two statement blocks will be executed. You
may also use the IF . . . ELSE syntax.
You may use IF statements in the body of both stored procedures and
triggers.
There is no limit to the number of nested IF statements allowed,
although the query remains subject to the usual total length
limitation and other applicable limitations.

Note You cannot use a mixed syntax containing Pervasive PSQL

and T.SQL. You may use either the IF...THEN...ELSE...END IF

syntax or the IFELSE syntax.
If you are using multiple statements with IF or ELSE conditions,
you must use BEGIN and END to indicate the beginning and
ending of the statement blocks.

Syntax

IF ( Boolean_condition )
BEGIN
Sql-statements

END
ELSE
BEGIN
Sql-statements

END

3-163

SQL Syntax Reference

Examples

The following example uses the IF statement to set the variable

Negative to either 1 or 0, depending on whether the value of vInteger
is positive or negative.
IF (:vInteger < 0) THEN
SET :Negative = '1';
ELSE
SET :Negative = '0';
END IF;

The following example uses the IF statement to test the loop for a
defined condition (SQLSTATE = '02000'). If it meets this condition,
then the WHILE loop is terminated.
FETCH_LOOP:
WHILE (:counter < :NumRooms) DO
FETCH NEXT FROM cRooms INTO :CurrentCapacity;
IF (SQLSTATE = '02000') THEN
LEAVE FETCH_LOOP;
END IF;
SET :counter = :counter + 1;
SET :TotalCapacity = :TotalCapacity +
:CurrentCapacity;
END WHILE;

IF(:vInteger >50)
BEGIN
set :vInteger = :vInteger + 1;
INSERT INTO test VALUES('Test');
END;
ELSE
set :vInteger = :vInteger - 1;

See Also

CREATE PROCEDURE on page 3-66

CREATE TRIGGER on page 3-103

3-164

Grammar Statements

IN
Remarks

Use the IN operator to test whether the result of the outer query is
included in the result of the subquery. The result table for the
statement includes only rows the outer query returns that have a
related row from the subquery.

Examples

The following example lists the names of all students who have taken
Chemistry 408:
SELECT p.First_Name + '

' +

p.Last_Name

FROM Person p, Enrolls e

WHERE (p.id = e.student_id)
AND (e.class_id IN
(SELECT c.ID FROM Class c WHERE c.Name = 'CHE
408'))

Pervasive PSQL first evaluates the subquery to retrieve the ID for

Chemistry 408 from the Class table. It then performs the outer query,
restricting the results to only those students who have an entry in the
Enrolls table for that course.
Often, you can perform IN queries more efficiently using either the
EXISTS keyword or a simple join condition with a restriction clause.
Unless the purpose of the query is to determine the existence of a
value in a subset of the database, it is more efficient to use the simple
join condition because Pervasive PSQL optimizes joins more
efficiently than it does subqueries.
See Also

SELECT on page 3-202

3-165

SQL Syntax Reference

INSERT
This statement inserts column values into one table.
Syntax

INSERT INTO table-name

[ ( column-name [ , column-name ]...) ]
insert-values
table-name ::= user-defined name
column-name ::= user-defined name
insert-values ::=

values-clause

| query-specification
values-clause ::= VALUES ( expression [ , expression ]... )

| DEFAULT VALUES

Remarks

INSERT, UPDATE, and DELETE statements behave in an atomic

manner. That is, if an insert, update, or delete of more than one row
fails, then all insertions, updates, or deletes of previous rows by the
same statement are rolled back.
All data types for data created prior to Pervasive.SQL 2000 (legacy
data) report back as nullable. This means that you can INSERT
NULL into any legacy column type without pseudo-NULL
conversion. The following data types are treated as pseudo-NULL by
default:
Date

Decimal

Money

NumericSA

NumericSTS

Timestamp

Numeric

Normally, when you convert a legacy column to pseudo-NULL, you

lose one of the binary values, forfeiting it for use as a null value, so
that you can query the column for NULL. These data types, however,
because of their design, have a different, unique internal value for
NULL in addition to their normal data range. With these data types,
no binary values are lost if they are converted to NULL so there is no
harm considering them as pseudo-NULL by default.
The rest of the data types are considered legacy nullable, meaning
that NULL may be inserted into them. When values are queried,
however, the non-NULL binary equivalent is returned. This same

3-166

Grammar Statements

binary equivalent must be used in WHERE clauses to retrieve

specific values.
The binary equivalents are:

CURTIME(),
CURDATE() and
NOW() variables

0 for Binary types

Empty string from string and BLOB types (legacy types LVAR
and NOTE)

You may use the variables CURTIME(), CURDATE() and NOW() in

INSERT statements to insert the current local date, time and
timestamp values.
CREATE TABLE table1 (col1 DATE)
INSERT INTO table1 VALUES (CURDATE())

In order to insert the current UTC time, date, or timestamp using

CURRENT_TIME() or related functions, you must structure your
SQL statement as shown:
CREATE TABLE table1 (col1 DATE)
INSERT INTO table1 SELECT CURRENT_DATE()

Using Default
Values

The following table describes the interaction between default values

and nullable columns:
Table 3-9 Default Values and Nullable Columns
Column
Type

Default value used if no literal

default value is defined for the
column:

Default value if literal value is

defined:

Nullable

NULL

As defined

Not NULL

Error"No default value

assigned for column."

As defined

Pre-v2000
Nullable

The pseudo-null value for the

column.

As defined

If a statement attempts to insert an explicit NULL value into a NOT

NULL column that has a default value defined, the statement fails
with an error. The default value is not used in place of the attempted
NULL insert.
For any column with a default value defined, the default value may
be invoked in an INSERT statement by omitting the column from

3-167

SQL Syntax Reference

the insert column list or by using the keyword DEFAULT in place of

the insert value.
If all the columns in a table are either nullable or have default values
defined, you can insert a record containing all default values by
specifying DEFAULT VALUES as the values-clause. If any column is
not nullable and no default is defined, or if you want to specify a
column list, you cannot use the DEFAULT VALUES clause.
Setting default values for BLOB, CLOB, or BINARY type column
definitions is not currently supported.
Long Data

The maximum literal string supported by Pervasive PSQL is 15,000

bytes. You can insert data longer than this through several different
methods. If you are using ODBC calls, you can use SQLPutData or
bind the data using a '?' placeholder and use SQLBindParameter.
Using only direct SQL statements, you can break the insert or update
statement into multiple calls. Start with a statement such as this:
update table1 set longfield = '15000 characters' where
restriction

Then issue the following statement to add more data:

update table1 set longfield = notefield + '15000 more
characters' where restriction

Examples

The following examples shows how to add data to a table by using

expressions in the VALUES clause:
CREATE TABLE t1 (c1 INT, c2 CHAR(20))
INSERT INTO t1 VALUES ((78 + 12)/3, 'This is' + CHAR(32)
+ 'a string')
SELECT * FROM t1
c1
c2
---------- ---------------30
This is a string

The following statement adds data to the Course table by directly

specifying the values in three VALUES clauses:
INSERT INTO Course(Name, Description, Credit_Hours,
Dept_Name)
VALUES ('CHE 308', 'Organic Chemistry II', 4,
'Chemistry')

3-168

Grammar Statements
INSERT INTO Course(Name, Description, Credit_Hours,
Dept_Name)
VALUES ('ENG 409', 'Creative Writing II', 3,
'English')
INSERT INTO Course(Name, Description, Credit_Hours,
Dept_Name)
VALUES ('MAT 307', 'Probability II', 4,
'Mathematics')

The following INSERT statement uses a SELECT clause to retrieve

from the Student table the ID numbers of students who have taken
classes.
The statement then inserts the ID numbers into the Billing table.
INSERT INTO Billing (Student_ID)
SELECT ID
FROM Student
WHERE Cumulative_Hours > 0

The following example illustrates the use of the CURTIME(),

CURDATE() and NOW() variables to insert the current local date,
time and timestamp values inside an INSERT statement.
CREATE TABLE Timetbl (c1 TIME, c2 DATE, c3 TIMESTAMP)
INSERT INTO Timetbl(c1, c2, c3) VALUES(CURTIME(),
CURDATE(), NOW())

The following examples demonstrate basic usage of default values

with INSERT and UPDATE statements.
CREATE
'abc')
INSERT
INSERT
INSERT
INSERT
INSERT

TABLE t1 (c1 INT DEFAULT 10, c2 CHAR(10) DEFAULT

INTO
INTO
INTO
INTO
INTO

t1
t1
t1
t1
t1

DEFAULT VALUES
(c2) VALUES (DEFAULT)
VALUES (100, DEFAULT)
VALUES (DEFAULT, 'bcd')
VALUES (DEFAULT, DEFAULT)

SELECT * FROM t1
c1
c2
---------- ---------10
abc
10
abc
100
abc

3-169

SQL Syntax Reference

10
10

bcd
abc

UPDATE t1 SET c1 = DEFAULT WHERE c1 = 100

UPDATE t1 SET c2 = DEFAULT WHERE c2 = 'bcd'
UPDATE t1 SET c1 = DEFAULT, c2 = DEFAULT
SELECT * FROM t1
c1
c2
---------- ---------10
abc
10
abc
10
abc
10
abc
10
abc

Based on the CREATE TABLE statement immediately above, the

following two INSERT statements are equivalent.
INSERT INTO t1 (c1,c2) VALUES (20,DEFAULT)
INSERT INTO t1 (c1) VALUES (20)

The following SQL code shows the use of DEFAULT with multiple
UPDATE values.
CREATE TABLE t2 (c1 INT DEFAULT 10,
c2 INT DEFAULT 20 NOT NULL,
c3 INT DEFAULT 100 NOT NULL)
INSERT INTO t2 VALUES (1, 1, 1)
INSERT INTO t2 VALUES (2, 2, 2)
SELECT * FROM t2
c1
c2
---------- ---------1
1
2
2

c3
---------1
2

UPDATE t2 SET c1 = DEFAULT,

c2 = DEFAULT,
c3 = DEFAULT
WHERE c2 = 2

3-170

Grammar Statements
SELECT * FROM t2
c1
c2
---------- ---------1
1
10
20

c3
---------1
100

Incorrect Examples of DEFAULT

The following examples show possible error conditions because a

column is defined as NOT NULL and with no default value defined:
CREATE TABLE t1 (c1 INT DEFAULT 10,
c2 INT NOT NULL,
c3 INT DEFAULT 100 NOT NULL)
INSERT INTO t1 DEFAULT VALUES
-- Error: No default value assigned for column <c2>.

INSERT INTO t1 VALUES (DEFAULT, DEFAULT, 10)

-- Error: No default value assigned for column <c2>.

INSERT INTO t1 (c1,c2,c3) VALUES (1, DEFAULT, DEFAULT)

-- Error: No default value assigned for column <c2>.

INSERT INTO t1 (c1,c3) VALUES (1, 10)

-- Error: Column <c2> not nullable.

The following example shows what occurs when you use INSERT for
IDENTITY columns and columns with default values.
CREATE
INSERT
INSERT
INSERT
INSERT
INSERT
SELECT

TABLE t (id IDENTITY, c1 INTEGER DEFAULT 100)

INTO t (id) VALUES (0)
INTO t VALUES (0,1)
INTO t VALUES (10,10)
INTO t VALUES (0,2)
INTO t (c1) VALUES (3)
* FROM t

The SELECT shows the table contains the following rows:

1, 100
2, 1
10, 10
11, 2
12, 3

The first row illustrates that if 0 is specified in the VALUES clause

for an IDENTITY column, then the value inserted is 1 if the table
is empty.

3-171

SQL Syntax Reference

The first row also illustrates that if no value is specified in the

VALUES clause for a column with a default value, then the specified
default value is inserted.
The second row illustrates that if 0 is specified in the VALUES
clause for an IDENTITY column, then the value inserted is one
greater than the largest value in the IDENTITY column.
The second row also illustrates that if a value is specified in the
VALUES clause for a column with a default value, then the specified
value overrides the default value.
The third row illustrates that if a value other than 0 is specified in
the VALUES clause for an IDENTITY column, then that value is
inserted. If a row already exists that contains the specified value for
the IDENTITY column, then the message The record has a key field
containing a duplicate value(Btrieve Error 5) is returned and the
INSERT fails.
The fourth rows shows again that if 0 is specified in the VALUES
clause for an IDENTITY column, then the value inserted is one
greater than the largest value in the IDENTITY column. This is true
even if gaps exist between the values (that is, the absence of one or
more rows with IDENTITY column values less than the largest
value).
The fifth row illustrates that if no value is specified in the VALUES
clause for an IDENTITY column, then the value inserted is one
greater than the largest value in the IDENTITY column.
See Also

CREATE TABLE on page 3-80

DEFAULT on page 3-116
SELECT on page 3-202
SET ANSI_PADDING on page 3-228

3-172

Grammar Statements

JOIN
You can specify a single table or view, multiple tables, or a single view
and multiple tables. When you specify more than one table, the
tables are said to be joined.
Syntax

join-definition ::= table-reference [ join-type ] JOIN table-reference ON searchcondition

| table-reference CROSS JOIN table-reference

| outer-join-definition
join-type ::= INNER | LEFT [ OUTER ] | RIGHT [ OUTER ] | FULL

[ OUTER ]
outer-join-definition ::= table-reference outer-join-type JOIN table-reference
ON search-condition
outer-join-type ::= LEFT [ OUTER ] | RIGHT [ OUTER ] | FULL [

OUTER ]

The following example illustrates a two-table outer join:

SELECT * FROM Person LEFT OUTER JOIN Faculty ON Person.ID
= Faculty.ID

The following example shows an outer join embedded in a vendor

string. The OJ can be either upper or lower case.
SELECT t1.deptno, ename FROM {OJ emp t2 LEFT OUTER JOIN
dept t1 ON t2.deptno=t1.deptno}

Pervasive PSQL supports two-table outer joins as specified in the

Microsoft ODBC Programmers Reference.
In addition to simple two-table outer joins, Pervasive PSQL supports
n-way nested outer joins.
The outer join may or may not be embedded in a vendor string. If a
vendor string is used, Pervasive PSQL strips it off and parses the
actual outer join text.
LEFT OUTER

The Pervasive PSQL database engine has implemented LEFT

OUTER JOIN using SQL92 (SQL2) as a model. The syntax is a
subset of the entire SQL92 syntax which includes cross joins, right
outer joins, full outer joins, and inner joins. The TableRefList below
occurs after the FROM keyword in a SELECT statement and before

3-173

SQL Syntax Reference

any subsequent WHERE, HAVING, and other clauses. Note the

recursive nature of TableRef and LeftOuterJoina TableRef can be a
left outer join that can include TableRefs which, in turn, can be left
outer joins and so forth.
TableRefList :
TableRef [, TableRefList]
| TableRef
| OuterJoinVendorString [, TableRefList]
TableRef :
TableName [CorrelationName]
| LeftOuterJoin
| ( LeftOuterJoin )
LeftOuterJoin :
TableRef LEFT OUTER JOIN TableRef ON SearchCond

The search condition (SearchCond) contains join conditions which

in their usual form are LT.ColumnName = RT.ColumnName, where
LT is left table, RT is right table, and ColumnName represents some
column within a given domain. Each predicate in the search
condition must contain some non-literal expression.
The implementation of left outer join goes beyond the syntax in the
Microsoft ODBC Programmers Reference.
Vendor Strings

The syntax in the previous section includes but goes beyond the
ODBC syntax in the Microsoft ODBC Programmers Reference.
Furthermore, the vendor string escape sequence at the beginning
and end of the left outer join does not change the core syntax of the
outer join.
The Pervasive PSQL database engine accepts outer join syntax
without the vendor strings. However, for applications that want to
comply with ODBC across multiple databases, the vendor string
construction should be used. Because ODBC vendor string outer
joins do not support more than two tables, it may be necessary to use
the syntax shown following Table 3-13 on page 3-175.
Examples

3-174

The following four tables are used in the examples in this section.

Grammar Statements

Table 3-10 Emp Table

FirstName

LastName

DeptID

EmpID

Franky

Avalon

D103

Gordon

Lightfoot

D102

Lawrence

Welk

D101

Bruce

Cockburn

D102

Table 3-11 Dept Table

DeptID

LocID

Name

D101

D102

Folk

Table 3-12 Addr Table

EmpID

Street

101 Mem Lane

14 Young St.

Table 3-13 Loc Table

LocID

Name

PlanetX

PlanetY

The following example shows a simple two-way Left Outer Join:

SELECT * FROM Emp LEFT OUTER JOIN Dept ON Emp.DeptID =
Dept.DeptID

This two-way outer join produces the following result set:

3-175

SQL Syntax Reference

Table 3-14 Two-way Left Outer Join

Emp

Dept

FirstName

LastName

DeptID

EmpID

DeptID

LocID

Name

Franky

Avalon

D103

NULL

Gordon

Lightfoot

D102

Folk

Lawrence

Welk

D101

Bruce

Cockburn

D102

Folk

Notice the NULL entry for Franky Avalon in the table. That is
because no DeptID of D103 was found in the Dept table. In a
standard (INNER) join, Franky Avalon would have been dropped
from the result set altogether.
Algorithm

The algorithm that the Pervasive PSQL Engine uses for the previous
example is as follows:
taking the left table, traverse the right table, and for every case where
the ON condition is TRUE for the current right table row, return a
result set row composed of the appropriate right table row appended
to the current left-table row.
If there is no right table row where the ON condition is TRUE, (it is
FALSE for all right table rows given the current left table row), create
a row instance of the right table with all column values NULL.
That result set, combined with the current left-table row for each
row, is indexed in the returned result set. The algorithm is repeated
for every left table row to build the complete result set. In the simple
two-way left outer join shown previously, Emp is the left table and
Dept is the right table.

3-176

Grammar Statements

Note Although irrelevant to the algorithm, the appending of the

left table to the right table assumes proper projection as specified

in the select list of the query. This projection ranges from all
columns (for example, SELECT * FROM . . .) to only one
column in the result set (for example, SELECT FirstName
FROM . . .).

With radiating left outer joins, all other tables are joined onto one
central table. In the following example of a three-way radiating left
outer join, Emp is the central table and all joins radiate from that
table.
SELECT * FROM (Emp LEFT OUTER JOIN Dept ON Emp.DeptID =
Dept.DeptID) LEFT OUTER JOIN Addr ON Emp.EmpID =
Addr.EmpID

Table 3-15 Three-way Radiating Left Outer Join

Emp

Dept

Addr

First
Name

Last
Name

Dept
ID

Emp
ID

Dept
ID

Loc
ID

Name

Emp
ID

Street

Franky

Avalon

D103

NUL
L

NULL

101
Mem
Lane

Gordon

Lightfoot

D102

Folk

14
Young St

Lawren
ce

Welk

D101

NUL
L

NULL

Bruce

Cockbur
n

D102

D101

NUL
L

NULL

In a chaining left outer join, one table is joined to another, and that
table, in turn, is joined to another. The following example illustrates
a three-way chaining left outer join:

3-177

SQL Syntax Reference

SELECT * FROM (Emp LEFT OUTER JOIN Dept ON Emp.DeptID =
Dept.DeptID) LEFT OUTER JOIN Loc ON Dept.LocID =
Loc.LocID

Table 3-16 Three-way Chaining Left Outer Join

Emp

Dept

Loc

First
Name

Last
Name

Dept
ID

Emp
ID

Dept
ID

Loc
ID

Name

Loc
ID

Name

Franky

Avalon

D103

NULL

Gordon

Lightfoot

D102

Folk

Planet
Y

Lawrence

Welk

D101

Planet
X

Bruce

Cockbur
n

D102

D101

Planet
X

This join could also be expressed as:

SELECT * FROM Emp LEFT OUTER JOIN (Dept LEFT OUTER JOIN
Loc ON Dept.LocID = Loc.LocID) ON Emp.DeptID =
Dept.DeptID

We recommend the first syntax because it lends itself to both the

radiating and chaining joins. This second syntax cannot be used for
radiating joins because nested left outer join ON conditions cannot
reference columns in tables outside their nesting. In other words, in
the following query, the reference to Emp.EmpID is illegal:
SELECT * FROM Emp LEFT OUTER JOIN (Dept LEFT OUTER JOIN
Addr ON Emp.EmpID = Addr.EmpID) ON Emp.DeptID =
Dept.DeptID

3-178

Grammar Statements

The following example shows a three-way radiating left outer join,

less optimized:
SELECT * FROM Emp E1 LEFT OUTER JOIN Dept ON E1.DeptID =
Dept.DeptID, Emp E2 LEFT OUTER JOIN Addr ON E2.EmpID =
Addr.EmpID WHERE E1.EmpID = E2.EmpID

Table 3-17 Three-way Radiating Left Outer Join, Less Optimized

Emp

Dept

Addr

First
Name

Last
Name

Dept
ID

Emp
ID

Dept
ID

Loc
ID

Name

Emp
ID

Street

Franky

Avalon

D103

NULL

101
Mem
Lane

Gordon

Lightfoot

D102

Folk

14
Young
St

Lawrence

Welk

D101

NULL

Bruce

Cockburn

D102

D101

NULL

This query returns the same results as shown in Table 3-16, assuming
there are no NULL values for EmpID in Emp and EmpID is a unique
valued column. This query, however, is not optimized as well as the
one show for Table 3-16 and can be much slower.
See Also

SELECT on page 3-202

3-179

SQL Syntax Reference

LEAVE
Remarks

A LEAVE statement continues execution by leaving a block or loop

statement. You can use LEAVE statements in the body of a stored
procedure or a trigger.

Examples

The following example increments the variable vInteger by 1 until it

reaches a value of 11, when the loop is ended with a LEAVE
statement.
TestLoop:
LOOP
IF (:vInteger > 10) THEN
LEAVE TestLoop;
END IF;
SET :vInteger = :vInteger + 1;
END LOOP;

See Also

IF on page 3-163
LOOP on page 3-183

3-180

Grammar Statements

LIKE
LIKE allows pattern matching within character-based column data.
Syntax

WHERE expr [ NOT ] LIKE value

Remarks

The value on the right side of a LIKE expression must be a simple

string constant, the USER keyword, or (outside a stored procedure)
a dynamic parameter supplied at runtime, indicated by a question
mark ?. Dynamic parameters are not supported within SQL Editor,
only in application code.
Use the percent sign % in the comparison value as many times as
desired to match zero or more characters in the column values. Use
the underscore _ to match any one character. If you need to match
one of these wildcard symbols as a literal character, use a back slash
in front of the symbol to mark the symbol as a literal character.

Table 3-18 Special Characters

Character

Purpose

Percent sign %

Wildcard: matches zero or more characters.

Underscore _

Wildcard: matches any single character.

Back slash \

Flags the following wildcard character as a literal character, indicating that you want
to match the actual wildcard character itself. To match a back slash, enter two back
slashes. For example, to match %, the pattern should specify \%0.

Two single quotes

Two single quotes without a space in between them must be used to match a single
quote that is part of the result string. For example, if a row in the database contains
the value Jims house, you can match this pattern by specifying LIKE Jims
house in the WHERE clause. A double-quote (") is not a special character within
the pattern string, and can be used like any letter or digit.

Examples

This example matches all column values that are five characters long
and have abc as the middle three characters:
SELECT Building_Name FROM Room WHERE Building_Name LIKE
'_abc_'

This example matches all column values that contain a back slash:
SELECT Building_Name FROM Room where Building_Name LIKE
'%\\%'

3-181

SQL Syntax Reference

This example matches all column values except those that begin with
a percent sign:
SELECT Building_Name FROM Room where Building_Name NOT
LIKE '\%%'

This example matches all column values that contain one or more
single-quotes:
SELECT Building_Name FROM Room where Building_Name LIKE
'%''%'

This example matches all column values where the second character
is a double-quote:
SELECT Building_Name FROM Room where Building_Name LIKE
'_"%'

This example creates a stored procedure that returns any rows where
the Building_Name column contains the characters stored in the
input variable :rname and where the Type column contains the
characters stored in the input variable :rtype.
CREATE PROCEDURE room_test(IN :rname CHAR(20), IN :rtype
CHAR(20))
RETURNS(Building_Name CHAR(25), Type CHAR(20));
BEGIN
DECLARE :like1 CHAR(25);
DECLARE :like2 CHAR(25);
SET :like1 = '%' + :rname + '%';
SET :like2 = '%' + :rtype + '%';
SELECT Building_Name, Type FROM Room WHERE Building_
Name LIKE :like1 AND Type LIKE :like2;
END;

Note that the following statement, if placed in the stored procedure

above, generates a syntax error because of the expression on the right
side of the LIKE operator. The right side must be a simple constant:
Incorrect syntax

SELECT Building_Name, Type from Room where Building_

Name LIKE '%' + :rname + '%';

3-182

Grammar Statements

LOOP
Remarks

A LOOP statement repeats the execution of a block of statements.

This statement is only allowed in stored procedures and triggers.
Pervasive PSQL does not support post-conditional loops
(REPEAT...UNTIL).

Examples

The following example increments the variable vInteger by 1 until it

reaches a value of 11, when the loop is ended.
TestLoop:
LOOP
IF (:vInteger > 10) THEN
LEAVE TestLoop;
END IF;
SET :vInteger = :vInteger + 1;
END LOOP;

See Also

CREATE PROCEDURE on page 3-66

CREATE TRIGGER on page 3-103
IF on page 3-163

3-183

SQL Syntax Reference

NOT
Remarks

Using the NOT keyword with the EXISTS keyword allows you to test
whether rows do not exist in the result of the subquery. For every row
the outer query evaluates, Pervasive PSQL tests for the existence of a
related row from the subquery. Pervasive PSQL excludes from the
statement's result table each row from the outer query that
corresponds to a related row from the subquery.
Including the NOT keyword along with the IN operator allows you
to test whether the result of the outer query is not included in the
result of the subquery. The result table for the statement includes
only rows the outer query returns that do not have a related row from
the subquery.

Examples

The following statement returns a list of students who are not

enrolled in any classes:
SELECT * FROM Person p WHERE NOT EXISTS
(SELECT * FROM Student s WHERE s.id = p.id
AND Cumulative_Hours = 0)

This statement can be rewritten to include IN:

SELECT * FROM Person p WHERE p.id NOT IN
(SELECT s.id FROM Student s WHERE Cumulative_Hours =
0)

See Also

SELECT on page 3-202

EXISTS on page 3-143
IN on page 3-165

3-184

Grammar Statements

OPEN
Remarks

The OPEN statement opens a cursor. A cursor must be defined

before it can be opened.
This statement is allowed only inside of a stored procedure or a
trigger, since cursors and variables are only allowed inside of stored
procedures and triggers.

Syntax

OPEN cursor-name
cursor-name ::= user-defined-name

Examples

The following example opens the declared cursor BTUCursor.

DECLARE BTUCursor CURSOR
FOR SELECT Degree, Residency, Cost_Per_Credit
FROM Tuition
ORDER BY ID;
OPEN BTUCursor;

CREATE PROCEDURE MyProc(IN :CourseName CHAR(7)) AS

BEGIN
DECLARE cursor1 CURSOR
FOR SELECT Degree, Residency, Cost_Per_Credit
FROM Tuition

ORDER BY ID;

OPEN cursor1;
FETCH cursor1 INTO :CourseName;

CLOSE cursor1;

END

See Also

CREATE PROCEDURE on page 3-66

CREATE TRIGGER on page 3-103
DECLARE CURSOR on page 3-114

3-185

SQL Syntax Reference

PARTIAL
Remarks

To allow indexing on CHAR and VARCHAR columns wider than

255 bytes, include the PARTIAL keyword in the CREATE INDEX
statement. If the column(s) that make up the partial index, including
overhead, contain less than 255 bytes, PARTIAL is ignored.
Note The PARTIAL keyword is not required with the DROP

INDEX statement to remove a partial index.

UNIQUE and PARTIAL are mutually exclusive and cannot be used
in the same CREATE INDEX statement.
See Also

CREATE INDEX on page 3-59

DROP INDEX on page 3-133
UNIQUE on page 3-268

3-186

Grammar Statements

PRIMARY KEY
Remarks

Include PRIMARY KEY in the ADD clause to add a primary key to

a table definition. The primary key is a unique index that does not
include null values. When you specify a primary key, Pervasive PSQL
creates a unique index with the specified attributes on the defined
group of columns.
Because a table can have only one primary key, you cannot add a
primary key to a table that already has a primary key defined. To
change the primary key of a table, delete the existing key using a
DROP clause in an ALTER TABLE statement and add the new
primary key.
Note You must be logged in to the database using a database

name before you can add a primary key or conduct any other
referential integrity (RI) operation.
Include PRIMARY KEY in the ADD clause with the ALTER TABLE
statement to add a primary key to a table definition.
Before adding the primary key, you must ensure that the columns in
the primary key column list are defined as NOT NULL. A primary
key is a unique index and can be created only on not nullable
columns.
If a unique index on not nullable columns already exists, the ADD
PRIMARY KEY does not create another unique index. Instead, the
existing unique index is promoted to a primary key. For example, the
following statements would promote the named index T1_C1C2 to
be a primary key.
CREATE TABLE t1 (c1 INT NOT NULL, c2 CHAR(10) NOT NULL)
CREATE UNIQUE INDEX t1_c1c2 ON t1(c1,c2)
ALTER TABLE t1 ADD PRIMARY KEY(c1, c2)

If such a primary key is dropped, the primary key would be switched

to a unique index.
ALTER TABLE t1 DROP PRIMARY KEY

If no unique index on not nullable columns exists in the table, ADD

PRIMARY KEY creates a unique index on not nullable columns.
DROP PRIMARY KEY completely deletes the unique index.

3-187

SQL Syntax Reference

Include a PRIMARY KEY clause with the CREATE TABLE statement

to add a primary key to a table definition.
To define referential constraints on your database, you must include
a PRIMARY KEY clause to specify the primary key on the parent
table. The primary key can consist of one column or multiple
columns but can only be defined on columns that are not null. The
columns you specify must also appear in the column Definitions list
of the CREATE TABLE statement.
When you specify a primary key, Pervasive PSQL creates an index
with the specified attributes on the defined group of columns. If the
columns are not specifically defined as NOT NULL in the CREATE
TABLE statement, Pervasive PSQL forces the columns to be not
nullable. Pervasive PSQL also creates a unique index on the columns.
For example, the following two statements yield the same results:
CREATE TABLE t1 (c1 INT, c2 CHAR(10), PRIMARY KEY(c1,c2))
CREATE TABLE t1 (c1 INT NOT NULL, c2 CHAR(10) NOT NULL,
PRIMARY KEY(c1,c2))

Examples

The following statement defines a primary key on a table called

Faculty. (The ID column is defined as a unique index that does not
include null values.)
ALTER TABLE Faculty ADD PRIMARY KEY (ID)

See Also

ALTER TABLE on page 3-10

CREATE TABLE on page 3-80

3-188

Grammar Statements

PRINT
Remarks

Use PRINT to print variable values or constants. The PRINT

statement applies only to Windows-based platforms. It is ignored on
other operating system platforms.
You can use PRINT only within stored procedures.

Examples

The following example prints the value of the variable :myvar.

PRINT( :myvar );

PRINT 'MYVAR = ' + :myvar;

The following example prints a text string followed by a numeric

value. You must convert a number value to a text string to print the
value.
PRINT 'Students enrolled in History 101: ' +
convert(:int_val, SQL_CHAR);

See Also

CREATE PROCEDURE on page 3-66

3-189

SQL Syntax Reference

PUBLIC
Remarks

You can include the PUBLIC keyword in the FROM clause to revoke
the Create Table right from all the users to whom the right was not
explicitly assigned.
Include a FROM clause to specify the group or user from whom you
are revoking rights. You can specify a single name or a list of names,
or you can include the PUBLIC keyword to revoke access rights from
all users whose rights are not explicitly assigned.

Examples

To assign access rights to all users in the dictionary, include the

PUBLIC keyword to grant the rights to the PUBLIC group, as in the
following example:
GRANT SELECT ON Course TO PUBLIC

This statement assigns the Select right on the Course table to all users
defined in the dictionary. If you later revoke the Select right from the
PUBLIC group, only users who are granted the Select right explicitly
can access the table.
The following statement includes the PUBLIC keyword to grant the
Create Table right to all the users defined in the dictionary:
GRANT CREATETAB TO PUBLIC

See Also

GRANT on page 3-149

REVOKE on page 3-194

3-190

Grammar Statements

RELEASE SAVEPOINT
Use the RELEASE SAVEPOINT statement to delete a savepoint.
Syntax

RELEASE SAVEPOINT savepoint-name

savepoint-name

Remarks

::= user-defined-name

RELEASE, ROLLBACK, and SAVEPOINT and are supported at the

session level (outside of stored procedures) only if AUTOCOMMIT
is off. Otherwise, RELEASE, ROLLBACK, and SAVEPOINT must be
used within a stored procedure.
Any committed statements within a stored procedure are controlled
by the outermost transaction of the calling ODBC application. This
means that, depending on the AUTOCOMMIT mode specified on
SQLSetConnectOption, calling the stored procedure externally from
an ODBC application performs one of two actions. It either commits
automatically (AUTOCOMMIT on, the default) or waits for you to
call SQLTransact with SQL_COMMIT or SQL_ROLLBACK (when
AUTOCOMMIT is set to off).

Examples

The following example sets a SAVEPOINT then checks a condition

to determine whether to ROLLBACK or to RELEASE the
SAVEPOINT.
CREATE PROCEDURE Enroll_student( IN :student ubigint, IN
:classnum INTEGER);
BEGIN
DECLARE :CurrentEnrollment INTEGER;
DECLARE :MaxEnrollment INTEGER;
SAVEPOINT SP1;
INSERT INTO Enrolls VALUES (:student,:classnum,
0.0);
SELECT COUNT(*) INTO :CurrentEnrollment FROM Enrolls
WHERE class_id = :classnum;
SELECT Max_size INTO :MaxEnrollment FROM Class WHERE
ID = :classnum;
IF :CurrentEnrollment >= :MaxEnrollment

3-191

SQL Syntax Reference

THEN
ROLLBACK TO SAVEPOINT SP1;
ELSE
RELEASE SAVEPOINT SP1;
END IF;
END;

Note that COUNT(expression) counts all non-NULL values for an

expression across a predicate. COUNT(*) counts all values,
including NULL values.
See Also

CREATE PROCEDURE on page 3-66

ROLLBACK on page 3-197
SAVEPOINT on page 3-199

3-192

Grammar Statements

RESTRICT
Remarks

If you specify RESTRICT, Pervasive PSQL enforces the DELETE

RESTRICT rule. A user cannot delete a row in the parent table if a
foreign key value refers to it.
If you do not specify a delete rule, Pervasive PSQL applies the
RESTRICT rule by default.

See Also

ALTER TABLE on page 3-10

3-193

SQL Syntax Reference

REVOKE
REVOKE deletes user IDs and removes permissions to specific users
in a secured database. You can use the REVOKE statement to revoke
CREATE TABLE, CREATE VIEW, and CREATE PROCEDURE
privileges.
Syntax

REVOKE CREATETAB | CREATEVIEW | CREATESP FROM public-or-usergroup-name [ , public-or-user-group-name ]...

REVOKE LOGIN FROM user-name [ , user-name ]...
REVOKE permission ON < * | [ TABLE ] table-name [ owner-name ]> |
VIEW view-name | PROCEDURE stored_procedure-name > FROM user-orgroup-name [ , user-or-group-name ]...
* ::= all of the objects (that is, all tables, views and
stored procedures)
permission ::=

ALL

| SELECT [ ( column-name [ , column-name ]... ) ]

| UPDATE [ ( column-name [ , column-name ]... ) ]
| INSERT [ ( column-name [ , column-name ]... ) ]
| DELETE
| ALTER
| REFERENCES
| EXECUTE
table-name ::= user-defined table-name
view-name ::= user-defined view-name
stored-procedure-name ::= user-defined stored_procedure-name
public-or-user-group-name ::= PUBLIC | user-group-name
user-group-name ::= user-name | group-name
user-name ::= user-defined user-name
group-name ::= user-defined group-name

3-194

Grammar Statements

The following table shows the syntax for a given action:

To REVOKE Privileges For This Action

Use This Syntax with REVOKE

CREATE TABLE

CREATETAB

CREATE VIEW

CREATEVIEW

CREATE PROCEDURE

CREATESP

The following table shows which permissions are removed if you use
the ALL key word.
Table 3-19 Permissions Removed with ALL Key Word by Object Type
Permission Removed
by ALL

Table

View

ALTER

DELETE

INSERT

REFERENCES

SELECT

UPDATE

Stored Procedure

EXECUTE

Examples

The following statement revokes all these privileges from dannyd for
table Class.
REVOKE ALL ON Class FROM 'dannyd'

The following statement revokes all privileges from dannyd and

travisk for table Class.
REVOKE ALL ON Class FROM dannyd, travisk

The following statement revokes DELETE privileges from dannyd

and travisk for table Class.
REVOKE DELETE ON Class FROM dannyd, travisk

3-195

SQL Syntax Reference

The following example revokes INSERT rights from keithv and

miked for table Class.
REVOKE INSERT ON Class FROM keithv, miked

The following example revokes INSERT rights from keithv and

brendanb for table Person and columns First_name and Last_name.
REVOKE INSERT(First_name,Last_name) ON Person FROM
keithv, brendanb

The following statement revokes ALTER rights from dannyd from

table Class.
REVOKE ALTER ON Class FROM dannyd

The following example revokes SELECT rights from dannyd and

travisk on table Class.
REVOKE SELECT ON Class FROM dannyd, travisk

The following statement revokes SELECT rights from dannyd and

travisk in table Person for columns First_name and Last_name.
REVOKE SELECT(First_name, Last_name) ON Person FROM
dannyd, travisk

The following example revokes UPDATE rights from dannyd and

travisk for table Person.
REVOKE UPDATE ON Person ON dannyd, travisk

The following example revokes CREATE VIEW privileges from

user1.
REVOKE CREATEVIEW FROM user1;

The following example revokes EXECUTE permissions for user1

pertaining to stored procedure MyProc1.
REVOKE EXECUTE ON PROCEDURE MyProc1 FROM user1;

See Also

3-196

GRANT on page 3-149

Grammar Statements

ROLLBACK
ROLLBACK returns the database to the state it was in before the
current transaction began. This statement releases the locks acquired
since the last SAVEPOINT or START TRANSACTION.
The ROLLBACK TO SAVEPOINT statement rolls back the
transaction to the specified savepoint.
Syntax

ROLLBACK [ WORK ] [ TO SAVEPOINT savepoint-name ]

savepoint-name ::= user-defined-name

Remarks

ROLLBACK, SAVEPOINT, and RELEASE are supported at the

session level (outside of stored procedures) only if AUTOCOMMIT
is off. Otherwise, ROLLBACK, SAVEPOINT, and RELEASE must be
used within a stored procedure.
Any committed statements within a stored procedure are controlled
by the outermost transaction of the calling ODBC application. This
means that, depending on the AUTOCOMMIT mode specified on
SQLSetConnectOption, calling the stored procedure externally from
an ODBC application performs one of two actions. It either commits
automatically (AUTOCOMMIT on, the default) or waits for you to
call SQLTransact with SQL_COMMIT or SQL_ROLLBACK (when
AUTOCOMMIT is set to off).
In the case of nested transactions, ROLLBACK rolls back to the
nearest START TRANSACTION. For example, if transactions are
nested five levels, then five ROLLBACK statements are needed to
undo all of the transactions. A transaction is either committed or
rolled back, but not both. That is, you cannot roll back a committed
transaction.

Examples

The following statement undoes the changes made to the database

since the beginning of a transaction.
ROLLBACK WORK;

The following statement undoes the changes made to the database

since the last savepoint, named Svpt1.
ROLLBACK TO SAVEPOINT Svpt1;

3-197

SQL Syntax Reference

See Also

COMMIT on page 3-44

RELEASE SAVEPOINT on page 3-191
SAVEPOINT on page 3-199

3-198

Grammar Statements

SAVEPOINT
SAVEPOINT defines a point in a transaction to which you can roll
back.
Syntax

SAVEPOINT savepoint-name
savepoint-name ::= user-defined-name

Remarks

ROLLBACK, SAVEPOINT, and RELEASE are supported at the

session level (outside of stored procedures) only if AUTOCOMMIT
is off. Otherwise, ROLLBACK, SAVEPOINT, and RELEASE must be
used within a stored procedure.
Any committed statements within a stored procedure are controlled
by the outermost transaction of the calling ODBC application. This
means that, depending on the AUTOCOMMIT mode specified on
SQLSetConnectOption, calling the stored procedure externally from
an ODBC application performs one of two actions. It either commits
automatically (AUTOCOMMIT on, the default) or waits for you to
call SQLTransact with SQL_COMMIT or SQL_ROLLBACK (when
AUTOCOMMIT is set to off).
A SAVEPOINT applies only to the procedure in which it is defined.
That is, you cannot reference a SAVEPOINT defined in another
procedure.

Examples

The following example sets a SAVEPOINT then checks a condition

to determine whether to ROLLBACK or to RELEASE the
SAVEPOINT.
CREATE PROCEDURE Enroll_student( IN :student ubigint, IN
:classnum INTEGER);
BEGIN
DECLARE :CurrentEnrollment INTEGER;
DECLARE :MaxEnrollment INTEGER;
SAVEPOINT SP1;
INSERT INTO Enrolls VALUES (:student, :classnum,
0.0);
SELECT COUNT(*) INTO :CurrentEnrollment FROM Enrolls
WHERE class_id = :classnum;
SELECT Max_size INTO :MaxEnrollment FROM Class WHERE
ID = :classnum;
IF :CurrentEnrollment >= :MaxEnrollment

3-199

SQL Syntax Reference

THEN
ROLLBACK TO SAVEPOINT SP1;
ELSE
RELEASE SAVEPOINT SP1;
END IF;
END;

Note that COUNT(expression) counts all non-NULL values for an

expression across a predicate. COUNT(*) counts all values,
including NULL values.
See Also

COMMIT on page 3-44

CREATE PROCEDURE on page 3-66
RELEASE SAVEPOINT on page 3-191
ROLLBACK on page 3-197

3-200

Grammar Statements

SELECT (with into)

The SELECT (with INTO) statement allows you to select column
values from a specified table to insert into variables or to populate a
temporary table with data.
Syntax

SELECT [ ALL | DISTINCT ] [ top-clause ] select-list

temp-table-name [ , variable ]...
FROM table-reference [ , table-reference ]... [ WHERE
[ GROUP BY expression [ , expression ]...[ HAVING
[ ORDER BY order-by-expression [ , order-by-expression

INTO variable |
search-condition ]
search-condition ]

]... ] ]

variable ::= user-defined-name

temp-table-name ::= user-defined-name of a temporary table

For the remaining syntax definitions, see SELECT on page 3-202.

Remarks

The variables must occur within a stored procedure, a trigger, or a

user-defined function.
You can populate a temporary table by using SELECT INTO only if
the SELECT INTO statement occurs outside of a user-defined
function or trigger. Populating, or creating, a temporary table with
SELECT INTO is not permitted within a user-defined function or
trigger.
SELECT INTO is permitted within a stored procedure.
Only a single temporary table can be created and populated with a
SELECT INTO statement. A single SELECT INTO statement cannot
create and populate multiple temporary tables.

Examples

See the examples for CREATE (temporary) TABLE on page 3-93

for how to use SELECT INTO to populate temporary tables.
The following example assigns into variables :x, :y the values of first_
name and last_name in the Person table where first name is Bill.
SELECT first_name, last_name INTO :x, :y FROM person
WHERE first_name = 'Bill'

See Also

CREATE FUNCTION on page 3-51

CREATE PROCEDURE on page 3-66
CREATE (temporary) TABLE on page 3-93

3-201

SQL Syntax Reference

SELECT
Retrieves specified information from a database. A SELECT
statement creates a temporary view.
Syntax

query-specification [ [ UNION [ ALL ] query-specification ]...

[ ORDER BY order-by-expression [ , order-by-expression ]... ] [ FOR
UPDATE ]
query-specification ::= ( query-specification )

| SELECT [ ALL | DISTINCT ] [ top-clause ] select-list

FROM table-reference [ , table-reference ]...
[ WHERE search-condition ]
[ GROUP BY expression [ , expression ]...
[ HAVING search-condition ] ]
order-by-expression ::= expression [ CASE (string) | COLLATE collationname ] [ ASC | DESC ]
top-clause ::= TOP number
select-list ::= * | select-item [ , select-item ]...
select-item ::= expression [ [ AS ] alias-name ] | table-name . *
table-reference ::= { OJ outer-join-definition }

| [db-name.]table-name [ [ AS ] alias-name ] [ WITH (table-hint ) ]

| [db-name.]view-name [ [ AS ] alias-name ]
| join-definition
| ( join-definition )
| ( table-subquery )[ AS ] alias-name [ (column-name [ , column-name
]... ) ]
outer-join-definition ::= table-reference outer-join-type JOIN table-reference
ON search-condition
outer-join-type ::= LEFT [ OUTER ] | RIGHT [ OUTER ] | FULL [

OUTER ]
table-hint ::= INDEX ( index-value [ , index-value ]... )
index-value ::= 0 | index-name
index-name

3-202

::= user-defined-name

Grammar Statements
join-definition ::= table-reference [ join-type ] JOIN table-reference ON searchcondition

| table-reference CROSS JOIN table-reference

| outer-join-definition
join-type ::= INNER | LEFT [ OUTER ] | RIGHT [ OUTER ] | FULL

[ OUTER ]
table-subquery ::= query-specification [ [ UNION [ ALL ]
query-specification ]... ]
search-condition ::= search-condition AND search-condition

| search-condition OR search-condition
| NOT search-condition
| ( search-condition )
| predicate
predicate ::= expression [ NOT ] BETWEEN expression AND expression

| expression-or-subquery comparison-operator expression-or-subquery

| expression [ NOT ] IN ( query-specification )
| expression [ NOT ] IN ( value [ , value ]... )
| expression [ NOT ] LIKE value
| expression

IS [ NOT ] NULL

| expression comparison-operator ANY ( query-specification )

| expression comparison-operator ALL ( query-specification )
| [ NOT ] EXISTS ( query-specification )
comparison-operator ::= < | > | <= | >= | = | <> | !=
expression-or-subquery ::= expression | ( query-specification )
value ::= literal | USER | ?
expression ::= expression - expression

3-203

SQL Syntax Reference

| +expression
| column-name
| ?
| literal
| set-function
| scalar-function
| { fn scalar-function }
| CASE case_value_expression WHEN when_expression THEN then_expression
[...] [ ELSE else_expression ] END
| COALESCE (expression, expression[,...])
| IF ( search-condition , expression , expression )
| SQLSTATE
| subquery-expression
| NULL
| : user-defined-name
| USER
| @:IDENTITY
| @:ROWCOUNT
| @@IDENTITY
| @@ROWCOUNT
| @@SPID
case_value_expression when_expression, then_expression

else_expression ::=

CASE (expression) on page 3-34

subquery-expression ::= ( query-specification )
set-function ::= COUNT (*)

| COUNT ( [ DISTINCT | ALL ] expression )

3-204

see Scalar Functions on page 5-1

see

Grammar Statements

Remarks

This Remarks section contains the following topics:

FOR UPDATE on page 3-205

GROUP BY on page 3-206
Use of Aliases on page 3-207
SUM and DECIMAL Precision on page 3-207
Subqueries on page 3-207
Table Hint on page 3-210

FOR UPDATE
SELECT FOR UPDATE locks the row or rows within the table that is
selected by the query. The record locks are released when the next
COMMIT or ROLLBACK statement is issued.
To avoid contention, SELECT FOR UPDATE locks the rows as they
are retrieved.
SELECT FOR UPDATE takes precedence within a transactions if
statement level SQL_ATTR_CONCURRENCY is set to SQL_
CONCUR_LOCK. If SQL_ATTR_CONCURRENCY is set to SQL_
CONCUR_READ_ONLY, the database engine does not return an
error.
SELECT FOR UPDATE does not support a WAIT or NOWAIT key
word. SELECT FOR UPDATE returns status code 84: The record or
page is locked if it cannot lock the rows within a brief period (20 retries).
Constraints

The SELECT FOR UPDATE statement has the following constraints:

Is valid only within a transaction. The statement is ignored if

used outside of a transaction.
Is supported only for a single table. You cannot use SELECT
FOR UPDATE with JOINs, non-simple views, or the GROUP
BY, DISTINCT, or UNION key words.
Is not supported within a CREATE VIEW statement.

3-205

SQL Syntax Reference

Note If SELECT FOR UPDATE is used outside of a stored

procedure, you must first specify the SQL_AUTOCOMMIT_

OFF attribute for SQLSetConnectOption or for
SQLSetConnectAttr.

GROUP BY
In addition to supporting a GROUP BY on a column-list, Pervasive
PSQL supports a GROUP BY on an expression-list or on any
expression in a GROUP BY expression-list. See GROUP BY on
page 3-160 for more information on GROUP BY extensions.
HAVING is not supported without GROUP BY.
Result sets and stored views generated by executing SELECT
statements with any of the following characteristics are read-only
(they cannot be updated). That is, a positioned UPDATE, a
positioned DELETE and an SQLSetPos call to add, alter or delete
data is not allowed on the result set or stored view if:

SQL_CONCUR_READ_ONLY was specified as the SQL_

CONCURRENCY type via SQLSetStmtOption
The selection-list contains an aggregate:
SELECT SUM(c1) FROM t1

The selection-list specifies DISTINCT:

SELECT DISTINCT c1 FROM t1

The view contains a GROUP BY clause:

SELECT SUM(c1), c2 FROM t1 GROUP BY c2

The view is a join (references multiple tables):

SELECT * FROM t1, t2

The view uses the UNION operator and UNION ALL is not
specified or all SELECT statements do not reference the same
table:
SELECT c1 FROM t1 UNION SELECT c1 FROM t1
SELECT c1 FROM t1 UNION ALL SELECT c1 FROM t2

Note that stored views do not allow the UNION operator.

The view contains a subquery that references a table other than
the table in the outer query:

SELECT c1 FROM t1 WHERE c1 IN (SELECT c1 FROM t2)

3-206

Grammar Statements

Dynamic parameters (?) are not supported as SELECT items. You

may use dynamic parameters in any SELECT statement if the
dynamic parameter is part of the predicate. For example, SELECT *
FROM faculty WHERE id = ? is valid because the dynamic
parameter is part of the predicate.
Note that the SQLExecDirect statement does not support the use of
dynamic parameters. For this reason, you cannot use SQL Editor to
execute an SQL statement with a dynamic parameter in the
predicate. (SQL Editor uses SQLExecDirect.)
You may use variables as SELECT items only within stored
procedures. See CREATE PROCEDURE on page 3-66.
Use of Aliases
Aliases may appear in a WHERE, HAVING, ORDER BY, or GROUP
BY clause. Alias names must differ from any column names within
the table. The following statement shows the use of aliases, a and
b, in a WHERE clause and in a GROUP BY clause.
SELECT Student_ID a, Transaction_Number b, SUM (Amount_
Owed) FROM Billing WHERE a < 120492810 GROUP BY a, b
UNION SELECT Student_ID a, Transaction_Number b, SUM
(Amount_Paid) FROM Billing WHERE a > 888888888 GROUP BY
a, b

SUM and DECIMAL Precision

When using the SUM aggregate function to sum a field that is of type
DECIMAL, the following rules apply:
The precision of the result is 74, while the scale is dependent on the
column definition.
The result may cause an overflow error if a number with precision
greater than 74 is calculated (a very large number indeed). If an
overflow occurs, no value is returned, and SQLSTATE is set to 22003,
indicating a numeric value is out of range.
Subqueries
A subquery is a SELECT statement with one or more SELECT
statements within it. A subquery produces values for further
processing within the statement. The maximum number of nested
subqueries allowed within the topmost SELECT statement is 16.

3-207

SQL Syntax Reference

The following types of subqueries are supported:

comparison
quantified
in
exists
correlated
expression

ORDER BY clauses are not allowed in a subquery clause.

Correlated subquery predicates in the HAVING clause which
contain references to grouped columns are not supported.
Expression subqueries allow the subquery within the SELECT list.
For example, SELECT (SELECT SUM(c1) FROM t1 WHERE t1.c2 =
t1.(c2) FROM t2. Only one item is allowed in the subquery SELECT
list. For example, the following statement returns an error because
the subquery SELECT list contains more than one item: SELECT
p.id, (SELECT SUM(b.amount_owed), SUM(b.amount_paid)
FROM billing b) FROM person p.
A subquery as an expression may be correlated or non-correlated. A
correlated subquery references one or more columns in any of the
tables in the topmost statement. A non-correlated subquery
references no columns in any of the tables in the topmost statement.
A subquery connected with the operators IN, EXISTS, ALL, or ANY
is not considered an expression.
Both correlated and non-correlated subqueries can return only a
single value. For this reason, both correlated and non-correlated
subqueries are also referred to as scalar subqueries.
Scalar subqueries may appear in the DISTINCT, GROUP BY, and
ORDER BY clause.
You may use a subquery on the left-hand side of an expression:
Expr-or-SubQuery CompareOp Expr-or-SubQuery

3-208

Grammar Statements

where Expr is an expression, and CompareOp is one of:

<
(less than)

>
(greater than)

<=
(less than or
equal to)

>=
(greater than
or equal to)

=
(equals)

<>
(not equal)

!=
(not equal)

NOT IN

Optimization

Left-hand subquery behavior has been optimized for IN, NOT IN,
and =ANY in cases where the subquery is not correlated and any join
condition is an outer join. Other conditions may not be optimized.
Here is an example of a query that meets these conditions:
SELECT count(*) FROM person WHERE id IN
(SELECT faculty_id FROM class)

Performance improves if you use an index in the subquery because

Pervasive PSQL optimizes a subquery based on the index. For
example, the subquery in the following statement is optimized on
student_id because it is an index in the Billing table:
SELECT (SELECT SUM(b.amount_owed) FROM billing b WHERE
b.student_id = p.id) FROM person p

UNION in Subquery

Parentheses on different UNION groups within a subquery are not

allowed. Parentheses are allowed within each SELECT statement.
For example, the parenthesis following IN and the last parenthesis
are not allowed the following statement:
SELECT c1 FROM t5 WHERE c1 IN ( (SELECT c1 FROM t1 UNION
SELECT c1 FROM t2) UNION ALL (SELECT c1 FROM t3 UNION
SELECT c1 from t4) )

Table Subqueries

Table subqueries can be used to combine multiple queries into one

detailed query. A table subquery is a dynamic view, which is not
persisted in the database. When the topmost SELECT query
completes, all resources associated with table subqueries are released.

3-209

SQL Syntax Reference

Table Hint
The table hint functionality allows you to specify which index, or
indexes, to use for query optimization. A table hint overrides the
default query optimizer used by the database engine.
If the table hint specifies INDEX(0), the engine performs a table scan
of the associated table. (A table scan reads each row in the table
rather than using an index to locate a specific data element.)
If the table hint specifies INDEX(index-name), the engine uses
index-name to optimize the table based on restrictions of any JOIN
conditions, or based on the use of DISTINCT, GROUP BY, or
ORDER BY. If the table cannot be optimized on the specified index,
the engine attempts to optimize the table based on any existing
index.
If you specify multiple index names, the engine chooses the index
that provides optimal performance or uses the multiple indexes for
OR optimization. An example helps clarify this. Suppose that you
have the following:
CREATE
CREATE
CREATE
SELECT
AND

INDEX ndx1 on t1(c1)

INDEX ndx2 on t1(c2)
INDEX ndx3 on t1(c3)
* FROM t1 WITH (INDEX (ndx1, ndx2)) WHERE c1 = 1
c2 > 1 AND c3 = 1

The database engine uses ndx1 to optimize on c1 = 1 rather than

using ndx2 for optimization. Ndx3 is not considered because the
table hint does not include ndx3.
Now consider the following:
SELECT * FROM t1 WITH (INDEX (ndx1, ndx2)) WHERE (c1 = 1
OR c2 > 1) AND c3 = 1

The engine uses both ndx1 and ndx2 to optimize on (c1 = 1 OR c2 >
1).
The order in which the multiple index names appear in the table hint
does not matter. The database engine chooses from the specified
indexes the one(s) that provides for the best optimization.
Duplicate index names within the table hint are ignored.

3-210

Grammar Statements

Note The table hint functionality is intended for advanced users.

Typically, table hints are not required because the database query
optimizer usually picks the best optimization method.
Restrictions

The maximum number of index names that can be used in a

table hint is limited only by the maximum length of an SQL
statement (64 KB).
The index name within a table hint must not be fully qualified
with the table name.

Incorrect SQL:

SELECT * FROM t1 WITH (INDEX(t1.ndx1)) WHERE t1.c1 = 1

Returns:

SQL_ERROR

szSqlState:

37000

Message:

Syntax Error: SELECT * FROM t1 WITH (INDEX(t1.<< ???

>>ndx1)) WHERE t1.c1 = 1

Table hints are ignored if they are used in a SELECT statement

with a view.

Incorrect SQL:

SELECT * FROM myt1view WITH (INDEX(ndx1))

Returns:

SQL_SUCCESS_WITH_INFO

szSqlState:

01000

Message:

Index hints supplied with views will be ignored

Zero is the only valid hint that is not an index name.

Incorrect SQL:

SELECT * FROM t1 WITH (INDEX(85))

Returns:

SQL_ERROR

szSqlState:

S1000

Message:

Invalid index hint

3-211

SQL Syntax Reference

Incorrect SQL:

SELECT * FROM t1 WITH (INDEX(ndx4))

Returns:

SQL_ERROR

szSqlState:

S0012

Message:

Invalid index name; index not found

Examples

The index name in a table hint must specify an existing index.

A table hint cannot be specified on a subquery AS table.

Incorrect SQL:

SELECT * FROM (SELECT c1, c2 FROM t1 WHERE c1 = 1) AS

a WITH (INDEX(ndx2)) WHERE a.c2 = 10

Returns:

SQL_ERROR

szSqlState:

37000

Message:

syntax Error: SELECT * FROM (SELECT c1, c2 FROM t1

WHERE c1 = 1) AS a WITH<< ??? >>(INDEX(ndx2)) WHERE
a.c2 = 10

This simple SELECT statement retrieves all the data from the Faculty
table.
SELECT * FROM Faculty

This statement retrieves the data from the person and the faculty
table where the id column in the person table is the same as the id
column in the faculty table.
SELECT Person.id, Faculty.salary FROM Person, Faculty
WHERE Person.id = Faculty.id

The following example retrieves student_id and sum of the amount_

paid where it is greater than or equal to 100 from the billing table. It
then groups the records by student_id.
SELECT Student_ID, SUM(Amount_Paid)
FROM Billing
GROUP BY Student_ID
HAVING SUM(Amount_Paid) >=100.00

If the expression is a positive integer literal, then that literal is

interpreted as the number of the column in the result set and

3-212

Grammar Statements

ordering is done on that column. No ordering is allowed on set

functions or an expression that contains a set function.

FOR UPDATE
The following example uses table t1 to demonstrate the use of FOR
UPDATE. Assume that t1 is part of the DEMODATA sample
database. The stored procedure creates a cursor for the SELECT FOR
UPDATE statement. A loop fetches each record from t1 and, for
those rows where c1=2, sets the value of c1 to four.
The procedure is called by passing the value 2 as the IN parameter.
The example assumes that two users, A and B, are logged in to
DEMODATA. User A performs the following:
DROP TABLE t1
CREATE TABLE t1 (c1 INTEGER, c2 INTEGER)
INSERT INTO t1 VALUES (1,1)
INSERT INTO t1 VALUES (2,1)
INSERT INTO t1 VALUES (1,1)
INSERT INTO t1 VALUES (2,1)
CREATE PROCEDURE p1 (IN :a INTEGER)
AS
BEGIN
DECLARE :b INTEGER;
DECLARE :i INTEGER;
DECLARE c1Bulk CURSOR FOR SELECT * FROM t1 WHERE
c1 = :a FOR UPDATE;
START TRANSACTION;
OPEN c1Bulk;
BulkLinesLoop:
LOOP
FETCH NEXT FROM c1Bulk INTO :i;
IF SQLSTATE = '02000' THEN
LEAVE BulkLinesLoop;
END IF;
UPDATE SET c1 = 4 WHERE CURRENT OF c1Bulk;
END LOOP;
CLOSE c1Bulk;

3-213

SQL Syntax Reference

SET :b = 0;
WHILE (:b < 100000) do
BEGIN
SET :b = :b + 1;
END;
END WHILE;
COMMIT WORK;
END;
CALL p1(2)

Notice that a WHILE loop delays the COMMIT of the transaction.

During that delay, assume that User B attempts to update t1 with
call SQLExecDirect UPDATE t1 SET c1=3 WHERE c1=2. A
status code 84 is returned to User B because those rows are locked by
the SELECT FOR UPDATE statement from User A.

The following example uses table t1 to demonstrate how SELECT

FOR UPDATE locks records when the statement is used outside of a
stored procedure. Assume that t1 is part of the DEMODATA sample
database.
The example assumes that two users, A and B, are logged in to
DEMODATA. User A performs the following:
DROP TABLE t1
CREATE TABLE t1 (c1 INTEGER, c2 INTEGER)
INSERT INTO t1 VALUES (1,1)
INSERT INTO t1 VALUES (2,1)
INSERT INTO t1 VALUES (1,1)
INSERT INTO t1 VALUES (2,1)

Call SQLSetConnectAttr with option SQL_AUTOCOMMIT and

attribute SQL_AUTOCOMMIT_OFF.
Call SQLExecDirect SELECT * FROM t1 WHERE c1 = 2 FOR
UPDATE.
The two records where c1 = 2 are locked until User A issues a
COMMIT WORK or ROLLBACK WORK statement.
User B attempts to update t1 with call SQLExecDirect UPDATE
t1 SET c1=3 WHERE c1=2. A status code 84 is returned to User B
because those rows are locked by the SELECT FOR UPDATE
statement from User A.

3-214

Grammar Statements

Now assume that User A issues call SQLEndTran with option SQL_
COMMIT. The two records where c1 = 2 are unlocked.
User B could now issue call SQLExecDirect UPDATE t1 SET
c1=3 WHERE c1=2 and change the values for c1.

approximate-numeric-literal
SELECT * FROM results WHERE quotient =-4.5E-2
INSERT INTO results (quotient) VALUES (+5E7)

between-predicate
The syntax expression1 BETWEEN expression2 and expression3
returns TRUE if expression1 >= expression2 and expression1<=
expression3. FALSE is returned if expression1 >= expression3, or is
expression1 <= expression2.
Expression2 and expression3 may be dynamic parameters (for
example, SELECT * FROM emp WHERE emp_id BETWEEN ? AND ?)
The next example retrieves the first names from the person table
whose ID fall between 10000 and 20000.
SELECT First_name FROM Person WHERE ID BETWEEN 10000 AND
20000

correlation-name
Both table and column correlation names are supported.
The following example selects data from both the person table and
the faculty table using the aliases T1 and T2 to differentiate between
the two tables.
SELECT * FROM Person t1, Faculty t2 WHERE t1.id = t2.id

The correlation name for a table name can also be specified in using
the FROM clause, as seen in the following example.
SELECT a.Name, b.Capacity FROM Class a, Room b
WHERE a.Room_Number = b.Number

3-215

SQL Syntax Reference

exact-numeric-literal
SELECT car_num, price FROM cars WHERE car_num =49042 AND
price=49999.99

in-predicate
This selects the records from table Person table where the first names
are Bill and Roosevelt.
SELECT * FROM Person WHERE First_name IN ('Roosevelt',
'Bill')

set-function
The following example selects the minimum salary from the Faculty
table.
SELECT MIN(salary) FROM Faculty

MIN(expression), MAX(expression), SUM(expression),

AVG(expression), COUNT(*), and COUNT(expression) are
supported.
COUNT(expression) counts all non-NULL values for an expression
across a predicate. COUNT(*) counts all values, including NULL
values.
The following example counts all the rows in q where a+b does not
equal NULL.
SELECT COUNT(a+b) FROM q

date-literal
Date constants may be expressed in SQL statements as a character
string or embedded in a vendor string. SQL_CHAR and the vendor
string representation are treated as a value of type SQL_DATE. This
becomes important when conversions are attempted.
Pervasive PSQL partially supports extended SQL grammar, as
outlined in this function.

3-216

Grammar Statements

The next two statements return all the classes whose start date is after
1995-06-05.
SELECT * FROM Class WHERE Start_Date > '1995-06-05'
SELECT * FROM Class WHERE Start_Date > {d '1995-06-05'}

Pervasive PSQL supports the following date literal format: 'YYYYMM-DD'.

Dates may be in the range of year 0 to 9999.

time-literal
The following two statements retrieve records from the class table
where the start time for the classes is 14:00:00.
SELECT * FROM Class WHERE Start_time = '14:00:00'
SELECT * FROM Class WHERE Start_time = {t '14:00:00'}

Pervasive PSQL supports the following time literal format:

'HH:MM:SS'.
Time constants may be expressed in SQL statements as a character
string or embedded in a vendor string. Character string
representation is treated as a string of type SQL_CHAR and the vendor
string representation as a value of type SQL_TIME.
Pervasive PSQL partially supports extended SQL grammar, as
outlined in this function.

timestamp-literal
Timestamp constants may be expressed in SQL statements as a
character string or embedded in a vendor string. Pervasive PSQL
treats the character string representation as a string of type SQL_CHAR
and the vendor string representation as a value of type SQL_
TIMESTAMP. Pervasive PSQL partially supports extended SQL
grammar, as outlined in this function.
The next two statements retrieve records from the Billing table where
the start day and time for the log is 1996-03-28 at 17:40:49.
SELECT * FROM Billing WHERE log = '1996-03-28
17:40:49.0000000'

3-217

SQL Syntax Reference

SELECT * FROM Billing WHERE log = {ts '1996-03-28
17:40:49.0000000'}

Pervasive PSQL supports the following time literal format: 'YYYYMM-DD HH:MM:SS.SSSSSSS'. Note that Pervasive PSQL ignores
the fractional seconds when processing Timestamp values, but the
MKDE does not.

string-literal
Literal strings are represented as single-quoted strings. If the string
itself contains a single-quote or apostrophe, the character must be
preceded by another single-quote.
SELECT * FROM t1 WHERE c1 = Robertas Restaurant
SELECT STREET FROM address WHERE city LIKE San%

date arithmetic
SELECT * FROM person P, Class C WHERE p.Date_Of_Birth <
' 1973-09-05' AND c.Start_date >{d '1995-05-08'} + 30

Pervasive PSQL supports adding or subtracting an integer from a

date where the integer is the number of days to add or subtract, and
the date is embedded in a vendor string. (This is equivalent to
executing a convert on the date).
You may also subtract one date from another to yield a number of
days.

IF
The IF system scalar function provides conditional execution based
on the truth value of a condition
This expression prints the column header as Prime1 and amount
owed as 2000 where the value of the column amount_owed is 2000
or it prints a 0 if the value of the amount_owed column is not equal
to 2000.
SELECT Student_ID, Amount_Owed,
IF (Amount_Owed = 2000, Amount_Owed, Convert(0, SQL_
DECIMAL)) Prime1

3-218

Grammar Statements
FROM Billing

From table Class, the following example prints the value in the
Section column if the section is equal to 001, else it prints xxx
under column header Prime1
Under column header Prime2, it prints the value in the Section
column if the value of the section column is equal to 002, or else it
prints yyy.
SELECT ID, Name, Section,
IF (Section = '001', Section, 'xxx') Prime1,
IF (Section = '002', Section, 'yyy') Prime2
FROM Class

You can combine header Prime1 and header Prime2 by using nested
IF functions. Under column header Prime, the following query
prints the value of the Section column if the value of the Section
column is equal to 001 or 002. Otherwise, it print xxx.
SELECT ID, Name, Section,
IF (Section = '001', Section, IF(Section = '002',
Section, 'xxx')) Prime
FROM Class

Multi-database Join
When needed, a database name may be prepended to an aliased table
name in the FROM clause, to distinguish among tables from two or
more different databases that are used in a join.
All of the specified databases must be serviced by the same database
engine. They do not need to reside on the same physical volume. The
current database may be secure or non-secure, but all other
databases in the join must be non-secure. With regard to Referential
Integrity, all RI keys must exist within the same database.
Literal database names are not permitted in the select-list or in the
WHERE clause. If you wish to refer to specific columns in the selectlist or in the WHERE clause, you must use an alias for each specified
table. See examples.
Assume two separate databases, accounting and customers, exist
on the same server. You can join tables from the two databases using
table aliases and SQL syntax similar to the following example:

3-219

SQL Syntax Reference

SELECT ord.account, inf.account, ord.balance,
inf.address
FROM accounting.orders ord, customers.info inf
WHERE ord.account = inf.account

In this example, the two separate databases are acctdb and

loandb. The table aliases are a and b, respectively.
SELECT a.loan_number_a, b.account_no, a.current_bal,
b.balance
FROM acctdb.ds500_acct_master b LEFT OUTER JOIN
loandb.ml502_loan_master a ON (a.loan_number_a =
b.loan_number)
WHERE a.current_bal <> (b.balance * -1)
ORDER BY a.loan_number_a

left outer join

The following example shows how to access the Person and
Student tables from the DEMODATA database to obtain the Last
Name, First Initial of the First Name and GPA of students. With the
LEFT OUTER JOIN, all rows in the Person table are fetched (the
table to the left of LEFT OUTER JOIN). Since not all people have
GPAs, some of the columns have NULL values for the results. This is
how outer join works, returning non-matching rows from either
table.
SELECT Last_Name,Left(First_Name,1) AS First_
Initial,Cumulative_GPA AS GPA FROM Person
LEFT OUTER JOIN Student ON Person.ID=Student.ID
ORDER BY Cumulative_GPA DESC, Last_Name

Assume that you want to know everyone with perfectly rounded

GPAs and have them all ordered by the length of their last name.
Using the MOD statement and the LENGTH scalar function, you
can achieve this by adding the following to the query:
WHERE MOD(Cumulative_GPA,1)=0 ORDER BY LENGTH(Last_
Name)

right outer join

The difference between LEFT and RIGHT OUTER JOIN is that all
non matching rows show up for the table defined to the right of

3-220

Grammar Statements

RIGHT OUTER JOIN. Change the query for LEFT OUTER JOIN to
include a RIGHT OUTER JOIN instead. The difference is that the all
non-matching rows from the right table, in this case Student, show
up even if no GPA is present. However, since all rows in the Student
table have GPAs, all rows are fetched.
SELECT Last_Name,Left(First_Name,1) AS First_
Initial,Cumulative_GPA AS GPA FROM Person
RIGHT OUTER JOIN Student ON Person.ID=Student.ID
ORDER BY Cumulative_GPA DESC, Last_Name

Cartesian join
A Cartesian join is the matrix of all possible combinations of the
rows from each of the tables. The number of rows in the Cartesian
product equals the number of rows in the first table times the
number of rows in the second table.
Assume you have the following tables in your database:
Table 3-20 Addr Table
EmpID

Street

101 Mem Lane

14 Young St.

Table 3-21 Loc Table

LocID

Name

PlanetX

PlanetY

The following performs a Cartesian JOIN on these tables:

SELECT * FROM Addr,Loc

This results in the following:

3-221

SQL Syntax Reference

Table 3-22 SELECT Statement with Cartesian JOIN

EmpID

Street

LocID

Name

101 Mem Lane

PlanetX

101 Mem Lane

PlanetY

14 Young St

PlanetX

14 Young St

PlanetY

DISTINCT
You can use DISTINCT with SUM, AVG, COUNT, MIN, and MAX
(but it does not change results with MIN and MAX). DISTINCT
eliminates duplicate values before calculating the sum, average or
count.
Suppose you want to know the salaries for different departments
including the minimum, maximum and salary, and you want to
remove duplicate salaries. The following statement would do this,
excluding the computer science department:
SELECT dept_name, MIN(salary), MAX(salary), AVG(DISTINCT
salary) FROM faculty WHERE dept_name<>'computer science'
GROUP BY dept_name

If you wanted to include duplicate salaries, you would use:

SELECT dept_name, MIN(salary), MAX(salary), AVG(salary)
FROM faculty WHERE dept_name<>'computer science' GROUP
BY dept_name

TOP
You may limit the number of rows returned by a single SELECT
statement by using the keyword TOP in the statement and specifying
a value for the maximum number of rows to return.
The specified number of rows must be a literal positive number. It is
defined as a 32-bit unsigned integer.

3-222

Grammar Statements

A SELECT statement can include both TOP and an ORDER BY

clause. If so, the database engine generates a temporary table and
populates it with the querys entire result set if no index can be used
for the ORDER BY. The rows in the temporary table are ordered as
specified by the ORDER BY clause and the TOP number of rows in
the ordered result set are returned.
Views that contain a TOP clause may be joined with other tables or
views.
The main difference between TOP and SET ROWCOUNT is that
TOP affects only the current statement, while SET ROWCOUNT
affects all subsequent statements issued during the current database
session.
If both SET ROWCOUNT and TOP are applied to a given query, the
query returns a number of rows equal to the lesser of the two values.

Cursor Types and TOP

A SELECT query with a TOP clause used in a cursor implicitly

changes the cursor type under several circumstances. When using
the table below, remember that any SELECT with ORDER BY on an
unindexed column requires a temporary table. If the ORDER BY is
on an indexed column, then a temporary table is not required.
Table 3-23 Effect of TOP Clause on Cursor Types
Original
Cursor Type

Converted to This Type if

SELECT query requires a
temporary table:

Converted to This Type if

SELECT query does not
require a temporary table:

Dynamic

Forward-only

Static

Forward-only

No change

Forward-only

No change

SELECT TOP 10 * FROM person

-- returns 10 rows

SET ROWCOUNT = 5;
SELECT TOP 10 * FROM person;
-- returns 5 rows

SET ROWCOUNT = 12;

SELECT TOP 10 * FROM person ORDER BY id;
-- returns the first 10 rows of the full list ordered by column id.

3-223

SQL Syntax Reference

The following examples show a variety of behaviors when TOP is

used in views, unions, or subqueries.
CREATE VIEW v1 (c1) AS SELECT TOP 10 id FROM person;
CREATE VIEW v2 (d1) AS SELECT TOP 5 c1 FROM v1;
SELECT
SELECT
SELECT
SELECT

* FROM v2 -- returns 5 rows

TOP 10 * FROM v2 -- returns 5 rows
TOP 0 * FROM v2 -- returns 0 rows
TOP 2 * FROM v2 -- returns 2 rows

SELECT TOP 10 id FROM person UNION SELECT TOP 13 faculty_

id FROM class
-- returns 14 rows

SELECT TOP 10 id FROM person UNION ALL SELECT TOP 13

faculty_id FROM class
-- returns 23 rows

SELECT id FROM person WHERE id IN (SELECT TOP 10 faculty_

id from class)
-- returns 4 rows

SELECT id FROM person WHERE id >= any (SELECT TOP 10

faculty_id from class)
-- returns 1493 rows

Incorrect Examples
The following SELECT statements generate error messages, because
the view defined contains a TOP clause, and thus cannot be involved
in a join.
CREATE VIEW v1 (c1) AS SELECT TOP 10 id FROM person
SELECT * FROM v1 INNER JOIN person ON v1.c1 = person.id
-- returns an error message

SELECT * FROM person V v1 ON person.c1 = v1.id

-- returns an error message

SELECT * FROM person, v1

-- returns an error message

Table Subquery

The following example provides the last name of the student and the
amount the student owes for all students with an ID greater than
714662900.

3-224

Grammar Statements
SELECT p_last_name, b_owed FROM
(SELECT id, last_name FROM person) p (p_id, p_last_
name),
(SELECT student_id, SUM (amount_owed) FROM billing
GROUP BY student_id) b (b_id, b_owed)
WHERE p.p_id = b.b_id AND p.p_id > 714662900
ORDER BY p_last_name ASC

Table Hints
The examples for table hints use table t1, t2, or both. You can create
and populate the example tables with the following SQL.
DROP TABLE t1
CREATE TABLE t1 (c1 INTEGER, c2 INTEGER)
INSERT INTO t1 VALUES (1,10)
INSERT INTO t1 VALUES (1,10)
INSERT INTO t1 VALUES (2,20)
INSERT INTO t1 VALUES (2,20)
INSERT INTO t1 VALUES (3,30)
INSERT INTO t1 VALUES (3,30)
CREATE INDEX it1c1 ON t1 (c1)
CREATE INDEX it1c1c2 ON t1 (c1, c2)
CREATE INDEX it1c2 ON t1 (c2)
CREATE INDEX it1c2c1 ON t1 (c2, c1)
DROP TABLE t2
CREATE TABLE t2 (c1 INTEGER, c2 INTEGER)
INSERT INTO t2 VALUES (1,10)
INSERT INTO t2 VALUES (1,10)
INSERT INTO t2 VALUES (2,20)
INSERT INTO t2 VALUES (2,20)
INSERT INTO t2 VALUES (3,30)
INSERT INTO t2 VALUES (3,30)

Note that certain restrictions apply to the use of table hints. See
Restrictions on page 3-211 for SQL examples.

The following example optimizes on index it1c1c2.

SELECT * FROM t1 WITH (INDEX(it1c1c2)) WHERE c1 = 1

Contrast this with the following example, which optimizes on index

it1c1 instead of on it1c2 because the restriction consists only of c1
= 1. If a query specifies an index that cannot be used to optimize the
query, the hint is ignored.

3-225

SQL Syntax Reference

SELECT * FROM t1 WITH (INDEX(it1c2)) WHERE c1 = 1

The following example performs a table scan of table t1.

SELECT * FROM t1 WITH (INDEX(0)) WHERE c1 = 1

The following example optimizes on indexes it1c1c2 and it1c2c1.

SELECT * FROM t1 WITH (INDEX(it1c1c2, it1c2c1)) WHERE c1
= 1 OR c2 = 10

The following example using a table hint in the creation of a view.

When all records are selected from the view, the SELECT statement
optimizes on index it1c1c2.
DROP VIEW v2
CREATE VIEW v2 as SELECT * FROM t1 WITH (INDEX(it1c1c2))
WHERE c1 = 1
SELECT * FROM v2

The following example uses a table hint in a subquery and optimizes

on index it1c1c2.
SELECT * FROM (SELECT c1, c2 FROM t1 WITH
(INDEX(it1c1c2)) WHERE c1 = 1) AS a WHERE a.c2 = 10

The following example optimizes the query based on the c1 = 1

restriction and optimizes the GROUP BY clause based on index
it1c1c2.
SELECT c1, c2, count(*) FROM t1 WHERE c1 = 1 GROUP BY c1,
c2

The following example optimizes on index it1c1 and, unlike the

previous example, optimizes only on the restriction and not on the
GROUP BY clause.
SELECT c1, c2, count(*) FROM t1 WITH (INDEX(it1c1)) WHERE
c1 = 1 GROUP BY c1, c2

Since the GROUP BY clause cannot be optimized using the specified

index, it1c1, the database engine uses a temporary table to process
the GROUP BY.

3-226

Grammar Statements

The following example uses a table hint in a JOIN clause and

optimizes on index it1c1c2.
SELECT * FROM t2 INNER JOIN t1 WITH (INDEX(it1c1c2)) ON
t1.c1 = t2.c1

Contrast this with the following statement, which does not use a
table hint and optimizes on index it1c1.
SELECT * FROM t2 INNER JOIN t1 ON t1.c1 = t2.c1

The following example uses a table hint in a JOIN clause to perform

a table scan of table t1.
SELECT * FROM t2 INNER JOIN t1 WITH (INDEX(0)) ON t1.c1
= t2.c1

Contrast this with the following example which also performs a table
scan of table t1. However, because no JOIN clause is used, the
statement uses a temporary table join.
SELECT * FROM t2, t1 WITH (INDEX(0)) WHERE t1.c1 = t2.c1

See Also

Global Variables on page 3-290

JOIN on page 3-173
SET ROWCOUNT on page 3-249

3-227

SQL Syntax Reference

SET ANSI_PADDING
The SET ANSI_PADDING statement allows the relational interface
to handle CHAR data types padded with NULLs (binary zeros).
CHAR is defined as a character data type of fixed length.
Pervasive PSQL supports two interfaces: transactional and relational.
The transactional interface allows a CHAR to be padded with
NULLs. The relational interface conforms to the ANSI standard for
padding, which specifies that a CHAR be padded with spaces. For
example, by default, a CHAR column created with a CREATE TABLE
statement is always padded with spaces.
An application that uses both interfaces may need to process strings
padded with NULLs.
Syntax

SET ANSI_PADDING=<ON|OFF>

Remarks

The default value is ON, meaning that strings padded with spaces are
inserted into CHARs. Trailing spaces are considered as insignificant
in logical expression comparisons. Trailing NULLs are considered as
significant in comparisons.
If set to OFF, the statement means that strings padded with NULLs
are inserted into CHARs. Both trailing NULLs and trailing spaces are
considered as insignificant in logical expression comparisons.
The following string functions support NULL padding:
CHAR_LENGTH

CONCAT

LCASE or LOWER

LEFT

LENGTH

LOCATE

LTRIM

POSITION

REPLACE

REPLICATE

RIGHT

RTRIM

STUFF

SUBSTRING

UCASE or UPPER

Restrictions
The following restrictions apply to SET ANSI_PADDING:

3-228

The statement applies only to character data types of fixed length

(CHAR), not to VARCHAR or LONGVARCHAR.
The statement applies to the session level.

Grammar Statements

Examples

The following example shows the results of string padding using the
INSERT statement with SET ANSI_PADDING set to ON and to
OFF.
DROP TABLE t1
CREATE TABLE t1 (c1 CHAR(4))
SET ANSI_PADDING = ON
INSERT INTO t1 VALUES (a) -- string a = a\0x20\0x20\0x20
INSERT INTO t1 VALUES (a + CHAR(0) + CHAR(0) + CHAR(0))
-- string a = a\0x00\0x00\0x00

DROP TABLE t1
CREATE TABLE t1 (c1 CHAR(4))
SET ANSI_PADDING = OFF
INSERT INTO t1 VALUES (a) -- string a = a\0x00\0x00\0x00
INSERT INTO t1 VALUES (a + CHAR(32) + CHAR(32) +
CHAR(32)) -- string a = a\0x20\0x20\0x20

The following example shows the results of string padding using the
UPDATE statement with SET ANSI_PADDING set to ON and to
OFF.
DROP TABLE t1
CREATE TABLE t1 (c1 CHAR(4))
SET ANSI_PADDING = ON
UPDATE t1 SET c1 = a -- all rows for c1 = a\0x20\0x20\0x20
UPDATE t1 SET c1 = a + CHAR(0) + CHAR(0) + CHAR(0)
-- all rows for c1 = a\0x00\0x00\0x00

DROP TABLE t1
CREATE TABLE t1 (c1 CHAR(4))
SET ANSI_PADDING = OFF
UPDATE t1 SET c1 = a -- all rows for c1 = a\0x00\0x00\0x00
UPDATE t1 SET c1 = a + CHAR(32) + CHAR(32) + CHAR(32)
-- all rows for c1 = a\0x20\0x20\0x20

The following example shows how a character column, c1, can be

cast to a BINARY data type so that you can display the contents of c1
in BINARY format. Assume that table t1 has the following six rows
of data:
a\x00\x00\x00\x00
a\x00\x00\x00\x00
a\x00\x20\x00\x00
a\x00\x20\x00\x00
a\x20\x20\x20\x20

3-229

SQL Syntax Reference

a\x20\x20\x20\x20

The following statement casts c1 as a BINARY data type:

SELECT CAST(c1 AS BINARY(4)) FROM t1

The SELECT statement returns the following:

0x61000000
0x61000000
0x61002000
0x61002000
0x61202020
0x61202020

See Also

INSERT on page 3-166

UPDATE on page 3-269
String Functions on page 5-2
Conversion Functions on page 5-20

3-230

Grammar Statements

SET CACHED_PROCEDURES
The SET CACHED_PROCEDURES statement specifies the number
of stored procedures that the database engine caches in memory for
an SQL session.
Syntax

SET CACHED_PROCEDURES = number

Remarks

The value of number can be any whole number in the range zero
through approximately two billion. The database engine
automatically defaults to 50. Each session can change its number of
cached procedures by issuing the SET statement.
The companion statement to SET CACHED_PROCEDURES is SET
PROCEDURES_CACHE.

If you set both SET statements to zero, the database engine does
not cache stored procedures. In addition, the engine removes
any existing cache used for stored procedures. That is, the engine
flushes from cache all stored procedures that were cached before
you set both statements to zero.
If you set only one of the statements to a value, either zero or a
nonzero value, the other statement is implicitly set to zero. The
statement implicitly set to zero is ignored. For example, if you
are only interested in caching 70 procedures and are not
concerned with the amount of memory, set CACHED_
PROCEDURES to 70. The database engine implicitly sets
PROCEDURES_CACHE to zero, which ignores the setting.

The following condition applies if you set CACHED_

PROCEDURES to a nonzero value. The database engine removes the
least-recently-used procedures from the cache if the execution of a
procedure causes the number of cached procedures to exceed the
CACHED_PROCEDURES value.
If a memory cache is used, it retains a compiled version of a stored
procedure after the procedure executes. Typically, caching results in
improved performance for each subsequent call to a cached
procedure. Note that excessive memory swapping, or thrashing,
could occur depending on the cache settings and the SQL being
executed by your application. Thrashing can cause a decrease in
performance.

3-231

SQL Syntax Reference

Registry Setting
In addition to the SET statement, the number of cached procedures
can be specified with a registry setting. The registry settings apply to
all sessions and provides a convenient way to set an initial value. Each
session can override the registry setting for that particular session by
using the SET statement.
The registry setting applies to all server platforms on which Pervasive
PSQL Server is supported. You must manually modify the registry
setting. On Windows, use the registry editor provided with the
operating system. On Linux, you can use the psregedit utility.
If the registry setting is not specified, the database engine
automatically defaults to 50.

To specify cached procedures registry setting on

Windows:
1

Locate the following key:

HKEY_LOCAL_MACHINE\SOFTWARE\Pervasive Software\SQL
Relational Engine

Note In most Windows operating systems, the Pervasive

Software key is HKEY_LOCAL_MACHINE\SOFTWARE\PERVASIVE

SOFTWARE. However, its location under HKEY_LOCAL_MACHINE\
SOFTWARE can vary depending on the operating system.
2

For this key, create a new string valued named

CachedProcedures.

Set CachedProcedures to the desired number of procedures that

you want to cache.

To specify cached procedures registry setting in the

Pervasive Registry on Linux:
1

Locate the following key:

PS_HKEY_CONFIG\SOFTWARE\Pervasive Software\SQL
Relational Engine

3-232

For this key, create a new string valued named

CachedProcedures.

Grammar Statements

Set CachedProcedures to the desired number of procedures that

you want to cache.

Caching Exclusions
A stored procedure is not cached, regardless of the cache setting(s),
for any of the following:

Examples

The stored procedure references a local or a global temporary

The following example sets a cache memory of 2 MB that stores up

to 20 stored procedures.
SET CACHED_PROCEDURES = 20
SET PROCEDURES_CACHE = 2

The following example sets a cache memory of 1,000 MB that stores

up to 500 stored procedures.
SET CACHED_PROCEDURES = 500
SET PROCEDURES_CACHE = 1000

The following example specifies that you do not want to cache stored
procedures and that any existing procedures cache will be removed.
SET CACHED_PROCEDURES = 0
SET PROCEDURES_CACHE = 0

3-233

SQL Syntax Reference

The following example specifies that you want to cache 120 stored
procedures and ignore the amount of memory used for the cache.
SET CACHED_PROCEDURES = 120

(The database engine implicitly sets PROCEDURES_CACHE to

zero.)
See Also

CREATE PROCEDURE on page 3-66

SET PROCEDURES_CACHE on page 3-245

3-234

Grammar Statements

SET DECIMALSEPARATORCOMMA
The ODBC database engine by default displays decimal data using a
period (.) as the separator between ones and tenths (for example,
100.95). The SET DECIMALSEPARATORCOMMA statement
allows you to specify that results should be displayed using a comma
to separate ones and tenths (for example, 100,95).
As with all SET statements, the effects of this statement apply to the
remainder of the current database session, or until another SET
DECIMALSEPARATORCOMMA statement is issued.
Syntax

SET DECIMALSEPARATORCOMMA=<ON|OFF>

Remarks

The default value is OFF, meaning that the period is used as the
default decimal separator.
In locales where the comma is used as the decimal separator, decimal
data can be entered using a comma or a period as the separator
(literal values that use the comma as the separator must be enclosed
in single quotes, for example: 123,43). When the data is returned,
however (as in the results of a SELECT statement), it is always
displayed using a period unless SET
DECIMALSEPARATORCOMMA=ON has been specified.
Likewise, if your database contains data that was entered using the
period as the decimal separator, you can choose to specify the
comma as the separator for output and display by using this
statement.
This command affects output and display only. It has no effect on
values being inserted, updated, or used in a comparison.

Examples

The following example shows how to insert period-delimited data

and the effects of the SET DECIMALSEPARATORCOMMA
statement on the SELECT results.
CREATE TABLE t1 (c1 real, c2 real)
INSERT INTO t1 VALUES (102.34, 95.234)
SELECT * FROM t1
Results:

c1
c2
------- ------102.34 95.234

3-235

SQL Syntax Reference

SET DECIMALSEPARATORCOMMA=ON
SELECT * FROM t1
Results:

c1
c2
------- ------102,34 95,234

The following example shows how to insert comma-delimited data,

and the effects of the SET DECIMALSEPARATORCOMMA
statement on the SELECT results.
Note The comma can only be used as the separator character if

the client and/or server operating system locale settings are set to
a locale that uses the comma as the separator. For example, if you
have U.S. locale settings on both your client and server, you will
receive an error if you attempt to run this example.
CREATE TABLE t1 (c1 real, c2 real)
INSERT INTO t1 VALUES (102,34, 95,234)
SELECT * FROM t1
Results:

c1
c2
------- ------102.34 95.234

SET DECIMALSEPARATORCOMMA=ON
SELECT * FROM t1
Results:
c1
c2
------- ------102,34 95,234

See Also

Comma as Decimal Separator on page 3-300

OEM to ANSI Support on page 3-304

3-236

Grammar Statements

SET DEFAULTCOLLATE
The SET DEFAULTCOLLATE statement specifies the collating
sequence file to use for all columns of data type CHAR, VARCHAR,
or LONGVARCHAR.
Syntax

SET DEFAULTCOLLATE = < NULL | 'acs-path' >

acs-path ::= location of the file that specifies the

collating sequence rules

Remarks

The SET DEFAULTCOLLATE statement offers the advantage of a

session setting, which is more convenient than specifying a collating
sequence for numerous columns individually.
Individual columns can still specify a collating sequence if you
choose. The use of the COLLATE key word as part of a column
definition overrides the SET DEFAULTCOLLATE setting for that
particular column. See the column definitions for ALTER TABLE
and CREATE TABLE.
The NULL parameter for SET DEFAULTCOLLATE causes the
session to use no alternate collating sequence (ACS) file. No collating
sequence is applied to any text columns except for those with
individual COLLATE definitions. An ACS file is a 265-byte image of
the same format used for an ACS in the transactional interface. See
User-Defined ACS on page 4-29 in Pervasive PSQL Programmer's
Guide.
The default session setting for DEFAULTCOLLATE is null.
The following requirements apply to the acs-path parameter.

The parameter must specify a path that is valid comparative to

the location of the database engine, not to the location of the
calling application. (That is, from the database engine's point of
view, not from the calling application's perspective.)
The directory structure in the path must exist. (SET
DEFAULTCOLLATE does not create a path.)
The path must include a file name. The file specifies the collating
rules (as, for example, upper.alt, which is provided with
Pervasive PSQL).
The path must be enclosed in single quotes.

3-237

SQL Syntax Reference

Examples

The path must be at least 1 character long and cannot exceed 255
characters.
Relative paths are allowed and are relative to the directory where
the DDFs are located. Relative paths and can contain a period
(current directory), double period (parent directory), slash, or
any combination of the three. Slash characters in relative paths
may be either forward (/) or backslash (\). You may mix the use
of the two types, if desired.
Universal naming convention (UNC) path names are permitted.

For default locations of Pervasive PSQL files, see Where are the
Pervasive PSQL v10 files installed? on page 7-2 in Getting Started
With Pervasive PSQL.
The following example sets a default collating sequence using the
upper.alt file supplied with Pervasive PSQL. A table, t1, is created
with three text columns and three columns not text. A SELECT
statement executes against Pervasive PSQL system tables to return
the ID, type, size, and attributes of the columns in t1. The result
shows that the three text columns have an attribute of UPPER.
SET DEFAULTCOLLATE = 'file_path\upper.alt'
DROP TABLE t1
CREATE TABLE t1 (c1 INT, c2 CHAR(10), c3 BINARY(10), c4
VARCHAR(10), c5 LONGVARBINARY, c6 LONGVARCHAR)
SELECT * FROM x$attrib WHERE xa$id in (SELECT xe$id FROM
x$field WHERE xe$file = (SELECT xf$id FROM x$file
WHERE xf$name = 't1'))
Xa$Id
=====
327
329
331

Xa$Type
=======
O
O
O

Xa$ASize
========
265
265
265

3 rows were affected.

3-238

Xa$Attrs
========
UPPER
UPPER
UPPER

Grammar Statements

The following example continues with the use of table t1. An ALTER
TABLE statement changes the text column c2 from a CHAR to an
INTEGER. The result of the SELECT statement shows that now only
two columns are affected by the default collating.
ALTER TABLE t1 ALTER c2 INT
SELECT * FROM x$attrib WHERE xa$id in (SELECT xe$id FROM
x$field WHERE xe$file = (SELECT xf$id FROM x$file
WHERE xf$name = 't1'))
Xa$Id
=====
329
331

Xa$Type
=======
O
O

Xa$ASize
========
265
265

Xa$Attrs
========
UPPER
UPPER

2 rows were affected.

The following example uses an ALTER TABLE statement to change

column c1 in table t1 from an INTEGER to a CHAR. The result of
the SELECT statement shows that three columns are affected by the
default collating.
ALTER TABLE t1 ALTER c1 CHAR(10)
SELECT * FROM x$attrib WHERE xa$id in (SELECT xe$id FROM
x$field WHERE xe$file = (SELECT xf$id FROM x$file
WHERE xf$name = 't1'))
Xa$Id
=====
326
329
331

Xa$Type
=======
O
O
O

Xa$ASize
========
265
265
265

Xa$Attrs
========
UPPER
UPPER
UPPER

3 rows were affected.

See Also

ALTER TABLE on page 3-10

CREATE TABLE on page 3-80

3-239

SQL Syntax Reference

SET OWNER
The SET OWNER statement allows you to specify one or more
owner names for use during the current database connection. An
owner name is assigned only through the transactional interface, not
through the relational interface. Note that no relationship exists
between an owner name and any system user name or database user
name. Think of an owner name as a simple file password that, if
assigned, is required to access a data file.
Syntax

SET OWNER = []ownername[] [,[]ownername[]] ...

Remarks

The SET OWNER statement allows you to specify a list of owner

names for data files that have owner names assigned through the
transactional interface. Pervasive PSQL passes the owner names to
the relational interface, enabling the relational interface to open the
data files.
You can specify any number of owner names with a SET OWNER
statement. If an owner name begins with a non-alphabetic character,
you must enclose the name in single quotes ( ).
The statement is effective for the current connection only. If the
current user logs out after issuing a SET OWNER command, the user
must re-issue the command the next time the user logs in.
Each SET OWNER statement issued during the same connection resets the owner list. That is, only the owner names specified in the
most recent SET OWNER statement are passed to the database
engine. You cannot add owner names to the owner list with
subsequent statements.
In a database with security turned Off, this command allows full
access to any data file that has an owner name the same as any name
supplied in the SET OWNER list.
In a database with security turned On, this command has no effect
for most users. It only has an effect when it is issued by the Master
user. If the Master user has not granted himself permissions yet,
issuing this command gives the Master user full access to any data file
with one of the specified owner names. Also, if the Master user
chooses to give himself permissions, he has two options. The Master
user can issue a SET OWNER followed by a GRANT without an
owner name, or the Master user can issue a GRANT that specifies the
owner name. See Examples on page 3-241.

3-240

Grammar Statements

Examples

The following example specifies one owner name.

SET OWNER = '12jerry'

The following example specifies several owner names.

SET OWNER = jimbo, terry, maximus

The following example shows the effects of multiple SET OWNER

statements within the same connection.
SET OWNER = jimbo, terry, maximus
--owner list contains: jimbo,terry,maximus.

SET OWNER = fred, jennie, lucinda

--owner list now contains: fred,jennie,lucinda. Previous contents are discarded.

The following example demonstrates the usage of SET OWNER for

the Master user in a secure database. Assume that security has just
been turned on, and no permissions have been granted in the
database. The inventory data file has the owner name admin.
To grant himself permissions, the Master user has two options. The
Master user can issue a SET OWNER followed by a GRANT without
an owner name, or the Master user can issue a GRANT that specifies
the owner name. Both methods achieve the same result:
SET OWNER = admin
GRANT ALL ON inventory TO MASTER

or
GRANT ALL ON inventory admin TO MASTER

See Also

GRANT on page 3-149

REVOKE on page 3-194

3-241

SQL Syntax Reference

SET PASSWORD
The SET PASSWORD statement provides the following
functionality for a secured database:

Syntax

The Master user can change the password for the Master user or
for another user.
A normal user (non-Master user) can change his or her logon
password to the database.

SET PASSWORD [ FOR 'user_name'] = password

user-name ::= name of user logged on the database or

authorized to log on the database

password ::= password string

Remarks

SET PASSWORD requires that the database have relational security

enabled and may be issued at any time. (In contrast, SET SECURITY
can be issued only when the session for the Master user is the only
current database connection. See SET SECURITY on page 3-250.)
SET PASSWORD may be issued by the Master user or by a normal
(non-Master user). The Master user can change the password for any
user authorized to log on the database. A normal user can change
only his or her own password. The changed password takes effect the
next time the user logs on the database.

User Issuing SET

PASSWORD statement

with FOR clause

without FOR clause

Master

Master can specify a user-name of

Master or of any user authorized to
log on the database.1

Password changed for entire database

(that is, changed for the Master user,
which affects the entire database).

Password changed for user-name.

Normal

Normal user can specify his or her

user-name. The user must be logged
on the database.
Password changed only for that user.

Password changed only for the user

issuing the SET PASSWORD statement.
The user must be logged on the
database.

User-name refers to a user who can log on a Pervasive PSQL database, which may differ from the name
assigned to a user at the operating system level. For example, assume that Yogine is a user who can log on
to the operating system. Security is enabled on database DEMODATA and Yogine is added to DEMODATA
as a user named DeptMgr. The user-name required for this person to log on DEMODATA is DeptMgr.

3-242

Grammar Statements

Password Characteristics

Examples

See Identifier Restrictions by Identifier Type on page 1-3 in

Advanced Operations Guide for the maximum length of a
password and the characters allowed.
Passwords are case sensitive. If the password begins with a nonalphabetic character, the password must be enclosed in single
quotes.
The space character may be used in a password provided it is not
the first character. If a password contains a space character, the
password must be enclosed by single quotes. As a general rule,
avoid using the space character in a password.
Password is not a reserved word. It may be used as a name for
a table or column. However, if used for a table or column name
in an SQL statement, password must be enclosed by double
quotes because it is a keyword.
If you want to use the literal null as a password, you must
enclose the word with single quotes (null). The quoted string
prevents confusion with the statement SET SECURITY = NULL,
which disables security on the database.

The following example shows the Master user enabling security on

the database with a password of bluesky. The Master user then
grants logon authority to user user45 with a password of
tmppword and grants user45 SELECT permissions to table person.
The Master user then changes the security password for Master to
reddawn and changes user45s password to newuser.
SET SECURITY = bluesky
--this enables security on the database

GRANT LOGIN TO user45:tmppword

GRANT SELECT ON person TO user45
SET PASSWORD = reddawn
--this changes the password for Master, which means for the entire database

SET PASSWORD FOR user45 = newuser

The following example assumes that user45 has logged on to the

database with a password of newuser. User45 changes her password
to tomato. User45 then selects all records in the person table.
SET PASSWORD FOR user45 = tomato
--this changes only user45s password

SELECT * FROM person

--user45 still has SELECT rights on table person

3-243

SQL Syntax Reference

See Also

ALTER USER on page 3-26

CREATE USER on page 3-106
GRANT on page 3-149
SET SECURITY on page 3-250

3-244

Grammar Statements

SET PROCEDURES_CACHE
The SET PROCEDURES_CACHE statement specifies the amount of
memory for an SQL session that the database engine reserves as a
cache for stored procedures.
Syntax

SET PROCEDURES_CACHE = megabytes

Remarks

The value of megabytes can be any whole number in the range zero
to approximately two billion. The database engine automatically
defaults to 5 MB. Each session can change its amount of cache
memory by issuing the SET statement.
The companion statement to SET PROCEDURES_CACHE is SET
CACHED_PROCEDURES.

If you set both SET statements to zero, the database engine does
not cache stored procedures. In addition, the engine removes
any existing cache used for stored procedures. That is, the engine
flushes from cache all stored procedures that were cached before
you set both statements to zero.
If you set only one of the statements to a value, either zero or a
nonzero value, the other statement is implicitly set to zero. The
statement implicitly set to zero is ignored. For example, if you
are only interested in 30 MB as the amount of memory cached
and are not concerned with the number of procedures cached,
set PROCEDURES_CACHE to 30. The database engine
implicitly sets CACHED_PROCEDURES to zero, which ignores
the setting.

The following condition applies if you set PROCEDURES_CACHE

to a nonzero value. The database engine removes the least-recentlyused procedures from the cache if the execution of a procedure
allocates memory that exceeds the PROCEDURES_CACHE value.
If a memory cache is used, it retains a compiled version of a stored
procedure after the procedure executes. Typically, caching results in
improved performance for each subsequent call to a cached
procedure. Note that excessive memory swapping, or thrashing,
could occur depending on the cache settings and the SQL being
executed by your application. Thrashing can cause a decrease in
performance.

3-245

SQL Syntax Reference

Registry Setting
In addition to the SET statement, the amount of memory reserved
for the cache can be specified with a registry setting. The registry
settings apply to all sessions and provides a convenient way to set an
initial value. Each session can override the registry setting for that
particular session by using the SET statement.
The registry setting applies to all server platforms on which Pervasive
PSQL Server is supported. You must manually modify the registry
setting. On Windows, use the registry editor provided with the
operating system. On Linux, you can use the psregedit utility.
If the registry setting is not specified, the database engine
automatically defaults to 5 MB.

To specify the amount of cache memory in a registry

setting on Windows:
1

Locate the following key:

HKEY_LOCAL_MACHINE\SOFTWARE\Pervasive Software\SQL
Relational Engine

Note In most Windows operating systems, the Pervasive

Software key is HKEY_LOCAL_MACHINE\SOFTWARE\PERVASIVE

SOFTWARE. However, its location under HKEY_LOCAL_MACHINE\
SOFTWARE can vary depending on the operating system.
2

For this key, create a new string valued named ProceduresCache.

Set ProceduresCache to the desired amount of memory that you

want to cache.

To specify the amount of cache memory in the

Pervasive Registry on Linux:
1

Locate the following key:

PS_HKEY_CONFIG\SOFTWARE\Pervasive Software\SQL
Relational Engine

3-246

For this key, create a new string valued named ProceduresCache.

Set ProceduresCache to the desired amount of memory that you

want to cache.

Grammar Statements

Caching Exclusions
A stored procedure is not cached, regardless of the cache setting(s),
for any of the following:

Examples

The stored procedure references a local or a global temporary

The following example sets a cache memory of 2 MB that stores up

to 20 stored procedures.
SET CACHED_PROCEDURES = 20
SET PROCEDURES_CACHE = 2

The following example sets a cache memory of 1,000 MB that stores

up to 500 stored procedures.
SET CACHED_PROCEDURES = 500
SET PROCEDURES_CACHE = 1000

The following example specifies that you do not want to cache stored
procedures and that any existing procedures cache will be removed.
SET CACHED_PROCEDURES = 0
SET PROCEDURES_CACHE = 0

3-247

SQL Syntax Reference

The following example specifies that you want to set the amount of
cache memory to 80 MB and ignore the number of procedures that
may be cached.
SET PROCEDURES_CACHE = 80

(The database engine implicitly sets CACHED_PROCEDURES to

zero.)
See Also

CREATE PROCEDURE on page 3-66

SET CACHED_PROCEDURES on page 3-231

3-248

Grammar Statements

SET ROWCOUNT
You may limit the number of rows returned by all subsequent
SELECT statements within the current session by using the keyword
SET ROWCOUNT.
The main difference between SET ROWCOUNT and TOP is that
TOP affects only the current statement, while SET ROWCOUNT
affects all statements issued during the current database session,
until the next SET ROWCOUNT or until the session is terminated.
Syntax

SET ROWCOUNT = number

Remarks

If a SELECT statement subject to a SET ROWCOUNT condition

contains an ORDER BY clause and an index cannot be used to
optimize on the ORDER BY clause, Pervasive PSQL generates a
temporary table. The temporary table is populated with the querys
entire result set. The rows in the temporary table are ordered as
specified by the ORDER BY clause and the ROWCOUNT number of
rows in the ordered result set are returned.
You may turn off the ROWCOUNT feature by setting ROWCOUNT
to zero:
SET ROWCOUNT = 0

SET ROWCOUNT is ignored when dynamic cursors are used.

If both SET ROWCOUNT and TOP are applied to a given query, the
number of rows returned is the lower of the two values.
Examples

Also see the examples for TOP on page 3-222.

SET ROWCOUNT = 10;
SELECT * FROM person;
-- returns 10 rows

See Also

TOP on page 3-222

3-249

SQL Syntax Reference

SET SECURITY
The SET SECURITY statement allows the Master user to enable or
disable security for the database to which Master is logged on.
Syntax

SET SECURITY = < password | NULL >

Examples

The following example enables security for the database and sets the
Master password to mypasswd.
SET SECURITY = mypasswd

The following example sets the password to 123456.

SET SECURITY = '123456'

The following example disables security.

SET SECURITY = NULL

Remarks

You must be logged on as Master to set security. You can then assign
a password by using the SET SECURITY statement. No password is
required for Master to log an unsecured databased. A password must
be assigned to Master to enable security for the database.
SET SECURITY can be issued only when the session for the Master
user is the only current database connection. You can also set
security from the Pervasive PSQL Control Center (PCC). See To
turn on security using Pervasive PSQL Explorer on page 3-38 in
Pervasive PSQL User's Guide.
Note The SET SECURITY statement cannot be executed within
the SQL Editor. An error results if you try. For a database with
no security, the SQL Editor locks the dictionary files, which
prevents your setting the password. For a secure database, the
SQL Editor opens a second connection to the database files,
which prevents your disabling security.

For password requirements, see Password Characteristics on page

3-243.

3-250

Grammar Statements

User Permissions

User permissions on objects (such as tables, views, and stored

procedures) are retained in the system tables after SET SECURITY is
set to NULL. Consider the following scenario:

Security for database mydbase is enabled and user Master is

logged in.
Master user creates users user1 and user2, and table t1 for
database mydbase.
User user2 is granted SELECT permission on t1.
Security for mydbase is disabled.
Table t1 is dropped.

Even though table t1 no longer exists, permissions for t1 are still

retained in the system tables (the ID for t1 is still in X$Rights).
Now consider the following:

Security for database mydbase is enabled again.

User1 logs in to the database.
User1 creates a new table tbl1 for mydbase. It is possible for
tbl1 to be assigned the same object ID that had been assigned
to t1. In this particular scenario, the object IDs assigned to "t1"
and "tbl1" are the same.
The previous permissions for t1 are reinstated for tbl1. That
is, user1 has SELECT permissions on tbl1 even though no
permissions to the new table have been explicitly granted.
Note If you want to delete permissions on an object, you must

explicitly revoke the permissions. This applies to tables, views,

and stored procedures because permissions are associated with
object IDs and the database reuses object IDs of deleted objects
for new objects.

See Also

ALTER USER on page 3-26

CREATE USER on page 3-106
GRANT on page 3-149
REVOKE on page 3-194
SET PASSWORD on page 3-242

3-251

SQL Syntax Reference

SET TIME ZONE

The SET TIME ZONE keyword allows you to specify a current time
offset from Coordinated Universal Time (UTC) for your locale,
overriding the operating system time zone setting where the database
engine is located.
Any SET TIME ZONE statement remains in effect until the end of
the current database session, or until another SET TIME ZONE
statement is executed.
Caution You should always use the default behavior unless you

have a specific need to override the time zone setting in your

operating system. If you are using Pervasive replication or your
application has dependencies on the sequential time order of
records inserted, use of SET TIME ZONE to modify your time
zone offset is not recommended.

Syntax

SET TIME ZONE < displacement | LOCAL >

displacement ::= <+|->hh:mm

Valid range of hh is 00 - 12.

Valid range of mm is 00 - 59.
Either a plus (+) or a minus (-) sign is required as part of the
displacement value.
Remarks

Default BehaviorSET TIME ZONE LOCAL is the default

behavior, which is the same as not using the SET TIME ZONE
command at all. Under the default behavior, the database engine
establishes its time zone based on the operating system where it is
running. For example, SELECT CURTIME ( ) returns the current
local time, while SELECT CURRENT_TIME ( ) returns the current
UTC time, both based on local system time and the time zone setting
in the operating system.
The LOCAL keyword allows you to restore default behavior after
specifying a displacement value, without having to terminate and reopen the database session.
Under default behavior, literal time and date values, such as 199603-28 and 17:40:46 are interpreted as current local time/date. In

3-252

Grammar Statements

addition, during inserts, TIMESTAMP literal values are interpreted

as specifying current local time. TIMESTAMP values are always
adjusted and stored internally using UTC time, and converted to
local time upon retrieval.
Table 3-24 Time/Date Functions with SET TIME ZONE Default
If no time zone is specified, or TIME ZONE LOCAL is specified ...
CURDATE(), CURTIME(), NOW()

These functions return current local time/

date based on system clock.

CURRENT_DATE(), CURRENT_
TIME(), CURRENT_TIMESTAMP()

These functions always return current

UTC time/date based on system clock and
operating system locale setting.

Behavior When Interval SpecifiedIf a valid displacement value is

specified, then that value is used instead of the operating system time
zone offset when generating values for NOW ( ), CURTIME ( ), or
CURDATE ( ). For example, if a displacement of -02:00 is specified,
then the local time value of CURDATE() will be calculated by adding
-02:00 to the UTC time returned from the operating system.
Under this behavior, time and date literals are interpreted as local
time, at their face values. TIMESTAMP literals are interpreted as
specifying a time such that if displacement is subtracted from it, the
result is UTC. Daylight savings is not a consideration since displacement
explicitly takes it into account. TIMESTAMP values are always stored
internally using UTC time.
Table 3-25 Time/Date Functions with SET TIME ZONE Specified
If a valid displacement value is specified ...
CURDATE(), CURTIME(), NOW()

These functions return current local time/

date values by adding displacement to the
current UTC time/date values.

CURRENT_DATE(), CURRENT_
TIME(), CURRENT_TIMESTAMP()

These functions always return current

UTC time/date based on system clock and
operating system locale setting.

To convert a given local time value to UTC, you must subtract your
time zone displacement value from the local time value. In other
words,
UTC time = local time - time zone displacement

3-253

SQL Syntax Reference

See Table 3-26 for example conversions.

Table 3-26 Local to UTC Conversion Examples
Local Time

Displacement

UTC

10:10:15
Austin, Texas

US Central Standard
Time -06:00

10:10:15-(-06:00)=16:10:15 UTC

16:10:15
London

Greenwich Mean Time

+00:00

16:10:15-(+00:00)=16:10:15 UTC

22:10:15
Dhaka

+06:00

22:10:15-(+06:00)=16:10:15 UTC

A note about TIMESTAMP data type

Because TIMESTAMP data is always stored as UTC, and literal
Timestamp values (including values stored on disk) are always
converted to local time when retrieved, the behavior of NOW ( ) and
CURRENT_TIMESTAMP ( ) values can be confusing. For example,
consider the following table, assuming the database engine is located
in Central Standard Time, U.S.:
Table 3-27 Timestamp Data Type Examples
Statement

Value

SELECT NOW()

2001-10-01 12:05:00.000000
displayed.

INSERT INTO t1 (c1) SELECT NOW()

2001-10-01 18:05:00.000000
stored on disk.

SELECT * from t1

2001-10-01 12:05:00.000000
displayed.

SELECT CURRENT_TIMESTAMP()

2001-10-01 18:05:00.000000
displayed.

INSERT INTO t2 (c1) SELECT CURRENT_

TIMESTAMP()

2001-10-01 18:05:00.000000
stored on disk.

SELECT * from t2

2001-10-01 12:05:00.000000
displayed.

It is important to note that the value displayed by a direct SELECT

NOW ( ) is not the same as the value stored on disk by the syntax
INSERT SELECT NOW ( ). Likewise, note that the display value of

3-254

Grammar Statements

SELECT CURRENT_TIMESTAMP ( ) is not the same value that you

will see if you INSERT the value of CURRENT_TIMESTAMP() then
SELECT it, because the literal value stored in the data file is adjusted
when it is retrieved.
Examples

In this example, no SET TIME ZONE statement has been issued yet,
and the computer on which the database engine is running has its
clock set to January 9, 2002, 16:35:03 CST (U.S.). Recall that
CURRENT_TIMESTAMP() and the other CURRENT_ functions
always return UTC time and/or date based on the system clock and
locale settings of the computer where the database engine is running.
SELECT CURRENT_TIMESTAMP(), NOW(),
CURRENT_TIME(), CURTIME(),
CURRENT_DATE(), CURDATE()

Results:
2002-01-09 22:35:03.0000000 2002-01-09 16:35:03.0000000
22:35:03
16:35:03
2002-01-09
2002-01-09

Note that CST is 6 hours ahead of UTC.

SET TIME ZONE -10:00

Now the same SELECT statement above returns the following:

2002-01-09 22:35:03.0000000 2002-01-09 12:35:03.0000000
22:35:03
12:35:03
2002-01-09
2002-01-09

Note that the value of NOW() changed after the SET TIME ZONE
statement, but the value of CURRENT_TIMESTAMP() did not.

The following example demonstrates the difference between

TIMESTAMP values that are stored as UTC values then converted to
local values upon retrieval, and TIME or DATE values that are stored
and retrieved at their face value. Assume that the system clock
currently shows January 9, 2002, 16:35:03 CST (U.S.). Also assume
that no SET TIME ZONE statement has been issued.
CREATE TABLE t1 (c1 TIMESTAMP, c2 TIMESTAMP, c3 TIME, c4
TIME, c5 DATE, c6 DATE)
INSERT INTO t1 SELECT CURRENT_TIMESTAMP(), NOW(),
CURRENT_TIME(), CURTIME(), CURRENT_DATE(), CURDATE()

3-255

SQL Syntax Reference

SELECT * FROM t1

Results:
c1
c2
--------------------------- --------------------------2002-01-09 16:35:03.0000000 2002-01-09 16:35:03.0000000
c3
c4
c5
c6
-------- -------- ---------- ---------22:35:03 16:35:03 2002-01-09 2002-01-09

Observe that NOW() and CURRENT_TIMESTAMP() have

different values when displayed to the screen with SELECT NOW(),
CURRENT_TIMESTAMP(), but once the literal values are saved to
disk, UTC time is stored for both values. Upon retrieval, both values
are converted to local time.
By setting the time zone interval to zero, we can view the actual data
stored in the file, because it is adjusted by +00:00 upon retrieval:
SET TIME ZONE +00:00
SELECT * FROM t1

Results:
c1
c2
--------------------------- --------------------------2002-01-09 22:35:03.0000000 2002-01-09 22:35:03.0000000
c3
c4
c5
c6
-------- -------- ---------- ----------

22:35:03 16:35:03 2002-01-09 2002-01-09

The following example demonstrates the expected behavior when

the local date is different than the UTC date (for example, UTC is
past midnight, but local time is not, or the reverse). Assume that the
system clock currently shows January 9, 2002, 16:35:03 CST (U.S.).
SET TIME ZONE +10:00
SELECT CURRENT_TIMESTAMP(), NOW(),
CURRENT_TIME(), CURTIME(),
CURRENT_DATE(), CURDATE()

3-256

Grammar Statements

Results:
2002-01-09 22:35:03.0000000 2002-01-10 08:35:03.0000000
22:35:03
08:35:03
2002-01-09
2002-01-10
INSERT INTO t1 SELECT CURRENT_TIMESTAMP(), NOW(),
CURRENT_TIME(), CURTIME(), CURRENT_DATE(), CURDATE()
SELECT * FROM t1

Results:
c1
c2
--------------------------- --------------------------2002-01-10 08:35:03.0000000 2002-01-10 08:35:03.0000000
c3
c4
c5
c6
-------- -------- ---------- ---------22:59:55 08:59:55 2002-01-09 2002-01-10

As you can see, the UTC time and date returned by CURRENT_
DATE() and CURRENT_TIME() are stored as literal values. Since
they are not TIMESTAMP values, no adjustment is made to these
values when they are retrieved from the database.
See Also

TIMESTAMP data type on page A-35

Time and Date Functions on page 5-9

3-257

SQL Syntax Reference

SET TRUEBITCREATE
The SET TRUEBITCREATE statement allows you to specify whether
the BIT data type can be indexed and can map to the LOGICAL
transactional data type.
Syntax

SET TRUEBITCREATE = < ON | OFF >

Remarks

The default is on. This means that the BIT data type is 1 bit, cannot
be indexed and is assigned a Pervasive PSQL type code of 16. When
of type code 16, BIT has no equivalent transactional data type to
which it maps.
For certain situations, such as compatibility with other DBMS
applications, you may want to map BIT to the LOGICAL data type
and be able to index the BIT data type. To do so, set
TRUEBITCREATE to off. This maps BIT to LOGICAL, which is a
1-byte data type of type code 7.
The creation mode remains in effect until it is changed by issuing the
statement again, or until the database connection is disconnected.
Because this setting is maintained on a per-connection basis,
separate database connections can maintain different creation
modes, even within the same application. Every connection starts
with the setting in default mode, where BITs are created with a
Pervasive PSQL type code of 16.
This feature does not affect existing BITs, only ones created after the
set statement is applied.
This setting can be toggled only by using SQL. It cannot be set using
the Pervasive PSQL Control Center. Note that Table Editor displays
the relational data types for columns (so the type is displayed as
BIT). If TRUEBITCREATE is set to off, Table Editor allows you
to index the BIT column.

Example

To toggle the setting and specify that new BITs should be created to
allow indexing, map to the LOGICAL transactional data type, and
have a type code of 7:
SET TRUEBITCREATE=OFF

3-258

Grammar Statements

SET TRUENULLCREATE
The SET TRUENULLCREATE statement turns on or off true NULLs
when you create new tables.
Syntax

SET TRUENULLCREATE = < ON | OFF >

Remarks

Pervasive PSQL v10 allows you to set the default format for creation
of tables with regard to NULL support. Normally, the product
creates new tables using the true NULL data record format, which
adds a NULL indicator byte to the beginning of every field. By
turning off this engine setting using an SQL statement, you can
create new tables that use the legacy NULL data record format that
was used in Pervasive.SQL 7.
The creation mode remains in effect until it is changed by issuing the
statement again, or until the connection is disconnected. Because
this setting is maintained on a per-connection basis, separate
database connections can maintain different creation modes, even
within the same application. Every connection starts with the setting
in default mode, where new tables are created with true NULL
support.
This feature does not affect existing tables or available column data
types. All tables are created using Pervasive PSQL data types. For
example, old data types such as NOTE or LVAR are not available for
use regardless of which type of NULL support is selected.
Also see the discussion about nullable data types under INSERT
on page 3-166.
This setting can be toggled only by using SQL. It cannot be set using
the Pervasive PSQL Control Center.

Examples

To toggle the setting and specify that new tables should be created
with legacy NULL support, use this SQL statement:
SET TRUENULLCREATE=OFF

To toggle the setting and return the engine to the default, which is
table creation with true NULL support, use this SQL statement:
SET TRUENULLCREATE=ON

3-259

SQL Syntax Reference

SET
The SET statement assigns a value to a declared variable.
Syntax

SET variable-name = proc-expr

Remarks

You must declare variables before you can set them. SET is allowed
only in stored procedures and triggers.

Examples

The following examples assigns a value of 10 to var1.

SET :var1 = 10;

See Also

CREATE PROCEDURE on page 3-66

DECLARE on page 3-113

3-260

Grammar Statements

SIGNAL
Remarks

The SIGNAL statement allows you to signal an exception condition

or a completion condition other than successful completion.
Signalling an SQLSTATE value causes SQLSTATE to be set to a
specific value. This value is then returned to the user, or made
available to the calling procedure (through the SQLSTATE value).
This value is available to the application calling the procedure.
You can also specify an error message with the SQLSTATE value.
Note SIGNAL is available only inside a stored procedure or user-

defined function.

Syntax

SIGNAL SQLSTATE_value [, error_message ]

SQLSTATE_value
error_message

Examples

::= user-defined value

::= user-defined message

The following example prints the initial SQLSTATE value 00000,

then prints SQLSTATE exception caught after the signal is raised.
The final SQLSTATE value printed is W9001.
CREATE PROCEDURE GenerateSignal();
BEGIN
SIGNAL 'W9001';
END;
CREATE PROCEDURE TestSignal() WITH DEFAULT HANDLER;
BEGIN
PRINT SQLSTATE;
CALL GenerateSignal();
IF SQLSTATE <> '00000' THEN
PRINT 'SQLSTATE exception caught';
END IF;
PRINT SQLSTATE;
END;

3-261

SQL Syntax Reference

CREATE PROCEDURE GenerateSignalWithErrorMsg();

BEGIN
SIGNAL 'W9001', 'Invalid Syntax';
END;
CALL GenerateSignalWithErrorMsg()

See Also

3-262

CREATE PROCEDURE on page 3-66

Grammar Statements

SQLSTATE
Remarks

The SQLSTATE value corresponds to a success, warning, or

exception condition. The complete list of SQLSTATE values defined
by ODBC can be found in the Microsoft ODBC SDK
documentation.
When a handler executes, the statements within it affect the
SQLSTATE value in the same way as statements in the main body of
the compound statement. However, a handler that is intended to take
specific action for a specific condition can optionally leave that
condition unaffected, by re-assigning that condition at its
conclusion. This does not cause the handler to be invoked again; that
would cause a loop. Instead, Pervasive PSQL treats the exception
condition as an unhandled exception condition, and execution
stops.

See Also

CREATE PROCEDURE on page 3-66

SELECT on page 3-202
SIGNAL on page 3-261

3-263

SQL Syntax Reference

START TRANSACTION
START TRANSACTION signals the start of a logical transaction and
must always be paired with a COMMIT or a ROLLBACK.
Syntax

START TRANSACTION
Sql-statements
COMMIT | ROLLBACK [WORK]

Remarks

START TRANSACTION is supported only within stored

procedures. You cannot use START TRANSACTION within SQL
Editor. (SQL Editor sets AUTOCOMMIT to on.)
This statement is not supported outside of a stored procedure
because the ODBC standard specifies that every statement is by
default inside a transaction. The ODBC standard does not have an
API to start a transaction.
ODBC provides for the application to decide if each SQL statement
is in its own transaction or if the application will specify when each
transaction is completed. ODBC automatically opens a transaction
prior to any statement that is not in a transaction. Thus, with the first
statement of a given connection, or with the first statement after a
COMMIT or ROLLBACK, ODBC automatically starts a new
transaction.
Within the ODBC standard, SQLSetConnectOption is used to
specify whether each statement is in its own transaction or the
application groups statements within a transaction.
Each statement is in its own transaction if SQLSetConnectOption is
called specifying the option SQL_AUTOCOMMIT and the value
SQL_AUTOCOMMIT_ON (this is the default). This usage means
that a transaction is started at the beginning of executing a statement
and the transaction is either automatically committed, if no error
occurs, or rolled back, if error occurred, upon completion of
statement execution.
The application can group statements in a transaction if
SQLSetConnectOption is called specifying the option SQL_
AUTOCOMMIT and the value SQL_AUTOCOMMIT_OFF value.
This usage means that a transaction is started at the beginning of the
first statement executed. The application then decides when and how
to end the transaction by calling SQLTransact or executing a

3-264

Grammar Statements

'COMMIT WORK' or 'ROLLBACK WORK' statement. When the

application ends one transaction, another transaction is
automatically started on execution of the next statement.
Examples

The following example, within a stored procedure, begins a

transaction which updates the Amount_Owed column in the Billing
table. This work is committed; another transaction updates the
Amount_Paid column and sets it to zero. The final COMMIT
WORK statement ends the second transaction.
START TRANSACTION;
UPDATE Billing B
SET Amount_Owed = Amount_Owed - Amount_Paid
WHERE Student_ID IN
(SELECT DISTINCT E.Student_ID
FROM Enrolls E, Billing B
WHERE E.Student_ID = B.Student_ID);
COMMIT WORK;
START TRANSACTION;
UPDATE Billing B
SET Amount_Paid = 0
WHERE Student_ID IN
(SELECT DISTINCT E.Student_ID
FROM Enrolls E, Billing B
WHERE E.Student_ID = B.Student_ID);
COMMIT WORK;

See Also

COMMIT on page 3-44

CREATE PROCEDURE on page 3-66
ROLLBACK on page 3-197

3-265

SQL Syntax Reference

UNION
Remarks

SELECT statements that use UNION or UNION ALL allow you to

obtain a single result table from multiple SELECT queries. UNION
queries are suitable for combining similar information contained in
more than one data source.
UNION eliminates duplicate rows. UNION ALL preserves duplicate
rows. Using the UNION ALL option is recommended unless you
require duplicate rows to be removed.
With UNION, the Pervasive PSQL Engine orders the entire result set
which, for large tables, can take several minutes. UNION ALL
eliminates the need for the sort.
The Pervasive PSQL database engine does not support
LONGVARBINARY columns in UNION statements.
LONGVARCHAR is limited to 65500 bytes in UNION statements.
The operator UNION cannot be applied to any SQL statement that
references one or more views.
The two query specifications involved in a union must be
compatible. Each query must have the same number of columns and
the columns must be of compatible data types.
You may use column names from the first SELECT list in the ORDER
BY clause of the SELECT statement that follows the UNION
keyword. (Ordinal numbers are also allowed to indicate the desired
columns.) For example, the following statements are valid:
SELECT c1, c2, c3 FROM t1 UNION SELECT c4, c5, c6 FROM
t2 ORDER BY t1.c1, t1.c2, t1.c3
SELECT c1, c2, c3 FROM t1 UNION SELECT c4, c5, c6 FROM
t2 ORDER BY 1, 2, 3

You may also use aliases for the column names:

SELECT c1 x, c2 y, c3 z FROM t1 UNION SELECT c1, c2, c3
FROM t2 ORDER BY x, y, z
SELECT c1 x, c2 y, c3 z FROM t1 a UNION SELECT c1, c2,
c3 FROM t1 b ORDER BY a.x, a.y, a.z

Aliases must differ from any table names and column names in the
query.

3-266

Grammar Statements

Examples

The following example lists the ID numbers of each student whose

last name begins with 'M' or who has a 4.0 grade point average. The
result table does not include duplicate rows.
SELECT Person.ID FROM Person WHERE Last_name LIKE M%
UNION SELECT Student.ID FROM Student WHERE Cumulative_
GPA = 4.0

The next example lists the column id in the person table and the
faculty table including duplicate rows.
SELECT person.id FROM person UNION ALL SELECT faculty.id
from faculty

The next example lists the ID numbers of each student whose last
name begins with 'M' or who has a 4.0 grade point average. The
result table does not include duplicate rows and orders the result set
by the first column
SELECT Person.ID FROM Person WHERE Last_name LIKE M%
UNION SELECT Student.ID FROM Student WHERE Cumulative_
GPA = 4.0 ORDER BY 1

It is common to use the NULL scalar function to allow a UNION

select list to have a different number of entries than the parent select
list. To do this, you must use the CONVERT function to force the
NULL to the correct type.
CREATE TABLE t1 (c1 INTEGER, c2 INTEGER)
INSERT INTO t1 VALUES (1,1)
CREATE TABLE t2 (c1 INTEGER)
INSERT INTO t2 VALUES (2)
SELECT c1, c2 FROM t1
UNION SELECT c1, CONVERT(NULL(),sql_integer)FROM t2

See Also

SELECT on page 3-202

3-267

SQL Syntax Reference

UNIQUE
Remarks

To specify that the index not allow duplicate values, include the
UNIQUE keyword. If the column or columns that make up the index
contains duplicate values when you execute the CREATE INDEX
statement with the UNIQUE keyword, Pervasive PSQL returns
Status Code 5 and does not create the index.
Note You should not include the UNIQUE keyword in the list of
index attributes following the column name you specify; the
preferred syntax is CREATE UNIQUE INDEX.

See Also

ALTER TABLE on page 3-10

CREATE INDEX on page 3-59
CREATE TABLE on page 3-80

3-268

Grammar Statements

UPDATE
The UPDATE statement allows you to modify column values in a
database.
Syntax

UPDATE < table-name | view-name > [ alias-name ]

SET column-name = < NULL | DEFAULT | expression | subquery-expression
> [ , column-name = ... ]
[ FROM table-reference [, table-reference ] ...
[ WHERE search-condition ]
table-name ::= user-defined-name
view-name ::= user-defined-name
alias-name ::= user-defined-name

(Alias-name is not allowed if a FROM clause

is used. See FROM Clause on page 3-272.)

table-reference ::= { OJ outer-join-definition }

OUTER ]
search-condition ::= search-condition AND search-condition

3-269

SQL Syntax Reference

[ OUTER ]
table-subquery ::= query-specification [ [ UNION [ ALL ]
query-specification ]... ]
subquery-expression ::= ( query-specification )

Remarks

INSERT, UPDATE, and DELETE statements behave in an atomic

manner. That is, if an insert, update, or delete of more than one row
fails, then all insertions, updates, or deletes of previous rows by the
same statement are rolled back.
In the SET clause of an UPDATE statement, you may specify a subquery. This feature allows you to update information in a table based
on information in another table or another part of the same table.
You may specify the keyword DEFAULT to set the value to the default
value defined for the given column. If no default value is defined,
Pervasive PSQL uses NULL or pseudo-null value if the column is
nullable, otherwise it returns an error. See also, further information
on DEFAULT found in INSERT on page 3-166.
The UPDATE statement can update only a single table at a time.
UPDATE can relate to other tables via a subquery in the SET clause.
This can be a correlated subquery that depends in part on the
contents of the table being updated, or it can be a non-correlated
subquery that depends only on another table.
Correlated Subquery
UPDATE t1 SET t1.c2 = (SELECT t2.c2 FROM t2 WHERE t2.c1
= t1.c1)

Non-correlated Subquery
UPDATE t1 SET t1.c2 = (SELECT SUM(t2.c2) FROM t2 WHERE
t2.c1 = 10)

The same logic is used to process pure SELECT statements and

subqueries, so the subquery can consist of any valid SELECT
statement. There are no special rules for subqueries.
If SELECT within an UPDATE returns no rows, then the UPDATE
inserts NULL. If the given column(s) is/are not nullable, then the

3-270

Grammar Statements

UPDATE fails. If select returns more than one row, then UPDATE
fails.
An UPDATE statement does not allow the use of join tables in the
statement. Instead, use a correlated subquery in the SET clause as
follows:
UPDATE t1 SET t1.c2 = (SELECT t2.c2 FROM t2 WHERE t2.c1
= t1.c1)

All data types for data created prior to Pervasive.SQL 2000 (legacy
data) report back as nullable. This means that you can UPDATE
NULL into any legacy column type without pseudo-NULL
conversion. The following data types are treated as pseudo-NULL by
default:
Date

Decimal

Money

NumericSA

NumericSTS

Timestamp

Numeric

Normally, when you convert a legacy column to pseudo-NULL, you

lose one of the binary values, forfeiting it so that you can query the
column for NULL. These data types, however, because of their
design, have a different, unique internal value for NULL in addition
to their normal data range. With these data types, no binary values
are lost if they are converted to NULL so there is no harm
considering them as pseudo-NULL by default.
The rest of the data types are considered legacy nullable, meaning
that NULL may be updated into them. When values are queried,
however, the non-NULL binary equivalent is returned. This same
binary equivalent must be used in WHERE clauses to retrieve
specific values.
The binary equivalents are:

0 for Binary types

Empty string from string and BLOB types (legacy types LVAR
and NOTE)
Note The maximum length for a single literal string is 15,000

bytes. If you need to enter data longer than this, see Long Data
on page 3-168 for a useful tip.

3-271

SQL Syntax Reference

FROM Clause
Some confusion may arise pertaining to the optional FROM clause
and references to the table being updated (referred to as the update
table). If the update table occurs in the FROM clause, then one of
the occurrences is the same instance of the table being updated.
For example, in the statement UPDATE t1 SET c1 = 1 FROM t1,
t2 WHERE t1.c2 = t2.c2, the t1 immediately after UPDATE is the
same instance of table t1 as the t1 after FROM. Therefore, the
statement is identical to UPDATE t1 SET c1 = 1 FROM t2 WHERE
t1.c2 = t2.c2.
If the update table occurs in the FROM clause multiple times, one
occurrence must be identified as the same instance as the update
table. The FROM clause reference that is identified as the same
instance as the update table is the one that does not have a specified
alias.
Therefore, the statement UPDATE t1 SET t1.c1 = 1 FROM t1 a,
t1 b WHERE a.c2 = b.c2 is invalid because both instances of t1 in
the FROM clause contain an alias. The following version is valid:
UPDATE t1 SET t1.c1 = 1 FROM t1, t1 b WHERE t1.c2 = b.c2.

The following conditions apply to the FROM clause:

If the UPDATE statement contains an optional FROM clause,

the table reference prior to the FROM clause cannot have an alias
specified. For example, UPDATE t1 a SET a.c1 = 1 FROM t2
WHERE a.c2 = t2.c2 returns the following error:
SQL_ERROR (-1)
SQLSTATE of 37000
[Pervasive][ODBC Client Interface][LNA][Pervasive]
[ODBC Engine Interface]Table alias not allowed in
UPDATE/DELETE statement with optional FROM.

A valid version of the statement is UPDATE t1 SET t1.c1 = 1

FROM t2 WHERE t1.c2 = t2.c2 or UPDATE t1 SET t1.c1 = 1
FROM t1 a, t2 WHERE a.c2 = t2.c2.

If more than one reference to the update table appears in the

FROM clause, then only one of the references can have a
specified alias. For example, UPDATE t1 SET t1.c1 = 1 FROM
t1 a, t1 b WHERE a.c2 = b.c2 returns the following error:
SQL_ERROR (-1)
SQLSTATE of 37000 and

3-272

Grammar Statements
[Pervasive][ODBC Client Interface][LNA][Pervasive]
[ODBC Engine Interface] The table t1 is
ambiguous.

In the erroneous statement, assume that you want table t1

with alias a to be the same instance of the update table. A valid
version of the statement would then be UPDATE t1 SET t1.c1
= 1 FROM t1, t1 b WHERE t1.c2 = b.c2.

Examples

The FROM clause is supported in an UPDATE statement only at

the session level. The FROM clause is not supported if the
UPDATE statement occurs within a stored procedure.

The following examples updates the record in the faculty table and
sets salary as 95000 for ID 103657107.
UPDATE Faculty SET salary = 95000.00 WHERE ID = 103657107

The following examples show how to use the DEFAULT keyword.

UPDATE t1 SET c2 = DEFAULT WHERE c2 = 'bcd'
UPDATE t1 SET c1 = DEFAULT, c2 = DEFAULT

The following example changes the credit hours for Economics 305
in the course table from 3 to 4.
UPDATE Course SET Credit_Hours = 4 WHERE Name = 'ECO 305'

The following example updates the address for a person in the

Person table:
UPDATE Person p
SET p.Street = '123 Lamar',
p.zip = '78758',
p.phone = 5123334444
WHERE p.ID = 131542520

Subquery Example A
Two tables are created and rows are inserted. The first table, t5, is
updated with a column value from the second table, t6, in each row
where table t5 has the value 2 for column c1. Because there is more
than one row in table t6 containing a value of 3 for column c2, the

3-273

SQL Syntax Reference

first UPDATE fails because more than one row is returned by the
subquery. This result occurs even though the result value is the same
in both cases. As shown in the second UPDATE, using the
DISTINCT keyword in the subquery eliminates the duplicate results
and allows the statement to succeed.
CREATE
CREATE
INSERT
INSERT

TABLE t5 (c1 INT, c2 INT)

TABLE t6 (c1 INT, c2 INT)
INTO t5(c1, c2) VALUES (1,3)
INTO t5(c1, c2) VALUES (2,4)

INSERT
INSERT
INSERT
SELECT

INTO t6(c1, c2) VALUES (2,3)

INTO t6(c1, c2) VALUES (1,2)
INTO t6(c1, c2) VALUES (3,3)
* FROM t5

Results:
c1
---------1
2

c2
----3
4

UPDATE t5 SET t5.c1=(SELECT c2 FROM t6 WHERE c2=3) WHERE

t5.c1=2 Note that the query fails
UPDATE t5 SET t5.c1=(SELECT DISTINCT c2 FROM t6 WHERE
c2=3) WHERE t5.c1=2 Note that the query succeeds
SELECT * FROM t5

Results:
c1
---------1
3

c2
----3
4

Subquery Example B
Two tables are created and a variety of valid syntax examples are
demonstrated. Note the cases where UPDATE fails because the
subquery returns more than one row. Also note that UPDATE
succeeds and NULL is inserted if the subquery returns no rows
(where NULL values are allowed).
CREATE TABLE t1 (c1 INT, c2 INT)
CREATE TABLE t2 (c1 INT, c2 INT)
INSERT INTO t1 VALUES (1, 0)

3-274

Grammar Statements
INSERT
INSERT
INSERT
INSERT

INTO
INTO
INTO
INTO

t1
t1
t2
t2

VALUES
VALUES
VALUES
VALUES

(2,
(3,
(1,
(2,

0)
0)
100)
200)

UPDATE t1 SET t1.c2 = (SELECT SUM(t2.c2) FROM t2)

UPDATE t1 SET t1.c2 = 0
UPDATE t1 SET t1.c2 = (SELECT t2.c2 FROM t2 WHERE t2.c1
= t1.c1)
UPDATE
UPDATE
UPDATE
UPDATE

t1
t1
t1
t1

SET
SET
SET
SET

t1.c2
t1.c2
t1.c2
t1.c2

=
=
=
=

@@IDENTITY
@@ROWCOUNT
(SELECT @@IDENTITY)
(SELECT @@ROWCOUNT)

UPDATE t1 SET t1.c2 = (SELECT t2.c2 FROM t2) update fails

INSERT INTO t2 VALUES (1, 150)
INSERT INTO t2 VALUES (2, 250)
UPDATE t1 SET t1.c2 = (SELECT t2.c2 FROM t2 WHERE t2.c1
= t1.c1) update fails
UPDATE t1 SET t1.c2 = (SELECT t2.c2 FROM t2 WHERE t2.c1
= 5) Note that the update succeeds, NULL is inserted
for all rows of t1.c2
UPDATE t1 SET t1.c2 = (SELECT SUM(t2.c2) FROM t2 WHERE
t2.c1 = t1.c1)

The following example creates table t1 and t2 and populates them

with data. The UPDATE statement uses a FROM clause to . The
SELECT
DROP table t1
CREATE table t1 (c1 integer, c2 integer)
INSERT INTO t1 VALUES (0, 10)
INSERT INTO t1 VALUES (0, 10)
INSERT INTO t1 VALUES (2, 20)
INSERT INTO t1 VALUES (2, 20)
DROP table t2
CREATE table t2 (c1 integer, c2 integer)
INSERT INTO t2 VALUES (2, 20)
INSERT INTO t2 VALUES (2, 20)
INSERT INTO t2 VALUES (3, 30)
INSERT INTO t2 VALUES (3, 30)
UPDATE t1 SET t1.c1 = 1 FROM t2 WHERE t1.c2 = t2.c2
SELECT * FROM t1

3-275

SQL Syntax Reference

See Also

ALTER TABLE on page 3-10

CREATE PROCEDURE on page 3-66
CREATE TRIGGER on page 3-103
DEFAULT on page 3-116
GRANT on page 3-149
INSERT on page 3-166

3-276

Grammar Statements

UPDATE (positioned)
The positioned UPDATE statement updates the current row of a
rowset associated with an SQL cursor.
Syntax

UPDATE [ table-name ] SET column-name = proc-expr [ , column-name = procexpr ]...

WHERE CURRENT OF cursor-name
table-name ::= user-defined-name
cursor-name ::= user-defined-name

Remarks

This statement is allowed in stored procedures, triggers, and at the

session level.
Note Even though positioned UPDATE is allowed at the session

level, the DECLARE CURSOR statement is not. Use the

SQLGetCursorName() API to obtain the cursor name of the
active result set.
The table-name may be specified in the positioned UPDATE
statement only when used at the session level. Table-name
cannot be specified with a stored procedure or trigger.

Examples

The following sequence of statements provide the setting for the

positioned UPDATE statement. The required statements for a
positioned UPDATE are DECLARE CURSOR, OPEN CURSOR,
and FETCH FROM cursorname.
The positioned UPDATE statement in this example updates the
name of the course HIS 305 to HIS 306.
CREATE PROCEDURE UpdateClass();
BEGIN
DECLARE :CourseName CHAR(7);
DECLARE :OldName CHAR(7);
DECLARE c1 CURSOR FOR SELECT name FROM course WHERE
name = :CourseName FOR UPDATE;
SET :CourseName = 'HIS 305';

3-277

SQL Syntax Reference

OPEN c1;
FETCH NEXT FROM c1 INTO :OldName;
UPDATE SET name = 'HIS 306'
END;

See Also

CREATE PROCEDURE on page 3-66

CREATE TRIGGER on page 3-103

3-278

WHERE CURRENT OF c1;

Grammar Statements

USER
Remarks

The USER keyword returns the current user name (such as Master)
for each row returned by the SELECT restriction.

Example

The following examples return the user name from the course table.
SELECT USER FROM course
-- returns 145 instances of Master (the table contains 145 rows)

SELECT DISTINCT USER FROM course

-- returns 1 instance of Master

See Also

SELECT on page 3-202

SET SECURITY on page 3-250

3-279

SQL Syntax Reference

WHILE
Use a WHILE statement is used to control flow. It allows code to be
executed repeatedly as long as the WHILE condition is true.
Optionally, you may use the WHILE statement with DO and END
WHILE.

Note You cannot use a mixed syntax for the WHILE statement.

You may use either WHILE with DO and END WHILE, or only
WHILE.
If you are using multiple statements with a WHILE condition,
you must use BEGIN and END to indicate the beginning and
ending of the statement blocks.

Syntax

[ label-name : ] WHILE proc-search-condition [ DO ] [ proc-stmt [; procstmt ] ]... [ END WHILE ][ label-name ]

Remarks

A WHILE statement can have a beginning label (the statement is

referred to as a labeled WHILE statement).

Examples

The following example increments the variable vInteger by 1 until it

reaches a value of 10, when the loop ends.
WHILE (:vInteger < 10) DO
SET :vInteger = vInteger + 1;
END WHILE

See Also

CREATE PROCEDURE on page 3-66

CREATE TRIGGER on page 3-103

3-280

Grammar Statements

Grammar Element Definitions

The following is an alphabetical summary of the element definitions
used in the grammar syntax section:
alter-options ::= alter-option-list1 | alter-option-list2
alter-option-list1 ::= alter-option |(alter-option [, alter-option ]...)
alter-option ::= ADD [

COLUMN ]

column-definition

ALTER [ COLUMN ] column-definition

DROP [ COLUMN ] column-name
DROP CONSTRAINT constraint-name
DROP PRIMARY KEY
MODIFY [ COLUMN ] column-definition

PSQL_MOVE [ COLUMN ] column-name TO [ [

PSQL_PHYSICAL ] PSQL_POSITION ] new-column-position |
RENAME COLUMN column-name TO new-column-name

alter-option-list2 ::=

as-or-semicolon

::= AS | ;

before-or-after ::=

BEFORE | AFTER

call-arguments ::= positional-argument [ , positional-argument ]...

NOT NULL
| UNIQUE
| PRIMARY KEY
| REFERENCES table-name [ (

col-constraint ::=

column-name ) ] [ referential-actions ]

collation-name ::= 'string' | user-defined-name

column-constraint ::= [

CONSTRAINT

constraint-name ] col-constraint

column-definition ::= column-name data-type [ DEFAULT Expression ] [

column-constraint [ column-constraint ]... [CASE | COLLATE
collation-name ]
column-name ::= user-defined-name
commit-statement

::= see COMMIT statement

comparison-operator ::= < | > | <= | >= | = | <> | !=

3-281

SQL Syntax Reference

constraint-name ::= user-defined-name
correlation-name ::= user-defined-name
cursor-name

::= user-defined-name

data-type ::= data-type-name [ (precision [ , scale ] ) ]

data-type-name ::=

see Pervasive PSQL Supported Data Types on page A-2

db-name ::= user-defined-name

Expression::= expression - expression

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|

expression + expression
expression * expression
expression / expression
expression & expression
expression | expression
expression ^ expression
( expression )
-expression
+expression
~expression
?
literal
scalar-function
{ fn scalar-function }
USER

literal ::= 'string'

|
|
|
|

number
{ d 'date-literal' }
{ t 'time-literal' }
{ ts 'timestamp-literal' }

scalar-function :: =

See Scalar Functions on page 5-1

expression-or-subquery ::= expression | ( query-specification )

fetch-orientation

::= | NEXT

group-name ::= user-defined-name

index-definition

::= ( index-segment-definition [ , index-segment-definition

]... )
index-segment-definition

3-282

::= column-name [ ASC | DESC ]

Grammar Statements
index-name

::= user-defined-name

ins-upd-del ::=

INSERT | UPDATE | DELETE

insert-values ::= values-clause

query-specification

join-definition ::= table-reference [

condition

| table-reference

INNER ] JOIN

CROSS JOIN

table-reference

search-

table-reference

| outer-join-definition
label-name

::= user-defined-name

literal ::= 'string'

| number
| { d 'date-literal' }
| { t 'time-literal' }
| { ts 'timestamp-literal' }
order-by-expression ::= expression [

CASE | COLLATE

collation-name ] [

ASC | DESC ]
outer-join-definition ::= table-reference outer-join-type JOIN table-reference
ON search-condition

LEFT [ OUTER ]| RIGHT [ OUTER ] | FULL

OUTER ]

outer-join-type ::=

parameter ::= parameter-type-name data-type

proc-expr ]

[ DEFAULT proc-expr | =

SQLSTATE

parameter-type-name ::= parameter-name

| parameter-type parameter-name
| parameter-name parameter-type
parameter-type
parameter-name

::= IN | OUT | INOUT | IN_OUT

::= [ : ] user-defined-name

password ::= user-defined-name | 'string'

positional-argument ::= expression
precision ::= integer

3-283

SQL Syntax Reference

predicate ::= expression [

NOT ] BETWEEN

expression

AND

expression

| expression comparison-operator expression-or-subquery

NOT ] IN ( query-specification )
NOT ] IN ( value [ , value ]... )
expression [ NOT ] LIKE value
expression IS [ NOT ] NULL
expression comparison-operator ANY ( query-specification )
expression comparison-operator ALL ( query-specification )
EXISTS ( query-specification )

::= same as normal expression but does not allow IF expression,

or ODBC-style scalar functions

proc-expr

::= same as normal search-condition, but does not

allow any expression that includes a subquery.

proc-search-condition

::= [ label-name : ] BEGIN [ ATOMIC ] [ proc-stmt

[ ; proc-stmt ]... ] END [ label-name ]

proc-stmt

| CALL procedure-name ( proc-expr [ , proc-expr ]... )

3-284

Grammar Statements

WHILE

proc-search-condition proc-stmt

UPDATE ]
query-specification ::= ( query-specification )

| SELECT [ ALL | DISTINCT ] [ top-clause ] select-list

FROM table-reference [ , table-reference ]...
[ WHERE search-condition ]
[ GROUP BY expression [ , expression ]...
[ HAVING search-condition ] ]
referencing-alias ::= OLD [
correlation-name ]

NEW [ AS ]

AS ]

correlation-name [

NEW [ AS ]

OLD [ AS ]

correlation-name ]

3-285

SQL Syntax Reference

referential-actions ::= referential-update-action [ referential-delete-action ]

| referential-delete-action [ referential-update-action ]
referential-update-action ::=

ON UPDATE RESTRICT

ON DELETE CASCADE
| ON DELETE RESTRICT

referential-delete-action ::=

::= see RELEASE statement

release-statement
result

::= user-defined-name data-type

rollback-statement
savepoint-name

::= see ROLLBACK WORK statement

::= user-defined-name

scalar-function ::= see Scalar Function list

scale ::= integer
search-condition ::= search-condition

| search-condition
|

NOT

AND

search-condition

| ( search-condition )
| predicate
select-item ::= expression [ [

AS ]

alias-name ] | table-name . *

select-list ::= * | select-item [ , select-item ]...

set-function ::=

|
|
|
|
|

sqlstate-value

::= 'string'

table-constraint-definition ::= [
constraint

CONSTRAINT

constraint-name ] table-

UNIQUE (column-name [ , column-name ]... )

PRIMARY
KEY ( column-name [ , column-name ]... )
|

table-constraint ::=

3-286

Grammar Statements
| FOREIGN KEY ( column-name [ ,
REFERENCES table-name

column-name ] )

[ ( column-name [ , column-name ]... ) ]

[ referential-actions ]
table-element ::= column-definition

| table-constraint-definition
table-expression ::=

FROM table-reference [ , table-reference ]...

[ WHERE search-condition ]
[ GROUP BY expression [ , expression ]...
[ HAVING search-condition ]
table-name ::= user-defined-name

ALL
SELECT [ ( column-name [ , column-name ]... ) ]
UPDATE [ ( column-name [ , column-name ]... ) ]
INSERT [ ( column-name [ , column-name ]... ) ]
DELETE
ALTER
REFERENCES

table-privilege ::=

|
|
|
|
|
|

table-reference ::= {

outer-join-definition }

| [db-name.]table-name [ [

AS ]

alias-name ]

| join-definition
| ( join-definition )
transaction-statement

::= commit-statement

| rollback-statement
| release-statement
trigger-name ::= user-defined-name
user-password ::= user-name [ : ] password
user-group-name ::= user-name | group-name
user-name ::= user-defined-name
value ::= literal |

USER | ?

3-287

SQL Syntax Reference

value-list ::= ( value [ , value ]... )
values-clause ::= DEFAULT
expression ]... )
variable-name

VALUES | VALUES (

expression [ ,

::= user-defined-name

view-name ::= user-defined-name

SQL Statement
List

Predicate

SqlStatementList is defined as:

A predicate is defined as:

Expression CompareOperator Expression

|Expression [ NOT ] BETWEEN Expression

3-288

AND

Expression

Grammar Statements
|'(' Predicate ')'CompareOperator ::= '=' | '>=' | '>' | '<=' |
'<' | '<>' | '!='
|[ NOT ] IN value-list

Expression

An expression is defined as:

Number

|StringLiteral
|ColumnName
|VariableName
|NULL
|CONVERT '(' Expression ',' DataType ')'
|'-' Expression
|Expression '+' Expression
|Expression '-' Expression
|Expression '*' Expression
|Expression '/' Expression
|Expression '&' Expression
|'~' Expression
|Expression '|' Expression
|Expression '^' Expression
|FunctionName '(' [ ExpressionList ] ')'
|'(' Expression')'
|'{' D StringLiteral '}'
|'{' T StringLiteral '}'
|'{' TS StringLiteral '}'
|@:IDENTITY
|@:ROWCOUNT
|@@IDENTITY
|@@ROWCOUNT

An expression list is defined as:

ExpressionList ::= Expression [ , Expression ... ]

3-289

SQL Syntax Reference

Global Variables
Pervasive PSQL supports the following global variables:

@@IDENTITY on page 3-290

@@ROWCOUNT on page 3-292
@@SESSIONID on page 3-292
@@SPID on page 3-293

Global variables are prefaced with two at signs, @@. All global
variables are variables per connection. Each database connection has
its own @@IDENTITY, @@ROWCOUNT, and @@SPID values.
@@IDENTITY
This variable returns the value of the most recently inserted
IDENTITY column value (IDENTITY or SMALLIDENTITY). The
value is a signed integer value. The initial value is NULL.
This variable can only refer to a single column. If the target table
includes more than one IDENTITY column, the value of this
variable refers to the IDENTITY column that is the tables primary
key. If no such column exists, then the value of this variable refers to
the first IDENTITY column in the table.
If the most recent insert was to a table without an IDENTITY
column, then the value of @@IDENTITY is set to NULL.
Examples
SELECT @@IDENTITY

Returns NULL if no records have been inserted in the current

connection, otherwise returns the IDENTITY column value of the
most recently inserted row.
SELECT * FROM t1 WHERE @@IDENTITY = 12

Returns the most recently inserted row if it has an IDENTITY

column value of 12. Otherwise, returns no rows.

3-290

Global Variables
INSERT INTO t1(c2) VALUES (@@IDENTITY)

Inserts the IDENTITY value of the last row inserted into column C2
of the new row.
UPDATE t1 SET t1.c1 = (SELECT @@IDENTITY) WHERE t1.c1 =
@@IDENTITY + 10

Updates column C1 with the IDENTITY value of the last row

inserted, if the value of C1 is 10 greater than the IDENTITY column
value of the last row inserted.
UPDATE t1 SET t1.c1 = (SELECT NULL FROM t2 WHERE t2.c1 =
@@IDENTITY)

Updates column C1 with the value NULL if the value of C1 equals

the IDENTITY column value of the last row inserted.
The example below creates a stored procedure and calls it. The
procedure sets variable V1 equal to the sum of the input value and
the IDENTITY column value of the last row updated. The procedure
then deletes rows from the table anywhere column C1 equals V1. The
procedure then prints a message stating how many rows were
deleted.
CREATE PROCEDURE TEST (IN :P1 INTEGER);
BEGIN
DECLARE :V1 INTERGER;
SET :V1 = :P1 + @@IDENTITY;
DELETE FROM t1 WHERE t1.c1 = :V1;
IF (@@ROWCOUNT = 0) THEN
PRINT 'No row deleted';
ELSE
PRINT CONVERT(@@ROWCOUNT, SQL_CHAR) +
' rows deleted';
END IF;
END;
CALL TEST (@@IDENTITY)

3-291

SQL Syntax Reference

@@ROWCOUNT
This variable returns the number of rows that were affected by the
most recent operation in the current connection. The value is an
unsigned integer. The initial value is zero.
Examples
SELECT @@ROWCOUNT

Returns zero if no records were affected by the previous operation in

the current connection, otherwise returns the number of rows
affected by the previous operation.
CREATE TABLE t1 (c1 INTEGER, c2 INTEGER)
INSERT INTO t1 (c1, c2) VALUES (100,200)
INSERT INTO t1(c2) VALUES (100, @@ROWCOUNT)
SELECT * FROM t1
SELECT @@ROWCOUNT

Results:
2

The first SELECT generates two rows and shows that the value of
@@ROWCOUNT was 1 when it was used to insert a row. The second
SELECT returns 2 as the value of @@ROWCOUNT, that is, after the
first SELECT returned two rows.
Also see the example for @@IDENTITY.
@@SESSIONID
This variable returns an eight-byte integer value for the Pervasive
PSQL connection. The integer is a combination of a time value and
an incremental counter. This variable can be used to identify
uniquely each Pervasive PSQL connection.
@@SESSIONID requires a connection to the database engine to
return a value. If the connection to the database engine is lost, the
variable cannot return an identifier.
Example
SELECT @@SESSIONID

The example returns an integer identifier such as 26552653137523.

3-292

Global Variables

@@SPID
This variable (server process identifier) returns the identifier integer
value of the system thread for the Pervasive PSQL connection.
If the connection to the database engine is lost, SPID cannot return
an identifier. Instead, ODBC returns SqlState 08S01.
Example
SELECT @@SPID

The example returns an integer identifier such as 402.

3-293

SQL Syntax Reference

Other Characteristics
This section describes other characteristics of the SQL grammar. It is
divided into the following sections:

Temporary
Files

Temporary Files on page 3-294

Working with Literal Values on page 3-296
Working with NULL Values on page 3-296
Working with Binary Data on page 3-298
Creating Indexes on page 3-299
Closing an Open Table on page 3-299
Concurrency on page 3-300
Comma as Decimal Separator on page 3-300
OEM to ANSI Support on page 3-304

When Pervasive PSQL must generate a temporary table in order to

process a given query, it creates the file in a location determined by
the following rules.
First, Pervasive PSQL uses the path specified in the registry key string
value HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBC.INI\
PervasiveEngineOptions\TempFileDirectory.
If the registry entry is not defined, then Pervasive PSQL uses the path
specified in the TMP environment variable.
If the TMP environment variable is not defined, then Pervasive
PSQL uses the path specified in the TEMP environment variable.
If the TEMP environment variable is not defined, then Pervasive
PSQL uses the Windows directory for Windows 32-bit platforms.
For non-Windows 32-bit platforms, the current directory is used.
Pervasive PSQL deletes all temporary files needed to process a query
when it has completed processing the query. If the query is a SELECT
statement, then the temporary files exist as long as the result set is
active, that is, until the result set is freed by the calling application.

3-294

Other Characteristics

When are Temporary Files Created?

Pervasive PSQL uses three types of temporary files: in-memory, ondisk, and Btrieve (transactional interface).
In-memory Temporary File

In-memory temporary files are used for the following circumstances:

forward-only cursor
number of bytes in the temporary file is less than 250,000
SELECT statements with ORDER BY, GROUP BY, or
DISTINCT that do not use an index, and that have no BLOB or
CLOB in the ORDER BY, GROUP BY, or DISTINCT, and that
have no BLOB or CLOB in selection list with UNION.

On-disk Temporary File

On-disk temporary files are used for the following circumstances:

forward-only cursor
number of bytes in the temporary file is greater than 250,000
SELECT statements with ORDER BY, GROUP BY, or
DISTINCT that do not use an index, and that have no BLOB or
CLOB in the ORDER BY, GROUP BY, or DISTINCT, and that
have no BLOB or CLOB in selection list with UNION.

Btrieve Temporary File

Btrieve temporary files are used for the following circumstances:

Forward-only cursor with BLOB or CLOB in ORDER BY,

GROUP BY, or DISTINCT or with BLOB or CLOB in selection
list with UNION
Dynamic or static cursor with UNION queries or SELECT
statements with ORDER BY, GROUP BY, or DISTINCT that do
not use an index.

Pervasive PSQL does not create a Btrieve temporary file for each base
table in a static cursor SELECT query. Instead, each base table is
opened by using the MicroKernel to reserve pages in the file as a
static representation of the file. Any change made through a static
cursor cannot be seen by that cursor.

3-295

SQL Syntax Reference

Working with
Literal Values

Pervasive PSQL supports all of the standard ODBC literal formats.

This section provides some examples of the most common literal
formats.

Date Values on page 3-296

Time Values on page 3-297
Timestamp Values on page 3-297
Date Arithmetic on page 3-298

String Values
String constants may be expressed in SQL statements by
surrounding the given string of characters with single quotes. Single
quotes contained within the string itself require a preceding single
quote as an escape character.
Examples

In the first example, the apostrophe or single quote contained within

the string must be escaped by another single quote.
SELECT * FROM t1 WHERE c1 = Robertas Restaurant
SELECT STREET FROM address WHERE city LIKE san

Date Values
Date constants may be expressed in SQL statements as a character
string or embedded in a vendor string. The first case is treated as data
type SQL_CHAR and the vendor string representation is treated as a
value of type SQL_DATE. This becomes important when conversions
are attempted.
Pervasive PSQL partially supports extended SQL grammar, as
outlined in this function.
Pervasive PSQL supports the following date literal format: 'YYYYMM-DD'.
Dates may be in the range of year 0 to 9999.

3-296

Other Characteristics

Examples

The next two statements return all the classes whose start date is after
1995-06-05.
SELECT * FROM Class WHERE Start_Date > '1995-06-05'
SELECT * FROM Class WHERE Start_Date > {d '1995-06-05'}

Time Values
Pervasive PSQL supports the following time literal format:
'HH:MM:SS'.
Time constants may be expressed in SQL statements as a character
string or embedded in a vendor string. Character string
representation is treated as a string of type SQL_CHAR and the vendor
string representation as a value of type SQL_TIME.
Pervasive PSQL partially supports extended SQL grammar, as
outlined in this function.
Examples

The following two statements retrieve records from the class table
where the start time for the classes is 14:00:00.
SELECT * FROM Class WHERE Start_time = '14:00:00'
SELECT * FROM Class WHERE Start_time = {t '14:00:00'}

Timestamp Values
Timestamp constants may be expressed in SQL statements as a
character string or embedded in a vendor string. Pervasive PSQL
treats the character string representation as a string of type SQL_CHAR
and the vendor string representation as a value of type SQL_
TIMESTAMP.
Pervasive PSQL partially supports extended ODBC SQL grammar, as
outlined in this function.
Pervasive PSQL supports the following timestamp literal format:
'YYYY-MM-DD HH:MM:SS'

3-297

SQL Syntax Reference

Examples

The next two statements retrieve records from the Billing table where
the start day and time for the log is 1996-03-28 at 17:40:49.
SELECT * FROM Billing WHERE log = '1996-03-28 17:40:49'
SELECT * FROM Billing WHERE log = {ts '1996-03-28
17:40:49'}

Date Arithmetic
Pervasive PSQL supports adding or subtracting an integer from a
date where the integer is the number of days to add or subtract, and
the date is embedded in a vendor string. (This is equivalent to
executing a convert on the date).
Pervasive PSQL also supports subtracting one date from another to
yield a number of days.
Examples
SELECT * FROM person P, Class C WHERE p.Date_Of_Birth <
' 1973-09-05' AND c.Start_date >{d '1995-05-08'} + 30

Working with
NULL Values

Pervasive PSQL interprets a NULL as an unknown value. Thus, if

you try to compare two NULL values, they will compare as not equal.
An expression that evaluates to WHERE NULL=NULL returns FALSE.

Working with
Binary Data

Consider the following scenario: you insert the literal value '1' into a
BINARY(4) column named c1, in table t1. Next, you enter the
statement, SELECT * FROM t1 WHERE c1='1'.
The engine can retrieve data using the same binary format as was
used to input the data. That is, the SELECT example above works
properly and returns the value, 0x01000000, even though there isnt
a literal match.

3-298

Other Characteristics

Note The engine always adds a zero (0) to the front of odd-digit

binary values that are inserted. For example, if you insert the
value '010', then the value '0x00100000' is stored in the data file.
Currently, Pervasive PSQL does not support suffix 0x to denote
binary constants. Binary constants are a string of hexadecimal
numbers enclosed by single quotation marks.
This behavior is the same as SQL Server.

Creating
Indexes

The maximum column size for VARCHAR columns is 254 bytes if

the column does not allow Null values and 253 bytes if the column is
nullable.
The maximum column size for CHAR columns is 255 bytes if the
column does not allow Null values and 254 bytes if the column is
nullable.
The maximum Btrieve key size is 255. When a column is nullable and
indexed a segmented key is created with 1 byte for the null indicator
and a maximum 254 bytes from the column indexed. VARCHAR
columns differ from CHAR columns in that either length byte
(Btrieve lstring) or a zero terminating byte (Btrieve zstring) are
reserved, reducing the effective storage by 1 byte.

Closing an
Open Table

Calling SQLFreeStmt with the SQL_CLOSE option changes the

SQLSTATE but does not close the open tables used by the hStmt. To
close the tables currently used by hStmt, SQLFreeStmt must be called
with the SQL_DROP option.
In the following example, the Emp and Dept tables remain open:
SQLPrepare(hStmt, SELECT * FROM Emp, Dept, SQL_NTS)
SQLExecute(hStmt)
SQLFetch until SQL_No_Data_Found
SQLFreeStmt(hStmt, SQL_CLOSE)

3-299

SQL Syntax Reference

When SQLPrepare is subsequently called on the hStmt, the tables used

in the previous statement are closed. For example, when the
following call is made, both the Emp and Dept tables are closed by
Pervasive PSQL:
SQLPrepare(hStmt, SELECT * FROM Customer,SQL_NTS)

The following call would then close the table Customer:

SQLFreeStmt(hStmt, SQL_DROP)

Concurrency

The timeliness of data, dynamic or snapshot, is determined by

whether or not execution of a query results in a sort. Queries with
DISTINCT, GROUP BY, or ORDER BY result in a temporary sort
unless an index exists that satisfies the required ordering.
For those queries which do not result in a temporary sort, the data
fetched is from the data files. For those queries that result in a
temporary sort, the data fetched is from a temporary table. The
temporary table is built from the required data in the original data
file at SQLExecute time.
Note For some sort operations (for example, SELECT

statements where long data columns are included in the selectlist, or SELECT statements with GROUP BY), Pervasive PSQL
may use bookmarks that it assumes are persistent within a
SELECT statement. The situation may arise whereby another
application updates or deletes the row that a bookmark
references.
To avoid this situation, an application may set an exclusive lock
on the table being sorted through a call to SQLSetStmtOption,
with fOption = 1153 and vParam = 1.

Comma as
Decimal
Separator

3-300

Many locales use a comma to separate whole numbers from

fractional numbers within a floating point numeric field. For
example, these locales would use 1,5 instead of 1.5 to represent the
number one-and-one-half.

Other Characteristics

Pervasive PSQL supports both the period . and the comma , as

decimal separators. Pervasive PSQL accepts input values using the
period or the comma, based on the regional settings for the
operating system. By default, the database engine displays values
using the period.
Note When the decimal separator is not a period, numbers

appearing in SQL statements must be enclosed in quotes.

For output and display only, the session-level command SET
DECIMALSEPARATORCOMMA on page 3-235 can be used to
specify output (for example, SELECT results) that uses the comma
as the decimal separator. This command has no effect on data entry
or storage.
Client/Server Considerations
Support for the comma as decimal separator is based on the locale
setting in the operating system. Both the client operating system and
the server operating system have a locale setting. The expected
behavior varies according to both settings.

If either the server or client locale setting uses the comma as

decimal separator, then Pervasive PSQL accepts both periodseparated values and quoted comma-separated values.
If neither the server nor the client locale setting uses the comma
decimal separator, then Pervasive PSQL does not accept commaseparated values.

Changing the Locale Setting

Decimal separator information can be retrieved or changed only for
a machine running a Windows operating system. The decimal
setting for Linux cannot be configured, and it is set to a period. If you
have a Linux server engine and you want to use the comma as
decimal separator, you must ensure that all your client computers are
set to a locale that uses the decimal separator.

3-301

SQL Syntax Reference

To view or change your locale setting

From the Start menu, choose SettingsControl Panel.

In the Control Panel window, double-click Regional Settings.

On the Regional Settings tab, select the desired country.

You must stop and restart the Pervasive PSQL services.

Examples
Example A - Server locale uses the comma for decimal
separator

Clients locale uses comma , as decimal separator:

CREATE TABLE t1 (c1 DECIMAL(10,3), c2 DOUBLE)
INSERT INTO t1 VALUES (10.123, 1.232)
INSERT INTO t1 VALUES ('10,123', '1.232')
SELECT * FROM t1 WHERE c1 = 10.123
SELECT * FROM t1 FROM c1 = '10,123'

The above two SELECT statements, if executed from the client,

return:
10.123, 1.232
10.123, 1.232
SET DECIMALSEPARATORCOMMA=ON
SELECT * FROM t1 FROM c1 = '10,123'

The above SELECT statement, if executed from the client after

setting the decimal separator for display, returns:
10,123, 1,232

3-302

Other Characteristics

Clients locale uses period . as decimal separator, and these

statements are issued from a new connection (meaning default
behavior for SET DECIMALSEPARATORCOMMA):
CREATE TABLE t1 (c1 DECIMAL(10,3), c2 DOUBLE)
INSERT INTO t1 VALUES (10.123, 1.232)
INSERT INTO t1 VALUES ('10,123', '1.232')
SELECT * FROM t1 WHERE c1 = 10.123
SELECT * FROM t1 WHERE c1 = '10,123'

The above two SELECT statements, if executed from the client,

return:
10.123, 1.232
10.123, 1.232

Example B - Server locale uses the period for decimal separator

Clients locale uses comma , as DECIMAL separator:

Same as client using comma , in Example A.
Clients locale uses period . as DECIMAL separator:
CREATE TABLE t1 (c1 DECIMAL(10,3), c2 DOUBLE)
INSERT INTO t1 VALUES (10.123, 1.232)
INSERT INTO t1 VALUES ('10,123', '1,232')
-- error in assignment

SELECT * FROM t1 WHERE c1 = 10.123

SELECT * FROM t1 WHERE c1 = '10,123'
-- error in assignment

The first SELECT statement above, if executed from the client,

returns:
10.123, 1.232
SET DECIMALSEPARATORCOMMA=ON
SELECT * FROM t1 FROM c1 = 10.123

The above SELECT statement, if executed after setting the

decimal separator for display, returns:
10,123, 1,232

3-303

SQL Syntax Reference

OEM to ANSI
Support

Applications can now store or retrieve character data in the OEM

character set using Pervasive PSQL, while allowing the data to be
manipulated and displayed using the ANSI Windows character set.
The Pervasive ODBC driver translation DLL can perform all
necessary translations between the two character sets. This feature
can be turned on or off for each DSN. To access the switch, click
Options... on the Pervasive ODBC DSN Setup dialog box.
The Pervasive PSQL Control Center and the SQL Editor are fully
OEM-character aware if you use extended ASCII characters for
column or table names. Any character data that is passed to and from
the database is correctly translated between the OEM and ANSI
character sets.
If your application connects to the data source using
SQLDriverConnect, you can also specify the translation DLL using
the connection string option TRANSLATIONDLL=path_and_DLL_
name. The translation DLL name for Pervasive is W32BTXLT.DLL.
NOTE: The OEM to ANSI translation option is available only for
client or local engine DSNs.

3-304

chapter

Bitwise Operators

A Reference to Pervasive PSQL Bitwise Operators

This chapter discusses the following topics:

Overview on page 4-2

Bitwise AND (&) on page 4-3
Bitwise NOT (~) on page 4-5
Bitwise OR (|) on page 4-6
Bitwise Exclusive OR (^) on page 4-8
Truth Table on page 4-9

4-1

Bitwise Operators

Overview
Bitwise operators allow you to manipulate the bits of one or more
operands. The following are the types of bitwise operators:
Operator

Meaning

bitwise AND

bitwise NOT

bitwise OR

bitwise exclusive OR

The storage length of the expression is a key factor to be considered

while performing a bitwise operation.
The following are the data types supported for bitwise operations:

4-2

BIT
TINYINT
SMALLINT
INTEGER
BIGINT
UTINYINT
USMALLINT
UINTEGER
UBIGINT

Bitwise AND (&)

The bitwise AND operator performs a bitwise logical AND
operation between two operands.
The bitwise AND compares two bits and assigns a value equal to 1 to
the result only if the values of both the bits are equal to 1. Otherwise,
the bit in the result is set to 0. The AND operator, like all other
bitwise operators, takes only numeric values as its operands.

Syntax

expression & expression

Expression is any valid expression containing the integer data type,
which is transformed into a binary number for the bitwise operation.

Values
Returned

In a bitwise AND operation involving operands of different integer

data types, the argument of the smaller data type is converted to the
larger data type or to the data type that is immediately larger than the
larger of the two operands. For example, when performing an AND
operation involving smallint and integer, the smallint expression is
converted to integer.
If any of the operands involved in a bitwise AND operation is signed,
then the resultant value is also signed.

Examples

The & operator can be used in conjunction with the IF function to

find out whether a table is a system table or a user-defined table.
SELECT Xf$Name, IF(Xf$Flags & 16 = 16, 'System
table','User table') FROM X$File

4-3

Bitwise Operators

When this statement is run against the Demodata sample database,

the following results are returned:

4-4

X$File

System table

X$Field

System table

X$Index

System table

Billing

User table

Class

User table

Room

User table

Student

User table

Tuition

User table

Course

User table

Department

User table

Enrolls

User table

Faculty

User table

Person

User table

X$Proc

System table

Bitwise NOT (~)

The bitwise NOT operator inverts the bit values of any variable and
sets the corresponding bit in the result.

Syntax

~ expression
Expression is any valid expression containing the integer data type,
which is transformed into a binary number for the bitwise operation.

Values
Returned

The bitwise NOT operator returns the reverse of its single operand
of the integer data type. All 1s are converted to 0s, and all 0s are
converted to 1s. The bitwise NOT can take only numeric values as its
operands.

Examples

The following query performs the complement operation on a

numeric literal:
SELECT ~12

The result is -13.

The result is negative because the complement operator
complements the sign bit also. This causes Pervasive PSQL to treat
the result as a negative number.
Binary representation of 12 (shortint)

complement of 12

0000 0000 0000 1100

1111 1111 1111 0011

The 2's complement of the result number is 13. Therefore, the result
is -13.
Note The tilde (~) cannot be used as part of a user-defined

name.

4-5

Bitwise Operators

Bitwise OR (|)
The bitwise OR operator performs a bitwise logical OR operation
between two operands.
The bitwise OR compares two bits and assigns a value equal to 1 to
the result if the values of either or both the bits are equal to 1. If
neither bit in the input expressions has a value of 1, the bit in the
result is set to 0. The OR operator can take only numeric values as its
operands.

Syntax

expression | expression
Expression is any valid expression containing the integer data type,
which is transformed into a binary number for the bitwise operation.

Values
Returned

In a bitwise OR operation involving operands of different integer

data types, the argument of the smaller data type is converted to the
larger data type or to the data type that is immediately larger than the
larger of the two operands. For example, when performing an OR
operation involving smallint and integer, the smallint expression is
converted to integer.
If any of the operands involved in a bitwise OR operation is signed,
then the resultant value will also be signed.

Examples

This example first shows how to create a foreign key entry and a
primary key entry in the X$Index table, then how to obtain a list of
foreign and primary key constraints.
Execute of the following statements to create two entries in the
X$Index table (one for a foreign key and one for a primary key).
CREATE TABLE Employee
(
empid
IDENTITY NOT NULL PRIMARY KEY, -- Employee ID
empname VARCHAR(50) NOT NULL, -- Name of employee
supid
INTEGER
NULL -- Id of supervisor
)
ALTER TABLE Employee
ADD CONSTRAINT SupIdMustBeValid
FOREIGN KEY (supid) REFERENCES Employee(empid)
ON DELETE CASCADE

4-6

Bitwise OR (|)

Execute the following to obtain a list of all foreign key and primary
constraints on all tables in the database.
SELECT B.Xf$Name "Table name", C.Xe$Name "Column name",
IF (Xi$Flags & 8192 = 0, 'Primary key', 'Foreign key')
"Key type" from X$Index A, X$File B, X$Field C
WHERE (A.Xi$Flags & (16384 | 8192)) > 0 AND
A.Xi$File = B.Xf$Id AND
A.Xi$Field = C.Xe$Id

The executed statement results in the following:

Employee
Employee

empid
supid

Primary key
Foreign key

4-7

Bitwise Operators

Bitwise Exclusive OR (^)

The bitwise exclusive OR operator performs a bitwise logical
exclusive OR operation between two operands.
The bitwise exclusive OR compares two bits and assigns a value equal
to 0 to the result if the values of both the bits are either 0 or 1.
Otherwise, this operator sets the corresponding result bit to 1. The
exclusive OR operator can take only numeric values as its operands.

Syntax

expression ^ expression
Expression is any valid expression containing the integer data type,
which is transformed into a binary number for the bitwise operation.

Values
Returned

In a bitwise exclusive OR operation involving operands of different

integer data types, the argument of the smaller data type is converted
to the larger data type or to the data type that is immediately larger
than the larger of the two operands. For example, when performing
an exclusive OR operation involving smallint and integer, the
smallint expression is converted to integer.
If any of the operands involved in a bitwise exclusive OR operation is
signed, then the resultant value is also signed.

Examples

The following SQL query performs the exclusive OR on two numeric

literals:
SELECT 12 ^ 8

The result is 4.
The binary representation of 12 (as a shortint) is 0000 0000 0000
0110 and that of 8 is 0000 0000 0000 0100. Performing the exclusive
OR operation on these numbers yields the value 4:
0000 0000 0000 1100 ^ 0000 0000 0000 1000
= 0000 0000 0000 0100 (4)

Note The circumflex (^) cannot be used as part of a user-defined

name.

4-8

Truth Table

Truth Table
The following is the truth table for bitwise operations.
Table 4-1 Truth Table for Bitwise Operations
A

A&B

A|B

A^B

4-9

Bitwise Operators

4-10

chapter

Scalar Functions

A Reference to Pervasive PSQL Scalar Functions

This chapter discusses the following topics:

String Functions on page 5-2

Numeric Functions on page 5-6
Time and Date Functions on page 5-9
System Functions on page 5-16
Logical Functions on page 5-17
Conversion Functions on page 5-20

Pervasive PSQL supports ODBC scalar functions that may be

included in an SQL statement as a primary expression.

5-1

Scalar Functions

String Functions
String functions are used to process and manipulate columns that
consist of text information, such as CHAR or LONGVARCHAR data
types.
The string functions support multiple-byte character strings. (Note,
however, that CASE (string) does not support multiple-byte
character strings. The CASE (string) keyword assumes that the string
data is single-byte ASCII. See CASE (string) on page 3-39.)
Arguments denoted as string can be the name of column, a string
literal, or the result of another scalar function.
Table 5-1 String Functions

5-2

Function

Description

ASCII (string)

Returns the ASCII value of the left most

character of string

BIT_LENGTH (string)

Returns the length in bits of string

CHAR (code)

Returns the ASCII character corresponding

to ASCII value code. The argument must be
an integer value.

CHAR_LENGTH (string)

Returns the number of characters in string as

defined for the column. Blanks are
significant.

CHARACTER_LENGTH (string)

Same as CHAR_LENGTH.

CONCAT (string1, string2)

Returns a string that results from combining

string1 and string2.

LCASE or LOWER (string)

Converts all upper case characters in string

to lower case.

LEFT (string, count)

Returns the left most count of characters in

string. The value of count is an integer.

LENGTH (string)

Returns the number of characters in string.

Trailing spaces are counted in a VARCHAR
or LONGVARCHAR string. Trailing NULLs
are counted in a CHAR and
LONGVARCHAR string. The string
termination character is not counted.

String Functions

Table 5-1 String Functions continued

Function

Description

LOCATE (string1, string2 [, start ])

Returns the starting position of the first

occurrence of string1 within string2. The
search within string2 begins at the first
character position unless you specify a
starting position (start). The search begins at
the starting position you specify. The first
character position in string2 is 1. The string1
is not found, the function returns the value
zero.

LTRIM (string)

Returns the characters of string with leading

blanks removed.

OCTET_LENGTH (string)

Returns the length of string in octets (bytes).

POSITION (string1, string2)

Returns the position of string1 in string2. If

string1 does not exist in string2, a zero is
returned.

REPLACE (string1, string2,

string3)

Searches string1 for occurrences of string2

and replaces each with string3. Returns the
result. If no occurrences are found, string1 is
returned.

REPLICATE (string, count)

Returns a character string composed of

string repeated count times. The value of
count is an integer.

RIGHT (string, count)

Returns the right most count of characters in

string. The value of count is an integer.

RTRIM (string)

Returns the characters of string with trailing

blanks removed.

SPACE (count)

Returns a character string consisting of

count spaces.

STUFF (string1, start, length,

string2)

Returns a character string where length

characters in string1 beginning at position
start have been replaced by string2. The
values of start and length are integers.

SUBSTRING (string1, start,

length)

Returns a character string derived from

string1 beginning at the character position
specified by start for length characters.

UCASE or UPPER (string)

Converts all lower case characters in string

to upper case.

5-3

Scalar Functions

Queries containing a WHERE clause with scalar functions RTRIM

or LEFT can be optimized. For example, consider the following
query:
SELECT * FROM T1, T2 WHERE T1.C1 = LEFT(T2.C1, 2)

In this case, both sides of the predicate are optimized if T1.C1 and
T2.C2 are index columns. The predicate is the complete search
condition following the WHERE keyword. Depending on the size of
the tables involved in the join, the optimizer chooses the appropriate
table to process first.
LTRIM and RIGHT cannot be optimized if they are contained in a
complex expression on either side of the predicate.

Examples

The following example creates a new table with an integer and a

character column. It inserts 4 rows with values for the character
column only, then updates the integer column of those rows with the
ASCII character code for each character.
CREATE TABLE numchars(num INTEGER,chr CHAR(1) CASE)
INSERT INTO numchars (chr) VALUES('a')
INSERT INTO numchars (chr) VALUES('b')
INSERT INTO numchars (chr) VALUES('A')
INSERT INTO numchars (chr) VALUES('B')
UPDATE numchars SET num=ASCII(chr)
SELECT * FROM numchars

Results of SELECT:
num
---------97
98
65
66

chr
--a
b
A
B

SELECT num FROM numchars WHERE num=ASCII('a')

Results of SELECT:
num
-----97

5-4

String Functions

The following example concatenates the first and last names in the
Person table and results in "RooseveltBora".
SELECT CONCAT(First_name, Last_name) FROM Person WHERE
First_name = 'Roosevelt'

The next example changes the case of the first name to lowercase and
then to upper case, and results in "roosevelt", "ROOSEVELT".
SELECT LCASE(First_name),UCASE(First_name) FROM Person
WHERE First_name = 'Roosevelt'

The following example results in first name trimmed to three

characters beginning from left, the length as 9 and locate results 0.
This query results in "Roo", 9, 0
SELECT LEFT(First_name, 3),LENGTH(First_name),
LOCATE(First_name, 'a') FROM Person WHERE First_name =
'Roosevelt'

The following example illustrates use of LTRIM and RTRIM

functions on strings, results in "Roosevelt", "Roosevelt", "elt".
SELECT LTRIM(First_name),RTRIM(First_name),
RIGHT(First_name,3) FROM Person WHERE First_name =
'Roosevelt'

This substring lists up to three characters starting with the second

character in the first name as oos.
SELECT SUBSTRING(First_name,2, 3) FROM Person WHERE
First_name = 'Roosevelt'

5-5

Scalar Functions

Numeric Functions
Numeric functions are used to process and manipulate columns that
consist of strictly numeric information, such as decimal and integer
values.
Table 5-2 Numeric Functions

5-6

Function

Description

ABS (numeric_exp)

Returns the absolute (positive) value of

numeric_exp.

ACOS (float_exp)

Returns the arc cosine of float_exp as an

angle, expressed in radians.

ASIN (float_exp)

Returns the arc sine of float_exp as an

angle, expressed in radians.

ATAN (float_exp)

Returns the arc tangent of float_exp as

an angle, expressed in radians.

ATAN2 (float_exp1, float_exp2)

Returns the arc tangent of the x and y

coordinates, specified by float_exp1 and
float_exp2, respectively, as an angle,
expressed in radians.

CEILING (numeric_exp)

Returns the smallest integer greater than

or equal to numeric_exp.

COS (float_exp)

Returns the cosine of float_exp, where

float_exp is an angle expressed in
radians.

COT (float_exp)

Returns the cotangent of float_exp,

where float_exp is an angle expressed in
radians.

DEGREES (numeric_exp)

Returns the number of degrees

corresponding to numeric_exp radians.

EXP (float_exp)

Returns the exponential value of

float_exp.

FLOOR (numeric_exp)

Returns the largest integer less than or

equal to numeric_exp.

LOG (float_exp)

Returns the natural logarithm of

float_exp.

Numeric Functions

Table 5-2 Numeric Functions continued

Function

Description

LOG10 (float_exp)

Returns the base 10 logarithm of

float_exp.

MOD (integer_exp1, integer_exp2)

Returns the remainder (modulus) of

integer_exp1 divided by integer_exp2.

PI ( )

Returns the constant value Pi as a

floating point value.

POWER (numeric_exp, integer_exp)

Returns the value of numeric_exp to the

power of integer_exp.

RADIANS (numeric_exp)

Returns the number of radians

equivalent to numeric_exp degrees.

RAND (integer_exp)

Returns a random floating-point value

using integer_exp as the optional seed
value.

ROUND (numeric_exp, integer_exp)

Returns numeric_exp rounded to

integer_exp places right of the decimal
point. If integer_exp is negative,
numeric_exp is rounded to |integer_exp|
(absolute value of integer_exp) places to
the left of the decimal point.

SIGN (numeric_exp)

Returns an indicator of the sign of

numeric_exp. If numeric_exp is less than
zero, -1 is returned. If numeric_exp
equals zero, 0 is returned. If
numeric_exp is greater than zero, 1 is
returned.

SIN (float_exp)

Returns the sine of float_exp, where

float_exp is an angle expressed in
radians.

SQRT (float_exp)

Returns the square root of float_exp.

TAN (float_exp)

Returns the tangent of float_exp, where

float_exp is an angle expressed in
radians.

TRUNCATE (numeric_exp,
integer_exp)

Returns numeric_exp truncated to

integer_exp places right of the decimal
point. If integer_exp is negative,
numeric_exp is truncated to
|integer_exp| (absolute value) places to
the left of the decimal point.

5-7

Scalar Functions

Examples

The following example lists the modulus of the number and capacity
columns in a table named Room.
SELECT Number, Capacity, MOD(Number, Capacity) FROM
Room WHERE Building_Name = Faske Building and Type =
Classroom

The following example selects all salaries from a table named Faculty
that are evenly divisible by 100.
SELECT Salary FROM Faculty WHERE MOD(Salary, 100) = 0

5-8

Time and Date Functions

Date and time functions can be used to generate, process, and
manipulate data that consists of date or time data types, such as
DATE and TIME.

Inserting Time
and Date
Function
Values

If you wish to insert the value of a function into a table, one method
supported by all the time/date functions is to use a SELECT
subquery in your INSERT statement, as shown:
INSERT INTO t1 (c1, c2) SELECT CURRENT_DATE(),
CURRENT_TIME()

Some functions, such as CURDATE(), CURTIME(), and NOW(),

also support direct INSERT, as shown:
INSERT INTO t1 (c1) VALUES (CURDATE())

Table 5-3 Time and Date Functions

Function

Description

CURDATE ( )

Returns the current local date in this format: yyyy-mm-dd. Uses the
local clock time by default. If SET TIME ZONE has been called, then the
value of CURDATE() is determined by calculating UTC time/date from
the system clock and operating system locale setting, then adding the
displacement value specified with SET TIME ZONE.

CURRENT_DATE ( )

Returns the current UTC date in this format: yyyy-mm-dd

CURTIME ( )

Returns the current local time in this format: hh:mm:ss. Uses the local
clock time by default. If SET TIME ZONE has been called, then the value
of CURTIME() is determined by calculating UTC time/date from the
system clock and operating system locale setting, then adding the
displacement value specified with SET TIME ZONE.

CURRENT_TIME ( )

Returns the current UTC time in this format: hh:mm:ss

CURRENT_TIMESTAMP ( )

Returns the current UTC date and time as a timestamp value in this
format:
yyyy-mm-dd hh:mm:ss.sssssss

5-9

Scalar Functions

Table 5-3 Time and Date Functions continued

Function

Description

DATEADD (datepart, interval,

date_exp)

Returns a new DATETIME value based on adding an interval to a date.

For example, a datapart day, an interval of 11, and a date_exp of January
26, 2020, returns February 6, 2020.
Datepart specifies the part of the date to which interval is added, and
must be one of the following values.
year
quarter
month
day
dayofyear
week
hour
minute
second
millisecond
Interval specifies a positive or negative integer value used to increment
datepart. If interval contains a fractional portion, the fraction part is
ignored.
Date_exp is an expression that returns a DATETIME value, a value that
can be implicitly converted to a DATETIME value, or a character string
in a DATE format. See DATETIME on page A-13.

5-10

Time and Date Functions

Table 5-3 Time and Date Functions continued

Function

Description

DATEDIFF (datepart, start, end)

Returns an integer for the difference between the two dates. The integer
is the number of date and time boundaries crossed between the two
dates.
For example, suppose that table mytest has two columns,col1 and col2,
both of which are DATETIME. The value in col1 is 2000-01-01
11:11:11.234 and the value in col2 is 2004-09-11 10:10:10.211. The
following SELECT statement returns 56, because that is the difference
in months between col1 and col2: SELECT DATEDIFF(month, col1,
col2) as Month_Difference FROM mytest.
Datepart specifies the part of the date on which to calculate the
difference, and must be one of the following values.
year
quarter
month
day
dayofyear
week
hour
minute
second
millisecond
Start specifies the beginning date for the difference calculation. Start is
an expression that returns a DATETIME value or a Unicode character
string in a DATE format.
End specifies the ending date for the difference calculation. End is an
expression that returns a DATETIME value or a Unicode character string
in a DATE format.
Start is subtracted from end. An error is returned if the return value is
outside of the range for integer values. See Data Type Ranges on page
A-5.

5-11

Scalar Functions

Table 5-3 Time and Date Functions continued

Function

Description

DATENAME (datepart, date_exp)

Returns a character string (a VARCHAR) that represents the datepart of

date_exp. For example, a datepart month returns the name of the month
such as January, February, and so forth. A datepart weekday returns the
day of the week such as Monday, Tuesday, and so forth (Sunday = 1,
Saturday = 7).
Datepart the part of the date to return, and must be one of the following
values.
year
quarter
month
day
dayofyear
week
weekday
hour
minute
second
millisecond
Date_exp is an expression that returns a DATETIME value, a value that
can be implicitly converted to a DATETIME value, or a character string
in a DATE format. See DATETIME on page A-13.

DATEPART (datepart, date_exp)

Returns an integer that represents the datepart of date_exp. For

example, a datepart month returns an integer representing the month
(January = 1, December = 12). A datepart weekday returns an integer
representing the day of the week (Sunday = 1, Saturday = 7).
Datepart the part of the date to return, and must be one of the following
values.
year
quarter
month
day
dayofyear
week
weekday
hour
minute
second
millisecond
Date_exp is an expression that returns a DATETIME value, a value that
can be implicitly converted to a DATETIME value, or a character string
in a DATE format. See DATETIME on page A-13.

5-12

Time and Date Functions

Table 5-3 Time and Date Functions continued

Function

Description

DAYNAME (date_exp)

Returns a character string containing the data source-specific name of

the day (for example, Sunday through Saturday for a data source that
uses English, or Sonntag through Samstag for a data source that uses
German) for the day portion of date_exp.
Date_exp can be a DATE, TIMESTAMP literal, or a column containing
DATE, TIMESTAMP, or DATETIME data.

DAYOFMONTH (date_exp)

Returns the day of the month in date_exp as an integer in the range of 1

to 31. Date_exp can be a DATE, TIMESTAMP literal, or a column
containing DATE, TIMESTAMP, or DATETIME data.

DAYOFYEAR (date_exp)

Returns the day of the year based on the year field in date_exp as an
integer value in the range of 1-366.

EXTRACT (extract_field,
extract_source)

Returns the extract_field portion of the extract_source. The

extract_source argument is a date, time or interval expression.
The permitted values of extract_field are:
YEAR
MONTH
DAY
HOUR
MINUTE
SECOND
These values are returned from the target expression.

HOUR (time_exp)

Returns the hour as an integer in the rage of 0 to 23. Time_exp can be

a DATE, TIMESTAMP literal, or a column containing DATE,
TIMESTAMP, or DATETIME data.

MINUTE (time_exp)

Returns the minute as an integer in the range 0 to 59. Time_exp can be

a DATE, TIMESTAMP literal, or a column containing DATE,
TIMESTAMP, or DATETIME data.

MONTH (date_exp)

Returns the month as an integer in the range of 1 to 12. Date_exp can

be a DATE, TIMESTAMP literal, or a column containing DATE,
TIMESTAMP, or DATETIME data.

MONTHNAME (date_exp)

Returns a character string containing the data source-specific name of

the month (for example, September through December for a data source
that uses English, or Settembre through Dicembre for a data source that
uses Italian) for the month portion of date_exp. Date_exp can be a
DATE, TIMESTAMP literal, or a column containing DATE, TIMESTAMP,
or DATETIME data.

5-13

Scalar Functions

Table 5-3 Time and Date Functions continued

Function

Description

NOW ( )

Returns the current local date and time as a timestamp value in this
format:
yyyy-mm-dd hh:mm:ss.sssssss
Uses the local clock time by default. If SET TIME ZONE has been called,
then the value of NOW() is determined by calculating UTC time/date
from the system clock and operating system locale setting, then adding
the displacement value specified with SET TIME ZONE.

QUARTER (date_exp)

Returns the quarter in date_exp as an integer value in the range of 1- 4,

where 1 represents January 1 through March 31. Date_exp can be a
DATE, TIMESTAMP literal, or a column containing DATE, TIMESTAMP,
or DATETIME data.

SECOND (time_exp)

Returns the second as an integer in the range of 0 to 59. Time_exp can

be a DATE, TIMESTAMP literal, or a column containing DATE,
TIMESTAMP, or DATETIME data.

TIMESTAMPADD (interval,
integer_exp, timestamp_exp)

Returns the timestamp calculated by adding integer_exp intervals of

type interval to timestamp_exp.
The allowed values for interval are:
SQL_TSI_YEAR
SQL_TSI_QUARTER
SQL_TSI_MONTH
SQL_TSI_WEEK
SQL_TSI_DAY
SQL_TSI_HOUR
SQL_TSI_MINUTE
SQL_TSI_SECOND

TIMESTAMPDIFF (interval,
timestamp_exp1,
timestamp_exp2)

Returns the integer number of intervals of type interval by which

timestamp_exp2 is greater than timestamp_exp1.
The values allowed for interval are the same as for TIMESTAMPADD

WEEK (date_exp)

Returns the week of the year based on the week field in date_exp as an
integer in the range of 1 to 53. Date_exp can be a DATE, TIMESTAMP
literal, or a column containing DATE, TIMESTAMP, or DATETIME data.

YEAR (date_exp)

Returns the year as an integer value. The range depends on the data
source. Date_exp can be a DATE, TIMESTAMP literal, or a column
containing DATE, TIMESTAMP, or DATETIME data.

Examples

5-14

The following example shows how to insert values from time or date
functions. Some functions, such as CURDATE(), you can use
directly in an INSERT statement. Other functions, however, are not
supported in this manner. The method with the widest support is to

Time and Date Functions

use INSERT with SELECT. In the example below, the UTC time value
returned by CURRENT_TIME() is inserted into table T1:
INSERT INTO T1 (C1) SELECT CURRENT_TIME()

The following example illustrates the use of hour.

SELECT c.Name,c.Credit_Hours FROM Course c WHERE c.Name
= ANY (SELECT cl.Name FROM Class cl WHERE c.Name =
cl.Name AND c.Credit_Hours >(HOUR (Finish_Time Start_Time) + 1))

The following is an example of minute.

SELECT MINUTE(log) FROM billing

The following example illustrates the use of second.

SELECT SECOND(log) FROM billing
SELECT log FROM billing WHERE SECOND(log) = 31

The following example illustrates the use of NOW().

SELECT NOW() - log FROM billing

The following is a complex example that uses month, day, year, hour
and minute.
SELECT Name, Section, MONTH(Start_Date),
DAY(Start_Date), YEAR(Start_Date), HOUR(Start_Time),
MINUTE(Start_Time) FROM Class

The following example illustrates use of CURDATE().

SELECT ID, Name, Section FROM Class WHERE (Start_Date CURDATE()) <= 2 AND (Start_Date - CURDATE()) >= 0

The next example gives the day of the month and day of the week of
the start date of class from the class table.
SELECT DAYOFMONTH(Start_date), DAYOFWEEK(Start_date)
FROM Class
SELECT * FROM person WHERE YEAR(Date_Of_Birth) < 1970

5-15

Scalar Functions

System Functions
System functions provide information at a system level.
Table 5-4 System Functions

Examples

Function

Description

DATABASE ( )

Returns the current database name.

NEWID ( )

Creates a unique value for data type

uniqueidentifier

USER ( )

Returns the login name of the current

user.

The following examples show how to obtain the name of the current
user and database:
SELECT USER()
SELECT DATABASE()

The following example creates a column of data type

UNIQUEIDENTIFIER as the first column in new table "table1."
Setting a default value with the NEWID function provides a unique
value for "col1" in each new row within the table.
CREATE TABLE table1 (col1 UNIQUEIDENTIFIER DEFAULT
NEWID() NOT NULL, col2 INTEGER)
INSERT INTO table1 (col2) VALUES (1)
INSERT INTO table1 (col2) VALUES (2)
INSERT INTO table1 (col2) VALUES (3)

5-16

Logical Functions

Logical Functions
Logical functions are used to manipulate data based on certain
conditions.
Table 5-5 Logical Functions
Function

Description

COALESCE (expression1,
expression2 [, ... ] )

Returns the first non-null argument,

starting from the left in the expression
list.
See also COALESCE on page 3-41 for
additional details.

Examples

IF (predicate, expression1,
expression2)

Returns expression1 if predicate is true;

otherwise, returns expression2.

NULL ( )

Sets a column as NULL values.

IFNULL (exp, value)

If exp is NULL, value is returned. If exp is

not null, exp is returned. The possible
data type or types of value must be
compatible with the data type of exp.

ISNULL (exp, value)

Replaces NULL with the value specified

for value. Exp is the expression to check
for NULL. Value is the value returned if
exp is NULL. Exp is returned if it is not
NULL. The data type of value must be
compatible with the data type of exp.

NULLIF (exp1, exp2)

NULLIF returns exp1 if the two

expressions are not equivalent. If the
expressions are equivalent, NULLIF
returns a NULL value.

The COALESCE scalar function takes two or more arguments and

returns the first non-null argument, starting from the left in the
expression list.
select COALESCE(10, 'abc' + 'def')

Ten is treated as a SMALLINT and ResultType (SQL_SMALLINT,

SQL_VARCHAR) is SQL_SMALLINT. Hence, the result type is
SQL_SMALLINT.
The first parameter is 10, which can be converted to result type
SQL_SMALLINT. Therefore, the return value of this example is 10.

5-17

Scalar Functions

The system scalar functions IF and NULL are SQL extensions.

IF allows you to enter different values depending on whether the
condition is true or false. For example, if you want to display a
column with logical values as true or false instead of a binary
representation, you would use the following SQL statement:
SELECT IF(logicalcol=1, 'True', 'False')

The system scalar function NULL allows you to set a column as null
values. The syntax is:
NULL()

For example, the following SQL statement inserts a row in the Room
table with a NULL value for Capacity:
INSERT INTO Room VALUES (Young Building, 222, NULL(),
Lab)

The following example demonstrates how ISNULL returns a value.

CREATE TABLE t8 (c1 INT, c2 CHAR(10))
INSERT INTO t8 VALUES (100, 'string1')
SELECT c1, c2, ISNULL(c1, 1000), ISNULL(C2, 'a string')
from t8

The SELECT returns 100 and string1 because both c1 and c2

contain a value, not a NULL.
INSERT INTO t8 VALUES (NULL, NULL)
SELECT c1, c2, ISNULL(c1, 1000), ISNULL(C2, 'a string')
from t8

The SELECT returns 1000 and a string because both c1 and c2

contain a NULL.

The following statements demonstrate the IFNULL and NULLIF

scalar functions. You use these functions when you want to do
certain value substitution based on the presence or absence of
NULLs and on equality.
CREATE TABLE Demo (col1 CHAR(3))
INSERT INTO Demo VALUES ('abc')
INSERT INTO Demo VALUES (NULL)

5-18

Logical Functions
INSERT INTO Demo VALUES ('xyz')

Since the second row contains the NULL value, 'foo' is substituted
in its place.
SELECT IFNULL(col1, 'foo') FROM Demo

This results in three rows fetched from one column:

"abc"
"foo"
"xyz"
3 rows fetched from 1 column.

The first row contains abc, which matches the second argument of
the following NULLIF call.
SELECT NULLIF(col1, 'abc') FROM Demo

A NULL is returned in its place:

<Null>
<Null>
"xyz"
3 rows fetched from 1 column.

5-19

Scalar Functions

Conversion Functions
The conversion functions convert an expression to a data type. The
CONVERT function can convert data only to an ODBC data type.
Note that more than one Pervasive PSQL data type may be mapped
to the same ODBC type. For example, DECIMAL, CURRENCY, and
BIGINT are all mapped to the ODBC data type SQL_DECIMAL.
The CAST function converts an expression to a Pervasive PSQL
relational data type (provided that the expression can be converted
to the data type). The CAST function can convert binary zeros in a
string. For example, CAST(c1 AS BINARY(10)), where c1 is a
character column that contains binary zeros (NULLs).
You cannot CAST or CONVERT user-defined data types.
If both the input and the output are character strings, the output
from CAST or CONVERT has the same collation as the input string.

5-20

Conversion Functions

Table 5-6 Conversion Functions

Function

Description

CAST (exp AS type)

Converts exp to the type indicated

Type may be any of the Pervasive PSQL
relational data types as listed in the table
Pervasive PSQL Data Types and
Equivalent ODBC Data Types on page
A-2.

CONVERT (exp, type [, style ])

Converts exp to the type indicated. The

possible types are:
SQL_BIGINT
SQL_BINARY
SQL_BIT
SQL_CHAR
SQL_DATE
SQL_DATETIME
SQL_DECIMAL
SQL_DOUBLE
SQL_FLOAT
SQL_GUID
SQL_INTEGER
SQL_LONGVARCHAR
SQL_NUMERIC
SQL_REAL
SQL_SMALLINT
SQL_TIME
SQL_TIMESTAMP
SQL_TINYINT
SQL_VARCHAR
SQL_LONGVARBINARY
The optional parameter style applies
only to the DATETIME data type. Use of
the parameter truncates the milliseconds
portion of the DATETIME datat type. A
style value may be either "20" or "120."
Both values specify the ODBC canonical
format: yyyy-mm-dd hh:mi:ss. See
Examples below.

Examples

The following example casts a DATE to a CHAR.

CREATE TABLE u1(cdata DATE)
INSERT INTO u1 VALUES(curdate())
SELECT CAST(cdate as CHAR20) FROM u1

5-21

Scalar Functions

If the current date were January 1, 2004, the SELECT returns 200401-01.

The following example converts, respectively, a UBIGINT to a

SQL_CHAR, and string data to SQL_DATE, SQL_TIME, and
SQL_TIMESTAMP.
SELECT CONVERT(id , SQL_CHAR), CONVERT( '1995-06-05',
SQL_DATE), CONVERT('10:10:10', SQL_TIME),
CONVERT('1990-10-10 10:10:10', SQL_TIMESTAMP) FROM
Faculty

The following example converts a string to SQL_DATE then adds 31

to SQL_DATE.
SELECT Name FROM Class WHERE Start_date > CONVERT ('199505-07', SQL_DATE) + 31

The following examples show how to cast and convert a

UNIQUEIDENTIFIER data type.
CREATE TABLE table1(col1 CHAR(36), col2 UNIQUEIDENTIFIER
DEFAULT NEWID())
INSERT INTO table1 (col1) VALUES ('1129619D-772C-AAABB221-00FF00FF0099')
SELECT CAST(col1 AS UNIQUEIDENTIFIER) FROM table1
SELECT CAST(col2 AS LONGVARCHAR) FROM table1
SELECT CONVERT(col2 , SQL_CHAR) FROM table1
SELECT CONVERT('1129619D-772C-AAAB-B221-00FF00FF0099' ,
SQL_GUID) FROM table1

The following examples show how to convert a DATETIME data type

with and without the style parameter.
CREATE TABLE table2(col1 DATETIME)
INSERT INTO table2 (col1) VALUES ('2006-12-25
10:10:10.987')
SELECT CONVERT(col1 , SQL_CHAR, 20) FROM table2

5-22

Conversion Functions

This returns 2006-12-25 10:10:10.

SELECT CONVERT(col1 , SQL_CHAR, 120) FROM table2

This returns 2006-12-25 10:10:10.

SELECT CONVERT(col1 , SQL_CHAR) FROM table2

This returns 2006-12-25 10:10:10.987.

If you want to include the DATETIME milliseconds, omit the style
parameter.
Note the following requirements when using the style parameter:

The type parameter must be SQL_CHAR. Any other data type is

ignored.
The column data type of the expression must be DATETIME.
The only permissible style values are 20 and 120. Any other value
returns an error. The values 20 or 120 specify the ODBC
canonical format: yyyy-mm-dd hh:mi:ss.

5-23

Scalar Functions

5-24

chapter

System Stored Procedures

A Reference to Pervasive PSQL System Stored Procedures

This chapter discusses the following topic:

Pervasive PSQL System Stored Procedures on page 6-2

6-1

System Stored Procedures

Pervasive PSQL System Stored Procedures

The system stored procedures help you accomplish those
administrative and informative tasks that are not covered by the Data
Definition Language. The system stored procedures have a psp_
prefix.
Note Since the system stored procedure names use the psp_

prefix, do not create any stored procedures with the psp_ prefix.
Any user-created stored procedure with the same name as that of
a system stored procedure will never be executed.
The following table lists the system stored procedures currently
supported.
Table 6-1 Pervasive PSQL System Stored Procedures
psp_columns

psp_column_attributes

psp_column_rights

psp_fkeys

psp_groups

psp_help_sp

psp_help_trigger

psp_help_udf

psp_help_view

psp_indexes

psp_pkeys

psp_procedure_rights

psp_rename

psp_stored_procedures

psp_tables

psp_table_rights

psp_triggers

psp_udfs

psp_users

psp_view_rights

psp_views

Unless otherwise noted, the code examples for the system stored
procedures refer to the Demodata sample database provided with
Pervasive PSQL or to Pervasive PSQL system tables. (For default
locations of Pervasive PSQL files, see Where are the Pervasive PSQL
v10 files installed? on page 7-2 in Getting Started With Pervasive
PSQL.)
If you execute a system stored procedure in the context of a database
(for example, A) and try to obtain information from a secured
database (for example, B), an error message appears. You cannot
obtain information from a secured database from any other
database.

6-2

Pervasive PSQL System Stored Procedures

psp_columns

Returns the list of columns and their corresponding information for

a specified table, from the current database or the specified database.
Syntax
call psp_columns(['database_qualifier'],'table_name',
['column_name'])

Arguments
Table 6-2 psp_columns Arguments
Parameter

Type

Default Value

Description

Database_qualifier

VARCHAR(20)

Current database

Name of the database from which

the details are to be obtained

table_name

VARCHAR(255)

(no default value)

Name of the table whose column

information is required

column_name

VARCHAR(255)

All columns for the

specified table

Column name of the table specified

Returned Result Set

Table 6-3 psp_columns Returned Result Set
Column Name

Data Type

Description

TABLE_QUALIFIER

VARCHAR (20)

Name of the database

TABLE_OWNER

VARCHAR (20)

Name of the table owner. Table owner is reserved for future use.
It currently returns empty (NULL).

TABLE_NAME

VARCHAR(255)

Name of the table

COLUMN_NAME

VARCHAR(255)

Column name of the table

DATA_TYPE

SMALLINT

ODBC data type code of the column. See Pervasive PSQL Data
Types and Equivalent ODBC Data Types on page A-2.

TYPE_NAME

VARCHAR (32)

Name of the data type of the column corresponding to DATA_

TYPE value

PRECISION

INTEGER

The precision of the column if the data type is Decimal, Numeric,

and so forth. See Precision and Scale of Decimal Data Types
on page A-9.

6-3

System Stored Procedures

Table 6-3 psp_columns Returned Result Set continued

Column Name

Data Type

Description

LENGTH

INTEGER

The ODBC length of the column

SCALE

SMALLINT

The scale of the column if the data type is Decimal, Numeric, and
so forth.

RADIX

SMALLINT

Base for numeric data types

NULLABLE

SMALLINT

Specifies nullability:
1 - NULL allowed
0 - NULL not allowed

REMARKS

VARCHAR(255)

Remarks field

Examples
create table tx (c_binary BINARY(10),
c_char CHAR(10),
c_tinyint TINYINT,
c_smallint SMALLINT,
c_int INT,
c_bigint BIGINT,
c_utinyint UTINYINT)
call psp_columns(, 'tx',)

6-4

Pervasive PSQL System Stored Procedures

Result Set
Table_
qualifier

Table_
owner

Table_
name

Column
_name

Data_
type

Type_
name

'demodata'

Null

C_binary

-2

Binary

Null

'demodata'

Null

C_char

-1

Char

Null

'demodata'

Null

C_tinyint

-6

Tinyint

Null

.....
Legend: P = Precision; L = Length; S = Scale; R = Radix; N = Nullable; R = Remarks

Assume that you have a database named "mydatabase" that contains

a table named "tx."
call psp_columns('mydatabase', 'tx', )

Result Set
Table_
qualifier

Table_
owner

Table_
name

Column
_name

Data_
type

Type_
name

'wsrde'

Null

C_binary

-2

Binary

Null

'wsrde'

Null

C_char

-1

Char

Null

'wsrde'

Null

C_tinyint

-6

Tinyint

Null

.....
Legend: P = Precision; L = Length; S = Scale; R = Radix; N = Nullable; R = Remarks

call psp_columns('mydatabase', 'tx', 'c_binary')

Result Set
Table_
qualifier

Table_
owner

Table_
name

Column
_name

Data_
type

Type_
name

'wsrde'

Null

C_binary

-2

Binary

Null

Legend: P = Precision; L = Length; S = Scale; R = Radix; N = Nullable; R = Remarks

6-5

System Stored Procedures

Error Conditions

psp_column_
attributes

Condition

Error Message

database_qualifier is a blank string

Please enter a valid database name.

Database name cannot be a blank string.

database_qualifier is an undefined
database

Unable to open table: X$File

table_name is undefined in the

database

No error is returned and no results are

returned

table_name is null

Table name cannot be null

table_name is a blank string

Table name cannot be a blank string

column_name is a blank string

Column name cannot be a blank string

column_name is undefined in the

table

No error is returned and no results are

returned

Returns the list of column attributes and the corresponding

information from the current database or the specified database.
Syntax
call psp_column_attributes(['database_qualifier'],
['table_name'], ['column_name'])

Arguments
Table 6-4 psp_column_attributes Arguments
Parameter

Type

Default Value

Description

Database_qualifier

VARCHAR(20)

Current database you are

logged in

Name of the database from which the

details are to be obtained

table_name

VARCHAR(255)

All tables for the specified

database

Name of the table whose column

information is required

column_name

VARCHAR(255)

All columns for the

specified table

Column name of the table specified

6-6

Pervasive PSQL System Stored Procedures

Returned Result Set

Table 6-5 psp_column_attributes Returned Result Set
Column Name

Data Type

Description

TABLE_QUALIFIER

VARCHAR (20)

Name of the database

TABLE_OWNER

VARCHAR (20)

Name of the table owner

TABLE_NAME

VARCHAR(255)

Name of the table

COLUMN_NAME

VARCHAR(255)

Column name of the table

ATTRIB_TYPE

CHAR(10)

"Default" if a default value has been assigned to the column

ATTRIB_SIZE

USMALLINT

Size of the column attribute

ATTRIB_VALUE

LONGVARCHAR

Value of the column attribute

Examples
create table tx (c_binary binary (10) default 01,
c_char char (11) default 'thisisatest',
c_tinyint TINYINT,
c_SMALLINT SMALLINT,
c_int INT,
c_bigint BIGINT,
c_utinyint uTINYINT)
call psp_column_attributes(, , )

Result Set
Table_
qualifier

Table_owner

Table_name

Column_name

Attrib_Type

Attrib_Size

Attrib_Value

'demodata'

Null

C_binary

Default

'demodata'

Null

C_char

Default

'Thisisatest'

6-7

System Stored Procedures

call psp_column_attributes(, 'tx', 'c_binary')

Result Set
Table_
qualifier

Table_owner

Table_name

Column_name

Attrib_Type

Attrib_Size

Attrib_Value

'demodata'

Null

C_binary

Default

Error Conditions

psp_column_
rights

Condition

Error Message

database_qualifier is a blank string

Please enter a valid database name.

Database name cannot be a blank string.

database_qualifier is an undefined
database

Unable to open table: X$File

table_name is undefined in the

database

No error is returned and no results are

returned

table_name is null

Table name cannot be null

table_name is a blank string

Table name cannot be a blank string

column_name is a blank string

Column name cannot be a blank string

column_name is undefined in the

table

No error is returned and no results are

returned

Returns the list of column rights and corresponding information for

the specified table, from the current database or the specified
database.
Note This system stored procedure returns the list of column

rights only if it has been explicitly specified using the GRANT

syntax.

Syntax
call psp_column_rights(['database_qualifier'], 'table_
name', ['column_name'], ['user_name'])

6-8

Pervasive PSQL System Stored Procedures

Arguments
Table 6-6 psp_column_rights Arguments
Parameter

Type

Default Value

Description

Database_qualifier

VARCHAR(20)

Current database

Name of the database from which the

details are to be obtained

table_name

VARCHAR(255)

All tables

Name of the table for which rights

have been specified

column_name

VARCHAR(255)

All columns of the

specified table

Name of the column whose rights are

to be obtained

user_name

VARCHAR(255)

Current user

Name of the user for whom the list of

column rights need to be obtained.
Pattern matching is supported.

Returned Result Set

Table 6-7 psp_column_rights Returned Result Set
Column Name

Data Type

Description

TABLE_QUALIFIER

VARCHAR (20)

Name of the database

TABLE_OWNER

VARCHAR (20)

Name of the owner of the table

USER_NAME
(GRANTEE)

VARCHAR(255)

Name of the user

TABLE_NAME

VARCHAR(255)

Name of the table

COLUMN_NAME

VARCHAR(255)

Name of the column for which the different rights have been
granted

RIGHTS

VARCHAR(12)

One of the following values:

SELECT
UPDATE
INSERT

Examples
Assume that the following permissions exist for the DEMODATA
sample database:

6-9

System Stored Procedures

GRANT SELECT(Name, Building_Name) ON Dept TO John
GRANT UPDATE(Name) ON Dept TO Mary
GRANT INSERT(Building_Name) ON Dept TO John
Call psp_column_rights(,'Dept', ,'%')

Result Set
Table_Qualifier

Table_owner

User_name

Table_name

Column_name

Rights

Demodata

Null

John

Dept

Name

SELECT

Demodata

Null

John

Dept

Building_name

SELECT

Demodata

Null

John

Dept

Building_name

INSERT

Demodata

Null

Mary

Dept

Name

UPDATE

Note The Master user does not have explicit column rights

defined, so psp_column_rights does not return any results for

user "Master."

Assume that user John is logged on the database. The following

statement prints the column permissions on the Dept table for the
current user (John).
call psp_column_rights ('demodata', 'Dept', ,)

Result Set
Table_Qualifier

Table_owner

User_name

Table_name

Column_name

Rights

Demodata

Null

John

Dept

Building_name

INSERT

Demodata

Null

John

Dept

Building_name

SELECT

Demodata

Null

John

Dept

Name

SELECT

6-10

Pervasive PSQL System Stored Procedures

Note If a user has been granted rights at the table level (for

example, GRANT SELECT ON Dept TO Mary), a call to psp_

column_rights does not return any rights. The rights were
granted to the table, not to specific columns.

The following statement prints the column permissions on the

Dept table for column Name for the current user.
call psp_column_rights ('demodata', 'dept', 'name',)

Result Set
Table_Qualifier

Table_owner

User_name

Table_name

Column_name

Rights

Demodata

Null

John

Dept

Name

SELECT

The following statement prints the column permissions on the

Dept table for user Mary.
call psp_column_rights('demodata', 'dept', , 'Mary')

Result Set
Table_Qualifier

Table_owner

User_name

Table_name

Column_name

Rights

Demodata

Null

Mary

Dept

Name

UPDATE

6-11

System Stored Procedures

Error Conditions

psp_fkeys

Condition

Error Message

database_qualifier is a blank string

Please enter a valid database name.

Database name cannot be a blank string.

table_name is null

Table name cannot be null.

table_name is a blank string

Table name cannot be a blank string.

column_name is a blank string

Column name cannot be a blank string.

user_name is a blank string

User name cannot be a blank string.

Returns the foreign key information for the specified table in the
current database.
Syntax
call psp_fkeys(['table_qualifier'], 'pkey_table_name',
['fkey_table_name'])

Arguments
Table 6-8 psp_fkeys Arguments
Parameter

Type

Default Value

Description

table_qualifier

VARCHAR(20)

Current database

Name of the database from which the

details are to be obtained

pkey_table_name

VARCHAR(255)

(no default value)

Name of the table whose foreign key

is associated with the primary key
column

fkey_table_name

VARCHAR(255)

(no default value)

Name of the table whose foreign key

information needs to be obtained

6-12

Pervasive PSQL System Stored Procedures

Returned Result Set

Table 6-9 psp_fkeys Returned Result Set
Column Name

Data Type

Description

PKTABLE_
QUALIFIER

VARCHAR (20)

Database name of the primary key table

PKTABLE_OWNER

VARCHAR (20)

Name of the owner of the primary key table

PKTABLE_NAME

VARCHAR(255)

Name of the primary key table

PKCOLUMN_NAME

VARCHAR(255)

Column name of the primary key column.

KEY_SEQ

USMALLINT

Sequence of Keys. The value of this column corresponds to

Xi$Part in X$Index. See X$Index on page C-9.

FKTABLE_
QUALIFIER

VARCHAR (20)

Database name of the foreign key table

FKTABLE_OWNER

VARCHAR (20)

Name of the owner of the foreign key table

FKTABLE_NAME

VARCHAR(255)

Name of the foreign key table

FKCOLUMN_NAME

VARCHAR(255)

Column name of the foreign key column.

UPDATE_RULE

Utinyint

Update Rule

DELETE_RULE

Utinyint

Delete Rule

PK_NAME

VARCHAR(255)

Name of the primary key

FK_NAME

VARCHAR(255)

Name of the foreign key

Examples
CREATE TABLE Employee
(
Id INTEGER NOT NULL,
Name VARCHAR(50) NOT NULL,
SupId INTEGER NOT NULL
)
ALTER TABLE Employee
ADD CONSTRAINT EmpPkey
PRIMARY KEY(Id)
ALTER TABLE Employee
ADD CONSTRAINT ForgnKey
FOREIGN KEY(SupId) REFERENCES

6-13

System Stored Procedures

Employee(Id) ON DELETE CASCADE
call psp_fkeys(,'Employee',)

Result Set
PkQ

PkO

PkT

PkCol

Seq

FkQ

FkO

FkT

FkCol

Demo
data

Null

Empl
oyee

Demo
data

Null

Employ
ee

Supid

Emp
Pkey

Forgn
Key

Legend: PkQ = Pkey_ table_ qualifier; PkO = Pkey_table_owner; PkT = Pktable_ name; PkCol = Pk_ column_
name; Seq = Key_seq; FkQ = Fktable_qualifier; FkO = Fktable_owner; FkT = Fktable_name; FkCol =
Fkcolumn_name; UR = Update_rule; DR = Delete_rule; Pk = Pk_ name; FK = Fk_ name

Error Conditions

psp_groups

Condition

Error Message

table_qualifier is a blank string

Table name cannot be a blank string.

pKey_table_name is a blank string

Primary key table name cannot be a blank

string.

pKey_table_name is null

No argument or default value supplied.

Argument: 2.

fKey_table_name is a blank string

Foreign key table name cannot be a blank

string.

Returns the list of groups and the corresponding information from

the current database or the specified database.
Syntax
call psp_groups(['database_qualifier'], ['group_name'])

6-14

Pervasive PSQL System Stored Procedures

Arguments
Table 6-10 psp_groups Arguments
Parameter

Type

Default Value

Description

Database_qualifier

VARCHAR(20)

Current database

Name of the database from which the

details are to be obtained

group_name

VARCHAR(255)

(no default value)

Name of the group used to return

group information. Pattern matching is
supported.

Returned Result Set

Table 6-11 psp_groups Returned Result Set
Column Name

Data Type

Description

DATABASE_
QUALIFIER

VARCHAR (20)

Name of the database

GROUP_ID

USMALLINT

Group Id

GROUP_NAME

VARCHAR (255)

Name of the group

Examples
Assume that the Demodata sample database has two groups defined:
DevGrp1 and DevGrp2.
call psp_groups(,)

Result Set
Database_qualifier

Group_Id

Group_Name

Demodata

PUBLIC

Demodata

DevGrp1

Demodata

DevGrp2

call psp_groups('Demodata', 'D%')

6-15

System Stored Procedures

Result Set
Database_qualifier

Group_Id

Group_Name

Demodata

DevGrp1

Demodata

DevGrp2

Error Conditions

psp_help_sp

Condition

Error Message

database_qualifier is a blank string

Please enter a valid database name.

Database name cannot be a blank string.

group_name is a blank string

Group name cannot be a blank string.

Returns the definition text of a given stored procedure from the

current database or the specified database.
Syntax
call psp_help_sp('[database_qualifier'], 'procedure_
name')

Arguments
Table 6-12 psp_help_sp - Arguments
Parameter

Type

Default Value

Description

Database_qualifier

VARCHAR(20)

Current database

Name of the database from which the

details are to be obtained

procedure_name

CHAR(255)

(no default value)

Name of the procedure whose

definition text is required. Pattern
matching is not supported.

6-16

Pervasive PSQL System Stored Procedures

Returned Result Set

Table 6-13 psp_help_sp - Returned Result Set
Column Name

Data Type

Description

DATABASE_QUALIFIER

VARCHAR (20)

Name of the database

SP_TEXT

LONGVARCHAR

Stored procedure definition text

Examples
Assume that the DEMODATA sample database contains the
following stored procedure saved as Myproc.
Create procedure Myproc(:a integer, OUT :b integer) as
Begin
Set :a = :a + 10;
Set :b = :a;
End

The following statement prints the definition text for stored

procedure Myproc in the current database.
call psp_help_sp(, 'Myproc')

Result Set
Database_Qualifier
Demodata

SP_TEXT

Create procedure Myproc(:a integer,

OUT :b integer) as
Begin
Set :a = :a + 10;
Set :b = :a;
End

Assume that a database named wsrde contains the following stored

procedure saved as Myproc1.
Create procedure Myproc1(:a integer)
char(20))
as
Begin

returns (name

6-17

System Stored Procedures

Select name from employee where Id =:a;
End

The following statement prints the definition text for stored

procedure Myproc1 in database wsrde.
call psp_help_sp('wsrde', 'Myproc1')

Result Set
Database_Qualifier
wsrde

SP_TEXT

Create procedure Myproc1(:a integer)

returns (name char(20))
as
Begin
Select name from employee where Id
=:a;
End

Error Conditions

psp_help_
trigger

Condition

Error Message

database_qualifier is a blank string

or null

Please enter a valid database name.

Database name cannot be a blank string

procedure_name is null

No argument or default value supplied.

procedure_name is a blank string

Procedure name cannot be a blank string.

Returns the definition text of a trigger from the current database or

the specified database.
Syntax
call psp_help_trigger (['database_qualifier'],
'trigger_name')

6-18

Pervasive PSQL System Stored Procedures

Arguments
Table 6-14 psp_help_trigger - Arguments
Parameter

Type

Default Value

Description

Database_qualifier

VARCHAR(20)

Current database

Name of the database from which the

details are to be obtained

trigger_name

VARCHAR(255)

(no default value)

Name of the trigger whose definition

text is to be returned. Pattern
matching is supported.

Returned Result Set

Table 6-15 psp_help_trigger - Returned Result Set
Column Name

Data Type

Description

DATABASE_
QUALIFIER

VARCHAR (20)

Name of the database

TRIGGER_TEXT

LONGVARCHAR

Trigger definition text.

Examples
The following statement prints the definition of the 'MyInsert'
trigger:
CREATE TABLE A
(
col1 INTEGER,
col2 CHAR(255)
)
CREATE TABLE B
(
col1 INTEGER,
col2 CHAR(255)
)
CREATE TRIGGER MyInsert
AFTER INSERT ON A
FOR EACH ROW
INSERT INTO B VALUES
(NEW.col1, NEW.col2)

6-19

System Stored Procedures

call psp_help_trigger(,'MyIns%')

Result Set
Database_Qualifier
Demodata

TRIGGER_TEXT

CREATE TRIGGER MyInsert

AFTER INSERT ON A
FOR EACH ROW
INSERT INTO B VALUES
(NEW.col1, NEW.col2);

Error Conditions

psp_help_udf

Condition

Error Message

database_qualifier is a blank string

Please enter a valid database name.

Database name cannot be a blank string

trigger_name is null

No argument or default value supplied.

trigger_name is a blank string

Trigger name cannot be a blank string.

Returns the text of a given user-defined function (UDF) from the

current database or the specified database.
Syntax
call psp_help_udf (['database_qualifier'], 'udf_name')

Arguments
Table 6-16 psp_help_udf - Arguments
Parameter

Type

Default Value

Description

Database_qual

VARCHAR(20)

Current database

Name of the database from which the

details are to be obtained

udf_name

VARCHAR(255)

(no default value)

Name of the user-defined function

whose function text is required.
Pattern matching is supported.

6-20

Pervasive PSQL System Stored Procedures

Returned Result Set

Table 6-17 psp_help_udf - Returned Result Set
Column Name

Data Type

Description

DATABASE_
QUALIFIER

VARCHAR (20)

Name of the database

UDF_TEXT

LONGVARCHAR

The text of the User Defined Function

Examples
call psp_help_udf(, 'Myfunction')

Result Set
Database_Qualifier
Demodata

UDF_TEXT

Create function Myfunction(:a integer)

Returns integer
as
Begin
Return :a * :a;
End

call psp_help_udf('mydbase', 'Get%')

6-21

System Stored Procedures

Result Set
Database_Qualifier
wsrde

UDF_TEXT

CREATE FUNCTION GetSmallest(:A

integer, :B Integer)
RETURNS Integer
AS
BEGIN
DECLARE :smallest INTEGER
IF (:A < :B ) THEN
SET :smallest = :A;
ELSE
SET :smallest = :B;
END IF;
RETURN :smallest;
END

Error Conditions

psp_help_view

Condition

Error Message

database_qualifier is a blank string

Please enter a valid database name.

Database name cannot be a blank string

udf_name is null

No argument or default value supplied.

udf_name is a blank string

User-defined function name cannot be a

blank string.

Returns the definition text of a view, from the current database or the
specified database.
Syntax
call psp_help_view(['database_qualifier'], 'view_name')

6-22

Pervasive PSQL System Stored Procedures

Arguments
Table 6-18 psp_help_view - Arguments
Parameter

Type

Default Value

Description

Database_qual

VARCHAR(20)

Current database

Name of the database from which the

details are to be obtained

view_name

VARCHAR(255)

(no default value)

Name of the view whose definition text

is required. Pattern matching is
supported.

Returned Result Set

Table 6-19 psp_help_view - Returned Result Set
Column Name

Data Type

Description

DATABASE_QUALIFIER

VARCHAR (20)

Name of the database

VIEW_TEXT

LONGVARCHAR

View definition text.

Example
Assume that the following view exists for the DEMODATA sample
database:
CREATE VIEW vw_Person (lastn,firstn,phone) AS
SELECT Last_Name, First_Name, Phone
FROM Person

The following statement returns the definition text for view vw_
Person in the DEMODATA database.
call psp_help_view(,'vw_Person')

or
call psp_help_view(,'vw_%')

6-23

System Stored Procedures

Result Set
Database_Qualifier
Demodata

VIEW_TEXT

SELECT "T1" ."Last_Name" ,"T1"

."First_Name" ,"T1" ."Phone"
FROM "Person" "T1"

Error Conditions

psp_indexes

Condition

Error Message

database_qualifier is a blank string

Please enter a valid database name.

Database name cannot be a blank string.

view_name is null

No argument or default value supplied.

view_name is a blank string

View name cannot be a blank string.

Returns the list of indexes defined for the specified table. For each
index, it also lists the index properties as persisted in the X$Index
table.
Syntax
call psp_indexes(['table_qualifier'], ['table_name'])

Arguments
Table 6-20 psp_indexes Arguments
Parameter

Type

Default Value

Description

table_qualifier

VARCHAR(20)

Current database

Name of the database from which the

details are to be obtained

table_name

VARCHAR(255)

(no default value)

Name of the table for whose indexes

are to be obtained. Pattern matching
is supported.

6-24

Pervasive PSQL System Stored Procedures

Returned Result Set

Table 6-21 psp_indexes Returned Result Set
Column Name

Data Type

Description

TABLE_QUALIFIER

VARCHAR (20)

Name of the database

TABLE_OWNER

VARCHAR (20)

Name of the owner of the primary key table

TABLE_NAME

VARCHAR(255)

Name of the primary key table

INDEX_NAME

VARCHAR(255)

Name of the index

INDEX_TYPE

VARCHAR (20)

Type of the Index: primary, foreign, or normal

COLUMN_NAME

VARCHAR(255)

Name of the column on which index is defined

ORDINAL_POSITION

USMALLINT

Ordinal position of the index (that is, the key number

DUPLICATES_ALLOWED

CHAR(3)

Yes, if it is a duplicate index

No, if it is not a duplicate index

UPDATABLE

CHAR(3)

Yes, if the index is updatable

No, if the index is not updatable

CASE_SENSITIVE

CHAR(3)

Yes, if the index is case-sensitive

No, if the index is not case-sensitive

ASC_DESC

CHAR(1)

D, Descending
A, Ascending

NAMED_INDEX

CHAR(3)

Yes, if it is a named index

No, if it is not a named index

Example
call psp_indexes(,)

6-25

System Stored Procedures

Result Set
Qual

Opos

Dup

Case

A/D

Demo
data

Null

Billing

Student_
Trans

Normal
Index

Student_ID

Yes

Demo
data

Null

Billing

Student_
Trans

Normal
Index

Transaction
_Number

Yes

Demo
data

Null

Billing

Student_
Trans

Normal
Index

Log

Yes

.....
Legend: Qual = Table_ qualifier; TO = Table_owner; TN = Table_name; IN = Index_name; IT = Index_type; CN
= Column_name; Opos = Ordinal_position; Dup = Duplicates_allowed; UP = Updatable; Case = Case_
sensitive; A/D = Asc_desc; NI = Named_index

call psp_indexes('demodata', 'Dep%')

Result Set
Qual

Opos

Dup

Case

A/D

Demo
data

Null

Dept

Building_Room

Normal
Index

Building
_Name

Yes

Demo
data

Null

Dept

Building_Room

Normal
Index

Room_
Number

Yes

Demo
data

Null

Dept

Dept_Head

Normal
Index

Head_
Of_Dept

Yes

Demo
data

Null

Dept

Dept_Name

Normal
Index

Name

Yes

Legend: Qual = Table_ qualifier; TO = Table_owner; TN = Table_name; IN = Index_name; IT = Index_type; CN

= Column_name; Opos = Ordinal_position; Dup = Duplicates_allowed; UP = Updatable; Case = Case_
sensitive; A/D = Asc_desc; NI = Named_index

6-26

Pervasive PSQL System Stored Procedures

Error Conditions

psp_pkeys

Condition

Error Message

database_qualifier is a blank string

Please enter a valid database name.

Database name cannot be a blank string.

table_name is a blank string

View name cannot be a blank string.

Returns the primary key information for the specified table, from the
current database or the database specified.
Syntax
call psp_pkeys(['pkey_table_qualifier']'table_name')

Arguments
Table 6-22 psp_pkeys Arguments
Parameter

Type

Default Value

Description

pkey_table_qualifier

VARCHAR(20)

Current database

Name of the database from which

the details are to be obtained

table_name

VARCHAR(255)

(no default value)

Name of the table whose primary

key information is requested.
Pattern matching is supported

Returned Result Set

Table 6-23 psp_pkeys Returned Result Set
Column Name

Data Type

Description

TABLE_QUALIFIER

VARCHAR (20)

Name of the database

TABLE_OWNER

VARCHAR (20)

Name of the owner of the primary key table

TABLE_NAME

VARCHAR(255)

Name of the primary key table

COLUMN_NAME

VARCHAR(255)

Name of the primary key column

COLUMN_SEQ

USMALLINT

Sequence of the columns (a segmented index)

PK_NAME

VARCHAR(255)

Name of the primary key

6-27

System Stored Procedures

Examples
The following statement returns the information about the primary
key defined on the 'pkeytest1' table:
CREATE TABLE pkeytest1
(
col1 int NOT NULL,
col2 int NOT NULL,
col3 VARCHAR(20) NOT NULL,
PRIMARY KEY(col1, col2),
UNIQUE(col3)
)
call psp_pkeys(,'pkeytest1')

Result Set
Table_
qualifier

Table_
owner

Table_name

Column_
name

Column_
Seq

PK_name

'demodata'

Null

Pkeytest1

Col1

PK_col1

'demodata'

Null

Pkeytest1

Col2

PK_col1

Error Conditions

psp_
procedure_
rights

Condition

Error Message

pkey_table_qualifier is a blank string

Please enter a valid database name.

Database name cannot be a blank string.

table_name is null

No argument or default value supplied.

table_name is a blank string

Table name cannot be a blank string.

Returns the list of procedure rights and corresponding information

for the specified stored procedure, from the current database or the
specified database. The stored procedure can be a trusted or a nontrusted one. See Trusted and Non-trusted Objects on page 3-154.
Syntax
call psp_procedure_rights(['database_qualifier'],
['procedure_name'], ['user_name'])

6-28

Pervasive PSQL System Stored Procedures

Arguments
Table 6-24 psp_procedure_rights Arguments
Parameter

Type

Default Value

Description

database_qualifier

VARCHAR(20)

Current database

Name of the database from which the details

are to be obtained

procedure_name

VARCHAR(255)

(no default value)

Name of the procedure for which rights are

specified. Pattern matching is supported.

user_name

VARCHAR(255)

Current user

Name of the user for whom the list of

procedure rights needs to be obtained. Pattern
matching is supported.

Returned Result Set

Table 6-25 psp_procedure_rights Returned Result Set
Column Name

Data Type

Description

PROCEDURE_QUALIFIER

VARCHAR (20)

Name of the database

PROCEDURE_OWNER

VARCHAR (20)

Name of the owner of the procedure

USER_NAME (GRANTEE)

VARCHAR(255)

Name of the user

PROCEDURE_NAME

VARCHAR(255)

Name of the procedure

RIGHTS

VARCHAR(12)

One of the following values:

ALTER
EXECUTE
Note that RIGHTS pertains only to procedures in a
database that uses V2 metadata.

Examples
Assume that the following permissions exist for the DEMODATA
sample database:
GRANT
GRANT
GRANT
GRANT
GRANT
GRANT

EXECUTE ON PROCEDURE Dept1_Proc TO John

ALTER ON PROCEDURE Dept1_Proc TO Mary
ALTER ON PROCEDURE Dept1_Proc TO John
EXECUTE ON PROCEDURE Proc2 TO Mary
ALTER ON PROCEDURE Proc2 TO Mary
ALTER ON PROCEDURE MyProc TO Mary

The following statement prints the permissions on the Dept1_

Proc stored procedure for user John.

6-29

System Stored Procedures

call psp_procedure_rights(,'Dept1_Proc', 'John')

Result Set
Procedure_Qualifier

Procedure_owner

User_name

Procedure_name

Rights

Demodata

Null

John

Dept1_Proc

ALTER

Demodata

Null

John

Dept1_Proc

EXECUTE

The following statement prints the permissions on the Proc2

stored procedure for user Mary.
call psp_procedure_rights('demodata', '%Pr%', 'M%')

Result Set
Procedure_Qualifier

Procedure_owner

User_name

Procedure_name

Rights

Demodata

Null

Mary

MyProc

ALTER

Demodata

Null

Mary

Proc2

ALTER

Demodata

Null

Mary

Proc2

EXECUTE

Error Conditions

6-30

Condition

Error Message

database_qualifier is a blank string

Please enter a valid database name.

Database name cannot be a blank string.

procedure_name is a blank string

Procedure name cannot be a blank string.

user_name is a blank string

User name cannot be a blank string.

psp_procedure_rights called for a

database with V1 metadata

View and Stored Procedure permissions

are not supported for metadata version 1.

Pervasive PSQL System Stored Procedures

psp_rename

Changes the name of a COLUMN, INDEX, FUNCTION,

PROCEDURE, TABLE, TRIGGER or VIEW in the database to which
your machine is currently connected.
Syntax
call psp_rename('object_name','new_name','object_type')

Arguments
Table 6-26 psp_rename Arguments
Parameter

Type

Description

object_name

VARCHAR(776)

The current name of the column, index, user-defined function, stored

procedure, table, trigger or view.
Object_name must be specified in a particular format depending on
the type of object:
Column: table_name.column_name.
Index: table_name.index_name.
Function: function_name
Procedure: procedure_name
Table: table_name
Trigger: table_name.trigger_name
View: view_name

new_name

VARCHAR(776)

A user-defined name for the object. The name must conform to the
naming conventions for the type of object. See Naming Conventions
on page 12-6 in Pervasive PSQL Programmer's Guide, which is part
of the Pervasive PSQL Software Developers Kit (SDK).

object_type

VARCHAR(13)

The type of object being renamed. Object_type must be one of the

following: COLUMN, INDEX, FUNCTION, PROCEDURE, TABLE,
TRIGGER or VIEW.

Example
The following statement renames stored procedure checkstatus to
eligibility in the current database.
call psp_rename('checkstatus', 'eligibility',
'PROCEDURE')

6-31

System Stored Procedures

Error Conditions
All errors returned from psp_rename use status code -5099. See 5099: error condition pertaining to psp_rename on page 1-45 in
Status Codes and Messages.

psp_stored_
procedures

Returns the list of stored procedures and their corresponding

information from the current database or the specified database.
Syntax
call psp_stored_procedures(['database_qualifier'],
['procedure_name'], ['procedure_type'])

Arguments
Table 6-27 psp_stored_procedures Arguments
Parameter

Type

Default Value

Description

Database_qualifier

VARCHAR(20)

Current database

Name of the database from which the

details are to be obtained

procedure_name

VARCHAR(255)

(no default value)

Name of the stored procedure whose

information is required. Pattern
matching is supported.

procedure_type

VARCHAR(5)

(no default value)

'SP' returns the stored procedures

'SSP' returns the system stored
procedures (this type is currently not
supported)

Note System stored procedures are defined in the internal

PERVASIVESYSDB database, which does not display in

Pervasive PSQL Control Center.

6-32

Pervasive PSQL System Stored Procedures

Returned Result Set

Table 6-28 psp_stored_procedures Returned Result Set
Column Name

Data Type

Description

PROCEDURE_QUALIFIER

VARCHAR (20)

Name of the database

PROCEDURE _OWNER

VARCHAR (20)

Name of the owner of the procedure

PROCEDURE _NAME

VARCHAR(255)

Name of the procedure

PROCEDURE_TYPE

VARCHAR(25)

Type of procedure. The different types of procedures may

be "STORED PROCEDURE" or "SYSTEM STORED
PROCEDURE"

NUM_INPUT_PARAMS

INT

Returns null, because SQLPROCEDURES returns null

when executed against Pervasive PSQL DSN

NUM_OUTPUT_PARAMS

INT

Returns null, because SQLPROCEDURES returns null

when executed against Pervasive PSQL DSN

NUM_RESULT_SETS

INT

Returns null, since SQLPROCEDURES returns null when

executed against Pervasive PSQL DSN

REMARKS

VARCHAR(255)

Remarks

TRUSTEE

INTEGER

For V2 metadata, returns 0 for a trusted stored procedure

and -1 for a non-trusted stored procedure. The TRUSTEE
column is empty for V1 metadata.

Examples
Assume that the current database, "mydbase," contains two stored
procedures: "myproc1" and "myproc2." The following statement lists
the information about them.
Call psp_stored_procedures(, ,)

6-33

System Stored Procedures

Result Set
Qualifier1

Owner1

Name1

Type1

Num_
input_
params

Num_
output_
params

Num_
result
_sets

Remarks

mydbase

Null

Myproc1

Stored
Procedure

Null

mydbase

Null

Myproc2

Stored
Procedure

Null

Trustee

1The

complete column name includes procedure_ prepended to this name: Procedure_qualifier, procedure_
owner, and so forth.

The following statement lists the information about the stored

procedures in the PERVASIVESYSDB internal database.
call psp_stored_procedures('PERVASIVESYSDB', psp_u%,
'SP')

Result Set
Qualifier1

Owner1

Name1

Type1

Num_
input_
params

Num_
output_
params

Num_
result
_sets

Remarks

pervasive
systdb

Null

psp_udfs

Stored
Procedure

Null

pervasive
systdb

Null

psp_users

Stored
Procedure

Null

Trustee

1
The complete column name includes procedure_ prepended to this name: Procedure_qualifier, procedure_
owner, and so forth.

6-34

Pervasive PSQL System Stored Procedures

Error Conditions

psp_tables

Condition

Error Message

database_qualifier is a blank string

Please enter a valid database name.

Database name cannot be a blank string

table_name is a blank string

Table name cannot be a blank string.

procedure_type is a blank string

Procedure type cannot be a blank string.

procedure_type is a value other than

SP, SSP, or null

Procedure type can be SP, SSP, or null.

Returns a list of tables along with their corresponding information,

from the current database or the specified database.
Syntax
call psp_tables(['database_qualifier'], ['table_name'],
['table_type'])

Arguments
Table 6-29 psp_tables Arguments
Parameter

Type

Default Value

Description

Database_qualifier

VARCHAR(20)

Current database

Name of the database from which the

details are to be obtained

table_name

VARCHAR(255)

(no default value)

Name of the table whose information

needs to be obtained. Pattern
matching is supported.

table_type

VARCHAR(20)

(no default value)

Must be one of the following:

'User table' returns only the user
tables
'System table' returns all the system
tables
NULL returns all tables

6-35

System Stored Procedures

Returned Result Set

Table 6-30 psp_tables Returned Result Set
Column Name

Data Type

Description

TABLE_QUALIFIER

VARCHAR (20)

Name of the database

TABLE_OWNER

VARCHAR (20)

Name of the table owner

TABLE_NAME

VARCHAR(255)

Name of the table

TABLE_TYPE

VARCHAR (15)

System table - if the table is a system table

User table - if the table has been created by any user

REMARKS

VARCHAR(255)

Remarks

FILE_LOCATION

VARCHAR(255)

Location where the file is saved

Examples
call psp_tables(,,)

Result Set
Table_Qualifier

Table_owner

Table_name

Table_Type

Remarks

File_
location

Demodata

Null

X$file

System table

Null

File.ddf

Demodata

Null

X$field

System table

Null

Field.ddf

Demodata

Null

X$Attrib

System table

Null

Attrib.ddf

Demodata

Null

Billing

User table

Null

Billing.mkd

.....

call psp_tables(, , 'user table')

6-36

Pervasive PSQL System Stored Procedures

Result Set
Table_Qualifier

Table_owner

Table_name

Table_Type

Remarks

File_
location

Demodata

Null

Class

User table

Null

class.mkd

Demodata

Null

Billing

User table

Null

Billing.mkd

.....

call psp_tables(, , 'system table')

Result Set
Table_Qualifier

Table_owner

Table_name

Table_Type

Remarks

File_
location

Demodata

Null

X$file

System table

Null

File.ddf

Demodata

Null

X$field

System table

Null

Field.ddf

Demodata

Null

X$Attrib

System table

Null

Attrib.ddf

.....

Error Conditions
Condition

Error Message

database_qualifier is a blank string

Please enter a valid database name.

Database name cannot be a blank string.

table_name is a blank string

Table name cannot be a blank string.

table_type is a blank string

Table type cannot be a blank string.

table_type is something other than

'system table,' 'user table,' or null

Table type can be system table, user table

or null.

6-37

System Stored Procedures

psp_table_
rights

Returns the list of table rights and corresponding information for the
specified table, from the current database or the specified database.
Syntax
call psp_table_rights(['database_qualifier'], ['table_
name'], ['user_name'])

Arguments
Table 6-31 psp_table_rights Arguments
Parameter

Type

Default Value

Description

Database_qualifier

VARCHAR(20)

Current database

Name of the database from which the details

are to be obtained

table_name

VARCHAR(255)

All tables

Name of the table for which rights have are

specified. Pattern matching is supported.

user_name

VARCHAR(255)

Current user

Name of the user for whom the list of table

rights needs to be obtained. Pattern matching
is supported.

6-38

Pervasive PSQL System Stored Procedures

Returned Result Set

Table 6-32 psp_table_rights Returned Result Set
Column Name

Data Type

Description

TABLE_QUALIFIER

VARCHAR (20)

Name of the database

TABLE_OWNER

VARCHAR (20)

Name of the owner of the table

USER_NAME
(GRANTEE)

VARCHAR(255)

Name of the user

TABLE_NAME

VARCHAR(255)

Name of the table

RIGHTS

VARCHAR(12)

One of the following values:

SELECT
ALTER
DELETE
INSERT
REFERENCES
SELECT
UPDATE

Examples
Assume that the following permissions exist for the DEMODATA
sample database.
GRANT
GRANT
GRANT
GRANT
GRANT

SELECT ON Dept TO John

ALTER ON Dept TO John
DELETE ON Dept TO John
SELECT ON Class TO Mary
ALTER ON Class TO Mary

The following statement prints the table permissions on the Dept

table for user John in the current database (DEMODATA).
call psp_table_rights(,'Dept', 'John')

6-39

System Stored Procedures

Result Set
Table_Qualifier

Table_owner

User_name

Table_name

Rights

Demodata

Null

John

Dept

ALTER

Demodata

Null

John

Dept

DELETE

Demodata

Null

John

Dept

SELECT

Assume that user Mary is logged on the database. The following

statement prints the table permissions on the Class table in the
DEMODATA database for the current user (Mary).
call psp_table_rights('demodata', 'cl%', )

Result Set
Table_Qualifier

Table_owner

User_name

Table_name

Rights

Demodata

Null

Mary

Class

SELECT

Demodata

Null

Mary

Class

ALTER

Error Conditions

psp_triggers

Condition

Error Message

database_qualifier is a blank string

Please enter a valid database name.

Database name cannot be a blank string.

table_name is a blank string

Table name cannot be a blank string.

user_name is a blank string

User name cannot be a blank string.

Returns the list of triggers and their corresponding information

from the current database or the specified database.
Syntax
call psp_triggers(['database_qualifier'], ['table_
name'])

6-40

Pervasive PSQL System Stored Procedures

Arguments
Table 6-33 psp_triggers Arguments
Parameter

Type

Default Value

Description

Database_qualifier

VARCHAR(20)

Current database

Name of the database from which the

details are to be obtained

table_name

VARCHAR(255)

All tables

Name of the table for which the trigger

is defined. Pattern matching is
supported.

Returned Result Set

Table 6-34 psp_triggers Returned Result Set
Column Name

Data Type

Description

TRIGGER_
QUALIFIER

VARCHAR (20)

Name of the database

TRIGGER_OWNER

VARCHAR (20)

Name of the owner of the Trigger

TABLE_NAME

VARCHAR(255)

Name of the table for which the trigger is defined.

TRIGGER_NAME

VARCHAR(255)

Name of the trigger

ISUPDATE

UTINYINT

Is set if it is an update trigger

ISDELETE

UTINYINT

Is set if it is an delete trigger

ISINSERT

UTINYINT

Is set if it an insert trigger

ISAFTER

UTINYINT

Is set if the trigger action time is "after"

ISBEFORE

UTINYINT

Is set if the trigger action time is "before"

REMARKS

VARCHAR(255)

Remarks

Examples
Assume that the current database is "mydbase." The following
statement returns the list of triggers defined in the database:
CREATE TABLE A
(
col1 INTEGER,
col2 CHAR(255)

6-41

System Stored Procedures

) ;
CREATE TABLE B
(
col1 INTEGER,
col2 CHAR(255)
) ;
CREATE TRIGGER Insert
AFTER INSERT ON A
FOR EACH ROW
INSERT INTO B VALUES
(NEW.col1, NEW.col2);
call psp_triggers(,)

Result Set
Trigger_
qualifier

Trigger
_owner

Table_
name

Trigger
_name

isupdate

isdelete

isinsert

isafter

isbefore

Remarks

mydbase

Null

Insert

Null

Error Conditions

psp_udfs

Condition

Error Message

database_qualifier is a blank string

Please enter a valid database name.

Database name cannot be a blank string.

table_name is a blank string

Table name cannot be a blank string.

Returns the list of user-defined functions (UDF) and their

corresponding information from the current database or the
specified database.
Syntax
call psp_udfs(['database_qualifier'], ['udf_name'])

6-42

Pervasive PSQL System Stored Procedures

Arguments
Table 6-35 psp_udfs Arguments
Parameter

Type

Default Value

Description

Database_qualifier

VARCHAR(20)

Current database

Name of the database from which the

details are to be obtained

udf_name

VARCHAR(255)

All user-defined functions

Name of the udf whose details are

needed. Pattern matching is
supported.

Returned Result Set

Table 6-36 psp_udfs Returned Result Set
Column Name

Data Type

Description

UDF_QUALIFIER

VARCHAR (20)

Name of the database

UDF_OWNER

VARCHAR (20)

Name of the owner of the UDF

UDF _NAME

VARCHAR(255)

Name of the UDF

UDF_TYPE

VARCHAR(25)

Type of UDF (always set to 1)

Currently, Pervasive PSQL does not support any special type of
UDF.

NUM_INPUT_
PARAMS

INT

Returns null, because SQLPROCEDURES returns null when

executed against Pervasive PSQL DSN.

NUM_OUTPUT_
PARAMS

INT

Returns 1, because UDFs return only scalar values

NUM_RESULT_
SETS

INT

Returns 0, because UDFs do not return resultsets

REMARKS

VARCHAR(255)

Remarks

Examples
Assume that the current database, "mydbase," has two user-defined
functions: "calcinterest" and "factorial."
call psp_udfs(, )

6-43

System Stored Procedures

Result Set
UDF_
qualifier

UDF_
owner

UDF_name

Udf_type

Num_ input_
params

Num_ output_
params

Num_
result_sets

Remarks

mydbase

Null

CalcInterest

Null

mydbase

Null

Factorial

Null

Error Conditions

psp_users

Condition

Error Message

database_qualifier is a blank string

Please enter a valid database name.

Database name cannot be a blank string.

udf_name is a blank string

User-defined function name cannot be a

blank string.

Returns the list of users and the corresponding information from the
current database or the specified database.
Syntax
call psp_users(['database_qualifier'], ['group_name'],
['user_name'])

Arguments
Table 6-37 psp_users Arguments
Parameter

Type

Default Value

Description

database_qualifier

VARCHAR(20)

Current database

Name of the database from which the

details are to be obtained

group_name

VARCHAR(255)

All groups (if group_name

is null)

Name of the group used to return the

user information. Pattern matching is
supported. If group name is specified
(i.e. if it is not NULL), only users
belonging to the same group will be
returned.

user_name

VARCHAR(255)

All users (if user_name is

null)

Name of the user. Pattern matching is

supported.

6-44

Pervasive PSQL System Stored Procedures

Returned Result Set

Table 6-38 psp_users Returned Result Set
Column Name

Data Type

Description

DATABASE_QUALIFIER

VARCHAR(20)

Name of the database

GROUP_ID

USMALLINT

Group ID of the group to which user belongs

GROUP_NAME

VARCHAR(255)

Name of the group to which user belongs

USER_ID

USMALLINT

ID of the user

USER_NAME

VARCHAR(255)

Name of the user

Examples
Assume that current database, "mydbase," has users "John," "Mary,"
and "Michael," and groups "DevGrp" and "DevGrp1."
call psp_users(, ,

Result Set
Database_qualifier

Group_Id

Group_Name

User_Id

User_Name

Demodata

DevGrp

John

Demodata

DevGrp1

Mary

Demodata

DevGrp

Michael

call psp_users(, 'Devgrp', )

6-45

System Stored Procedures

Result Set
Database_qualifier

Group_Id

Group_Name

User_Id

User_Name

Demodata

DevGrp

John

Demodata

DevGrp

Michael

Error Conditions

psp_view_
rights

Condition

Error Message

database_qualifier is a blank string

Please enter a valid database name.

Database name cannot be a blank string.

user_name is null

User name cannot be a null.

group_name is a blank string

Group name cannot be a blank string.

Returns the list of list of view rights and corresponding information

for the specified view, from the current database or the specified
database. The view can be a trusted or a non-trusted one. See See
Trusted and Non-trusted Objects on page 3-154.
Psp_view_rights applies only to a database using V2 metadata.
Syntax
call psp_view_rights(['database_qualifier'], ['view_
name'], ['user_name'])

Arguments
Table 6-39 psp_view_rights Arguments
Parameter

Type

Default Value

Description

database_qualifier

VARCHAR(20)

Current database

Name of the database from which the details

are to be obtained

view_name

VARCHAR(255)

All views (if view_

name is null)

Name of the view for which rights are

specified. Pattern matching is supported.

user_name

VARCHAR(255)

Curent user (if

user_name is null)

Name of the user for whom the list of view

rights needs to be obtained. Pattern
matching is supported.

6-46

Pervasive PSQL System Stored Procedures

Returned Result Set

Table 6-40 psp_view_rights Returned Result Set
Column Name

Data Type

Description

VIEW_QUALIFIER

VARCHAR (20)

Name of the database

VIEW_OWNER

VARCHAR (20)

Name of the owner of the view

USER_NAME (GRANTEE)

VARCHAR(255)

Name of the user

VIEW_NAME

VARCHAR(255)

Name of the view

RIGHTS

VARCHAR(12)

One of the following values:

ALTER
DELETE
INSERT
SELECT
UPDATE

Examples
Assume that the following permissions exist for the DEMODATA
sample database:
GRANT
GRANT
GRANT
GRANT
GRANT
GRANT

SELECT ON VIEW vw_Dept TO John

ALTER ON VIEW vw_Dept TO John
DELETE ON VIEW vw_Dept TO John
SELECT ON VIEW vw_Class TO Mary
ALTER ON VIEW vw_Class TO Mary
SELECT ON VIEW vw_Class TO Prakesh

The following statement prints the view permissions on the vw_

Dept view for user John.
call psp_view_rights(,'vw_Dept', 'John')

Result Set
View_Qualifier

View_owner

User_name

View_name

Rights

Demodata

Null

John

vw_Dept

ALTER

Demodata

Null

John

vw_Dept

DELETE

Demodata

Null

John

vw_Dept

SELECT

6-47

System Stored Procedures

Assume that user Mary is logged on the database. The following

statement prints the view permissions on all views in the sample
database DEMODATA for the current user (Mary).
call psp_view_rights('demodata', , )

Result Set
View_Qualifier

View_owner

User_name

View_name

Rights

Demodata

Null

Mary

vw_Class

ALTER

Demodata

Null

Mary

vw_Class

SELECT

The following statement prints the view permissions on the vw_

Class view for user Mary.
call psp_view_rights('demodata', 'vw_C%', 'Mary')

Result Set
View_Qualifier

View_owner

User_name

View_name

Rights

Demodata

Null

Mary

vw_Class

ALTER

Demodata

Null

Mary

vw_Class

SELECT

Error Conditions

6-48

Condition

Error Message

database_qualifier is a blank string

Please enter a valid database name.

Database name cannot be a blank string

view_name is a blank string

View name cannot be a blank string.

user_name is a blank string

User name cannot be a blank string.

psp_procedure_rights called for a

database with V1 metadata

View and Stored Procedure permissions

are not supported for metadata version 1.

Pervasive PSQL System Stored Procedures

psp_views

Returns the list of views along with their corresponding information,

from the current database or from the database specified.
Syntax
call psp_views(['database_qualifier'], ['view_name'])

Arguments
Table 6-41 psp_views Arguments
Parameter

Type

Default Value

Description

Database_qualifier

VARCHAR(20)

Current database

Name of the database from which the

details are to be obtained

view_name

VARCHAR(255)

(no default value)

Name of the view whose information

is required. Pattern matching is
supported.

Returned Result Set

Table 6-42 psp_views Returned Result Set
Column Name

Data Type

Description

VIEW_QUALIFIER

VARCHAR (20)

Name of the database

VIEW_OWNER

VARCHAR (20)

Name of the owner of the view

VIEW_NAME

VARCHAR(255)

Name of the view

REMARKS

VARCHAR(255)

Remarks

TRUSTEE

INTEGER

For V2 metadata, returns 0 for a trusted view and -1 for a nontrusted view. The TRUSTEE column is empty for V1 metadata.

Examples
Assume that the following view exists for a V2 metadata database
named DEMODATA2.
CREATE VIEW vw_Person (lastn,firstn,phone) WITH EXECUTE
AS Master AS
SELECT Last_Name, First_Name,Phone FROM Person;

6-49

System Stored Procedures

The following statement prints the list of views in the current

database, which is DEMODATA2.
call psp_views(, ,)

Result Set
View_Qualifier

View_Owner

View_Name

Remarks

Trustee

Demodata

Null

Vw_Person

Null

The following statement prints the view information for the vw_
Person view in the DEMODATA database.
call psp_views('demodata', 'vw_P%')

Result Set
View_Qualifier

View_Owner

View_Name

Remarks

Demodata

Null

Vw_Person

Null

Trustee

Error Conditions

6-50

Condition

Error Message

database_qualifier is a blank string

Please enter a valid database name.

Database name cannot be a blank string

view_name is a blank string

Table name cannot be a blank string.

Pervasive PSQL System Stored Procedures

6-51

System Stored Procedures

6-52

chapter

Performance Reference

An Examination of the Performance Features in the Database Engine

The purpose of this chapter is to explain in detail the optimizations

used in the database engine, and how to best take advantage of them
in your SQL statements.
This chapter contains complex technical material and is intended for
expert-level SQL users. For definitions of the technical terms used in
this chapter, see Terminology on page 7-18.

Restriction Analysis on page 7-2

Restriction Optimization on page 7-4
Push-Down Filters on page 7-11
Efficient Use of Indexes on page 7-12
Temporary Table Performance on page 7-15
Row Pre-fetch on page 7-16
Terminology on page 7-18

7-1

Performance Reference

Restriction Analysis
This section explains one method that the database engine uses to
analyze and optimize on a Restriction. For definitions of the
technical terms used in this chapter, see Terminology on page 7-18.

Modified CNF
Conversion

During SQL statement execution, the database engine attempts to

convert the restriction into Modified Conjunctive Normal Form
(Modified CNF). Conversion to modified CNF is a method for
placing Boolean expressions in a uniform structure to facilitate
restriction analysis for possible query processing optimizations. If
the restriction can be converted to modified CNF, the database
engine can methodically and thoroughly analyze the query for
possible optimizations that make efficient use of available Indexes. If
the database engine is unable to convert the restriction to modified
CNF, it still analyzes the restriction for possible optimizations. In this
case, however, the database engine is often unable to make use of the
available indexes as effectively as it would for restrictions that either
are already in modified CNF or can be converted internally to
modified CNF.

Restrictions
that Cannot be
Converted

The database engine is unable to convert some restrictions into

modified CNF depending on the contents of the restriction. A
restriction is not converted to modified CNF if any of the following
conditions is true:

Conditions
Under Which
Conversion is
Avoided

7-2

The restriction contains a subquery.

The restriction contains a NOT operator.
The restriction contains a dynamic parameter (a dynamic
parameter is a question mark (?) in the SQL statement, which
will be prompted for when the statement is executed).

There are some cases in which the database engine may be capable of
converting a restriction into modified CNF but will not do so. The
database engine chooses not to convert a restriction to modified
CNF in cases where it has determined that the restriction is more
likely to benefit from optimizations that can be applied to its original
form than from optimizations that could be applied after modified
CNF conversion.

Restriction Analysis

A restriction is not converted to modified CNF if either of the

following conditions is true:

The restriction is in Disjunctive Normal Form (DNF) and all

Predicates involve only the equal (=), LIKE or IN comparison
operators.
For example, the database engine does not convert the following
restriction to modified CNF:
(c1 = 1 AND c2 = 1) OR (c1 = 1 AND c2 = 2) OR (c1 = 2)

The restriction meets all of the following conditions:

It contains an expression in Disjunctive Normal Form

(DNF) that is AND connected to the rest of the restriction

The specified DNF expression contains only Predicates that

involve the equal (=), LIKE or IN comparison operator

The predicates in identical positions in each Conjunct in the

DNF expression reference the same column.
For example, a Restriction that contains the following
Expression will not be converted to modified CNF:
(c1 = 1 AND c2 = 1) OR (c1 = 1 AND c2 = 2)

7-3

Performance Reference

Restriction Optimization
This section provides a detailed description of the primary
techniques employed by the database engine to make use of
expressions in a restriction for optimization purposes. The types of
optimizations performed by the database engine are described below
in order from the simplest to the most complex.
A clear understanding of optimization techniques used by the
database engine may aid you in structuring queries to achieve
optimal performance from the database engine. In addition, by
understanding how the database engine uses indexes to optimize
queries, you can determine how to construct indexes that provide the
best performance for a given set of typical uses.
For the sake of simplicity, the descriptions below initially address
expressions that reference columns from only a single table.
Optimizations making use of join conditions, in which predicates
compare columns from two different tables, are described following
the single table optimizations.
For definitions of the technical terms used in this chapter, see
Terminology on page 7-18.

Single
Predicate
Optimization

The simplest form of Restriction optimization involves the use of a

single Predicate. A predicate can be used for optimization if it meets
all of the following conditions:

the predicate is joined to the rest of the restriction by the AND

operator
one operand of the predicate consists of a column reference
which is a leading segment of an index and the other operand
consists of an expression that does not contain a column
reference (that is, the other operand contains only a literal value
or dynamic parameter)
the comparison operator is one of: <, <=, =, >=, >, LIKE, or IN.

For example, suppose an index exists with the first segment on

column c1. The following predicates can be used for optimization:
c1 = 1
c1 IN (1,2)
c1 > 1

7-4

Restriction Optimization

The LIKE operator is optimized only if the second operand starts

with a character other than a wildcard. For example, C2 LIKE
ABC% can be optimized, but C2 LIKE %ABC will not be.

Closed Range
Optimization

A Closed Range can be used for optimization if it satisfies all the

requirements for Single Predicate Optimization.
For example, suppose an index exists with the first segment on
column c1. The following closed range can be used for optimization:
c1 >= 1 AND c1 < 10

Modified
Disjunct
Optimization

A Modified Disjunct can be used for optimization if it satisfies all of

the following conditions:

it is joined to the rest of the Restriction by the AND operator

each Predicate and Closed Range in the disjunct satisfies the
requirements for Single Predicate Optimization and Closed
Range Optimization
each predicate or closed range references the same column as the
others.

For example, suppose an index exists with the first segment on

column c1. The following modified disjunct can be used for
optimization:
c1 = 1 OR (c1 > 5 AND c1 < 10) OR c1 > 20

The following modified disjunct cannot be used for this type of

optimization because the same column is not referenced in all
predicates and closed ranges:
c1 = 1 OR (c1 > 5 AND c1 < 10) OR c2 = 1

Conjunct
Optimization

A Conjunct can be used for optimization if it satisfies all of the

following conditions:

it is joined to the rest of the restriction by the AND operator

each Predicate in the conjunct satisfies the requirements for
Single Predicate Optimization
each predicate optimizes on the leading segments of an index
with only one predicate for each leading segment (that is, there
are not two different predicates that use the same set of leading
segments)

7-5

Performance Reference

all predicates, except for the predicate referencing the last

segment used for optimization, use the equal (=) comparison
operator.

For example, suppose an index exists with the first three segments on
columns c1, c2 and c3, in that order. The following conjunct
assignments can be used for optimization:
c1 = 1 AND c2 = 1 AND c3 = 1
c1 = 1 AND c2 = 1 AND c3 >= 1
c1 = 1 AND c2 > 1

The order of the predicates does not matter. For example, the
following conjunct can be used for optimization:
c2 = 1 AND c3 = 1 AND c1 = 1

The following conjunct cannot be used for optimization because the

second segment of the index is skipped (there is no reference to
column c2):
c1 = 1 AND c3 = 1

In this case, the single predicate, c1 = 1, can still be used for

optimization.

Disjunctive
Normal Form
Optimization

An expression in Disjunctive Normal Form (DNF) can be used for

optimization if it satisfies all of the following conditions:

it is joined to the rest of the restriction by the AND operator

each of the conjuncts in the expression satisfies the requirements
for Conjunct Optimization with the additional limitation that
all the predicates must contain the equal (=) comparison
operator
all the conjuncts must use the same index and the same number
of segments for optimization.

The database engine does not convert restrictions that are originally
in DNF into modified CNF, because it can optimize on DNF.
For example, suppose an index exists with the first three segments on
columns c1, c2 and c3, in that order. The following expression in
DNF can be used for optimization:
(c1 = 1 AND c2 = 1 AND c3 = 1) OR (c1 = 1 AND c2 = 1 AND
c3 = 2) OR (c1 = 2 AND c2 = 2 AND c3 = 2)

7-6

Restriction Optimization

The following expression in DNF cannot be used for optimization

because both conjuncts do not reference the same number of
segments:
(c1 = 1 AND c2 = 1 AND c3 = 1) OR (c1 = 1 AND c2 = 2)

Modified
Conjunctive
Normal Form
Optimization

An expression in Modified Conjunctive Normal Form (Modified

CNF) can be used for optimization if it satisfies all of the following
conditions:

it is joined to the rest of the restriction by the AND operator

each Modified Disjunct satisfies the requirements for Modified
Disjunct Optimization except that each modified disjunct must
reference a different index segment which together make up the
Leading Segments (that is, taking all the disjuncts together, no
segments can be skipped)
all the modified disjuncts except for the one that references the
last segment must contain at least one predicate that contains the
equals (=) comparison operator.

Modified CNF optimization is similar to DNF optimization but

allows combinations of predicates involving different comparison
operations not supported by DNF optimization.
For example, suppose an index exists with the first three segments on
columns c1, c2 and c3, in that order. The following expression in
modified CNF can be used for optimization:
(c1 = 1 OR c1 = 2) AND (c2 = 1 OR (c2 > 2 AND c2 < 5))
AND (c3 > 1)

It may be easier to understand how the database engine uses this

expression for optimization by looking at the equivalent expression
in modified DNF:
(c1 = 1 AND c2 = 1 AND c3 > 1) OR (c1 = 1 AND (c2 > 2 AND
c2 < 5) AND c3 > 1) OR (c1 = 2 AND c2 = 1 AND c3 > 1) OR
(c1 = 2 AND (c2 > 2 AND c2 < 5) AND c3 > 1)

Closing Open
Ended Ranges
through
Modified CNF
Optimization

Two Modified Disjuncts can be combined to form one or more

Closed Ranges if the following conditions are satisfied:

both modified disjuncts satisfy the requirements for Modified

Disjunct Optimization
both modified disjuncts use the same segment in the same index

7-7

Performance Reference

both modified disjuncts contain open ended ranges that can be

combined to form one or more closed ranges.

For example, suppose an index exists with the first segment on

column c1. The following expression in modified CNF can be used
for optimization:
(c1 = 1 OR c1 > 2) AND (c1 < 5 OR c1 = 10)

It may be easier to understand how the database engine uses this

expression for optimization by looking at an equivalent expression
which is simply a modified disjunct:
c1 = 1 OR (c1 > 2 AND c1 < 5) OR c1 = 10

Single Join
Condition
Optimization

The simplest form of optimization involving two tables makes use of

a single Join Condition. Single join condition optimization is similar
to Single Predicate Optimization. A join condition can be used for
optimization if it satisfies the requirements for single predicate
optimization. The table that will be optimized through the use of the
join condition will be processed after the other table referenced in
the join condition. The table optimized through the use of the join
condition uses an optimization value retrieved from a row in the
other table referenced in the join condition.
For example, suppose an index exists on table t1 with the first
segment on column c1. The following join conditions can be used
for optimization:
t1.c1 = t2.c2
t1.c1 > t2.c2

During optimization, a row is retrieved from table t2. From this row,
the value of column c2 is used to optimize on table t1 according to
the join condition.
If, instead of an index on t1.c1, there is an index on t2.c2, then
t1.c1=t2.c2 could be used to optimize on table t2. In this case, table
t1 would be processed first and the value for t1.c1 would be used to
optimize on table t2 according to the join condition.
In the case that there is an index on t1.c1 as well as an index on t2.c2,
the database engine query optimizer examines the size of both tables
as well as the characteristics of the two indexes and chooses the table
to optimize that will provide the best overall query performance.

7-8

Restriction Optimization

Conjunct with
A Conjunct that consists of a mixture of join conditions and other
Join Conditions Predicates can be used for optimization if it satisfies all of the
following conditions:
Optimization

all the join conditions compare columns from the same two
tables
the conjunct satisfies the requirements for regular Conjunct
Optimization for one of the two tables.

The table that will be optimized through the use of the conjunct will
be processed after the other table referenced.
For example, suppose an index exists on table t1 with the first three
segments on columns c1, c2 and c3, in that order. The following
conjuncts can be used for optimization:
t1.c1
t1.c1
t1.c1
t1.c1

Modified
Conjunctive
Normal Form
with Join
Conditions
Optimization

=
=
=
=

t2.c1
t2.c1
t2.c1
1 AND

AND t1.c2 = t2.c2 AND t1.c3 = t2.c3

AND t1.c2 > t2.c2
AND t1.c2 = 1
t1.c2 = t2.c2

An Expression in Modified Conjunctive Normal Form (Modified

CNF) that contains join conditions can be used for optimization if it
satisfies all the following conditions:

it satisfies the conditions for Modified Conjunctive Normal

Form Optimization
in addition, all disjuncts but the disjunct optimizing on the last
portion of the leading segment being used must contain only a
single join condition or a single predicate and at least one of
these is a single join condition.

For example, suppose an index exists on table t1 with the first three
segments on columns c1, c2 and c3, in that order. The following
expressions in modified CNF can be used for optimization:
(t1.c1 = t2.c1) AND (t1.c2 = t2.c2 OR
(t1.c2 > 2 AND t1.c2 < 5))
(t1.c1 = 1) AND (t1.c2 = t2.c2) AND
(t1.c3 > 2 AND t1.c3 < 5)

7-9

Performance Reference

Closing Join
Condition Open
Ended Ranges
through
Modified CNF
Optimization

This type of optimization is exactly like Closing Open Ended Ranges

through Modified CNF Optimization except that the range being
closed may be a Join Condition.
For example, suppose an index exists on table t1 with the first two
segments on columns c1 and c2, in that order. The following
expressions in modified CNF can be used for optimization:
(t1.c1 > t2.c1) AND (t1.c1 < t2.c2 OR t1.c1 = 10)
(t1.c1 = t2.c1) AND (t1.c2 > t2.c2) AND (t1.c2 < 10 OR
t1.c2 = 100)

Multi-Index
Modified
Disjunct
Optimization

A Modified Disjunct can be used for optimization through the use of

more than one index if it satisfies all of the following conditions:

is joined to the rest of the restriction by the AND operator

each Predicate and Closed Range in the disjunct satisfies the
requirements for Single Predicate Optimization or Closed Range
Optimization, respectively
each predicate or closed range references a column that is the
first segment in an index. If all predicates and closed ranges
reference the same column, then this scenario is simply Modified
Disjunct Optimization, as described previously.

For example, suppose an index exists with the first segment on

column c1 and another index exists with the first segment on column
c2. The following modified disjunct can be used for optimization:
c1 = 1 OR (c1 > 5 AND c1 < 10) OR c2 = 1

7-10

Push-Down Filters

Push-Down Filters
Push-down filters are strictly an internal optimization technique. By
taking advantage of high speed filtering capabilities, the database
engine can efficiently identify certain rows to be rejected from the
result set depending on characteristics of the restriction. Because
rows are rejected from the result set before they are returned, the
database engine has to analyze fewer rows and completes the
operation faster than it would without push-down filters.
The database engine can use an expression or combination of
expressions as a push-down filter if the following conditions are
satisfied:

A Predicate can be used in a push-down filter if it is joined to the

rest of the Restriction by the AND operator.
A Predicate can be used in a push-down filter if one operand
consists of a column reference and the other operand consists of
either a literal value or a dynamic parameter (?). Also, the
referenced column must not be of one of the following data
types: bit, float, double, real, longvarchar, longvarbinary, or
binary.
A Predicate can be used in a push-down filter if the comparison
operator is one of the following: <, <=, =, >=, >, or <>.
A Disjunct can be used in a push-down filter if it is joined to the
rest of the restriction by the AND operator and all the predicates
within the disjunct satisfy the requirements for a predicate to be
used in a push-down filter, except for the condition that the
predicate must be joined to the rest of the restriction by an AND
operator. Only one disjunct may be included in the push-down
filter.
A push-down filter may combine a single disjunct with other
predicates that satisfy the requirements for a predicate to be used
in a push-down filter.

For definitions of the technical terms used in this chapter, see

Terminology on page 7-18.

7-11

Performance Reference

Efficient Use of Indexes

Indexes can optimize on query characteristics other than the
Restriction, such as a DISTINCT or ORDER BY clause.
For definitions of the technical terms used in this chapter, see
Terminology on page 7-18.

DISTINCT in
Aggregate
Functions

An index can be used to reduce the number of rows retrieved for

queries with a selection-list that consists of an Aggregate Function
containing the DISTINCT keyword. To be eligible for this type of
optimization, the expression on which the DISTINCT keyword
operates must consist of a single column reference. Furthermore, the
column must be the leading segment of an index.
For example, suppose an index exists on table t1 with the first
segment on column c1. The index can be used to avoid retrieving
rows with duplicate values of column c1:
SELECT COUNT(DISTINCT c1) FROM t1 WHERE c2 = 1

DISTINCT
Preceding
Selection-list

An index can be used to reduce the number of rows retrieved for

some queries with the DISTINCT keyword preceding the selectionlist. To be eligible for this type of optimization, the selection-list
must consist only of column references (no complex expressions
such as arithmetic expressions or scalar functions), and the
referenced columns must be the leading segments of a single index.
For example, suppose an index exists on table t1 with the first three
segments on columns c1, c2 and c3, in any order. The index can be
used to avoid retrieving rows with duplicate values for the selectionlist items:
SELECT DISTINCT c1, c2, c3 FROM t1 WHERE c2 = 1

Relaxed Index
Segment Order
Sensitivity

Whether an index can be used to optimize on an ORDER BY clause

depends on the order in which the columns appear as segments in
the index. Specifically, to be eligible for this type of optimization, the
columns in the ORDER BY clause must make up the leading
segments of an index, and the columns must appear in the ORDER
BY clause in the same order as they appear as segments in the index.
In contrast, an index can be used to optimize on a DISTINCT
preceding a selection-list or on a GROUP BY clause as long as the

7-12

Efficient Use of Indexes

selection-list or GROUP BY clause consists of columns that are the

leading segments of the index. This statement is true regardless of the
order in which the columns appear as segments in the index.
For example, suppose an index exists on table t1 with the first three
segments on columns c1, c2 and c3, in any order. The index can be
used to optimize on the DISTINCT in the following queries:
SELECT DISTINCT c1, c2, c3 FROM t1
SELECT DISTINCT c2, c3, c1 FROM t1 WHERE c3 > 1

The index can be used to optimize on the GROUP BY in the

following queries:
SELECT c1, c2, c3, count(*) FROM t1 GROUP BY c2, c1, c3
SELECT c2, c3, c1, count(*) FROM t1 GROUP BY c3, c2, c1

For the index to be used to optimize on the ORDER BY, however, the
index segments must be in the order of c2, c1, c3:
SELECT c1, c2, c3 FROM t1 ORDER BY c2, c1, c3

Relaxed
Segment
Ascending
Attribute
Sensitivity

Whether an index can be used to optimize on an ORDER BY clause

depends on several conditions.
Specifically, an index can be used for optimization of ORDER BY if
all of the following conditions are satisfied:

the DESC keyword follows the column in the ORDER BY clause

the corresponding index segment is defined as descending
the specified column is not nullable.

In addition, an index can be used for optimization of ORDER BY if

all of the following converse conditions are satisfied (note that
nullable columns are allowed for ascending ORDER BY):

the ASC keyword or neither ASC nor DESC follows the column
in the ORDER BY statement
the corresponding index segment is defined as ascending.

As well, an index can be used for optimization of ORDER BY if the

ascending/descending attributes of all the involved segments are the
exact opposite of each ASC or DESC keyword specified in the
ORDER BY. Again, the segments defined as descending can only be
used if the associated columns are not nullable.
Indexes can be used for any of the restriction optimizations,
optimization on a DISTINCT, or optimization on a GROUP BY

7-13

Performance Reference

clause, regardless of the ascending/descending attribute of any of the

segments.
For example, suppose an index exists on table t1 with the first two
segments on columns c1 and c2, in that order, and both segments are
ascending. The index can be used to optimize on the following
queries:
SELECT
SELECT
SELECT
SELECT
SELECT

c1, c2, c3 FROM

c1, c2, c3 FROM
DISTINCT c1, c2
DISTINCT c2, c1
* FROM t1 WHERE

t1 ORDER BY c1, c2
t1 ORDER BY c1 DESC, c2 DESC
FROM t1
FROM t1
c1 = 1

Suppose an index exists on table t1 with the first two segments on

columns c1 and c2, in that order, with the segment on c1 defined as
ascending and the segment on c2 defined as descending. Suppose
also that c2 is nullable. The second segment cannot be used to
optimize on ORDER BY because the column is both descending and
nullable. The index can be used to optimize on the following queries:
SELECT
SELECT
SELECT
SELECT
SELECT

c1, c2, c3 FROM

c1, c2, c3 FROM
DISTINCT c1, c2
DISTINCT c2, c1
* FROM t1 WHERE

t1 ORDER BY c1
t1 ORDER BY c1 DESC
FROM t1
FROM t1
c1 = 1

If column c2 is not nullable, then the index can also be used to

optimize on the following queries:
SELECT c1, c2, c3 FROM t1 ORDER BY c1, c2 DESC
SELECT c1, c2, c3 FROM t1 ORDER BY c1 DESC, c2

Search Update
Optimization

You may take advantage of search optimization when you update a

leading segment index by using the same index in the WHERE clause
for the search. The database engine uses one session (client ID) for
the UPDATE and another session for the search.
The following statements benefit from search optimization.
CREATE
CREATE
INSERT
INSERT
INSERT
INSERT
INSERT
UPDATE
UPDATE

7-14

TABLE t1 (c1 INT)

INDEX t1_c1 ON t1(c1)
INTO t1 VALUES(1)
INTO t1 VALUES(1)
INTO t1 VALUES(9)
INTO t1 VALUES(10)
INTO t1 VALUES(10)
t1 SET c1 = 2 WHERE c1 = 10
t1 SET c1 = c1 + 1 WHERE c1 >= 1

Temporary Table Performance

Performance improvements have been made to the implementation
of temporary sort tables in this release. To process certain queries,
the database engine must generate temporary tables for internal use.
The performance for many of these queries has been improved.
In general, the database engine generates at least one temporary table
to process a given query if any of the following conditions is true:

The DISTINCT keyword precedes the selection list and the items
in the selection list are not columns that are the leading segments
of an index.
For example, a temporary table is generated to process the
following query unless an index exists with columns c1 and c2 as
leading segments:
SELECT DISTINCT c1, c2 FROM t1

A GROUP BY clause exists, and the items in the GROUP BY

clause are not columns that are the leading segments of an index.
For example, a temporary table is generated to process the
following query unless an index exists with columns c1 and c2 as
leading segments:
SELECT c1, c2, COUNT(*) FROM t1 GROUP BY c1, c2

A static cursor is being used.

For example, a temporary table is generated if an application
calls the ODBC API SQLSetStmtOption specifying the
SQL_CURSOR_TYPE option and the SQL_CURSOR_STATIC
value prior to creation of the result set.

The result set includes bookmarks.

For example, if the ODBC API SQLSetStmtOption is called
specifying the SQL_USE_BOOKMARKS option and the
SQL_UB_ON value prior to generating the result set.

A query contains a non-correlated subquery to the right of the

IN or =ANY keywords.
For example:
SELECT c1 FROM t1 WHERE c2 IN (SELECT c2 FROM t2)

7-15

Performance Reference

Row Pre-fetch
For definitions of the technical terms used in this chapter, see
Terminology on page 7-18.
Under certain circumstances, upon execution of a SELECT
statement, this release of the database engine attempts to pre-fetch to
the client the first two rows of the resulting rowset. This pre-fetch
greatly improves the performance of fetching data from result sets
that consist of zero or one row.
Pre-fetching rows can be a costly waste of time if the result set
consists of more than one row and the first data retrieval operation
requests a row other than the first row in the result set, such as the
last row. Therefore, pre-fetching is limited to a maximum of two
rows with the goal of improving performance for the cases that
would benefit most while avoiding cases where pre-fetching would
not provide significant benefits.
Pre-fetching occurs only if Array Fetch is enabled in the client DSN
setup options. Array fetching is similar to pre-fetching except that an
array fetch does not occur until the first explicit data retrieval
operation is performed. This difference exists because the first
explicit data retrieval operation may provide enough information to
allow the database engine to extrapolate how the rest of the result set
will be retrieved. For example, if the first data retrieval operation is a
call to the ODBC API SQLFetch, then the database engine can
assume with complete certainty that the entire result set will be
retrieved one record at a time in the forward direction only. This
assumption can be made because, according to the ODBC
specification, an SQLFetch entails that the rest of the result set will be
retrieved via SQLFetch as well. On the other hand, if a
SQLExtendedFetch call is made, and the row set size is greater than
one, then the client assumes that the developer-specified rowset size
is optimal, and it does not override that setting with the array fetch.
Pre-fetching occurs only when all of the following conditions are
satisfied:

7-16

Array fetch is enabled.

The result set does not include large variable length data; for
example, the selection list does not contain a column of type
LONGVARCHAR or LONGVARBINARY.

Row Pre-fetch

The result set does not include bookmarks.

For example, pre-fetching does not occur if the ODBC API
SQLSetStmtOption is called prior to generating the result set,
specifying the SQL_USE_BOOKMARKS option and the
SQL_UB_ON value.

A cursor with read-only concurrency is being used.

For example, pre-fetching does not occur if the ODBC API
SQLSetStmtOption is called, specifying the
SQL_CONCURRENCY option and any value other than
SQL_CONCUR_READ_ONLY, prior to generating the result
set. By default, concurrency is read-only.

7-17

Performance Reference

Terminology
This section provides definitions and examples designed to help you
understand the complex technical material in this chapter.
Aggregate Function
An aggregate function uses a group of values in the SELECT or
HAVING clause of a query to produce a single value. Aggregate
functions include: COUNT, AVG, SUM, MAX, MIN, and
DISTINCT.
Closed Range
A closed range is a pair of Open-Ended Ranges joined by an AND
operator. Both open-ended ranges must reference the same column
and one must contain the < or <= comparison operator and the
other must contain the >= or > comparison operator. A BETWEEN
clause also defines a closed range.
For example, the following expressions are closed ranges:
c1 > 1 AND c1 <= 10
c1 BETWEEN 1 AND 10

Conjunct
A conjunct is an expression in which two or more Predicates are
joined by AND operators. For example, the following Restrictions
are conjuncts:
c1=2 AND c2<5
c1>2 AND c1<5 AND c2= abc

Conjunctive Normal Form (CNF)

An Expression is in Conjunctive Normal Form if it contains two or
more Disjuncts joined by AND operators. For example, the
following expressions are in CNF:
c1 = 2 AND c2 < 5
(c1 = 2 OR c1 = 5) AND (c2 < 5 OR c2 > 20) AND (c3 = abc
OR c3 = efg)

7-18

Terminology

Disjunct
A disjunct is an Expression in which two or more Predicates are
joined by OR operators. For example, the following expressions are
disjuncts:
c1 = 2 OR c2 = 5
c1 = 2 OR c1 > 5 OR c2 = abc

Disjunctive Normal Form (DNF)

An Expression is in disjunctive normal form if it contains two or
more Conjuncts joined by OR operators. For example, the following
expressions are in DNF:
c1 = 2 OR c2 < 5
(c1 = 2 AND c2 = 5) OR (c2 > 5 AND c2 < 10) OR c3 = abc

Expression
An expression consists of any Boolean algebra allowed in a
Restriction. An entire restriction or any part of the restriction that
includes at least one or more complete Predicates is an expression.
Index
An index is a construct associated with one or more columns in a
table that allows the database engine to perform efficient searches
and sorts. The database engine can make use of indexes to improve
search performance by reading only specific rows that will satisfy the
search conditions rather than by examining all the rows in the table.
The database engine can make use of indexes to retrieve rows in the
order specified by an SQL query rather than having to use inefficient
techniques to order the rows after retrieving them.
Join Condition
A join condition is a Predicate that compares a column in one table
to a column in another table using any of the comparison operators:
<, <=, =, >=, >.
For example, the following predicates are join conditions:
t1.c1 = t2.c1
t1.c1 > t2.c2

7-19

Performance Reference

Leading Segments
A group of index segments are leading segments if they consist of the
first n columns in an Index, where n is any number up to and
including the total number of segments in the index. For example, if
an index is defined with segments on columns c1, c2, and c4, then c1
is a leading segment, c1 and c2 together are leading segments, and all
three together are leading segments. c2 alone is not a leading
segment, because the segment c1 precedes c2 and is excluded.
Columns c1 and c4 together are not leading segments, because c2
precedes c4 and is excluded.
Modified Conjunctive Normal Form (Modified CNF)
An Expression in Modified Conjunctive Normal Form is like an
expression in Conjunctive Normal Form (CNF) except that each
Disjunct may contain Closed Ranges as well as Predicates.
For example, the following expressions are in Modified CNF:
c1 = 2 AND c2 < 5
(c1 = 2 OR (c1 > 4 AND c1 < 6) OR c1 = 10) AND (c2 = 1
OR c3 = efg)

Modified Disjunct
A modified disjunct is like a Disjunct except that it may contain
Closed Ranges as well as Predicates.
For example, the following expressions are modified disjuncts:
c1 = 2 OR (c1 > 4 AND c1 < 5)
(c1 = 2 OR (c1 > 4 AND c1 < 5)) OR c2 = abc

Open-Ended Range
An open-ended range is a Predicate that contains any of the
following comparison operators: <, <=, >= or >. Furthermore, one
of the predicates operands must consist entirely of a single column
and the other operand must consist entirely of either a single column
from another table or a literal.
For example, the following expressions are open ended ranges:
c1 > 1
c1 <= 10
t1.c1 > t2.c1

7-20

Terminology

Predicate
A predicate is a Boolean expression that does not include any AND
or OR Boolean operators (with the exception of a BETWEEN
predicate).
For example, the following expressions are predicates:
(c1 = 1)
(c1 LIKE abc)
(c1 BETWEEN 1 AND 2)

The following examples are not predicates:

(c1 > 1 AND c1 < 5)
(c1 = 1 OR c1 = 2)

Restriction
A restriction is the entire WHERE clause of an SQL query.

7-21

Performance Reference

7-22

Appendix

Data Types

Pervasive PSQL Supported Data Types

This appendix describes the data types and data type mappings
offered by Pervasive PSQL through the ODBC interface and the
Btrieve interface.

Pervasive PSQL Supported Data Types on page A-2

Notes on Data Types on page A-11
Legacy Data Types on page A-20
Btrieve Key Data Types on page A-21

A-1

Data Types

Pervasive PSQL Supported Data Types

The following table shows information about the transactional and
relational data types supported by Pervasive PSQL. The SRDE
converts the relational data types to ODBC default types unless
another data type conversion is specified when SQLGetData or
SQLBindCol is called. (For a discussion of data type conversions, see
the data types appendix in the Microsoft ODBC Programmers
Reference.).
Table A-1

Pervasive PSQL Data Types and Equivalent ODBC Data Types

Transactional
Type (Size)

Relational Type

ODBC Type (code)1

Type
Code2

Size
(bytes)

AUTOINC(2)

SMALLIDENTITY

SQL_SMALLINT(5)

AUTOINC(4)

IDENTITY

SQL_INTEGER(4)

BFLOAT(4)

BFLOAT4

SQL_REAL(7)

not null

BFLOAT(8)

BFLOAT8

SQL_DOUBLE(8)

not null

BLOB

LONGVARBINARY

SQL_LONGVARBINARY
(-4)

n/a3

not null

2, 3, 6

CLOB

LONGVARCHAR

SQL_LONGVARCHAR
(-1)

n/a3

not null
case
insensitive

5, 6

CURRENCY

SQL_DECIMAL(3)

not null

DATE

SQL_DATE(9)

not null

none

DATETIME

SQL_TIMESTAMP(11)

not null

DECIMAL

SQL_DECIMAL(3)

1 - 64

precision
scale
not null

FLOAT(4)

REAL

SQL_REAL(7)

not null

FLOAT(8)

DOUBLE

SQL_DOUBLE(8)

not null

GUID

UNIQUEIDENTIFIER SQL_GUID(-11)

not null

INTEGER(1)

TINYINT

SQL_TINYINT(-6)

not null

INTEGER(2)

SMALLINT

SQL_SMALLINT(5)

not null

A-2

Create/Add Notes
Parameters4

Pervasive PSQL Supported Data Types

Table A-1

Pervasive PSQL Data Types and Equivalent ODBC Data Types continued

Transactional
Type (Size)

Relational Type

ODBC Type (code)1

Type
Code2

Size
(bytes)

Create/Add Notes
Parameters4

INTEGER(4)

INTEGER

SQL_INTEGER(4)

not null

INTEGER(8)

BIGINT

SQL_DECIMAL(3)

not null

NUMERIC

SQL_NUMERIC(2)

1 - 15

precision
scale
not null

NUMERICSA

SQL_NUMERIC(2)

1 - 15

precision
scale
not null

NUMERICSTS

SQL_NUMERIC(2)

1- 14

precision
scale
not null

STRING

BINARY

SQL_BINARY(-2)

1- 8,000 size
not null
case
insensitive

2, 3

STRING

CHAR

SQL_CHAR(1)

1- 8,000 size
not null
case
insensitive

TIME

SQL_TIME(10)

not null

TIMESTAMP

SQL_TIMESTAMP(11)

not null

UNSIGNED(1)
BINARY

UTINYINT

SQL_TINYINT(-6)

not null

UNSIGNED(2)
BINARY

USMALLINT

SQL_SMALLINT(5)

not null

UNSIGNED(4)
BINARY

UINTEGER

SQL_INTEGER(4)

not null

UNSIGNED(8)
BINARY

UBIGINT

SQL_DECIMAL(3)

not null

WSTRING

not supported in SQL not supported in SQL

n/a3

WSZSTRING

not supported in SQL not supported in SQL

n/a3

A-3

Data Types

Table A-1

Pervasive PSQL Data Types and Equivalent ODBC Data Types continued

Transactional
Type (Size)

Relational Type

ODBC Type (code)1

Type
Code2

Size
(bytes)

ZSTRING

VARCHAR

SQL_VARCHAR(12)

1- 8,000 size
not null
case
insensitive

none

BIT

SQL_BIT(-7)

1 bit

6, 8

LOGICAL(1)

BIT

SQL_BIT(-7)

1 bit

LOGICAL(2)

SMALLINT

SQL_SMALLINT(5)

SQL_FLOAT and SQL_VARBINARY are not supported by Pervasive PSQL

The Pervasive PSQL metadata type code

"n/a" stands for "not applicable"

Create/Add Notes
Parameters4

not null

The required parameters are precision and size. The optional parameters are case insensitive, not null, and
scale.
Notes:
1. Padded with spaces
2. Flag set in FIELD.DDF to tell SQL to use binary
3. Padded with binary zeros
4. Cannot be used as variable or in stored procedures
5. Not padded
6. Cannot be indexed
7. Transactional only
8. TRUEBITCREATE must be set to "on" (the default)
9. TRUEBITCREATE must be set to "off"
10. Type code 30 is not a transactional interface type code. It is the identifier for DATETIME within the relational
interface metadata

A-4

Pervasive PSQL Supported Data Types

Data Type
Ranges
Table A-2

The following table lists the value range for the Pervasive PSQL data
types.

Pervasive PSQL Data Type Ranges

Relational Data Type

Valid Value Range

BFLOAT4

-1.70141172e+38 +1.70141173e+38
The smallest value by which you can increment or decrement a BLOAT4 is
2.938736e-39

BFLOAT8

-1.70141173e+38 +1.70141173e+38
The smallest value by which you can increment or decrement a BLOAT8 is
2.93873588e-39

BIGINT

-9223372036854775808 +9223372036854775807

BINARY

range not applicable

BIT

range not applicable

STRING

range not applicable

CURRENCY

-922337203685477.5808 +922337203685477.5807

DATE

01-01-0001 12-31-9999

DATETIME

January 1, 1753 through December 31, 9999, to an accuracy of one threehundredth of a second

DECIMAL

depends on the length and number of decimal places

DOUBLE

-1.7976931348623157e+308 +1.7976931348623157e+308
The smallest value by which you can increment or decrement a DOUBLE is
2.2250738585072014e-308

FLOAT

-1.7976931348623157E+308 +1.7976931348623157E+308
The smallest value by which you can increment or decrement a FLOAT is
2.2250738585072014e-308

IDENTITY

+1 +2147483647

INTEGER

-2147483648 +2147483647

LOGICAL

range not applicable

LONGVARBINARY

range not applicable

LONGVARCHAR

range not applicable

MONEY

-99999999999999999.99 +99999999999999999.99

A-5

Data Types

Table A-2

Pervasive PSQL Data Type Ranges continued

Relational Data Type

Valid Value Range

NUMERIC

Depends on the length and number of decimal places. See Precision and Scale of
Decimal Data Types on page A-9.

NUMERICSA

Depends on the length and number of decimal places. See Precision and Scale of
Decimal Data Types on page A-9.

NUMERICSTS

Depends on the length and number of decimal places. See Precision and Scale of
Decimal Data Types on page A-9.

REAL

-3.4028234E+38 +3.4028234e+38
The smallest value by which you can increment or decrement a REL is 1.4E-45

SMALLIDENTITY

+1 +32767

SMALLINT

-32768 +32767

TIME

00:00:00 23:59:59

TIMESTAMP

0001-01-01 00:00:00.0000000 9999-12-31 23:59:59.9999999 UTC

TINYINT

-128 +127

UBIGINT

0 18446744073709551615

UINTEGER

0 4294967295

UNIQUEIDENTIFIER

range not applicable

USMALLINT

0 65535

UTINYINT

0 255

VARCHAR

range not applicable

Operator
Precedence

A-6

An expression may have multiple operators. Operator precedence

determines the sequence in which the operations are performed.
Pervasive PSQL uses the following levels of precedence. An operator
on a higher level is evaluated before an operator on a lower level.
Level one is the highest, level nine the lowest.
1

+ (positive), - (negative), ~ (bitwise NOT)

* (multiply), / (divide), % (modulo)

+ (add), (+ concatenate), - (subtract), & (bitwise AND)

Pervasive PSQL Supported Data Types

=, >, <, >=, <=, <>, != (these comparison operators mean

the following, respectively: equals, greater than, less than, greater
than equal to, less than equal to, not equal, not equal)

^ (bitwise Exclusive OR), | (bitwise OR)

NOT

AND

ALL, ANY, BETWEEN, IN, LIKE, OR, SOME

= (assignment)

Two operators in an expression that have the same precedence level

are evaluated left to right based on their position within the
expression.
For example, in the SET statement in the following procedure, the
division operator is evaluated before the multiplication operator.
The procedure returns 21.
CREATE PROCEDURE checkvalue();
BEGIN
DECLARE :Counter INTEGER;
SET :Counter = 12 / 4 * 7;
PRINT :Counter;
END
CALL checkvalue

Parentheses
You may use parentheses to override the defined precedence of the
operators in an expression. Everything within the parentheses is
evaluated first to yield a single value. The value may then be used by
an operator outside of the parentheses.
For example, in the SET statement in the following procedure, the
division operator would ordinarily be evaluated before the addition
operator. The result would be 12 (that is, 8 + 4). However, the
addition is performed first because of the parentheses, so the
procedure returns a result of 4.

A-7

Data Types
CREATE PROCEDURE checkvalue1();
BEGIN
DECLARE :Counter INTEGER;
SET :Counter = 32 / (4 + 4);
PRINT :Counter;
END
CALL checkvalue1

If an expression has nested parentheses, the most deeply nested

expression is evaluated first, followed by the next most deeply nested
expression, and so forth.
For example, in the following SET statement, the addition is
performed first (most deeply nested), then the multiplication, then
the subtraction, and finally the division. The result is that the
variable evaluates to 5.
SET :Counter = 100 / (40 - (2 * (5 + 5)));

Data Type
Precedence

Data type precedence determines which data type results when two
expressions of different data types are combined by an operator. The
data type with the lower precedence is converted to the data type
with the higher precedence.
Note Pervasive PSQL returns an error if you perform an

operation on incompatible data types. For example, you try to

add an INTEGER to a CHAR.

Numeric Data Types

Pervasive PSQL supports the following precedence for the relational
numeric data types:

A-8

DOUBLE, FLOAT, BFLOAT8 (highest)

REAL, BFLOAT4
DECIMAL, NUMERIC, NUMERICSA, NUMERICSTS
CURRENCY, MONEY
BIGINT, UBIGINT
INTEGER, UINTEGER, IDENTITY

Pervasive PSQL Supported Data Types

SMALLINT, USMALLINT, SMALLIDENTITY

TINYINT, UTINYINT
BIT (lowest)

Character Data Types

The precedence for the relational character data types is:

LONGVARCHAR
CHAR, VARCHAR

If you concatenate a CHAR or VARCHAR with a LONGVARCHAR,

the result is a LONGVARCHAR.
If you concatenate a CHAR with a VARCHAR, the result is the type
of the first data type in the concatenation (moving left to right). For
example, if c1 is a CHAR and c2 is a VARCHAR, the result of (c1 +
c2) is a CHAR; the result of (c2 + c1) is a VARCHAR.
Time and Date Data Types
The precedence for the time and data data types is:

DATETIME
TIMESTAMP
DATE
TIME

Data Types To Which Precedence Does Not Apply

The BINARY, LONGVARBINARY, and UNIQUEIDENTIFIER data
types do not have a precedence because operations to combine them
are not allowed.

Precision and
Scale of
Decimal Data
Types

Precision is the number of digits in a number. Scale is the number of

digits to the right of the decimal point in a number. The number
909.777 has a precision of 6 and a scale of 3, for instance.
The default maximum precision of numeric and decimal data types
is 64.
Precision and scale are fixed for all numeric data types except
DECIMAL. An arithmetic operation on two expressions of the same
data type results in the same data type, with the precision and scale
for that type. If the operation involves expressions with different data

A-9

Data Types

types, the precedence rules determine the data type of the result. The
result has the precision and scale defined for its data type.
The result is a DECIMAL for the following conditions:

Both expressions are DECIMAL.

One expression is DECIMAL and the other is a data type with a
precedence lower than DECIMAL.

Table A-3 defines how precision and scale are derived when the result
of an operation is of data type DECIMAL. Exp stands for
expression, s stands for scale, and p stands for precision.
Table A-3

Calculation of Precision and Scale for DECIMAL Operation

Operation

Precision

Scale

Addition (exp1 + exp2)

max(s1, s2) + max(p1 - s1, p2 - s2) +1

max(s1, s2)

Subtraction (exp1 - exp2)

max(s1, s2) + max(p1 - s1, p2 - s2) +1

max(s1, s2)

Multiplication (exp1 * exp2)

p1 + p2 + 1

s1 + s2

Division (exp1 / exp2)

p1 - s1 + s2 + max(6, s1 + p2 +1)

max(6, s1 + p2 +1)

UNION (exp1 UNION exp2)

max(s1, s2) + max(p1 - s1, p2 - s2) +1

max(s1, s2)

For example, if you add or subtract two fields defined as

DECIMAL(8,2) and DECIMAL(7,4), the resulting field is
DECIMAL(11,4).

Truncation

If your application runs against different SQL DBMS products, you

may encounter the following issues pertaining to truncation.
In certain situations, some SQL DBMS products prevent insertion of
data because of truncation, while Pervasive PSQL allows the
insertion of that same data. Additionally, Pervasive PSQLs reporting
of SQL_SUCCESS_WITH_INFO and the information being
truncated differs with some SQL DMBS products in some scenarios
regarding when the message is reported.
Numeric string data and true numeric data are always truncated by
Pervasive PSQL. Some SQL DBMS products round this data when
applicable. So if you have a numeric string or true numeric value of
123.457 and you insert it into a 6 bytes string column or precision 2
numeric column, Pervasive PSQL always inserts 123.45. Other
DBMS products, by comparison, may insert a value of 123.46.

A-10

Notes on Data Types

This section covers various behaviors and key information regarding
the available data types.

CHAR,
VARCHAR, and
LONGVARCHAR

CHAR columns are padded with blanks to fill the columns

VARCHAR/LONGVARCHAR columns are not padded with
blanks to fill the columns. The significant data is terminated
with a NULL character.
In all cases the trailing blanks are NOT significant in comparison
operations (LIKE and =). However, in the LIKE case, if a space is
explicitly entered in the query (like 'abc %'), the space before the
wildcard does matter. In this example you are looking for
'abc<space><any other character>'

BINARY columns are padded with binary zeros to fill the

columns
LONGVARBINARY columns are NOT padded with blanks to
fill the columns.
The database engine does not compare LONGVARBINARY
columns. The database engine does compare fixed length
BINARY data.

Pervasive PSQL now supports multiple LONGVARCHAR and

LONGVARBINARY columns per table. The data is stored according
to the offset in the variable length portion of the record. The variable
length portion of data can vary from the column order of the data
depending on how the data is manipulated. Consider the following
example.
CREATE TABLE BlobDataTest
(
Nbr

UINT,

// Fixed record (Type 14)

Clob1 LONGVARCHAR,

// Fixed record (Type 21)

Clob2 LONGVARCHAR,

// Fixed record (Type 21)

Blob1 LONGVARBINARY, // Fixed record (Type 21)

)

On disk, the physical record would normally look like this:

A-11

Data Types
[Fixed Data (Nbr, Clob1header, Clob2header,
Blob1header)][ClobData1][ClobData2][BlobData1]

Now alter column Nbr to a LONGVARCHAR column:

ALTER TABLE BlobDataTest ALTER Nbr LONGVARCHAR

On disk, the physical record now looks like this:

[Fixed Data (Nbrheader, Clob1header, Clob2header,
Blob1header)][ClobData1][ClobData2][BlobData1]
[NbrClobData]

As you can see, the variable length portion of the data is not in the
column order for the existing data.
For newly inserted records, however, the variable length portion of
the data is in the column order for the existing data. This assumes
that all columns have data assigned (the columns are not NULL).
[Fixed Data (Nbrheader, Clob1header, Clob2header,
Blob1header)][NbrClobData][ClobData1][ClobData2]
[BlobData1]

The LIKE predicate operates on the first 65500 characters of the

LONGVARBINARY
column data.

A-12

All other predicates operate on the first 256 characters of the

column data.
SELECT statements with GROUP BY, DISTINCT, and ORDER
BY return all the data but only order on the first 256 characters
of the column data.
In a single call to SQLGetData, the maximum number of
characters returned by Pervasive PSQL for a LONGVARCHAR
or LONGVARBINARY columns is 65500. Multiple calls must be
made to SQLGetData to retrieve column data over 65500
characters.
Though the maximum amount of data that can be inserted into
a LONGVARCHAR/LONGVARBINARY column is 2GB, using a
literal in an INSERT statement reduces this amount to 15000
characters. You can insert more than 15000 characters by using
a parameterized insert.

Notes on Data Types

DATETIME

The DATETIME data type represents a date and time value. The data
type is stored internally as two 4-byte integers. The first four bytes
store the number of days before or after the base date of January 1,
1900. The other four bytes store the time of day represented as the
number of milliseconds after midnight.
The DATETIME data type can be indexed. The accuracy of
DATETIME is one three-hundredth of a second.
DATETIME is a relational data type only. No corresponding
transactional data type (Btrieve type) is available.
Format of DATETIME
The only permissible format for DATETIME is YYYY-MM-DD
HH:MM:SS.mmm. (The CONVERT function contains an optional
parameter that allows you to truncate the milliseconds portion of
DATETIME. See the "Convert" function under Conversion
Functions on page 5-20.)
The following table indicates the data components and their valid
values for DATETIME.
Table A-4

DATETIME Components and Valid Values

Component

Valid Values

YEAR (YYYY)

1753 to 9999

MONTH (MM)

01 to 12

DAY (DD)

01 to 31

HOUR (HH)

00 to 23

MINUTE (MM)

00 to 59

SECOND (SS)

00 to 59

MILLISECOND (mmm)

000 to 999

A-13

Data Types

Millisecond Rounding
The following table explains the rounding used for milliseconds.
Table A-5

Millisecond Rounding

Last Digit of
Millisecond

Rounding Rule
for Last Digit

Example

0, 1

2020-01-01 23:59:59.990 and 2020-01-01

23:59:59.991 round to 2020-01-01
23:59:59.991

2, 3, 4

2020-01-01 23:59:59.992, 2020-01-01

23:59:59.993, and 2020-01-01
23:59:59.993 round to 2020-01-01
23:59:59.993

5, 6, 7, 8

2020-01-01 23:59:59.995, 2020-01-01

23:59:59.996, 2020-01-01 23:59:59.997,
and 2020-01-01 23:59:59.998 round to
2020-01-01 23:59:59.997

add 1 to last digit

2020-01-01 23:59:59.999 rounds to 202001-02 00:00:00.000

Compatibility of Data Types

The following table shows the resultant data type for addition and
subtraction operations of DATE, TIME, TIMESTAMP, and
DATETIME with other data types. Data types marked with an "X"
are incompatible with DATE, TIME, TIMESTAMP, and DATETIME.
Table A-6

Operands Involving DATE, DATETIME, TIME, and

TIMESTAMP

Operand 2

DATE

DATETIME

TIME

TIMESTAMP

Operand 1

A-14

BFLOAT4

DATETIME

TIMESTAMP

BFLOAT8

DATETIME

TIMESTAMP

BIGINT

DATETIME

BINARY

BIT

CHAR

Notes on Data Types

Table A-6

Operands Involving DATE, DATETIME, TIME, and

TIMESTAMP continued

Operand 2

DATE

DATETIME

TIME

TIMESTAMP

Operand 1
CURRENCY

DATETIME

DATE

DATETIME

DECIMAL

DATETIME

DOUBLE

DATETIME

TIMESTAMP

IDENTITY

DATETIME

TIMESTAMP

INTEGER

DATE

LONGVARBINARY

LONGVARCHAR

MONEY

DATETIME

NUMERIC

DATETIME

NUMERICSA

NUMERICSTS

REAL

DATETIME

TIMESTAMP

SMALLIDENTITY

DATE

DATETIME

TIMESTAMP

SMALLINT

DATE

DATETIME

TIMESTAMP

TIME

TIMESTAMP

TINYINT

DATE

DATETIME

TIMESTAMP

UBIGINT

DATE

DATETIME

TIMESTAMP

UINTEGER

DATE

DATETIME

TIMESTAMP

A-15

Data Types

Table A-6

Operands Involving DATE, DATETIME, TIME, and

TIMESTAMP continued

Operand 2

DATE

DATETIME

TIME

TIMESTAMP

Operand 1
UNIQUEIDENTIFIER

USMALLINT

DATE

DATETIME

TIMESTAMP

UTINYINT

DATE

DATETIME

TIMESTAMP

VARCHAR

The CONVERT and CAST functions can be used with DATE,

DATETIME, TIME, and TIMESTAMP as the following tables
explain.
Table A-7

Permitted CONVERT Operations

CONVERT From

Permitted Resultant Data Type (to)

DATE

DATE, DATETIME, TIMESTAMP, VARCHAR

DATETIME

Any of the supported SQL_xxxx data types except for

SQL_GUID, SQL_BINARY, and SQL_LONGVARBINARY

TIME

TIME, DATETIME, TIMESTAMP, VARCHAR

TIMESTAMP

DATE, DATETIME, TIME, TIMESTAMP, VARCHAR

VARCHAR

DATE, DATETIME, TIME, TIMESTAMP

Note The CONVERT function contains an optional parameter

that allows you to truncate the milliseconds portion of

DATETIME. See the "Convert" function under Conversion
Functions on page 5-20.

A-16

Notes on Data Types

Table A-8

Permitted CAST Operations

CAST From

Permitted Resultant Data Type (to)

DATE

DATE, DATETIME, TIMESTAMP, VARCHAR

DATETIME

Any of the relational data types

TIME

TIME, DATETIME, TIMESTAMP, VARCHAR

TIMESTAMP

DATE, DATETIME, TIME, TIMESTAMP, VARCHAR

VARCHAR

DATE, DATETIME, TIME, TIMESTAMP

UNIQUEIDENTIFIER The UNIQUEIDENTIFIER data type is a 16-byte binary value

known as a globally unique identifier (GUID). A GUID is useful
when a row must be unique among other rows.
UNIQUEIDENTIFIER requires a file format of 9.5 or greater .
You can initialize a column or local variable of
UNIQUEIDENTIFIER the following ways:

By using the NEWID() scalar function. See NEWID ( ) on

page 5-16.
By providing a quoted string in the form 'xxxxxxxx-xxxxxxxx-xxxx-xxxxxxxxxxxx' in which each x is a hexadecimal
digit in the range 0-9 or A-F. For example, '1129619D-772CAAAB-B221-00FF00FF0099' is a valid UNIQUEIDENTIFIER
value.

If you provide a quoted string, all 32 digits are required. The database
engine does not pad a partial string.

A-17

Data Types

You may use only the following comparison operators with

UNIQUEIDENTIFIER values:
Operator

Meaning

Equals

<> or !=

Not equal to

Less than

Greater than

Less than or equal to

Greater than or equal to

IS NULL

the value is NULL

IS NOT NULL

the value is not NULL

Note that ordering is not implemented by comparing the bit patterns

of the two values.
Declaring Variables
You may declare variables of the UNIQUEIDENTIFIER data type
and set the variable value with the SET statement.
DECLARE :Cust_ID UNIQUEIDENTIFIER DEFAULT NEWID()
DECLARE :ISO_ID uniqueidentifier
SET :ISO_ID = '1129619D-772C-AAAB-B221-00FF00FF0099'

Converting UNIQUEIDENTIFIER to Another Data Type

The UNIQUEIDENTIFER can be coverted with the CAST or
CONVERT scalar functions to any of the following data types:

CHAR
LONGVARCHAR
VARCHAR

For conversion examples, see Conversion Functions on page 5-20.

A-18

Notes on Data Types

Representation When Pervasive PSQL is required by an application to represent

infinity, it can do so in either a 4-byte (C float type) or 8-byte (C
of Infinity
double type) form, and in either a hexadecimal or character
representation, as shown in the following table:
Table A-9

Infinity Representation

Value

Float
Hexadecimal

Float
Character

Double Hexadecimal

Maximum Positive

0x7FEFFFFFFFFFFFFF

Maximum Negative

0xFFEFFFFFFFFFFFFF

Double
Character

Infinity Positive

0x7F800000

1E999

0x7FF0000000000000

1E999

Infinity Negative

0xFF800000

-1E999

0xFFF0000000000000

-1E999

A-19

Data Types

Legacy Data Types

Some older (legacy) data types are not supported by the current
release of Pervasive PSQL. The following table shows the new data
type to use in place of the legacy data type.
Table A-10

Data Types Used to Replace Legacy Data Types

Legacy Type

Type Code

Replaced by

Type Code

LOGICAL(1)

BIT

LOGICAL(2)

SMALLINT

LSTRING

VARCHAR

LVAR

LONGVARCHAR

NOTE

LONGVARCHAR

Existing databases that use these data types are supported and
function correctly. New databases, however, cannot create tables
with the legacy data types.

A-20

Btrieve Key Data Types

This section discusses the Btrieve data types that can be indexed (key
types). Internally, the MicroKernel compares string keys on a byteby-byte basis, from left to right. By default, the MicroKernel sorts
string keys according to their ASCII value. You may, however, define
string keys to be case insensitive or to use an alternate collating
sequence (ACS).
The MicroKernel compares unsigned binary keys one word at a time.
It compares these keys from right to left because the Intel 8086 family
of processors reverses the high and low bytes in an integer.
If a particular data type is available in more than one size (for
example, both 4- and 8-byte FLOAT values are allowed), the Key
Length parameter (used in the creation of a new key) defines the size
that will be expected for all values of that particular key. Any attempt
to define a key using a Key Length that is not allowed results in a
Status 29 (Invalid Key Length).
The following table lists the key types and their associated codes.
Following the table is a discussion of the internal storage formats for
each key type.
Table A-11

Btrieve Key Data Types and Type Codes

Data Type

Type Code

AUTOINC

BFLOAT

BLOB

STRING

CLOB

CURRENCY

DATE

DECIMAL

FLOAT

GUID

A-21

Data Types

Table A-11

Btrieve Key Data Types and Type Codes continued

Data Type

Type Code

INTEGER

LOGICAL

LSTRING

MONEY

NUMERIC

NUMERICSA

NUMERICSTS

TIME

TIMESTAMP

UNSIGNED BINARY

WSTRING

WZSTRING

ZSTRING

AUTOINC
The AUTOINC key type is a signed Intel integer that can be either
two or four bytes long. Internally, AUTOINC keys are stored in Intel
binary integer format, with the high-order and low-order bytes
reversed within a word. The MicroKernel sorts AUTOINC keys by
their absolute (positive) values, comparing the values stored in
different records a word at a time from right to left. AUTOINC keys
may be used to automatically assign the next highest value when a
record is inserted into a file. Because the values are sorted by absolute
value, the number of possible records is roughly half what you would
expect given that the data type is signed.
Values that have been deleted from the file are not re-used
automatically. If you indicate that you want the database engine to
assign the next value by entering a zero (0) value in an insert or
update, the database simply finds the highest number, adds 1, and
inserts the resulting value.

A-22

Btrieve Key Data Types

You can initialize the value of a field in all or some records to zero and
later add an index of type AUTOINC. This feature allows you to
prepare for an AUTOINC key without actually building the index
until it is needed.
When you add the index, the MicroKernel changes the zero values in
each field appropriately, beginning its numbering with a value equal
to the greatest value currently defined in the field, plus one. If
nonzero values exist in the field, the MicroKernel does not alter
them. However, the MicroKernel returns an error status code if
nonzero duplicate values exist in the field.
The MicroKernel maintains the highest previously used autoincrement value associated with each open file containing an
AUTOINC key. This value is established and increments only when
an INSERT operation occurs for a record with ASCII zeros in the
AUTOINC field. The value is used by all clients so that concurrent
changes can take place, taking advantage of Key Page Concurrency.
The next AUTOINC value for a file is raised whenever any INSERT
occurs that uses the previous AUTOINC value. This happens
whether or not the INSERT is in a transaction or the change is
committed.
However, this value may be lowered during an INSERT if all of the
following are true:

The highest AUTOINC value found in the key is lower than the
next AUTOINC value for the file
No other client has a pending transaction affecting the page that
contains the highest AUTOINC value
The key page containing the highest AUTOINC value is not
already pending by the client doing the INSERT.

In other words, only the first INSERT within a transaction can lower
the next available AUTOINC value. After that, the next available
AUTOINC value just keeps increasing.
An example helps clarify how an AUTOINC value may be lowered.
Assume an autoincrement file exists with records 1, 2, 3 and 4. The
next available AUTOINC value is 5.
Client1 begins a transaction and inserts two new records, raising the
next available AUTOINC value to 7. (Client1 gets values 5 and 6).
Client2 begins a transaction and also inserts two new records. This

A-23

Data Types

raises the next available AUTOINC value to 9. (Client 2 gets values 7

and 8).
Client1 the deletes records 4, 5, and 6. The next AUTOINC value
remains the same since it is adjusted only on INSERTS. Client1 then
commits. The committed version of the file now contains records 1,
2, and 3.
For Client2, the file contains records 1, 2, 3, 7, and 8 (7 and 8 are not
yet committed). Client2 then inserts another record, which becomes
record 9. The next available AUTOINC value is raised to 10. Client2
deletes records 3, 7, 8, and 9. For Client2, the file now contains only
the committed records 1 and 2.
Next Client2 inserts another record, which becomes record 10. The
next available AUTOINC value is raised to 11. The next
autoincrement value is not lowered to 3 since the page containing the
change has other changes pending on it.
Client2 then aborts the transaction. The committed version of the
file now contains records 1, 2, and 3, but the next available
AUTOINC value is still 11.
If either client inserts another record, whether in a transaction or
not, the next available AUTOINC value will be lowered to 4. This
occurs because all of the conditions required for lowering the value
are true.
If a resulting auto-increment value is out of range, a Status Code 5
results. The database engine does not attempt to wrap the values
and start again from zero. You may, however, insert unused values
directly if you know of gaps in the autoincrement sequence where a
previously inserted value has been deleted.
Restrictions

The following restrictions apply to AUTOINC keys:

A-24

The key must be defined as unique.

The key cannot be segmented. However, an AUTOINC key can
be included as an integer segment of another key, as long as the
AUTOINC key has been defined as a separate, single key first,
and the AUTOINC key number is lower than the segmented key
number.
The key cannot overlap another key.
All keys must be ascending.

Btrieve Key Data Types

The MicroKernel treats AUTOINC key values as follows when you

insert records into a file:

If you specify a value of binary 0 for the AUTOINC key, the

MicroKernel assigns a value to the key based on the following
criteria:

If you are inserting the first record in the file, the

MicroKernel assigns the value of 1 to the AUTOINC key.

If records already exist in the file, the MicroKernel assigns

the key a value that is one number higher than the highest
existing absolute value in the file.
If you specify a positive, nonzero value for the AUTOINC key,
the MicroKernel inserts the record into the file and uses the
specified value as the key value. If a record containing that value
already exists in the file, the MicroKernel returns an error status
code, and does not insert the record.

BFLOAT
The BFLOAT key type is a single or double-precision real number. A
single-precision real number is stored with a 23-bit mantissa, an 8bit exponent biased by 128, and a sign bit. The internal layout for a
4-byte float is as follows:
3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1
1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0

8-bit exponent

23-bit mantissa
Sign

The representation of a double-precision real number is the same as

that for a single-precision real number, except that the mantissa is 55
bits instead of 23 bits. The least significant 32 bits are stored in bytes
0 through 3.
The BFLOAT type is commonly used in legacy BASIC applications.
Microsoft refers to this data type as MBF (Microsoft Binary Format),
and no longer supports this type in the Visual Basic environment.
New database definitions should use FLOAT rather than BFLOAT.

A-25

Data Types

BLOB
The Binary Large Object (BLOB) type provides support for binary
data fields up to 2 GB in size. This type consists of 2 parts:

an 8-byte header in the fixed-length portion of the record. The

header contains a 4-byte integer that identifies the offset to the
beginning of the data in the variable-length portion of the
record, and a 4-byte integer that specifies the size of the data.
the binary data itself is stored within the variable-length portion
of the record. The size of all BLOB and CLOB fields must sum to
2 GB or less, because the offset pointer into the variable-length
portion of the record is limited to 2 GB maximum offset. To
store the maximum BLOB size of 2 GB, you may have only 1
BLOB or CLOB field defined in the record.

For additional information, see BINARY and LONGVARBINARY

on page A-11 and Limitations on LONGVARCHAR and
LONGVARBINARY on page A-12.
CHAR
Note In previous versions of Pervasive PSQL, this data type was

referred to as STRING
The CHAR key type is a sequence of characters ordered from left to
right. Each character is represented in ASCII format in a single byte,
except when the MicroKernel is determining whether a key value is
null. CHAR data is expected to be padded with blanks to the full size
of the key.
CLOB
The Character Large Object (CLOB) type provides support for
character data fields up to 2 GB in size. This type consists of 2 parts:

A-26

an 8-byte header in the fixed-length portion of the record. The

header contains a 4-byte integer that identifies the offese to the
beginning of the data in the variable-length portion of the
record, and a 4-byte integer that specifies the size of the data.

Btrieve Key Data Types

the character data itself is stored within the variable-length

portion of the record. The size of all BLOB and CLOB fields must
sum to 2 GB or less, because the offset pointer into the variablelength portion of the record is limited to 2 GB maximum offset.
To store the maximum BLOB size of 2 GB, you may have only 1
BLOB or CLOB field defined in the record.

For additional information, see CHAR, VARCHAR, and

LONGVARCHAR on page A-11 and Limitations on
LONGVARCHAR and LONGVARBINARY on page A-12.
CURRENCY
The CURRENCY key type represents an 8-byte signed quantity,
sorted and stored in Intel binary integer format; therefore, its
internal representation is the same as an 8-byte INTEGER data type.
The CURRENCY data type has an implied four digit scale of decimal
places, which represents the fractional component of the currency
data value.
DATE
The DATE key type is stored internally as a 4-byte value. The day and
the month are each stored in 1-byte binary format. The year is a 2byte binary number that represents the entire year value. The
MicroKernel places the day into the first byte, the month into the
second byte, and the year into a two-byte word following the month.

An example of C structure used for date fields would be:

TYPE dateField {
char day;
char month;
integer year;
}

A-27

Data Types

The year portion of a date field is expected to be set to the integer

representation of the entire year. For example, 2,001 for the year
2001.
DECIMAL
The DECIMAL key type is stored internally as a packed decimal
number with two decimal digits per byte. The internal
representation for an n-byte DECIMAL field is as follows:
byte 0

1 1 1 1 1 1 1
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6

digit
1

digit
2

byte n-1

byte 1

digit
3

...
...
...

digit
4

digit
2n-1

sign
nibble

The sign nibble is either 0xF or 0xC for positive numbers and 0xD for
negative numbers. Pervasive ODBC and Pervasive ActiveX controls
always use 0xF for the positive sign nibble. The decimal point is
implied; no decimal point is stored in the DECIMAL field. Your
application is responsible for tracking the location of the decimal
point for the value in a DECIMAL field. All the values for a
DECIMAL key type must have the same number of decimal places in
order for the MicroKernel to collate the key correctly. The DECIMAL
type is commonly used in COBOL applications.
An eight-byte decimal can hold 15 digits plus the sign. A ten-byte
decimal can hold 19 digits plus the sign. The decimal value is
expected to be left-padded with zeros.
FLOAT
Caution Precision beyond that supported by the C-language

definitions for the FLOAT (4-byte) or DOUBLE (8-byte) data

type will be lost. If you require precision to many decimal points,
consider using the DECIMAL type.

A-28

Btrieve Key Data Types

The FLOAT key type is consistent with the IEEE standard for single
and double-precision real numbers. The internal format for a 4-byte
FLOAT consists of a 23-bit mantissa, an 8-bit exponent biased by
127, and a sign bit, as follows:
3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1
1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0

8-bit exponent

23-bit mantissa

Sign

A FLOAT key with 8 bytes has a 52-bit mantissa, an 11-bit exponent

biased by 1023, and a sign bit. The internal format is as follows:
bytes 7-4:
6 6 6 6 5 5 5 5 5 5 5 5 5 5 4 4 4 4 4 4 4 4 4 4 3 3 3 3 3 3 3 3
3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2

11-bit exponent

20-bit mantissa

Sign

bytes 3-0:
3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1
1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0

32-bit mantissa

GUID
The GUID data type is a 16-byte number that is stored internally as
a 16-byte binary value. Its extended data type value is 27.
GUIDs are commonly used as globally unique identifiers. The
corresponding data type for the relational interface is
UNIQUEIDENTIFIER. (See UNIQUEIDENTIFIER on page A17.)

A-29

Data Types

Note that GUID requires a file format of 9.5 or greater.

GUID Keys

The sort order for the bytes composing the GUID are compared in
the following sequence: 10, 11, 12, 13, 14, 15, 8, 9, 6, 7, 4, 5, 0, 1, 2, 3.
The key segment length for a GUID must be 16 bytes. See Key
Specification Blocks on page 2-23 in Btrieve API Guide, which is
part of the Pervasive PSQL software development kit (SDK).
INTEGER
The INTEGER key type is a signed whole number and can contain
any number of digits. Internally, INTEGER fields are stored in Intel
binary integer format, with the high-order and low-order bytes
reversed within a word. The MicroKernel evaluates the key from
right to left. The sign must be stored in the high bit of the rightmost
byte. The INTEGER type is supported by most development
environments.
Table A-12

INTEGER Key Type

Length in Bytes

Value Ranges

0 255

-32768 32767

-2147483648 2147483647

-9223372036854775808 9223372036854775807

LOGICAL
The LOGICAL key type is stored as a 1 or 2-byte value. The
MicroKernel collates LOGICAL key types as strings. Doing so allows
your application to determine the stored values that represent true or
false.
LSTRING
The LSTRING key type has the same characteristics as a regular
STRING type, except that the first byte of the string contains the
binary representation of the strings length. The LSTRING key type
is limited to a maximum size of 255 bytes. The length stored in byte
0 of an LSTRING key determines the number of significant bytes.

A-30

Btrieve Key Data Types

The database engine ignores any values beyond the specified length
of the string when sorting or searching for values. The LSTRING
type is commonly used in legacy Pascal applications.
MONEY
The MONEY key type has the same internal representation as the
DECIMAL type, with an implied two decimal places.
NUMERIC
Each digit of a NUMERIC data type occupies one byte. NUMERIC
values are stored as ASCII strings and right justified with leading
zeros. The rightmost byte of the number includes an embedded sign
with an EBCDIC value. By default, the sign value for positive
NUMERIC data types is an unsigned numeric number. The
NUMERIC type is commonly used in COBOL applications.
Optionally, you may specify that you want to shift the value of the
sign for positive NUMERIC data types. The following table
compares the sign values in the default (unshifted) and shifted states.
Table A-13
Digit

Comparison of Shifted and Unshifted Sign Values for

NUMERICS
Default (unshifted) Sign Value

Shifted Sign Value

Positive

Negative

Positive

Negative

A-31

Data Types

Enabling the Shifted Format

You must manually specify a setting on the machine running the

Pervasive PSQL database engine to enable the shifted format. The
setting, DBCobolNumeric, must be set to yes. The following table
summarizes how to specify the setting depending on the engine
server platform. See NUMERIC on page A-31 in SQL Engine
Reference for the complete steps.
Table A-14

Specifying the DBCobolNumeric Setting for Different Platforms

Server Platform

Setting Specification

Windows 32-bit

Using the registry editor provided with the operating system, add the DBCobolNumeric
setting to the registry as a new string value to the following key:

HKEY_LOCAL_MACHINE/SOFTWARE/PERVASIVE SOFTWARE/DATABASE
NAMES/VERSION x/ SETTINGS
(where x represents the version number)
Set the string value to yes.
Note: In most Windows operating systems, the Pervasive Software key is
HKEY_LOCAL_MACHINE\SOFTWARE\PERVASIVE SOFTWARE. However, its location
under HKEY_LOCAL_MACHINE\SOFTWARE can vary depending on the operating system.
Caution: Editing the registry is an advanced procedure. If done improperly, the editing
could cause your operating system not to boot. If necessary, obtain the services of a
qualified technician to perform the editing. Pervasive Software does not accept
responsibility for a damaged registry.
Stop and restart the database engine or the engine services. See Starting and Stopping
the Server Engine on a Windows Server on page 2-2 and Starting and Stopping the
Workgroup Engine on Windows on page 2-5, both in Pervasive PSQL User's Guide.
Linux

Add the DBCobolNumeric setting to bti.ini below the [Database Names] entry:

[Database Names]
DBCobolNumeric=yes
By default, bti.ini is located in the /usr/local/psql/etc directory.
Stop and restart the database engine. Starting and Stopping the Database Engine on
Linux on page 2-7 in Pervasive PSQL User's Guide.

Consistent Sign Values for Positive NUMERIC Data

You may already have positive NUMERIC data with the sign value in
the default (unshifted) format. If you set DBCobolNumeric to yes
and continue adding data to the same table, mixed formats result.
Leaving your data with mixed formats for the sign value is not
recommended.

A-32

Btrieve Key Data Types

To correct, or prevent, a condition of mixed formats, use the

UPDATE statement to update the NUMERIC columns to
themselves. For example, suppose that table t1 contains column c1
that is a NUMERIC data type. After you set DBCobolNumeric to
yes, update c1 as follows: UPDATE TABLE t1 SET c1 = c1.
See UPDATE on page 3-269.
NUMERICSA
The NUMERICSA key type (sometimes called NUMERIC SIGNED
ASCII) is a COBOL data type that is the same as the NUMERIC data
type, except that the embedded sign has an ASCII value instead of an
EBCDIC value.
Table A-15
Digit

Sign Values for NUMERICSA

Default Sign Value
Positive

Negative

1 or Q

2 or R

3 or S

4 or T

5 or U

6 or V

7 or W

8 or X

9 or Y

0 or P

A-33

Data Types

NUMERICSTS
The NUMERICSTS key type (sometimes called SIGN TRAILING
SEPARATE) is a COBOL data type that has values resembling those
of the NUMERIC data type. NUMERICSTS values are stored as
ASCII strings and right justified with leading zeros. However, the
rightmost byte of a NUMERICSTS string is either + (ASCII 0x2B)
or - (ASCII 0x2D). This differs from NUMERIC values that embed
the sign in the rightmost byte along with the value of that byte.
REAL
The REAL type is defined as a 4-byte FLOAT.
TIME
The TIME key type is stored internally as a 4-byte value. Hundredths
of a second, second, minute, and hour values are each stored in 1byte binary format. The MicroKernel places the hundredths of a
second value into the first byte, followed respectively by the second,
minute, and hour values.

A-34

Btrieve Key Data Types

TIMESTAMP
The TIMESTAMP data type represents a time and date value. In SQL
applications, use this data type to stamp a record with the time and
date of the last update to the record.
Note According to the ODBC standard, scalar functions such as

CURRENT_TIME() or NOW() ignore the portion of the data

type that represents fractional seconds. For this reason,
TIMESTAMP values generated from scalar functions always
have zero fractional seconds. For example: 2002-06-11
16:15:50.0000000. If you require your TIMESTAMP values to
have significance in fractions of a second, do not use scalar
functions to generate values to be inserted or updated.
TIMESTAMP is intended to cover time and data values made up of
the following components: year, month, day, hour, minute, and
second. The following table indicates the valid values of each of these
components:
Table A-16

TIMESTAMP Components

YEAR

0001 to 9999

MONTH

01 to 12

DAY

01 to 31, constrained by the value of MONTH and YEAR in the

Gregorian calendar.

HOUR

00 to 23

MINUTE

00 to 59

SECOND

00 to 59

The value is stored internally as a TIMESTAMP MicroKernel key, an

8-byte long field that contains the complete date and time value
converted to the fractions of seconds that timestamp precision
specifies. For example, it is converted to microseconds when
timestamp precision is 6, and it is converted to milliseconds when
timestamp precision is 3.

A-35

Data Types

You provide the value of a TIMESTAMP in local time and SRDE

converts it to Coordinated Universal Time (UTC), formerly
Greenwich Mean Time (GMT), before storing it in a MicroKernel
record. When you request the value of a TIMESTAMP, SRDE
converts it from UTC to local time before returning the data.
Caution It is critical that you correctly set time zone information

on the computer where the database engine runs. If you move

across time zones or change time zone information, the returned
data will change when it is converted from UTC to local time.
The local time/UTC conversions occur in SRDE using the time
zone information where SRDE is running. The time zone
information for sessions that are in different time zones than
SRDE engine are not used in the local time/UTC conversions.
Because timestamp data is converted to UTC before it is stored, the
TIMESTAMP type is inappropriate for use with local time and local
date data that reference events external to the database itself,
particularly in time zones where seasonal time changes take place
(such as Daylight Savings Time in the United States).
For example, assume it is October 15, and you enter a timestamp
value to track an appointment on November 15 at 10 a.m. Assume
you are in the U. S. Central Time Zone. When the SRDE stores the
value, it converts it to UTC using current local time information
(UTC-5 hours for CDT). So it stores the hour value 15. Assume, on
November 1, you check the time of your appointment. Your
computer is now in Standard Time, because of the switch that
occurred in October, so the conversion is (UTC-6 hours). When you
extract the appointment time, it will show 9 a.m. local time (15 UTC
- 6 CST), which is not the correct appointment time.
The same type of issue will occur if a database engine is moved from
one time zone to another.
Because the SRDE does not convert DATE and TIME values to UTC,
you should almost always use DATE and TIME columns to record
external data. The only reason to use a TIMESTAMP column is a
need for the specific ability to determine the sequential time order of
records entered into the database.

A-36

Btrieve Key Data Types

UNSIGNED BINARY
UNSIGNED BINARY keys can be any number of bytes up to the
maximum key length of 255. UNSIGNED keys are compared bytefor-byte from the most significant byte to the least significant byte.
The first byte of the key is the least significant byte. The last byte of
the key is the most significant.
The database engine sorts UNSIGNED BINARY keys as unsigned
INTEGER keys. The differences are that an INTEGER has a sign bit,
while an UNSIGNED BINARY type does not, and an UNSIGNED
BINARY key can be longer than 4 bytes.
WSTRING
WSTRING is a Unicode string that is not null-terminated. The
length of the string is determined by the field length. WSTRING is
not supported in SQL.
WZSTRING
WZSTRING is a Unicode string that is double null-terminated. The
length of this string is determined by the position of the Unicode
NULL (two null bytes) within the field. This corresponds to the
ZSTRING type supported in Btrieve. WZSTRING is not supported
in SQL.
ZSTRING
The ZSTRING key type corresponds to a C string. It has the same
characteristics as a regular string type except that a ZSTRING type is
terminated by a binary 0. The MicroKernel ignores any values
beyond the first binary 0 it encounters in the ZSTRING, except when
the MicroKernel is determining whether a key value is null.
The maximum length of a ZSTRING type is 255 characters,
including the null terminator character. If used as a key for a nullable
column, only the first 254 bytes of the string are used in the key. This
minor limitation occurs because the key is limited to 255 bytes total
length, and one byte is occupied by the null indicator for the column,
leaving only 254 bytes for the key value.

A-37

Data Types

A-38

Appendix

SQL Reserved Words

Supported Pervasive PSQL Reserved Words

Reserved words are SQL keywords and other symbols that have
special meanings when they are processed by the SRDE. Reserved
words are not recommended for use as database, table, column,
variable or other object names. If a reserved word is used as an object
name, it must be enclosed in double-quotes to notify the SRDE that
the word is not being used as a keyword in the given context.
You can avoid having to worry about reserved words by always
enclosing user-defined object names in double-quotes.
This appendix contains the following topic:

Reserved Words on page B-2

Words to Avoid on page B-7

B-1

SQL Reserved Words

Reserved Words
Each of the symbols or words listed below has a special meaning
when processed by the SRDE, unless it is delimited by doublequotes. Using one of these words as a table or object name without
double quotes will cause an error.
See also the next section, Words to Avoid on page B-7.
Symbols
#

A
ABORT

ACCELERATED

ADD

AFTER

ALL

ALTER

AND

ANY

ASC

ATOMIC

AVG

BEFORE

BEGIN

BETWEEN

BORDER

B-2

CALL

CASCADE

CASE

CAST

CHECK

COALESCE

COLLATE

COLUMN

COMMIT

COMMITTED

CONSTRAINT

CONVERT

COUNT

CREATE

CREATESP

CREATETAB

CREATEVIEW

CROSS

CURDATE

CURRENT

CURSOR

CURTIME

Reserved Words

D
DATABASE

DCOMPRESS

DDF

DECIMALSEPARATORCOMMA

DECLARE

DEFAULT

DEFAULTCOLLATE

DELETE

DENY

DESC

DIAGNOSTICS

DICTIONARY

DISTINCT

DROP

DSN

E
EACH

ELSE

END

ENFORCED

EXCLUSIVE

EXEC

EXECUTE

EXISTING

FETCH

FOR

FOREIGN

FROM

FULL

EXISTS

FUNCTION

G
GRANT

GROUP

H
HANDLER

HAVING

B-3

SQL Reserved Words

I
IF

INDEX

INNER

INOUT

INSERT

INTEGRITY

INTERNAL

INTO

ISOLATION

JOIN
K

KEY
L
LEAVE

LEFT

LEGACYOWNERNAME

LEVEL

MAX

MIN

MODE

MODIFIABLE

MODIFY

LOOP

N
NEW

NORMAL

NOT

NOW

NULL

B-4

Reserved Words

O
OF

OFF

OLD

ONLY

OPEN

ORDER

OUT

OUTER

OWNER

P
PAGESIZE

PARTIAL

PRIMARY

PROCEDURE

PUBLIC

READ

REFERENCES

REFERENCING

RELATIONAL

RELEASE

REPEAT

REPEATABLE

REPLACE

RESTRICT

RETURN

RETURNS

REVOKE

RIGHT

ROLLBACK

ROW

SAVEPOINT

SECURITY

SELECT

SERIALIZABLE

SET

SIGNAL

SIZE

SQLSTATE

SSP_EXPR

SSP_PRED

START

SUM

SVBEGIN

SVEND

ROWCOUNT

B-5

SQL Reserved Words

T
T

TABLE

THEN

TOP

TRANSACTION

TRIGGER

TRIGGERSTAMPMISC

TRUEBITCREATE

TRUENULLCREATE

U
UNCOMMITTED

UNION

UNIQUE

UNIQUEIDENTIFIER

UNTIL

UPDATE

USER

USING

V
VALUES

VIEW

B-6

WHEN

WHERE

WHILE

WITH

WORK

WRITE

Words to Avoid

Words to Avoid
The following table lists common keywords from the SQL-92 and
SQL-99 ANSI standards. While Pervasive PSQL may not support or
offer all of these keywords, you should avoid using these words as
names for tables, columns, or other objects, if you do not use doublequotes around them. Pervasive reserves the right to add support for
any of these keywords as well as any future ANSI SQL keywords in
future releases.
If you use double-quotes to delimit all table, column, and userdefined object names, you do not need to worry about possible
future conflicts with reserved words.
See also the previous section, Reserved Words on page B-2.
Table B-1

Words to Avoid as User-Defined Names

ABSOLUTE

ACTION

ADD

ALL

ALLOCATE

ALTER

AND

ANY

ARE

ASC

ASSERTION

AUTHORIZATION

AVG

BEGIN

BETWEEN

BIT

BIT_LENGTH

BOTH

CASCADE

CASCADED

CASE

CAST

CATALOG

CHAR

CHARACTER

CHAR_LENGTH

CHARACTER_LENGTH

CHECK

COALESCE

COLLATE

COLLATION

COLUMN

COMMIT

CONNECT

CONNECTION

CONSTRAINT

CONSTRAINTS

CONTINUE

CONVERT

CORRESPONDING

COUNT

CREATE

CROSS

CURRENT

B-7

SQL Reserved Words

Table B-1

B-8

Words to Avoid as User-Defined Names continued

CURRENT_DATE

CURRENT_TIME

CURRENT_TIMESTAMP

CURRENT_USER

CURSOR

DATE

DAY

DEALLOCATE

DEC

DECIMAL

DECLARE

DEFAULT

DEFERRABLE

DEFERRED

DELETE

DESC

DESCRIBE

DESCRIPTOR

DIAGNOSTICS

DISCONNECT

DISTINCT

DOMAIN

DOUBLE

DROP

ELSE

END

END-EXEC

ESCAPE

EXCEPT

EXCEPTION

EXEC

EXECUTE

EXISTS

EXTERNAL

EXTRACT

FALSE

FETCH

FIRST

FLOAT

FOR

FOREIGN

FOUND

FROM

FULL

FUNCTION

GET

GLOBAL

GOTO

GRANT

GROUP

HAVING

HOUR

IDENTITY

IMMEDIATE

INDICATOR

INITIALLY

INNER

INPUT

INSENSITIVE

INSERT

INT

INTEGER

INTERSECT

INTERVAL

INTO

ISOLATION

JOIN

KEY

LANGUAGE

LAST

LEADING

LEFT

LEVEL

LOCAL

Words to Avoid

Table B-1

Words to Avoid as User-Defined Names continued

LOWER

MASK

MATCH

MAX

MIN

MINUTE

MODULE

MONTH

NAMES

NATIONAL

NATURAL

NCHAR

NOT

NULL

NULLIF

NUMERIC

OCTET_LENGTH

ONLY

OPEN

OPTION

ORDER

OUTER

OUTPUT

OVERLAPS

PAD

PARTIAL

POSITION

PRECISION

PREPARE

PRESERVE

PRIMARY

PRIOR

PRIVILEGES

PROCEDURE

PUBLIC

READ

REAL

REFERENCES

RELATIVE

RESTRICT

REVOKE

RIGHT

ROLLBACK

ROWS

SCHEMA

SCROLL

SECOND

SECTION

SELECT

SESSION

SESSION_USER

SET

SIZE

SMALLINT

SOME

SPACE

SQL

SQLCODE

SQLERROR

SQLSTATE

SUBSTRING

SUM

SYSTEM_USER

TABLE

TEMPORARY

THEN

TIME

TIMESTAMP

TIMEZONE_HOUR

TIMEZONE_MINUTE

TRAILING

TRANSACTION

B-9

SQL Reserved Words

Table B-1
TRANSLATE

TRANSLATION

TRIM

TRUE

UNION

UNIQUE

UNKNOWN

UPDATE

UPPER

USAGE

USER

USING

VALUE

VALUES

VARCHAR

VARYING

VIEW

WHEN

WHENEVER

WHERE

WITH

WORK

WRITE

YEAR

ZONE

B-10

Words to Avoid as User-Defined Names continued

Appendix

System Tables

Pervasive PSQL System Tables Reference

This appendix describes the Pervasive PSQL system tables. The

following sections are included:

Overview on page C-2

System Tables Structure on page C-4

C-1

System Tables

Overview
The information used by Pervasive PSQL and its components is
stored in special tables called system tables.
Caution Do not attempt to modify system tables with DELETE,
UPDATE, or INSERT statements, or user-defined triggers.
System tables should never be altered directly.

Do not write your applications to query system tables directly. Some

columns in system tables may not be documented. Your application
can retrieve information stored in system tables by using any of the
following methods:

System Stored Procedures on page 6-1

Transact-SQL statements and functions
Functions provided in the Pervasive PSQL application
programming interfaces (API)

Note that the Pervasive PSQL APIs are documented in the Pervasive
PSQL Software Development Kit (SDK). The SDK components are
compatible with the database engine from release to release. The
format of the system tables depends on the internal architecture of
the Pervasive PSQL database engine. The architecture may change
from release to release. Application that directly access
undocumented columns of system tables may have to be changed if
the internal architecture of Pervasive PSQL changes.
For each system table, the following table indicates the name of the
associated file and briefly describes the system tables contents.
Note Some data in the system tables cannot be displayed. User

passwords, for example, display in encrypted form.

C-2

Overview

Table C-1

System Tables

System Table

Dictionary File

Contents

V11

V22

X$Attrib

ATTRIB.DDF

PVATTRIB.DDF

Column attributes definitions.

X$Depend

DEPEND.DDF

PVDEPEND.DDF

Trigger dependencies such as tables, views,

and procedures.

X$Field

FIELD.DDF

PVFIELD.DDF

Column and named index definitions.

X$File

FILE.DDF

PVFILE.DDF

Names and locations of the tables in your

database.

X$Index

INDEX.DDF

PVINDEX.DDF

Index definitions.

X$Proc

PROC.DDF

PVPROC.DDF

Stored procedure definitions.

X$Relate

RELATE.DDF

PVRELATE.DDF

Referential integrity (RI) information.

X$Rights

RIGHTS.DDF

PVRIGHTS.DDF

User and group access rights definitions.

X$Trigger

TRIGGER.DDF

PVTRIG.DDF

Trigger information.

X$User

USER.DDF

PVUSER.DDF

User names, group names, and passwords.

X$View

VIEW.DDF

PVVIEW.DDF

View definitions.

1Applies

to version 1 (V1) metadata. See Versions of Metadata on page 2-2.

2Applies

to version 2 (V2) metadata. See Versions of Metadata on page 2-2.

Pervasive PSQL creates all of the system tables when you create a
database.
Two other system tables that you may encounter are VARIANT.DDF
and OCCURS.DDF (for a V1 database) and PVVARIANT.DDF and
PVOCCURS.DDF (for a V2 database).These two system files are
used for COBOL support and do not require any direct intervention
by a user. Future versions of the utilities for COBOL may implement
a different architecture, in which case these system tables may no
longer be required. See also SQL Access for COBOL Applications
on page D-1.

C-3

System Tables

System Tables Structure

This section discusses the structure of the system tables:

V1 Metadata
System Tables

Table C-2

V1 Metadata System Tables on page C-4

V2 Metadata System Tables on page C-19

X$Attrib
The X$Attrib system table is associated with the file ATTRIB.DDF.
X$Attrib contains information about the column attributes of each
column in the database; there is an entry for each column attribute
you define. The structure of X$Attrib is described in X$Attrib
System Table Structure:

X$Attrib System Table Structure

Column Name

Type

Size

Case Insensitive

Description

Xa$Id

USMALLINT

not applicable

Corresponds to Xe$Id in X$Field.

Xa$Type

CHAR

C for character; D for default; H for

heading; M for mask; O for column
collation; R for range; or V for value.1

Xa$ASize

USMALLINT

not applicable

Length of text in Xa$Attrs.

Xa$Attrs

LONGVARCHAR
(NOTE)

<=2048

not applicable

Text that defines the column

attribute.

1Attribute

type C, H, M, R and V are legacy validation types valid only in a Pervasive.SQL 7 or Scalable SQL
environment. Pervasive PSQL releases newer than Pervasive.SQL 7 use only the D (default) and O (column
collation) attributes.

When you define multiple attributes for a single column, the

X$Attrib system table contains multiple entries for that column
IDone for each attribute you define. If you do not define column
attributes for a particular column, that column has no entry in the
X$Attrib table. The text in the Xa$Attrs column appears exactly as
you define it with Pervasive PSQL. One index is defined for the

C-4

System Tables Structure

X$Attrib table, as explained in X$Attrib System Table Index

Definitions:
Table C-3

X$Attrib System Table Index Definitions

Index Number

Segment Number

Column Name

Duplicates

Case Insensitive

Segmented

Xa$Id

not applicable

Yes

Xa$Type

X$Depend
The X$Depend system table is associated with the file
DEPEND.DDF. X$Depend contains information about trigger
dependencies such as tables, views, and procedures. The structure of
X$Depend is as follows:
Table C-4

X$Depend System Table Structure

Column Name

Type

Size

Case Insensitive

Description

Xd$Trigger

CHAR

Yes

Name of trigger. It corresponds to

Xt$Name in X$Trigger.

Xd$DependType

UNSIGNED

not applicable

1 for Table, 2 for View, 3 for

Procedure.

Xd$DependName

CHAR

Yes

Name of dependency with which the

trigger is associated. It corresponds
to either Xf$Name in X$File,
Xv$Name in X$View, or Xp$Name in
X$Proc.

Two indexes are defined for the X$Depend table, as follows:

Table C-5

X$Depend System Table Index Definitions

Index Number

Segment
Number

Column Name

Duplicates

Case Insensitive

Segmented

Xd$Trigger

Yes

Xd$DependType

not applicable

Yes

Xd$DependName

Yes

Xd$DependType

Yes

not applicable

Yes

Xd$DependName

Yes

C-5

System Tables

Index Number corresponds to the value stored in the Xi$Number

column in the X$Index system table. Segment Number corresponds
to the value stored in the Xi$Part column in the X$Index system
table.
X$Field
The X$Field system table is associated with the file FIELD.DDF.
X$Field contains information about all the columns and named
indexes defined in the database. The structure of X$Field is as
follows:
Table C-6

X$Field System Table Structure

Column Name

Type

Size

Case Insensitive

Description

Xe$Id

USMALLINT

not applicable

Internal ID Pervasive PSQL assigns, unique

for each field in the database.

Xe$File

USMALLINT

not applicable

ID of table to which this column or named

index belongs. It corresponds to Xf$Id in
X$File.

Xe$Name

CHAR

Yes

Column name or index name.

Xe$DataType

UTINYINT

not applicable

Control field:
0 through 26: column data type
227: constraint name
255: index name

Xe$Offset

USMALLINT

not applicable

Column offset in table; index number if named

index. Offsets are zero-relative.
Index Number corresponds to the value stored
in the Xi$Number column in the X$Index
system table.

Xe$Size

USMALLINT

not applicable

Column size, representing the internal

storage, in bytes, required for the field.
Size does not include the NULL byte for TRUE
NULL fields.

C-6

System Tables Structure

Table C-6

X$Field System Table Structure continued

Column Name

Type

Size

Case Insensitive

Description

Xe$Dec

UTINYINT

not applicable

Column decimal place (for DECIMAL,

NUMERIC, NUMERICSA, NUMERICSTS,
MONEY, or CURRENCY types). Relative bit
positions for contiguous bit columns.
Fractional seconds for TIMESTAMP data type.

Xe$Flags

USMALLINT

not applicable

Flags word.
Bit 0 is the case flag for string data types.
If bit 0 = 1, the field is case insensitive.
If bit 2 = 1, the field allows null values.
Bit 3 of Xe$flag is used to differentiate a
Pervasive.SQL v7 1-byte TINYINT
(B_TYPE_INTEGER unsigned) from SRDE's
1-byte TINYINT (B_TYPE_INTEGER, but
signed).
If bit 3 = 1 and Xe$datatype = 1 and Xe$size
=1, then it means that TINYINT column is
created by the SRDE and is a signed 1-byte
TINYINT.
If bit 3 = 0 and Xe$datatype = 1 and xe$size =
1 then it means that TINYINT column is
created by the legacy SQL engine and is an
unsigned 1-byte TINYINT.
If bit 12 = 1, the field is interpreted as BINARY.
If bit 13 = 1, the field is interpreted as
DECIMAL with even-byte precision.

The column Xe$File corresponds to the column Xf$Id in the X$File

system table and is the link between the tables and the columns they
contain. So, for example, the following query shows you all of the
field definitions in order for the Billing table.
SELECT "X$Field".*
FROM X$File,X$Field
WHERE Xf$Id=Xe$File AND Xf$Name = Billing AND
Xe$DataType <= 26
ORDER BY Xe$Offset

The integer values in column Xe$DataType are codes that represent

the Pervasive PSQL data types. See Pervasive PSQL Supported Data
Types on page A-2 for the codes.

C-7

System Tables

Five indexes are defined for the X$Field table, as follows:

Table C-7

X$Field System Table Index Definitions

Index Number

Segment Number

Column Name

Duplicates

Case Insensitive

Segmented

Xe$Id

not applicable

Xe$File

Yes

not applicable

Xe$Name

Yes

Xe$File

not applicable

Yes

Xe$Name

Yes

Xe$File

Yes

not applicable

Yes

Xe$Offset

Yes

not applicable

Yes

Xe$Dec

Yes

not applicable

X$File
The X$File system table is associated with the file FILE.DDF. For
each table defined in the database, X$File contains the table name,
the location of the associated table, and a unique internal ID number
that Pervasive PSQL assigns. The structure of X$File is as follows:
Table C-8

X$File System Table Structure

Column Name

Type

Size

Case Insensitive

Description

Xf$Id

USMALLINT

not applicable

Internal ID Pervasive PSQL assigns.

Xf$Name

CHAR

Yes

Table name.

Xf$Loc

CHAR

File location (path name).

Xf$Flags

UTINYINT

not applicable

File flags. If bit 4=1, the file is a

dictionary file. If bit 4=0, the file is
user-defined. If bit 6=1, the table
supports true nullable columns.

Xf$Reserved

CHAR

Reserved.

C-8

System Tables Structure

Two indexes are defined for the X$File table.

Table C-9

X$File System Table Index Definitions

Index Number

Segment Number

Column Name

Duplicates

Case Insensitive

Segmented

Xf$Id

not applicable

Xf$Name

Yes

X$Index
The X$Index system table is associated with the file INDEX.DDF.
X$Index contains information about all the indexes defined on the
tables in the database. The structure of X$Index is as follows:
Table C-10

X$Index System Table Structure

Column Name

Type

Size

Case Insensitive

Description

Xi$File

USMALLINT

not applicable

Unique ID of the table to which the index

belongs. It corresponds to Xf$Id in X$File.

Xi$Field

USMALLINT

not applicable

Unique ID of the index column. It

corresponds to Xe$Id in X$Field.

Xi$Number

USMALLINT

not applicable

Index number (range 0 119).

Xi$Part

USMALLINT

not applicable

Segment number (range 0 119).

Xi$Flags

USMALLINT

not applicable

Index attribute flags.

The Xi$File column corresponds to the Xf$Id column in the X$File

system table. The Xi$Field column corresponds to the Xe$Id column
in the X$Field system table. Thus, an index segment entry is linked
to a file and to a field.
The Xi$Flags column contains integer values that define the index
attributes. The following table describes how Pervasive PSQL
interprets each bit position when the bit has the binary value of 1. Bit
position 0 is the rightmost bit in the integer.
Table C-11

X$Index System Table Index Definitions

Bit
Position

Decimal
Equivalent

Description

Index allows duplicates.

Index is modifiable.

C-9

System Tables

Table C-11

X$Index System Table Index Definitions continued

Bit
Position

Decimal
Equivalent

Description

Indicates an alternate collating sequence.

Null values are not indexed (refers to Btrieve NULLs, not SQL true NULLS).

Another segment is concatenated to this one in the index.

Index is case-insensitive.

Index is collated in descending order.

128

Index is a named index if bit 0 is 0. If bit 0 is 1 and bit 7 is 1, the index uses the
repeating duplicates key method. If bit 0 is 1 and bit 7 is 0, the index uses the
linked duplicates key method. See also LINKDUP on page 3-88. For a detailed
discussion of linked duplicates method and repeating duplicates method, see
Methods for Handling Duplicate Keys on page 13-14 in Advanced Operations
Guide.)

256

Index is a Btrieve extended key type.

512

Index is partial.

8192

Index is a foreign key.

16384

Index is a primary key referenced by some foreign key.

The value in the Xi$Flags column for a particular index is the sum of
the decimal values that correspond to that indexs attributes. Three
indexes are defined for the X$Index table, as follows:
Table C-12

X$Index System Table Index Definitions

Index Number

Segment Number

Column Name

Duplicates

Case Insensitive

Segmented

Xi$File

Yes

not applicable

Xi$Field

Yes

not applicable

Xi$File

not applicable

Yes

Xi$Number

not applicable

Yes

Xi$Part

not applicable

Index Number corresponds to the value stored in the Xi$Number

column in the X$Index system table. Index numbering starts at zero.

C-10

System Tables Structure

Segment Number corresponds to the value stored in the Xi$Part

column in the X$Index system table.
To see the information about the index segments defined for the
Billing table, for example, issue the following query:
SELECT Xe$Name,Xe$Offset, "X$Index".*
FROM X$File,X$Index,X$Field
WHERE Xf$Id=Xi$File and Xi$Field=Xe$Id and Xf$Name =
Billing
ORDER BY Xi$Number,Xi$Part

X$Proc
The X$Proc system table is associated with the file PROC.DDF.
X$Proc contains the compiled structure information for every stored
procedure defined. The structure of X$Proc is as follows:
Table C-13

X$Proc System Table Structure

Column Name

Type

Size

Case Insensitive

Description

Xp$Name

CHAR

Yes

Stored procedure name.

Xp$Ver

UTINYINT

not applicable

Version ID. This is reserved for

future use.

Xp$Id

USMALLINT

not applicable

0-based Sequence Number.

Xp$Flags

UTINYINT

not applicable

1 for stored statement, 2 for stored

procedure or 3 for external
procedure.

Xp$Misc

LONGVARCHAR
(LVAR)

<=990

not applicable

Internal representation of stored

procedure.

Note Stored statements and external procedures were supported

in versions of Pervasive.SQL prior to Pervasive.SQL 2000i. Only

stored procedures have been supported since Pervasive.SQL
2000i.

C-11

System Tables

One index is defined for the X$Proc table, as follows:

Table C-14

X$Proc System Table Index Definitions

Index Number

Segment Number

Column Name

Duplicates

Case Insensitive

Segmented

Xp$Name

Yes

Xp$Id

not applicable

A single stored procedure may be stored in multiple entires in

X$Proc, linked by Xp$Name.
X$Relate
The X$Relate system table is associated with the file RELATE.DDF.
X$Relate contains information about the referential integrity (RI)
constraints defined on the database. X$Relate is automatically
created when the first foreign key is created, since this results in a
relationship being defined.
The structure of X$Relate is as follows:
Table C-15

X$Relate System Table Structure

Column Name

Type

Size

Case Insensitive

Description

Xr$PId

USMALLINT

not applicable

Primary table ID.

Xr$Index

USMALLINT

not applicable

Index number of primary key in primary table.

Xr$FId

USMALLINT

not applicable

Dependent table ID.

Xr$FIndex

USMALLINT

not applicable

Index number of foreign key in dependent

table.

Xr$Name

CHAR

Yes

Foreign key name.

Xr$UpdateRule

UTINYINT

not applicable

1 for restrict.

Xr$DeleteRule

UTINYINT

not applicable

1 for restrict, 2 for cascade.

Xr$Reserved

CHAR

Reserved.

C-12

System Tables Structure

Five indexes are defined for the X$Relate table, as follows:

Table C-16

X$Relate System Table Index Definitions

Index Number

Segment Number

Column Name

Duplicates

Case Insensitive

Segmented

Xr$PId

Yes

not applicable

Xr$FId

Yes

not applicable

Xr$Name

Yes

Xr$Pld

not applicable

Yes

Xr$Name

Yes

Xr$Fld

not applicable

Yes

Xr$Name

Yes

X$Rights
The X$Rights system table is associated with the file RIGHTS.DDF.
X$Rights contains access rights information for each user. Pervasive
PSQL uses this table only when you enable the security option. The
structure of X$Rights is as follows:
Table C-17

X$Rights System Table Structure

Column Name

Type

Size

Case Insensitive

Description

Xr$User

USMALLINT

not applicable

User ID

Xr$Table

USMALLINT

not applicable

Table ID

Xr$Column

USMALLINT

not applicable

Column ID

Xr$Rights

UTINYINT

not applicable

Table or column rights flag

The Xr$User column corresponds to the Xu$Id column in the

X$User table. The Xr$Table column corresponds to the Xf$Id
column in the X$File table. The Xr$Column column corresponds to
the Xe$Id column in the X$Field table.
Note For any row in the system table that describes table rights,

the value for Xr$Column is null.

C-13

System Tables

The Xr$Rights column contains integer values whose rightmost 8

bits define the users access rights. The following table describes how
Pervasive PSQL interprets the value. Values from this table may be
combined into a single Xr$Rights value.
Table C-18

Xr$Rights System Table Bit Position Definitions

Hex Value

Decimal Equivalent

Description

Reorganization in progress.

0x90

144

References rights to table.

0xA0

160

Alter Table rights.

0x40

Select rights to table or column.

0x82

130

Update rights to table or column.

0x84

132

Insert rights to table or column.

0x88

136

Delete rights to table or column.

A decimal equivalent of 0 implies no rights.

The value in the Xr$Rights column for a particular user is the bitwise intersection of the hex values corresponding to the access rights
that apply to the user. It is not the sum of the decimal values.
For example, the value in Xr$Rights for a user with all rights assigned
would be represented as follows:
144 | 160 | 64 | 130 | 132 | 136 = 254
Three indexes are defined for the X$Rights table, as follows:
Table C-19

X$Rights System Table Index Definitions

Index Number

Segment Number

Column Name

Duplicates

Case Insensitive

Segmented

Xr$User

Yes

not applicable

Xr$User

not applicable

Yes

Xr$Table

not applicable

Yes

Xr$Column

not applicable

Xr$Table

Yes

not applicable

Yes

Xr$Column

Yes

not applicable

C-14

System Tables Structure

X$Trigger
The X$Trigger system table is associated with the file
TRIGGER.DDF. X$Trigger contains information about the triggers
defined for the database. The structure of X$Trigger is as follows:
Table C-20

X$Trigger System Table Structure

Column Name

Type

Size

Case Insensitive

Description

Xt$Name

CHAR

Yes

Trigger name.

Xt$Version

USMALLINT

not applicable

Trigger version. A 4 indicates

Scalable SQL v4.

Xt$File

USMALLINT

not applicable

File on which trigger is defined.

Corresponds to Xf$Id in X$File.

Xt$Event

UNSIGNED

not applicable

0 for INSERT, 1 for DELETE, 2 for

UPDATE.

Xt$ActionTime

UTINYINT

not applicable

0 for BEFORE, 1 for AFTER.

Xt$ForEach

UTINYINT

not applicable

0 for ROW (default), 1 for

STATEMENT.

Xt$Order

USMALLINT

not applicable

Order of execution of trigger.

Xt$Sequence

USMALLINT

not applicable

0-based sequence number.

Xt$Misc

LONGVARCHAR
(LVAR)

<=4054

not applicable

Internal representation of trigger.

A trigger that is long enough may require multiple entries in

Trigger.DDF. Each entry has the same trigger name in the Xt$Name
field, and is used in the order specified by the Xt$Sequence field.
Three indexes are defined for the X$Trigger table, as follows:
Table C-21

X$Trigger System Table Index Definitions

Index Number

Segment Number

Column Name

Duplicates

Case Insensitive

Segmented

Xt$Name

Yes

Xt$Sequence

not applicable

Xt$File

not applicable

Yes

Xt$Name

Yes

Xt$Sequence

not applicable

C-15

System Tables

Table C-21

X$Trigger System Table Index Definitions continued

Index Number

Segment Number

Column Name

Duplicates

Case Insensitive

Segmented

Xt$File

Yes

not applicable

Yes

Xt$Event

Yes

not applicable

Yes

Xt$ActionTime

Yes

not applicable

Yes

Xt$ForEach

Yes

not applicable

Yes

Xt$Order

Yes

not applicable

Yes

Xt$Sequence

Yes

not applicable

The trigger may be stored in more than one entry in X$Trigger,

linked by Xt$Name and ordered by Xt$Sequence.
X$User
The X$User system table is associated with the file USER.DDF.
X$User contains the name and password of each user and the name
of each user group. Pervasive PSQL uses this table only when you
enable the security option. The structure of X$User is as follows:
Table C-22

X$User System Table Structure

Column Name

Type

Size

Case Insensitive

Description

Xu$Id

USMALLINT

not applicable

Internal ID assigned to the user or

group.

Xu$Name

CHAR

Yes

User or group name.

Xu$Password

CHAR

User password (encrypted)

Xu$Flags

USMALLINT

not applicable

User or group flags.

Note For any row in the X$User system table that describes a

group, the column value for Xu$Password is NULL.

The Xu$Flags column contains integer values whose rightmost 8 bits
define the user or group attributes. The following table describes

C-16

System Tables Structure

how Pervasive PSQL interprets each bit position when the bit has the
binary value of 1. Bit position 0 is the rightmost bit in the integer.
Table C-23

Xu$Flags System Table Bit Position Definitions

Bit
Position

Decimal Equivalent

Description

Reserved.

Name is a group name.

128

User or group has the right to define tables in the dictionary.

The value in the Xu$Flags column for a particular user or group is

the sum of the decimal values corresponding to the attributes that
apply to the user or group.
Two indexes are defined for the X$User table, as follows:
Table C-24

X$User System Table Index Definitions

Index Number

Segment Number

Column Name

Duplicates

Case Insensitive

Segmented

Xu$Id

Yes

not applicable

Xu$Name

Yes

X$View
The X$View system table is associated with the file VIEW.DDF.
X$View contains view definitions, including information about
joined tables and the restriction conditions that define views. You
can query the X$View table to retrieve the names of the views that are
defined in the dictionary.

C-17

System Tables

The first column of the X$View table contains the view name; the
second and third columns describe the information found in the
LVAR column, Xv$Misc. The structure of X$View is as follows:
Table C-25

X$View System Table Structure

Column Name

Type

Size

Case Insensitive

Description

Xv$Name

CHAR

Yes

View name.

Xv$Ver

UTINYINT

not applicable

Version ID. This is reserved for

future use.

Xv$Id

UTINYINT

not applicable

Sequence number.

Xv$Misc

LONGVARCHAR
(LVAR)

<=2000

not applicable

Pervasive PSQL internal definitions.

Two indexes are defined for the X$View table, as follows:

Table C-26

X$View System Table Index Definitions

Index Number

Segment Number

Column Name

Duplicates

Case Insensitive

Segmented

Xv$Name

Yes

Xv$Name

Yes

Xv$Ver

not applicable

Yes

Xv$Id

not applicable

A single view may be stored in multiple X$View entries, linked by

Xv$Name and ordered by Xv$Id.

C-18

System Tables Structure

V2 Metadata
System Tables

Table C-27

X$Attrib
The X$Attrib system table is associated with the file PVATTRIB.DDF.
X$Attrib contains information about the column attributes of each
column in the database; there is an entry for each column attribute
you define. The structure of X$Attrib is as follows:

X$Attrib System Table Structure for V2 Metadata

Column Name

Type

Size

Case Insensitive

Description

Xa$Id

UINTEGER

not applicable

Corresponds to Xe$Id in X$Field

Xa$Type

CHAR

D for default, O for column collation

Xa$ASize

USMALLINT

Not applicable

Length of text in Xa$Attrs

Xa$Attrs

LONGVARCHAR
(NOTE)

32,763

not applicable

Text that defines the column attribute

When you define multiple attributes for a single column, the

X$Attrib System Table Index Definitions for V2 Metadata

Index Number

Segment Number

Column Name

Duplicates

Case Insensitive

Segmented

Xa$Id

not applicable

Yes

Xa$Type

C-19

System Tables

X$Depend
The X$Depend system table is associated with the file
PVDEPEND.DDF. X$Depend contains information about trigger
dependencies for such objects as tables, views, and procedures. The
structure of X$Depend is as follows:
Table C-29

X$Depend System Table Structure for V2 Metadata

Column Name

Type

Size

Case Insensitive

Description

Xd$Trigger

CHAR

128

Yes

Name of trigger. It corresponds to

Xt$Name in X$Trigger.

Xd$DependType

UTINYINT

not applicable

1 for Table, 2 for View, 3 for Procedure.

Xd$DependName

CHAR

Yes

Name of dependency with which the trigger

is associated. It corresponds to either
Xf$Name in X$File, Xv$Name in X$View,
or Xp$Name in X$Proc.

1
128

Two indexes are defined for the X$Depend table, as follows:

Table C-30

X$Depend System Table Index Definitions for V2 Metadata

Index Number

Segment Number

Column Name

Duplicates

Case Insensitive

Segmented

Xd$Trigger

Yes

Xd$DependType

not applicable

Xd$DependType

Yes

not applicable

Yes

Xd$DependName

Yes

C-20

System Tables Structure

X$Field
The X$Field system table is associated with the file PVFIELD.DDF.
X$Field contains information about all the columns and named
indexes defined in the database. The structure of X$Field is as
follows:
Table C-31

X$Field System Table Structure for V2 Metadata

Column Name

Type

Xe$Id

UINTEGER

Xe$File

UINTEGER

Xe$Name

CHAR

Xe$Datatype

UTINYINT

Xe$Offset

UINTEGER

Size

Case Insensitive

Description

not applicable

Internal ID Pervasive PSQL assigns, unique

for each field in the database.

not applicable

ID of table to which this column or named index

belongs. It corresponds to Xf$Id in X$File.

Yes

Column name or index name.

not applicable

0 through 26: column data type

227: constraint name
255: index name

not applicable

Column offset in table; index number if named

index. Offsets are zero-relative.

128

Index Number corresponds to the value stored

in the Xi$Number column in the X$Index
system table.
Xe$Size

UINTEGER

not applicable

Column size, representing the internal storage,

in bytes, required for the field.

C-21

System Tables

Table C-31

X$Field System Table Structure for V2 Metadata continued

Column Name

Type

Size

Xe$Dec

USMALLINT

Xe$Flags

UINTEGER

Case Insensitive

Description

not applicable

Column decimal place (for DECIMAL,

NUMERIC, NUMERICSA, NUMERICSTS,
MONEY, or CURRENCY types). Relative bit
positions for contiguous bit columns.
Fractional seconds for TIMESTAMP data type.

not applicable

The column Xe$File corresponds to the column Xf$Id in the X$File

The integer values in column Xe$DataType are codes that represent

the Pervasive PSQL data types. See Pervasive PSQL Supported Data
Types on page A-2 for the codes.

C-22

System Tables Structure

Five indexes are defined for the X$Field table, as follows:

Table C-32

X$Field System Table Index Definitions for V2 Metadata

Index Number

Segment Number

Column Name

Duplicates

Case Insensitive

Segmented

Xe$Id

not applicable

Xe$File

Yes

not applicable

Xe$Name

Yes

Xe$File

not applicable

Yes

Xe$Name

Yes

Xe$File

Yes

not applicable

Yes

Xe$Offset

Yes

not applicable

Yes

Xe$Dec

Yes

not applicable

X$File
The X$File system table is associated with the file PVFILE.DDF. For
each table defined in the database, X$File contains the table name,
the location of the associated table, and a unique internal ID number
that Pervasive PSQL assigns. The structure of X$File is as follows:
Table C-33

X$File System Table Structure for V2 Metadata

Column Name

Type

Xf$Id

UINTEGER

Xf$Name

CHAR

Xf$Loc

CHAR

Xf$Flags

UINTEGER

Xf$Reserved

CHAR

Size

Case Insensitive

Description

not applicable

Internal ID Pervasive PSQL assigns.

128

Yes

Table name.

250

File location (path name).

not applicable

File flags. If bit 4=1, the file is a dictionary file.

If bit 4=0, the file is user-defined. If bit 6=1,
the table supports true nullable columns.

Reserved.

C-23

System Tables

Two indexes are defined for the X$File table.

Table C-34

X$File System Table Index Definitions for V2 Metadata

Index Number

Segment Number

Column Name

Duplicates

Case Insensitive

Segmented

Xf$Id

not applicable

Xf$Name

Yes

X$Index
The X$Index system table is associated with the file PVINDEX.DDF.
X$Index contains information about all the indexes defined on the
tables in the database. The structure of X$Index is as follows:
Table C-35

X$Index System Table Structure for V2 Metadata

Column Name

Type

Size

Case Insensitive

Description

Xi$File

UINTEGER

not applicable

Unique ID of the table to which the index

belongs. It corresponds to Xf$Id in X$File.

Xi$Field

UINTEGER

not applicable

Unique ID of the index column. It corresponds

to Xe$Id in X$Field.

Xi$Number

UINTEGER

not applicable

Index number (range 0 119).

Xi$Part

UINTEGER

not applicable

Segment number (range 0 119).

Xi$Flags

UINTEGER

not applicable

Index attribute flags.

The Xi$File column corresponds to the Xf$Id column in the X$File

system table. The Xi$Field column corresponds to the Xe$Id column
in the X$Field system table. Thus, an index segment entry is linked
to a file and to a field.

C-24

System Tables Structure

The Xi$Flags column contains integer values that define the index
attributes. The following table describes how Pervasive PSQL
interprets each bit position when the bit has the binary value of 1. Bit
position 0 is the rightmost bit in the integer.
Table C-36
Bit
Position

Xi$Flags Bit Positions for V2 Metadata

Decimal Equivalent

Description

Index allows duplicates.

Index is modifiable.

Indicates an alternate collating sequence.

Null values are not indexed (refers to Btrieve NULLs, not SQL true
NULLS).

Another segment is concatenated to this one in the index.

Index is case-insensitive.

Index is collated in descending order.

128

Index is a named index if bit 0 is 0. If bit 0 is 1 and bit 7 is 1, the index

uses the repeating duplicates key method. If bit 0 is 1 and bit 7 is 0, the
index uses the linked duplicates key method. See also LINKDUP. For
a detailed discussion of linked duplicates method and repeating
duplicates method, see Methods for Handling Duplicate Keys in
Advanced Operations Guide.)

256

Index is a Btrieve extended key type.

8,192

16,384

Index is a foreign key.

Index is a primary key referenced by some foreign key.

C-25

System Tables

X$Index System Table Index Definitions for V2 Metadata

Index Number

Segment Number

Column Name

Duplicates

Case Insensitive

Segmented

Xi$File

Yes

not applicable

Xi$Field

Yes

not applicable

Xi$File

not applicable

Yes

Xi$Number

not applicable

Yes

Xi$Part

not applicable

Index Number corresponds to the value stored in the Xi$Number

column in the X$Index system table. Index numbering start at zero.
Segment Number corresponds to the value stored in the Xi$Part
column in the X$Index system table.
To see the information about the index segments defined for the
Billing table, for example, issue the following query:
SELECT Xe$Name,Xe$Offset, "X$Index".*
FROM X$File,X$Index,X$Field
WHERE Xf$Id=Xi$File and Xi$Field=Xe$Id and Xf$Name =
Billing
ORDER BY Xi$Number,Xi$Part

C-26

System Tables Structure

X$Proc
The X$Proc system table is associated with the file PVPROC.DDF.
X$Proc contains the compiled structure information for every stored
procedure defined. The structure of X$Proc is as follows:
Table C-38

X$Proc System Table Structure for V2 Metadata

Column Name

Type

Xp$Name

CHAR

Xp$Ver

UTINYINT

Xp$Id

Size

Case Insensitive

Description

Yes

Stored procedure name

not applicable

Version ID. This is reserved for future

use.

UINTEGER

not applicable

Internal ID assigned by Pervasive PSQL

Xp$Flags

UINTEGER

not applicable

1 for stored statement, 2 for stored

procedure or 3 for external procedure

Xp$Trustee

INTEGER

not applicable

0 for a trusted stored procedure and -1

for a non-trusted stored procedure. See
Trusted and Non-trusted Objects on
page 3-154.

Xp$Sequence

USMALLINT

not applicable

A sequence number. A procedure that

exceeds 32,765 bytes requires multiple
entries in PVPROC.DDF to handle the
overflow. Each entry has the same
procedure name in the Xp$Name field
and is assigned a sequence number.
The Xp$Sequence field is used to
correctly order the multiple entries.

128

The sequence starts at zero (the first

sequence number is zero).
Xp$Misc

LONGVARCHAR
(LVAR)

32,765

not applicable

Internal representation of stored

procedure

Note Stored statements and external procedures were supported

in versions of Pervasive PSQL prior to Pervasive.SQL 2000i.

Only stored procedures have been supported since
Pervasive.SQL 2000i.

C-27

System Tables

Four indexes are defined for the X$Proc table, as follows:

Table C-39

X$Proc System Table Index Definitions for V2 Metadata

Index Number

Segment Number

Column Name

Duplicates

Case Insensitive

Segmented

Xp$Name

Yes

Xp$Name

Yes

Xp$Ver

not applicable

Yes

Xp$Sequence

not applicable

Xp$Id

Yes

Xp$Id

not applicable

Yes

Xp$sequence

not applicable

X$Relate
The X$Relate system table is associated with the file
PVRELATE.DDF. X$Relate contains information about the
referential integrity (RI) constraints defined on the database.
X$Relate is automatically created when the first foreign key is
created, since this results in a relationship being defined.
The structure of X$Relate is as follows:
Table C-40

X$Relate System Table Structure for V2 Metadata

Column Name

Type

Xr$PId

UINTEGER

Xr$Index

Case Insensitive

Description

not applicable

Primary table ID.

UINTEGER

not applicable

Index number of primary key in primary table.

Xr$FId

UINTEGER

not applicable

Dependent table ID.

Xr$FIndex

UINTEGER

not applicable

Index number of foreign key in dependent

table.

Xr$Name

CHAR

Yes

Foreign key name.

Xr$UpdateRule

UTINYINT

not applicable

1 for restrict.

Xr$DeleteRule

UTINYINT

not applicable

1 for restrict, 2 for cascade.

Xr$Reserved

CHAR

Reserved.

C-28

Size

128

250

System Tables Structure

Five indexes are defined for the X$Relate table, as follows:

Table C-41

X$Relate System Table Index Definitions for V2 Metadata

Index
Number

Segment
Number

Column Name

Duplicates

Modifiable

Case Insensitive

Segmented

Xr$PId

Yes

not applicable

Xr$FId

Yes

not applicable

Xr$Name

Yes

Xr$Pld

Yes

not applicable

Yes

Xr$Name

Yes

Xr$Fld

Yes

not applicable

Yes

Xr$Name

Yes

X$Rights
The X$Rights system table is associated with the file
PVRIGHTS.DDF. X$Rights contains access rights information for
each user. Pervasive PSQL uses this table only when you enable the
security option. The structure of X$Rights is as follows:
Table C-42

X$Rights System Table Structure for V2 Metadata

Column Name

Type

Size

Case Insensitive

Description

Xr$User

UINTEGER

not applicable

User ID

Xr$Object

UINTEGER

not applicable

Table identification corresponding to Xf$Id,

view identification corresponding to Xv$Id or
stored procedure identification corresponding
to Xp$Id

Xr$Type

UINTEGER

not applicable

1 for Tables, 3 for Views and 4 for Procedures

Xr$Column

UINTEGER

not applicable

Column ID

Xr$Rights

UINTEGER

not applicable

Rights flag for table, column, views or stored

procedures

The Xr$User column corresponds to the Xu$Id column in the

X$User table. The Xr$Object column corresponds to one of the
following:

Xf$Id column in the X$File table

C-29

System Tables

Xv$Id column in X$Views table

Xp$Id column in X$Proc table.

The Xr$Column column corresponds to the Xe$Id column in the

X$Field table.
Note For any row in the system table that describes table rights,
view rights, or stored procedure rights, the value for Xr$Column
is null.

The Xr$Rights column contains integer values whose rightmost 8

bits define the users access rights. The following table describes how
Pervasive PSQL interprets the value. Values from this table may be
combined into a single Xr$Rights value.
Table C-43

Xr$Rights Bit Positions for V2 Metadata

Hex Value

Decimal
Equivalent

Description

Object owner right

0x90

144

References rights to table

0xA0

160

Alter table rights

0x40

Select rights to view, table or column

0x82

130

Update rights to view, table or column

0x84

132

Insert rights to view, table or column

0x88

136

Delete rights to table or column

0xC0

192

Execute and call rights to a stored procedure

A decimal equivalent of 0 implies no rights.

The value in the Xr$Rights column for a particular user is the bitwise intersection of the hex values corresponding to the access rights
that apply to the user. It is not the sum of the decimal values.
For example, the value in Xr$Rights for a user with all rights assigned
is represented as follows:
144 | 160 | 64 | 130 | 132 | 136 = 254

C-30

System Tables Structure

The value in Xr$Rights for a user with all rights assigned for a view
is represented as follows:
64 | 130 | 132 | 136 = 206
The value in Xr$Rights for a user with all rights assigned for a stored
procedure is represented as follows:
192 = 192
Three indexes are defined for the X$Rights table, as follows:
Table C-44

X$Rights System Table Index Definitions for V2 Metadata

Index Number

Segment Number

Column Name

Duplicates

Case Insensitive

Segmented

Xr$User

Yes

not applicable

Xr$User

not applicable

Yes

Xr$Object

not applicable

Yes

Xr$Type

not applicable

Yes

Xr$Column

not applicable

Xr$Object

Yes

not applicable

Yes

Xr$Type

Yes

not applicable

Yes

Xr$Column

Yes

not applicable

C-31

System Tables

X$Trigger
The X$Trigger system table is associated with the file PVTRIG.DDF.
X$Trigger contains information about the triggers defined for the
database. The structure of X$Trigger is as follows:
Table C-45

X$Trigger System Table Structure for V2 Metadata

Column Name

Type

Xt$Name

CHAR

Xt$Version

UTINYINT

Xt$File

Size

Case Insensitive

Description

Yes

Trigger name.

not applicable

Trigger version. A 4 indicates

Scalable SQL v4.

UINTEGER

not applicable

File on which trigger is defined.

Corresponds to Xf$Id in X$File.

Xt$Event

UTINYINT

not applicable

0 for INSERT, 1 for DELETE, 2 for

UPDATE.

Xt$ActionTime

UTINYINT

not applicable

0 for BEFORE, 1 for AFTER.

Xt$ForEach

UTINYINT

not applicable

0 for ROW (default), 1 for

STATEMENT.

Xt$Order

USMALLINT

not applicable

Order of execution of trigger.

Xt$Sequence

USMALLINT

not applicable

A sequence number. A trigger that

exceeds 4,054 bytes requires
multiple entries in PVTRIG.DDF to
handle the overflow. Each entry has
the same procedure name in the
Xt$Name field and is assigned a
sequence number. The Xt$Sequence
field is used to correctly order the
multiple entries.

128

The sequence starts at zero (the first

sequence number is zero).
Xt$Misc

C-32

LONGVARCHAR
(LVAR)

4,054

not applicable

Internal representation of trigger.

System Tables Structure

Three indexes are defined for the X$Trigger table, as follows:

Table C-46

X$Trigger System Table Index Definitions for V2 Metadata

Index Number

Segment Number

Column Name

Duplicates

Case Insensitive

Segmented

Xt$Name

Yes

Xt$Sequence

not applicable

Xt$Name

Yes

Xt$File

Yes

Xt$Sequence

not applicable

Xt$File

Yes

not applicable

Yes

Xt$Event

Yes

not applicable

Yes

Xt$ActionTime

Yes

not applicable

Yes

Xt$ForEach

Yes

not applicable

Yes

Xt$Order

Yes

not applicable

Yes

Xt$Sequence

Yes

not applicable

X$User
The X$User system table is associated with the file PVUSER.DDF.
X$User contains the name and password of each user and the name
of each user group. Pervasive PSQL uses this table only when you
enable the security option. The structure of X$User is as follows:
Table C-47

X$User System Table Structure for V2 Metadata

Column Name

Type

Xu$Id

UINTEGER

Xu$Name

CHAR

Xu$Password

CHAR

Xu$Flags

UINTEGER

Size

Case Insensitive

Description

not applicable

Internal ID assigned to the user or group.

128

Yes

User or group name.

128

User password (encrypted)

not applicable

User or group flags.

C-33

System Tables

Note For any row in the X$User system table that describes a

group, the column value for Xu$Password is NULL.

The Xu$Flags column contains integer values whose rightmost 8 bits
define the user or group attributes. The following table describes
how Pervasive PSQL interprets each bit position when the bit has the
binary value of 1. Bit position 0 is the rightmost bit in the integer.
Table C-48

Xu$Flags Bit Positions for V2 Metadata

Bit
Position

Decimal
Equivalent

Description

Reserved.

Name is a group name.

128

User or group has the right to define tables in the

dictionary.

The value in the Xu$Flags column for a particular user or group is

the sum of the decimal values corresponding to the attributes that
apply to the user or group.
Two indexes are defined for the X$User table, as follows:
Table C-49

X$User System Table Index Definitions for V2 Metadata

Index Number

Segment Number

Column Name

Duplicates

Case Insensitive

Segmented

Xu$Id

Yes

not applicable

Xu$Name

Yes

C-34

System Tables Structure

X$View
The X$View system table is associated with the file PVVIEW.DDF.
X$View contains view definitions, including information about
joined tables and the restriction conditions that define views. You
can query the X$View table to retrieve the names of the views that are
defined in the dictionary.
The first column of the X$View table contains the view name; the
second and third columns describe the information found in the
LVAR column, Xv$Misc. The structure of X$View is as follows:
Table C-50

X$View System Table Structure for V2 Metadata

Column Name

Type

Xv$Name

CHAR

Xv$Version

UTINYINT

Xv$Id

Size

Case Insensitive

Description

Yes

View name.

not applicable

Version ID. This is reserved for future

use.

UINTEGER

not applicable

Internal ID assigned by Pervasive

PSQL

Xv$Trustee

INTEGER

not applicable

0 for a trusted view and -1 for a nontrusted view. See Trusted and Nontrusted Objects on page 3-154.

Xv$Sequence

USMALLINT

not applicable

A sequence number. A view that

exceeds 32,765bytes requires
multiple entries in PVVIEW.DDF to
handle the overflow. Each entry has
the same view name in the Xv$Name
field and is assigned a sequence
number. The Xv$Sequence field is
used to correctly order the multiple
entries.

128

The sequence starts at zero (the first

sequence number is zero).
Xv$Misc

LONGVARCHAR
(LVAR)

32,765

not applicable

Pervasive PSQL internal definitions.

C-35

System Tables

Three indexes are defined for the X$View table, as follows:

Table C-51

X$View System Table Index Definitions

Index Number

Segment Number

Column Name

Duplicates

Case Insensitive

Segmented

Xv$Name

Yes

Xv$Name

Yes

Xv$Ver

not applicable

Yes

Xv$Sequence

not applicable

Xv$Id

Yes

not applicable

Xv$Id

not applicable

Yes

Xv$Sequence

not applicable

C-36

Appendix

SQL Access for COBOL

Applications

Providing SQL Access for COBOL Applications

This appendix includes the following sections:

Overview on page D-2

Components on page D-4
Using SQL Access on page D-6
Example of How to Execute a Sample XML File on page D-13

D-1

SQL Access for COBOL Applications

Overview
The Pervasive PSQL relational interface includes support for
COBOL OCCURS constructs, partial REDEFINES, and variable
record layouts.
A partial REDEFINE redefines a portion of the data within a record
(such as a 05 level within a 01 level). A variable record layout is also
referred to as a REDEFINES because the entire record is being
redefined. To avoid confusion with terminology, this section refers to
partial REDEFINES and to variable record layouts.
No changes are required to your COBOL application to take
advantage of the SQL access.
You enable SQL access by describing the applications understanding
of data to the Pervasive PSQL relational interface. In developers
terms, you define the metadata to the relational interface.
Note that this section applies only to COBOL applications that
include OCCURS, partial REDEFINES, or variable record layouts.

Restrictions

The following restrictions currently apply to providing SQL access

for COBOL applications.

D-2

OCCURS cannot be nested within OCCURS

OCCURS cannot be nested within partial REDEFINES
Partial REDEFINES cannot be nested within partial
REDEFINES
Partial REDEFINES cannot be nested within OCCURS
Only one index can be defined for an OCCURS. Additional
indexes cannot be defined for the items within the OCCURS.
The only data types supported are those defined for the
Pervasive PSQL transactional and relational interfaces. The data
types are described in the XML control file by using only the
transactional data types. See cobolschemaexec.xsdin Table D2 for a discussion of the XML control file. For a discussion of
data types, see Pervasive PSQL Supported Data Types on page
A-2 in SQL Engine Reference.

Overview

SQL
Statements
Table D-1

The following table lists the use of SQL statements with data tables
created from OCCURS, partial REDEFINES, or variable record
layouts.

Use of SQL Statements With COBOL Data Constructs

Statement

Use with
OCCURs and
partial
REDEFINES

Use with
Variable
Record
Layouts

Notes

ALTER TABLE

CREATE INDEX

CREATE INDEX IN
DICTIONARY

Yes

CREATE TRIGGER

DELETE

Yes

DROP TABLE

Yes

INSERT INTO

UPDATE

Yes

An UPDATE statement cannot update a column on

which a table filter has been defined. A table filter is a
logical expression associated with a table. Table filters
are defined as part of your metadata in the XML files.

all other SQL

statements listed in
SQL Engine
Reference.

Yes

See Grammar Statements on page 3-2 in SQL Engine

Reference.

A DROP TABLE statement removes all of the entries

from the system tables. The data file itself is not deleted
or modified. Also, when you drop a main table, a
message informs you to drop any dependent tables if
any are detected. A dependent table depends on a main
table and results from conditions such as an OCCURS
that contains an index or from partial REDEFINES.
Once you drop the dependent tables, you can drop the
main table.

D-3

SQL Access for COBOL Applications

Components
Pervasive PSQL v10 installs the following components to provide
SQL access for COBOL applications.
Table D-2

Components Installed to Provide SQL Access for COBOL Applications

Component

Purpose

Location1

w3cobolschemaexec100.dll

Library of routines used by

Schema Executor

file_path\PSQL\bin

libpsqlcobolschemaexec100.so
cobolschemaexec.xsd

cobolschemaexec.log

cobolschemaexec.exe

Linux server: /usr/local/psql/lib

Control file (document type
definition) used by Schema
Executor when processing XML
files

Windows server:
file_path\PSQL\schemas

Default logging file for messages

produced by Schema Executor
when processing of XML files

Window server:
file_path\PSQL\logs

Utility that populates the system

tables used by the relational
interface to interpret the ISAM
data as normalized SQL tables.

file_path\PSQL\bin

Linux server:
/user/local/psql/schemas/

Linux server:
/usr/local/psql/logs/

Also referred to as Schema

Executor.
cobolschemaexec

Utility that populates the system

tables used by the relational
interface to interpret the ISAM
data as normalized SQL tables.

Linux install:
/usr/local/psq/bin/

Also referred to as Schema

Executor.
SampleMainTable.xml

Sample XML template that defines

data for a simple table.
See also Example of How to
Execute a Sample XML File on
page D-13.

D-4

Windows server and client:

file_path\PSQL\samples\cobolschem
aexec
Linux install:
/usr/local/psql/samples/
cobolschemaexec

Components

Table D-2

Components Installed to Provide SQL Access for COBOL Applications

Component

Purpose

Location1

SampleMainWithOccurs.xml

Sample XML template used to

define data that contains
OCCURS constructs.

Windows server and client:

file_path\PSQL\samples\cobolschem
aexec

Sample XML template used to

define data that contains
REDEFINES constructs.

Windows server and client:

file_path\PSQL\samples\cobolschem
aexec

XML template used to define data

that contains variable record
layouts.

Windows server and client:

file_path\PSQL\samples\cobolschem
aexec

See Schema Executor Command

Format on page D-8

Same as current directory if no path is

specified. Otherwise, location
depends on user-supplied path.

SampleMainWithRedefines.xml

SampleVariantRecord.xml

A log file on a Windows client or

a Linux client is optional and
may be specified when Schema
Executor is run
1For

default locations of Pervasive PSQL files, see Where are the Pervasive PSQL v10 files installed? on
page 7-2 in Getting Started With Pervasive PSQL.

D-5

SQL Access for COBOL Applications

Using SQL Access

Complete the following tasks to take advantage of SQL access:
1

Manually edit the appropriate XML template to describe the

data layout.

Copy the data file(s) specified in the XML template(s) to the

database folder.

Execute the utility to populate the system tables used by the

relational interface (use the XML to create normalized data).

Optionally, if you are a COBOL applications developer, ensure

that you deploy any new system tables created by Schema
Executor.

Step 1: Modify Pervasive PSQL v10 includes sample XML templates that you use to
define the layout of data as required by your COBOL application. See
the Sample
XML Templates Table D-2. In developers terms, you describe your metadata in the
XML files.

To Modify an XML Template

Step 2: Copy
the Data File
Specified in the
XML Template

Open the XML template in a text editor.

Modify the XML as described in the files comments.

Save the modified template with a path and file name of your
choosing.

Copy the data file(s) specified in the XML file to the data file location
of the database before you run Schema Executor. The database is the
one to which you need to add the tables.
For example, you want to add a table (specified in the XML as
mytable.mkd) to a database "test" that has its data files under
c:\data\test. Copy the data file mytable.mkd to c:\data\test before you
run Schema Executor.

Step 3: Run the Pervasive PSQL v10 includes a command line utility called the
Schema Executor, which is also referred to as SchemaExec.
Schema
Executor Utility Schema Executor performs the following actions:

D-6

parses the XML file(s) that you manually edited.

Using SQL Access

populates existing system tables that the relational interface uses

to interpret the data as normalized SQL tables (a database
created with Pervasive PSQL v10 contains all of the required
system tables to support SQL access)
creates additional system tables and populates them if you run
the utility against a database created with a version of Pervasive
PSQL prior to Pervasive PSQL v10.

To Process an XML File with Schema Executor

See also Example of How to Execute a Sample XML File on page
D-13.
1

Access a command prompt at the operating system.

Execute Schema Executor at the command line (see Table D-2

for where this executable is installed by default).
Provide the required options, XMLfilename and databasename,
and any desired optional options. See Schema Executor
Command Format on page D-8.
If errors occur during the processing of the XML content, review
the errors reported in the Schema Executor log file. See Log
Messages on page D-10. Re-execute the utility with corrected
XML until no errors result from the processing.

D-7

SQL Access for COBOL Applications

Schema Executor Command Format

cobolschemaexec XMLfilename databasename [-s servername]
[-u login_id] [-p password] [-i svr_loginid] [-c
svr_password] [-l log_file] [ -h | -? ]

Table D-3

Options for Schema Executor Utility

Option

Meaning

XMLfilename

The file name of the XML schema that defines the layout of the data. Required option.
See Step 1: Modify the Sample XML Templates on page D-6.

databasename

The name of the Pervasive PSQL database accessed by your application. Required
option. If the database specified does not exist, the utility prompts for a path and file
name.
See also Creating a New Database with Schema Executor on page D-10.

-s servername

The name or IP address of the server running the Pervasive PSQL database engine. You
may use localhost as the name if running SchemaExec on the same machine as the
database engine. If servername is not specified, the local machine is assumed to be the
server.

-u login_id

The user name required to access a secure database. See Pervasive PSQL Security
on page 7-1 in Advanced Operations Guide for a discussion of the Pervasive PSQL
security models.

-p password

The password required to access a secure database. See Pervasive PSQL Security on
page 7-1 in Advanced Operations Guide for a discussion of the Pervasive PSQL security
models.

-i svr_loginid

The login name required to access the operating system on a remote machine. This
option is required if SchemaExec is processing an XML file located on a remote server.

-c svr_password

The password required to access the operating system on a remote machine. This option
is required if SchemaExec is processing an XML file located on a remote server.

-l log_file

Log file to use for messages produced during processing of the XML file.
If you execute SchemaExec on a machine running the Pervasive PSQL database engine,
a default log is created automatically. You do not need to use the -l log_file option. The
default log is named cobolschemaexec.log.
If you execute SchemaExec on a client machine (a machine not running the Pervasive
PSQL database engine), you can specify a log file for the client machine.
See Log Messages on page D-10.

-h or -?

D-8

Display command usage. Ignore all other options.

Using SQL Access

Note The required options XMLfilename and databasename are

positional and must appear in that order.

Example Usage

The following examples illustrate usage of Schema Executor.

For default locations of Pervasive PSQL files, see Where are the
Pervasive PSQL v10 files installed? on page 7-2 in Getting Started
With Pervasive PSQL.

Database already exists (with server running on local host):

cobolschemaexec
file_path\PSQL\samples\cobolschemaexec\test.xml
demodata\

Database does not exist (with server running on local host):

cobolschemaexec
file_path\PSQL\samples\cobolschemaexec\test.xml mytest

The utility prompts as follows:

CB103 : Could not connect to mytest
Do you want to create database (y/n) ?

If you press "y," the utility prompts for a database path:

Please enter the Database Path:

Provide an existing path or the utility returns an error. Ensure that

the database file (for example, a .MKD file) being used in the XML
file is available in the path.

Database exists on a remote server:

cobolschemaexec
file_path\PSQL\samples\cobolschemaexec\test.xml
demodata -s TestMachine -i testuser -c testuser

This example assumes that a user "testuser" (with password

"testuser") exists on the remote machine (TestMachine) with
administrative privileges, and that the database file being used in the
XML file is available in the data file directory of the database on the
remote machine.

D-9

SQL Access for COBOL Applications

Database does not exist on a remote server:

cobolschemaexec
file_path\PSQL\samples\cobolschemaexec\test.xml
mytest -s RemoteMachine -i testuser -c testuser

This example assumes that a user "testuser" (with password

"testuser") exists on the remote machine (TestMachine) with
administrative privileges.
The utility prompts as follows:
CB103 : Could not connect to mytest
Do you want to create database (y/n) ?

If you press "y," the utility prompts for a database path:

Please enter the Database Path:

Provide an existing path or the utility returns an error. Ensure that

the database file (for example, a .MKD file) being used in the XML
file is available in the path.
Creating a New Database with Schema Executor
If the utility option databasename specifies a database that does not
exist, Schema Executor prompts you whether to create a new
database. If you specify yes, the utility prompts for a location of the
new database. The location (path and folder name) must already
exist for Schema Executor to create the database.
Note that Schema Executor also expects to find the data files for
databasename in the default folder. The utility informs you if it finds
no data files. Manually copy the data files to the default folder and
run Schema Executor again to process the XML.
Log Messages
This section lists the codes that may appear in a log file after
processing an XML file with Schema Executor.
The success code is CB100 : Schemaexec completed successfully.

D-10

Using SQL Access

The following table lists the error codes.

Table D-4

Possible Error Codes in a CobolSchemaExec Log File

Error Code

Description

CB001

Unknown error.

CB002

Property name attribute missing

CB003

Both MAINTABLE and VARIANTRECORDTABLES not supported

CB004

Occurs Table Name specified is Invalid

CB005

Occurs Count specified is Invalid

CB006

Occurs Mapping Index specified is Invalid

CB007

TableName - Duplicate TableName

CB008

FieldName - Duplicate FieldName

CB009

IndexName - Duplicate IndexName

CB010

Table name parameter is not specified

CB012

Identifier - contains invalid characters

CB013

Offset has to be a non-negative integer

CB014

Identifier length cannot exceed 20 characters

CB016

Precision has to be greater than zero

CB017

Invalid Precision specified for - FieldName

CB018

Scale cannot be greater Precision for - FieldName

CB019

Log and XML file names must be different

CB022

TableFilter - TableFilter cannot have more than 255 characters

CB023

FieldName is not a field of TableName

CB024

TableFilters should be defined for all REDEFINES Table or for

NONE

CB025

Incorrect Parent Element

CB028

Identifier name identifiername should start with an alphabetic

character

CB029

Identifier name identifiername cannot be a keyword

D-11

SQL Access for COBOL Applications

Table D-4

Step 4:
Optionally,
Deploy the
System Tables

D-12

Possible Error Codes in a CobolSchemaExec Log File continued

Error Code

Description

CB050

DataFile - doesn't exist at DatabasePath

CB051

OCCURS/REDEFINES Length must be a non-negative integer

CB052

Length of Btrievefilename cannot exceed 64 characters

CB057

No index specified for Parent Table - ParentTableName

CB099

Parser error

CB100

Schemaexec completed successfully

CB101

Invalid value for command line argument argument

CB102

Value for Password cannot be specified without Login

CB103

Could not connect to DatabaseName

CB105

Could not create database DatabaseName in the dictionary path

Databasepath

CB106

Could not create the specified DSN

CB108

Could not close the database databasename

CB109

Could not read data from XML file

CB110

Could not drop the database

If you are a COBOL applications developer, ensure that you deploy

all of the system tables with your application. Such deployment is
nothing new and is mentioned only because you may have additional
system tables. For example, Schema Executor creates additional
system tables and populates them if you run the utility against a
database created with a version of Pervasive PSQL prior to Pervasive
PSQL v10. Therefore, you may have a few additional system tables
(DDF files) to deploy.

Example of How to Execute a Sample XML File

The sample XML and data files are provided under
file_path\PSQL\samples\cobolschemaexec. For default locations of
Pervasive PSQL files, see Where are the Pervasive PSQL v10 files
installed? on page 7-2 in Getting Started With Pervasive PSQL.
To execute the XML file SampleMainTable.xml using Schema
Executor perform the following steps.
1

Copy maintbl.mkd to the data file folder of the database to

which you wish to connect.
For example, suppose that database "test" exists with a data file
location of c:\data\test. Copy maintbl.mkd to c:\data\test.

Open a command prompt at the PSQL\bin directory .

Execute the following command at a DOS prompt:

cobolschemaexec
file_path\PSQL\samples\cobolschemaexec\samplemai
ntable.xml test

Additional
Notes

On successful execution of Schema Executor, the table maintbl

(as specified in the XML file) is created in the "test" database.

You man now perform SQL operations on table maintbl using

PCC.

This section provides notes pertaining to SELECT statements and

table filters.
SELECT Statements
A SELECT query on an OCCURS table returns the following:

the columns of the OCCURS table

the column of the main table that comprises the mapping index
an OCCURS counter that indicates the number of occurrences
of the OCCURS clause.

For example, you perform the query SELECT * FROM FIELD for the
tables created by the execution of Schema Executor on the sample
XML file file_path\PSQL\samples\cobolschemaexec\
SampleMainWithOccurs.xml.

D-13

SQL Access for COBOL Applications

The utility returns columns Id, OccursCounter, Field_1, Field_2 and

Field_3
A SELECT query on a REDEFINES table returns all of the columns
of the parent table and the columns of the REDEFINES table.
For example, you perform the query SELECT * FROM
Redefined_group for the tables created by the execution of Schema
Executor on the sample XML file file_path\PSQL\samples\
cobolschemaexec\SampleMainWithRedefines.xml.
The utility returns columns Id, Account_Num, Category,
Redef_Struct_Num (all columns of the parent table),
Redefined_field_1 (column of the REDEFINES table).
Table Filters
A table filter (referred to as TABLEFILTER in the sample XML
files) is a filter condition for a particular table.

A TABLEFILTER may have an expression with left and right

operands both being column names. For example, Cust_Num =
My_Cust_Num (where both Cust_Num and My_Cust_Num are
column names).
Provide a blank space between operands and the operator.

If a constant value is used in the expression for a TABLEFILTER,

the value must be specified within single quotes.
Example: Cust_Num = '100' (where Cust_Num is the column
name)

D-14

Use the following XML entities when specifying a TABLEFILTER

in an XML file:
XML Entity

Used For

less than (<)

greater than (>)

ampersand (&) (AND)

double quotes (")

single quotes (')

Example of How to Execute a Sample XML File

Examples of valid TABLEFILTERs:

Cust_Num = '100' (equivalent to Cust_Num = 100)

Cust_Num < '100' (equivalent to Cust_Num < 100)
Cust_Num > '100' (equivalent to Cust_Num > 100)
Cust_Num <> '100' (equivalent to Cust_Num <>
100)
'a' = Category | Account_Num <= 'a123' (equivalent to
'a'=category OR account_num <= 'a123')
'a' = Category & Account_Num = 'a123' (equivalent to
'a' = category AND account_num = 'a123')
Cust_Num = My_cust_Num (where both the operands are
column names)

D-15

SQL Access for COBOL Applications

D-16

Appendix

Query Plan Viewer

A Utility To Help You Optimize Queries

Perhaps the most complex aspect of SQL performance is query

optimization. The database engine performs query optimization
automatically, but the query structure itself can affect the overall
performance and how the engine optimizes.
Nearly all queries can be written more than one way and yet return
the same result set. For example, consider the simple query "SELECT
* FROM table1." Assume that table1 has five columns named col1,
col2, and so forth. You could write the query as "SELECT col1, col2,
col3, col4, col5 FROM table1" to give the same result set.
Visually comparing these two queries, SELECT * appears much
simpler than listing each column by name. However, listing each
column by name in the query delivers a very slight performance
boost. The reason is that with SELECT *, the asterisk symbol must be
parsed into the column names. Such parsing is not needed when the
query itself has already performed that task.
The best way to improve performance is to minimize the time
required to run queries against the database. This appendix cannot
discuss every possible query optimization because queries can be
quite complex and can vary tremendously in structure. However,
you can better determine how to optimize your queries by using
Query Plan Viewer.
Query Plan Viewer is a graphical utility with which you can view
query plans selected by the database engine. A query plan can be
viewed for a SELECT, INSERT, UPDATE, or DELETE statement.

E-1

Query Plan Viewer

Query Plan Settings

Two SQL statements let you control whether you want to create a
query plan and what name to give the plan. Both statements apply
only to the SQL session.
You can execute the statements in Pervasive PSQL Control Center or
from any utility that can send SQL statements to the Pervasive PSQL
database engine.
Table E-1

Query Plan SQL Statements for Settings

SQL Statement

Discussion

SET QRYPLAN=<on | off>

Instructs the database engine to create a query plan for use

with Query Plan Viewer, or not.

SET QRYPLANOUTPUT=<NULL | file_name>

Sets the location and name of the query plan file. NULL
specifies not to create a query plan file. A single query plan
output file can contain plans resulting from multiple queries.
By default, Query Plan Viewer looks for a file name
extension of "qpf." You may use whatever file name
extension you want, or omit one.
Example: You want to create a query plan named
"select_salary" and store the query plan file in a directory
named "mydirectory" on drive D off of the root:
SET QRYPLANOUTPUT='d:\mydirectory\select_salary.qpf'
The database engine creates the query plan output file, so
the path must be a location on the machine where the
database engine is running. The path should not reference
client-side locations or client drive mappings.

Graphical User Interface

Query Plan Viewer contains two windows: the Query Pane and the
Plan Pane.

Query Pane

The SQL query displays in the Query Pane. The Query Pane also
contains menu commands to open a query plan file and to navigate
to the desired query plan when two or more plans are open
concurrently.
Only one query plan can be viewed at a time but multiple plans can
be opened concurrently.

Plan Pane

The Plan Pane contains a graphical representation of the query plan

in a tree form with nodes. At the top of the pane is the main entry
point for executing the query. As you move toward the bottom of the
pane, different query parts are represented.
Different types of nodes appear in the Query Pane depending on the
query. Each node represents a state in the execution of a query in
which something significant happens. For example, nodes represent
selection from a base table, joining the results from two tables into a
single result set, calculating an aggregate value, determining group
break occurrences and combining group results into a single result
set.

E-3

Query Plan Viewer

Nodes
The following table summarizes the nodes.
Table E-2

Plan Pane Nodes

Node Symbol

Node Meaning
Represents data coming from a table in the
database. The name displayed under the
rectangle is the name of the table. If present, the
name shown under the table indicates the index
used to retrieve data from the table. An asterisk to
the right of the index name indicates that the index
contains unique values.
Represents a row selection operation. The word in
parentheses can be either "Normal" or "Range:"

A Normal filter is applied after the row is

returned from the downstream node.

A Range filter appears only directly above a

base table. The Range filter causes a restricted
record retrieval from the table based on an
index value.

Performs a distinct operation. This node normally

appears at the top or close to the top of the plan
tree. Eliminates duplicates from the result set
before returning rows from the query.

Detects group breaks based on a GROUP BY

clause.

Works with Group Break node to assist in correctly

accumulating aggregates for SELECT and
HAVING clauses.

E-4

Graphical User Interface

Table E-2

Plan Pane Nodes continued

Node Symbol

Node Meaning
Performs a JOIN between two nodes. The value in
parentheses indicates the type of JOIN performed:

"Outer" indicates left for right outer join without

any indexes.

"OuterRange" indicates left or right outer join

using an index.

"Normal" indicates a Cartesian join.

"Range" indicates an inner join using an index.

Performs aggregate value accumulation. This

node is used for MIN, MAX, AVG, COUNT, and
SUM, and for these aggregates when the
DISTINCT clause is used with them. The word
inside the node indicates the type of aggregate
being accumulated.
When an aggregate is accumulated in conjunction
with a GROUP BY clause, the aggregate nodes
appear between the group break and group nodes.
Handles accumulating aggregates when no
GROUP BY clause is present.

Handles data retrieval from a single subquery of

the main query. This node never appears when
you view the "root" query plan, only when you view
a subquery.

Handles creation of temporary tables and data

retrieval from temporary tables. References to the
base table under this node are changed to
reference columns of the temporary table.

Processes the UNION and UNION ALL

operations. Cycles through the underlying query
execution plans to retrieve data for the UNION
result set. The Plan Pane displays unions with the
first query as the root query, the second query as
Subquery 1, and so forth.

E-5

Query Plan Viewer

Node Details

If you double-click the following query plan nodes, a pop-up

window appears, showing more detailed information:

Table
Filter
Subquery
Ordered temporary table

Double-clicking the other nodes provides no detailed information

for them.
The following table explains the type of detailed information
displayed:
Node Type

Detailed Information

Table

Name of table

Total rows in table

Estimated number of rows to be read

Range information. Range information is used only when the base table is on
the right side of a JOIN and the retrieval of data from the table can be optimized
through the use of an index. Range information includes:

Column or columns retrieved

Value used to initiate range retrieval (the value normally comes from another
table and column) and the value to terminate retrieval

Initial operations to perform, such as greater than (GT), greater than or equal to
(GE), less than (LT), and so forth

Method of comparison to determine when to stop (GT, GE, and so forth)

Filter (Normal)
Filter (Range)

Subquery
Ordered temp table

Text representation of conditions used to evaluate row.

Information about index used

How filter is reducing set of rows returned

Type of first read from table (GT, GE, and so forth)

Condition that must evaluate to TRUE to stop reading more records (GT, GE,
and so forth)

Type of subquery and optimizations being performed for subquery

List of columns included in the temporary table

Column indication of whether column is used to order rows of the temporary

table (a key) or is a value to pass up the tree

The Plan Pane also contains menu commands to view the plan at
different zoom levels and to display subqueries, if any.

E-6

Query Plan Viewer Tasks

This section discusses the following tasks:

To create a query plan on page E-7

To start Query Plan Viewer on page E-7
To view a query plan on page E-7
To reload a changed query plan on page E-8
To view details of a query plan node on page E-8
To wiew a subquery on a query plan on page E-8

To create a query plan

Execute SET QRYPLAN = on to turn on the creation of a query

plan.

Execute the SET QRYPLANOUTPUT statement and specify the

location and name of the query plan file.
See Query Plan Settings on page E-2.

Execute an SQL SELECT, INSERT, UPDATE, or DELETE

statement (which creates its corresponding query plan).

Execute SET QRYPLAN = off to turn off the creation of query

plans.

To start Query Plan Viewer

Perform one of the following actions:

a. In Pervasive PSQL Control Center, click Tools Query
Plan Viewer.
b. Execute the file w3sqlqpv.exe located in the PSQL\Bin
directory.

To view a query plan

In the Query Pane, click FileOpen.

Navigate to the location of the desired query plan file, click the
file then click Open.

E-7

Query Plan Viewer

Note that the title bar of the Query Pane informs you how many
query plans are open and which plan you are viewing. For
example, if you open three query plans, you might see something
similar to the following:

If you have more than one query plan open, use the View menu
commands to navigate among the plans:

First. Displays the oldest loaded query plan.

Last. Displays the newest loaded query plan.
Next. Displays the next newer query plan.
Prev(ious). Displays the next older query plan.
Goto. Displays the query plan based on the ordinal number
of the loaded plans.

To reload a changed query plan

In the Query Pane, click FileRefresh.
This re-reads the currently loaded query plan file.

To view details of a query plan node

In the Query Pane, double-click one of the following nodes:

Table
Filter
Subquery
Ordered temporary table

See Node Details on page E-4.

To wiew a subquery on a query plan

In the Plan Pane, click Subquery then the number of the
subquery (the first subquery in the main query corresponds to
"Subquery 1," the second subquery corresponds to "Subquery 2"
and so forth).

E-8

Examining Query Plans and Evaluating Query Performance

Query Plan Viewer is particularly useful in the development stage of
a project for you to test your queries and see how the database engine
executes them. You can prepare each of your queries, generate a
query plan file and then examine each plan. Based on the
information for each query, you can add or remove indexes and then
see the affect of the changes. You can also modify the queries to see if
a change in the syntax of the statement affects its performance.

Creating
Example Query
Plans for
Comparison

As an example, you can demonstrate the use of Query Plan Viewer

using the following steps and a few tables from the DEMODATA
database sample database provided with Pervasive PSQL.
For comparison, you will delete an index from the Enrolls table,
execute a query and create a query plan file, add the index back to
Enrolls, then execute the query again and create a comparison query
plan file.
1

In Pervasive PSQL Control Center (PCC), execute the SQL

statements to turn on the creation of a query plan and specify the
following name of the query plan file: example1.qpf. See Query
Plan Settings on page E-2.

In PCC, execute the following query for the DEMODATA

database:
DROP INDEX Enrolls.ClassID

Since DEMODATA is optimized when installed, you need to

drop the index from the Class_ID column of the Enrolls table.
3

In PCC, execute the following query for the DEMODATA

database:
SELECT Student.ID, Class.Name, Course.Credit_Hours
FROM Student, Enrolls, Class, Course WHERE
Student.ID = Enrolls.Student_Id AND
Enrolls.Class_ID = Class.ID AND Class.Name =
Course.Name

This query retrieves all enrolled students, the classes in which

they are enrolled, and the credit hours for each course.
4

In PCC, specify the following name of the query plan file:

example2.qpf. See Query Plan Settings on page E-2.

E-9

Query Plan Viewer

In PCC, execute the following query for the DEMODATA

database:
CREATE INDEX ClassID ON Enrolls(Class_ID)

In PCC, execute the following query for the DEMODATA

database:
SELECT Student.ID, Class.Name, Course.Credit_Hours
FROM Student, Enrolls, Class, Course WHERE
Student.ID = Enrolls.Student_Id AND
Enrolls.Class_ID = Class.ID AND Class.Name =
Course.Name

Notice that the query runs faster.

Viewing the
Example Query
Plans

In Query Plan Viewer, open example1.qpf (through FileOpen).

You should see something similar to the following:

Now, for comparison, open example2.qpf in Query Plan Viewer. You

should see something similar to the following:

E-10

Examining Query Plans and Evaluating Query Performance

Note the following about this plan:

Records are scanned from the Course table.

Records are retrieved from the Class table based on the
Course.Name value using the Class.Name index.
Records are retrieved from the Enrolls table based on the
Class.ID value scanning through the Enrolls table.
Records are retrieved from the Student table based on the
Enrolls.Student_Id using the Student.ID index.
The selection of data from Enrolls uses the newly created index,
ClassID.

In a similar manner to this example, you can compare your own

queries to determine which syntax and structure is right for your
needs.

E-11

Query Plan Viewer

E-12

Index
Symbols
@@IDENTITY global variable 3-290
Example of 3-290
@@ROWCOUNT global variable 3-292
Example of 3-292
@@SESSIONID global variable 3-292
Example of 3-292
@@SPID global variable 3-293
Example of 3-293

A
ABS 5-6
ACOS 5-6
ADD 3-3
grammar supported 3-3
Aggregate functions
AVG 3-204
COUNT 3-204
MAX 3-204
MIN 3-204
SUM 3-204
DECIMAL precision and 3-207
ALL 3-4
grammar supported 3-4
ALTER (rename) 3-5
ALTER GROUP 3-8
ALTER TABLE 3-10
grammar supported 3-10
IN DICTIONARY keyword 3-12
use with COBOL D-3
USING keyword 3-14
WITH REPLACE keyword 3-16
ALTER USER 3-26
Alternate collating sequence
setting a default for SQL session 3-237
alter-option (grammar element defined) 3-10, 3-281
alter-option-list1 (grammar element defined) 3-10,
3-281
alter-option-list2 (grammar element defined) 3-10,
3-281

alter-options (grammar element defined) 3-10, 3281

AND bitwise operator 4-3
ANDed predicate
maximum in SQL statement 2-4
ANSI
character translation 3-304
ANY 3-28
grammar supported 3-28
API functions
ODBC supported 2-9
Approximate-numeric-literal
grammar supported 3-215
Arguments
number in a parameter list for stored procedures
2-3, 3-70
AS 3-29
grammar supported 3-29
ASCII 5-2
ASIN 5-6
as-or-semicolon SQL grammar element definition
3-281
ATAN 5-6
ATAN2 5-6
BEGIN 3-31
SQL
BEGIN 3-31
ATTRIB.DDF C-3
attributes ignored by Pervasive PSQL C-4, C-19
AUTOINC data type A-2
AUTOINC(4) data type A-2
AUTOINCREMENT data type A-22
AVG aggregate function 3-204

B
before-or-after (grammar element defined) 3-103
before-or-after SQL grammar element definition 3281
BEGIN
grammar supported 3-31

Index 1

Between-predicate
grammar supported 3-215
BFLOAT data type A-2, A-25
BFLOAT4 data type A-2
BFLOAT8 data type A-2
BIGINT data type A-3
BINARY data type A-3
0-padded if odd digits 3-298
default value not supported 3-168
notes about A-11
SELECT and 3-298
Binary Large Objects A-26
BIT data type A-4
BIT_LENGTH 5-2
Bitwise operators
See Operators
BLOB data type A-2, A-26
default value not supported 3-168
Bound databases
IN DICTIONARY not permitted 3-13, 3-63
Btrieve owner names See Owner names
Btrieve temporary file 3-295

C
Cache
cached_procedures setting 3-231
excluding stored procedures with DDL 3-233, 3247
excluding stored procedures with EXEC 3-233, 3247
excluding stored procedures with temporary
tables 3-233, 3-247
exclusions to caching stored procedures 3-233, 3247
procedures_cache setting 3-245
stored procedures 3-231, 3-245
Cached_procedures setting 3-231
Caching
cached_procedures setting 3-231
excluding stored procedures with DDL 3-233, 3247
excluding stored procedures with EXEC 3-233, 3247
excluding stored procedures with temporary
tables 3-233, 3-247

2 Index

exclusions to caching stored procedures 3-233, 3247

procedures_cache setting 3-245
stored procedures 3-231, 3-245
CALL 3-32
calling a stored procedure 3-78
grammar supported 3-32
call-arguments SQL grammar element definition 3281
CASCADE 3-33
grammar supported 3-33
ON DELETE 3-84
CASE
grammar supported 3-39
CASE (expression) 3-34
CASE (grammar element defined) 3-34
CASE (string) 3-39
case_value_expression (grammar element defined)
3-204
CAST 5-21
CB001 D-11
CB002 D-11
CB003 D-11
CB004 D-11
CB005 D-11
CB006 D-11
CB007 D-11
CB008 D-11
CB009 D-11
CB010 D-11
CB012 D-11
CB013 D-11
CB014 D-11
CB016 D-11
CB017 D-11
CB018 D-11
CB019 D-11
CB022 D-11
CB023 D-11
CB024 D-11
CB025 D-11
CB028 D-11
CB029 D-11
CB050 D-12
CB051 D-12
CB052 D-12

CB057 D-12
CB099 D-12
CB100 D-12
CB101 D-12
CB102 D-12
CB103 D-12
CB105 D-12
CB106 D-12
CB108 D-12
CB109 D-12
CB110 D-12
CEILING 5-6
Changing
System Tables C-2
CHAR 5-2
CHAR column size 2-3
CHAR data type A-3
notes about A-11
CHAR_LENGTH 5-2
Character
escape for wildcard characters 3-181
translation
OEM to ANSI 3-304
CHARACTER_LENGTH 5-2
CLOB data type A-2, A-26
default value not supported 3-168
CLOSE 3-40
grammar supported 3-40
Closing
open tables 3-299
COALESCE 3-41, 5-17
grammar supported 3-41
COALESCE ( (grammar element defined) 3-41
COBOL
DBCobolNumeric setting A-31
Schema Executor D-4
example usage D-9
executing sample XML file D-13
log messages D-10
sign value for positive NUMERIC data types A31
SQL access for applications D-8
SQL enhanced access
components D-4
Schema Executor D-4
using D-6

use of ALTER TABLE statement D-3

use of CREATE INDEX D-3
use of CREATE INDEX IN DICTIONARY D-3
use of CREATE TRIGGER D-3
use of DELETE D-3
use of DROP TABLE D-3
use of INSERT INTO D-3
use of UPDATE D-3
Codes
data type A-22
col-constraint (grammar element defined) 3-81, 394
col-constraint SQL grammar element definition 3281
Collate
setting a default for SQL session 3-237
Collating
setting a default for SQL session 3-237
collation-name (grammar element defined) 3-82, 394
collation-name SQL grammar element definition 3281
Column
attributes
system table (X$Attrib) C-4, C-19
definitions
changing 3-10
creating 3-80
maximum
name length 2-3
number 2-3
number allowed in a trigger 2-3
number in a select list 2-5
number in a table 2-3
size of 2-3
system table (X$Field) C-6, C-21
column-constraint (grammar element defined) 381, 3-94
column-constraint SQL grammar element definition
3-281
column-definition (grammar element defined) 380, 3-93
column-definition SQL grammar element definition
3-281
column-name (grammar element defined) 3-80, 393

Index 3

column-name SQL grammar element definition 3281

Columns
number allowed in a trigger 3-70
Comma
as decimal separator
data display 3-228, 3-235
data entry 3-300
COMMIT 3-44
grammar supported 3-44
commit-statement SQL grammar element definition
3-281
comparison-operator (grammar element defined) 3203
comparison-operator SQL grammar element
definition 3-281
Compressing data files 3-87
Compressing pages 3-87
CONCAT 5-2
Concurrency 3-300
Connection
maximum number of connections 2-3
Connection strings
DSN 2-7
TRANSLATIONDLL 3-304
Constant values, expressing
date 3-296
string 3-296
time 3-297
timestamp 3-297
constraint-name (grammar element defined) 3-81,
3-94
constraint-name SQL grammar element definition
3-282
CONVERT 5-20, 5-21
truncating DATETIME milliseconds 5-22
Converting
data to other types 5-20
Converting metadata 2-2
Correlated subquery 3-208, 3-270
Correlation-name
grammar supported 3-215
correlation-name SQL grammar element definition
3-282
COS 5-6
COT 5-6

4 Index

COUNT aggregate function 3-204

COUNT( ), COUNT(*) functions
differences 3-71, 3-160
CREAT VIEW
ORDER BY clause 3-109
CREATE (temporary) TABLE 3-93
CREATE DATABASE 3-46
grammar supported 3-46
CREATE FUNCTION 3-51
grammar supported 3-51
CREATE GROUP 3-58
grammar supported 3-58
CREATE INDEX 3-59
grammar supported 3-59
limitations 3-59
use with COBOL D-3
CREATE INDEX IN DICTIONARY
use with COBOL D-3
CREATE PROCEDURE 3-66
grammar supported 3-66
CREATE TABLE 3-80
and temporary tables 3-93
grammar supported 3-80
IN DICTIONARY keyword 3-84
page compression 3-87
page size 3-87
record compression 3-87
USING keyword 3-84
WITH REPLACE keyword 3-86
CREATE TABLE syntax
and temporary tables 3-93
CREATE TRIGGER 3-103
grammar supported 3-103
use with COBOL D-3
CREATE USER 3-106
grammar supported 3-106
Create user
using CREATE USER 3-106
using GRANT LOGIN 3-149
CREATE VIEW 3-108
grammar supported 3-108

Creating
groups 1-11
stored procedures 3-78
tables with legacy null support 3-259
user-defined functions 1-5
users and groups 3-152
views 1-9
CURDATE 5-9
CURRENCY data type A-2, A-27
Current Date
adding to an INSERT statement 3-167, 3-169
Current Time
adding to an INSERT statement 3-167, 3-169
CURRENT_DATE 5-9
CURRENT_TIME 5-9
CURRENT_TIME() 3-252
CURRENT_TIMESTAMP 5-9
Cursor
how to loop through 3-77
limits 3-79
type changed by TOP 3-223
cursor-name SQL grammar element definition 3282
CURTIME 5-9
CURTIME() 3-252

D
Data
long, inserting or updating 3-168
Data control statements 1-10
Data definition language
see DDL
Data definition statements 1-3
Data dictionaries
list of system tables C-2
Data files
binary compatible cross-platform 3-15, 3-85
replacing existing 3-16, 3-86
system table (X$File) C-8, C-23
Data manipulation
statements 1-5
Data Source Names
connection string keywords 2-7
clients 2-7
engine 2-8
Data type

AUTOINC A-2
AUTOINC(4) A-2
BFLOAT A-2
BFLOAT4 A-2
BFLOAT8 A-2
BIGINT A-3
BINARY A-3
BIT A-4
BLOB A-2
CHAR A-3
CLOB A-2
CURRENCY A-2
DATE A-2
DATETIME A-2
DECIMAL A-2
DOUBLE A-2
FLOAT(4) A-2
FLOAT(8) A-2
GUID A-2, A-29
IDENTITY A-2
INTEGER A-3
INTEGER(1) A-2
INTEGER(2) A-2
INTEGER(4) A-3
INTEGER(8) A-3
LONGVARBINARY A-2
LONGVARCHAR A-2
NUMERIC A-3
NUMERICSA A-3
NUMERICSTS A-3
REAL A-2
SMALLIDENTITY A-2
SMALLINT A-2
SQL_BINARY(-2) A-3
SQL_BIT(-7) A-4
SQL_CHAR(1) A-3
SQL_DATE(9) A-2
SQL_DECIMAL(3) A-2, A-3
SQL_DOUBLE(8) A-2
SQL_GUID(-11) A-2
SQL_INTEGER(4) A-2, A-3
SQL_LONGVARBINARY(-4) A-2
SQL_LONGVARCHAR(-1) A-2
SQL_NUMERIC(2) A-3
SQL_REAL(7) A-2
SQL_SMALLINT(5) A-2, A-3, A-4

Index 5

SQL_TIME(10) A-3
SQL_TIMESTAMP(11) A-3
SQL_TINYINT(-6) A-2, A-3
SQL_VARCHAR(12) A-4
STRING A-3
TIME A-3
TIMESTAMP A-3
TINYINT A-2
UBIGINT A-3
UINTEGER A-3
UNIQUEIDENTIFIER 3-118, 5-16, A-2, A-17
UNSIGNED(1) BINARY A-3
UNSIGNED(2) BINARY A-3
UNSIGNED(4) BINARY A-3
UNSIGNED(8) BINARY A-3
USMALLINT A-3
UTINYINT A-3
VARCHAR A-4
WSTRING A-3
WSZSTRING A-3
ZSTRING A-4
Data types
AUTOINCREMENT A-22
BFLOAT A-25
BLOB A-26
CLOB A-26
codes A-22
conversion A-2
converting to other types 5-20
CURRENCY A-27
DATE A-27
DECIMAL A-28
extended A-22
FLOAT A-28
INTEGER A-30
lengths and ranges A-5
limitations in stored procedures 3-70
limitations in triggers 3-104
limitations in user-defined functions 3-52
LOGICAL A-30
LSTRING A-30
MONEY A-31
not supported by relational interface A-4
NUMERIC A-31
NUMERICSA A-33
NUMERICSTS A-34

6 Index

REAL A-34
STRING A-26
supported A-2
that cannot be indexed 3-61
TIME A-34
TIMESTAMP A-35
UNSIGNED BINARY A-37
WSTRING A-37
WZSTRING A-37
ZSTRING A-37
DATABASE 5-16
Database
in which temporary tables are stored 3-97
object name
fully qualified restriction 2-6
Databases
joining multiple 3-219
data-type (grammar element defined) 3-80, 3-93
data-type SQL grammar element definition 3-282
data-type-name SQL grammar element definition 3282
Date
adding in INSERT statements 3-167
format supported 3-216, 3-296
functions supported 5-9
inserting current 3-167, 5-9
inserting or updating column values 3-216, 3296
literal format 3-216, 3-296
literal values 3-296
TIMESTAMP data type
why not to use A-36
Date arithmetic
grammar supported 3-218, 3-298
DATE data type A-2, A-27
DATEADD scalar function 5-10
DATEDIFF scalar function 5-11
Date-literal
grammar supported 3-216
DATENAME scalar function 5-12
DATEPART scalar function 5-12
DATETIME
truncating milliseconds with CONVERT 5-22
DATETIME data type A-2
Daylight savings, see Time
DAYNAME 5-13

DAYOFMONTH 5-13
DAYOFYEAR 5-13
DBCobolNumeric setting A-31
db-name SQL grammar element definition 3-282
DCOMPRESS 3-87
DDFs
changing data definitions without affecting data
files 3-63
DDL 1-3
creating index 1-4
creating stored procedure 1-4
creating table 1-3
creating trigger 1-4
creating user-defined function 1-5
creating view 1-4
deleting index 1-4
deleting stored procedure 1-4
deleting table 1-3
deleting trigger 1-4
deleting user-defined function 1-5
deleting view 1-4
exclusion to caching stored procedure 3-233, 3247
modifying table 1-3
DECIMAL data type A-2, A-28
precision of SUM() function result 3-207
Decimal separator
comma
display only 3-228, 3-235
comma as 3-228, 3-235, 3-300
DECLARE 3-113
grammar supported 3-113
DECLARE CURSOR 3-114
grammar supported 3-114
DEFAULT 3-116, 3-166
example of use in CREATE TABLE 3-87, 3-88
in UPDATE 3-269, 3-273
Default collating setting 3-237
Default values, see Values, default
default-value-expression (grammar element
defined) 3-80, 3-93
Definitions
index
Btrieve indexes and 3-14, 3-59, 3-86
DEGREES 5-6
DELETE 3-125

grammar supported 3-123, 3-125

use with COBOL D-3
Delete
rule 3-84
cascade 3-84
restrict 3-84
DELETE (positioned) 3-123
Deleting
view 1-9
Delimited identifier
in SQL Statements 2-19
Delimiter
for identifiers in SQL statements 2-19
SQL statement in PCC 3-2
DEPEND.DDF C-3
Disabling security 1-10
Disjointed index, definition of 3-64
DISTINCT 3-128, 3-222
grammar supported 3-128
in subquery 3-274
DOUBLE data type A-2
Double quote
matching data that contains a 3-181
Double quotes
delimiter for identifiers in SQL statements 2-19
DROP DATABASE 3-129
DROP FUNCTION 3-131
grammar supported 3-131
DROP GROUP 3-132
DROP INDEX 3-133
grammar supported 3-133
DROP PROCEDURE 3-135
grammar supported 3-135
DROP TABLE 3-136
grammar supported 3-136
IN DICTIONARY keyword 3-136
use with COBOL D-3
DROP TRIGGER 3-137
grammar supported 3-137
DROP USER 3-138
DROP VIEW 3-139
grammar supported 3-139
DSN
connection strings 2-7

Index 7

Dynamic cursors
SET ROWCOUNT and 3-249
type changed by TOP 3-223

E
Enabling
security 1-10
END 3-140
grammar supported 3-140
Escape character 3-181
Exact-numeric-literal
grammar supported 3-216
Exceptions
to ODBC API support
SQLGetData 2-12
SQLGetInfo 2-12
SQLGetTypeInfo 2-12
SQLSpecialColumns 2-12
Exclusive OR bitwise operator 4-8
EXEC
exclusion to caching stored procedure 3-233, 3247
EXECUTE 3-141
exclusion to caching stored procedure 3-233, 3247
EXISTS 3-143
grammar supported 3-143
EXP 5-6
Expression
in stored procedures 3-289
subquery on left side of 3-208
expression (grammar element defined) 3-203
expression-or-subquery (grammar element defined)
3-203
expression-or-subquery SQL grammar element
definition 3-282
Expressions as Default Values for Date-Time
Columns 3-121
Supported Data Types and Constraints 3-119
Usage Context 3-122
Extended data types A-22
EXTRACT 5-13

F
FETCH 3-145
grammar supported 3-145

8 Index

fetch-orientation (grammar element defined) 3-68

fetch-orientation SQL grammar element definition
3-282
FIELD.DDF C-3
Field.ddf C-3
File
query plan output E-2
File.ddf
FILE.DDF C-3
Files
location of temporary 3-294
temporary 3-295
FLOAT data type A-28
FLOAT(4) data type A-2
FLOAT(8) data type A-2
FLOOR 5-6
FOREIGN KEY 3-147
cannot ALTER column 3-17
grammar supported 3-147
Format
literal values
date 3-296
string 3-296
time 3-297
timestamp 3-297
Formats, literal
date 3-216, 3-296
string 3-296
time 3-217, 3-297
timestamp 3-217, 3-297
Functions
aggregate
AVG 3-204
COUNT 3-204
MAX 3-204
MIN 3-204
SUM 3-204, 3-207
conversion 5-20
date 5-9
inserting value 5-9
DATEADD 5-10
DATEDIFF 5-11
DATENAME 5-12
DATEPART 5-12
logical 5-17
numeric 5-6

string 5-2
system 5-16
time
inserting current 5-9
inserting value 5-9

G
Global variables 3-290
@@IDENTITY 3-290
@@ROWCOUNT 3-292
@@SESSIONID 3-292
@@SPID 3-293
Grammar Element Definitions 3-281
Grammar element definitions
alter-option 3-10, 3-281
alter-option-list1 3-10, 3-281
alter-option-list2 3-10, 3-281
alter-options 3-10, 3-281
before-or-after 3-103
CASE 3-34
case_value_expression 3-204
COALESCE ( 3-41
col-constraint 3-81, 3-94
collation-name 3-82, 3-94
column-constraint 3-81, 3-94
column-definition 3-80, 3-93
column-name 3-80, 3-93
comparison-operator 3-203
constraint-name 3-81, 3-94
data-type 3-80, 3-93
default-value-expression 3-80, 3-93
expression 3-201, 3-203
expression-or-subquery 3-203
fetch-orientation 3-68
ins-upd-del 3-103
join-definition 3-203
join-type 3-203
literal 3-81, 3-94
order-by-expression 3-108, 3-202
outer-join-definition 3-202
outer-join-type 3-202
parameter 3-66
parameter-type 3-66
parameter-type-name 3-66
predicate 3-203
procedure-name 3-66

proc-expr 3-66
proc-search-condition 3-68
proc-stmt 3-66
query-specification 3-202
referencing-alias 3-103
referential-actions 3-81, 3-94
referential-delete-action 3-81, 3-94
referential-update-action 3-81, 3-94
scalar-function 3-204
search-condition 3-203
select-item 3-202
select-list 3-201, 3-202
set-function 3-204
sqlstate-value 3-68
subquery-expression 3-204
table-constraint 3-81, 3-94
table-constraint-definition 3-81, 3-94
table-element 3-80, 3-93
table-name 3-80, 3-93
table-reference 3-201, 3-202
top-clause 3-202
transaction-statement 3-67
trigger-name 3-103
value 3-203
values-clause 3-166
view-name 3-108
GRANT 3-149
creating a user with GRANT LOGIN 3-149
grammar supported 3-149
Granting
rights 1-11
Greater than (>) operator 3-202
Group
creating a 1-11
GROUP BY 3-160
grammar supported 3-160
with a HAVING clause 3-162
group-name SQL grammar element definition 3282
GUID data type A-2, A-29

H
HAVING 3-162
in a GROUP BY expression 3-162
HOUR 5-13

Index 9

I
Identifiers
delimited in SQL statements 2-19
IDENTITY data type A-2
IDENTITY global variable. See @@IDENTITY
IF 3-163, 5-17
grammar supported 3-163
nesting limit 3-163
IF (with SELECT)
grammar supported 3-218
IFNULL 5-17
IN 3-165
grammar supported 3-165
IN DICTIONARY keyword 3-12, 3-63, 3-84, 3-136
not permitted on bound databases 3-13, 3-63
Index
creating 1-4
data types that cannot be indexed 3-61
definitions, SQL
Btrieve indexes and 3-14, 3-59, 3-86
disjointed, definition of 3-64
dropping named 1-4
maximum indexed nullable columns 3-59
name
maximum length of 2-4
optimizations 7-12
Index.ddf 3-64
INDEX.DDF C-3
index-definition SQL grammar element definition
3-282
Indexes
existing Btrieve and relational definitions 3-14, 359, 3-86
existing used when possible 3-14, 3-59, 3-86
partial 3-61, 3-186
system tables
X$Field C-6, C-21
X$Index C-9, C-24
index-name SQL grammar element definition 3202, 3-283
index-segment-definition SQL grammar element
definition 3-282
Infinity
representation A-19
In-memory temporary file 3-295
In-predicate

10 Index

grammar supported 3-216

INSERT 3-166
default values and 3-166
grammar supported 3-166
INSERT INTO
use with COBOL D-3
Inserting
current time, current date and timestamp 3-167,
3-169, 5-9
insert-values SQL grammar element definition 3283
ins-upd-del (grammar element defined) 3-103
ins-upd-del SQL grammar element definition 3-283
INTEGER data type A-3, A-30
INTEGER(1) data type A-2
INTEGER(2) data type A-2
INTEGER(4) data type A-3
INTEGER(8) data type A-3
Invalid row-count in subquery
returned if SELECT within UPDATE returns
multiple rows 3-271
ISNULL 5-17

J
JOIN 3-173
grammar supported 3-173
Join
Cartesian 3-221
cross-database 3-219
LEFT OUTER 3-220
maximum tables in a 2-5
multi-database 3-219
RIGHT OUTER 3-220
TOP clause in a 3-223
two-way LEFT OUTER JOIN 3-175
join type (grammar element defined) 3-203
join-definition (grammar element defined) 3-203
join-definition SQL grammar element definition 3283

L
label-name SQL grammar element definition 3-283
LCASE 5-2
LEAVE 3-180
grammar supported 3-180
LEFT 5-2

LEFT OUTER JOIN

and vendor strings 3-174
syntax 3-173
LENGTH 5-2
Length
maximum for column name 2-3
of path name in USING 3-14, 3-85
Less than (<) operator 3-202
LIKE 3-181
syntax and usage 3-181
LIKE predicates
on LONGVARBINARY A-12
on LONGVARCHAR A-12
Limitations
columns, number of 2-3
of LONGVARBINARY A-12
of LONGVARBINARY in INSERT statements A12
of LONGVARCHAR A-12
of LONGVARCHAR in INSERT statements A12
of LONGVARCHAR in UNION statements 3266
Limits
cursors 3-79
maximum ANDed predicates in SQL statement
2-4
maximum size of quoted string in SQL statement
2-5
relational interface 2-2
SQL variables and parameters 3-79
stored procedures 3-78
arguments in a parameter list 2-3, 3-70
procedure name 3-78
size 2-5, 3-70
variable name 3-78
triggers
number of columns 2-3, 3-70
when using long data 3-79
literal (grammar element defined) 3-81, 3-94
literal SQL grammar element definition 3-283
Literal values
date 3-296
string 3-296
entering data longer than max 3-168
time 3-297

timestamp 3-297
Locale
setting time zone 3-252
Locale-specific behavior
comma as decimal separator
data display 3-228, 3-235
data entry 3-300
LOCATE 5-3
LOG 5-6
LOG10 5-7
LOGICAL data type A-30
Logical functions supported 5-17
Long data
inserting or updating 3-168
limits when using 3-79
LONGVARBINARY
limitation A-12
limitations in INSERT statements A-12
notes about A-11
using SQLGetData A-12
LONGVARBINARY data type A-2
LONGVARCHAR
limitations A-12
limitations in INSERT statements A-12
limitations in UNION statements 3-266
notes about A-11
using SQLGetData A-12
LONGVARCHAR data type A-2
LOOP 3-183
grammar supported 3-183
LSTRING data type A-30
LTRIM 5-3

M
Master user 3-152
MAX aggregate function 3-204
Maximum
column name length 2-3
length of view name 3-108
Metadata
conversion utility 2-2
Schema Executor D-8
system tables for version 2 C-2
version 2 2-2
versions of 2-2

Index 11

Milliseconds
truncating from DATETIME 5-22
MIN aggregate function 3-204
MINUTE 5-13
MOD 5-7
Modifying
data
statements for 1-8
MONEY data type A-31
MONTH 5-13
MONTHNAME 5-13

N
Name
fully qualified name of database object 2-6
Named databases
and file names 3-14, 3-84
Names
maximum length 2-3
Nesting limits
IF 3-163
NEWID scalar function 5-16
Nodes
used in query plan viewer E-4
Non-correlated subquery 3-270
Non-trusted objects 3-153
NOT 3-184
grammar supported 3-184
NOT bitwise operator 4-5
NOT NULL
default values and 3-167
NOW 5-14
NULL 5-17
attempted insert into NOT NULL column with
default value 3-167
cannot make column nullable 3-17
inserted by UPDATE if subquery returns no rows
3-270
Null
support
creating tables with legacy 3-259
setting for table creation 3-258, 3-259
Nullable columns
default value for 3-167
maximum number of indexed 3-59
NULLIF 5-17

12 Index

NUMERIC data type A-3, A-31

sign value for positive data type A-31
Numeric functions supported 5-6
NUMERICSA data type A-3, A-33
NUMERICSTS data type A-3, A-34

O
Object name
fully qualified restriction 2-6
Occurs DDF C-3
Occurs.DDF C-3
OCTET_LENGTH 5-3
ODBC
API
exceptions 2-12
support 2-9
security 3-152
Support 2-9
Attribute 2-14
Descriptor Field 2-15
Interface 2-9
support 2-9
supported APIs 2-9
ODBC API
functions
supported 2-9
OEM to ANSI
character translation 3-304
connection string 3-304
ON DELETE 3-84
ON UPDATE 3-84
On-disk temporary file 3-295
ONLY
grammar supported 3-185
OPEN 3-185
Operators
bitwise 4-2
bitwise AND (&) 4-3
bitwise Exclusive OR (^) 4-8
bitwise NOT (~) 4-5
bitwise OR (|) 4-6
truth table for bitwise operations 4-9
greater than 3-202
less than 3-202

Optimizations
index usage 7-12
restriction 7-4
SQL Relational Database Engine 7-1
subquery on left side of expression 3-208
Optimizing queries E-1
OR bitwise operator 4-6
ORDER BY 3-109
in view 3-109
SET ROWCOUNT and 3-249
TOP and 3-223
order-by-expression (grammar element defined) 3108, 3-202
order-by-expression SQL grammar element
definition 3-283
outer-join-definition (grammar element defined) 3202
outer-join-definition SQL grammar element
definition 3-283
outer-join-type (grammar element defined) 3-202
outer-join-type SQL grammar element definition 3283
Owner names 3-153
in secured databases 1-10
specifying in SQL 3-240

P
Padding
in BINARY columns A-11
in CHAR columns A-11
in LONGVARBINARY columns A-11
in LONGVARCHAR columns A-11
in VARCHAR columns A-11
Page
compression 3-87
sizes
specifying with SQL 3-87
Page compression
with CREATE TABLE statement 3-87
PAGESIZE 3-87
parameter (grammar element defined) 3-66
Parameter List
number of arguments for stored procedures 2-3,
3-70
parameter SQL grammar element definition 3-283

parameter-name SQL grammar element definition

3-283
parameter-type (grammar element defined) 3-66
parameter-type SQL grammar element definition 3283
parameter-type-name (grammar element defined)
3-66
parameter-type-name SQL grammar element
definition 3-283
PARTIAL 3-186
grammar supported 3-186
Partial indexes 3-61, 3-186
Password
for Master user 3-152
restrictions 3-26
used a table or column name 3-243
password SQL grammar element definition 3-283
Path
length for data files 2-3
Path name
length in USING 3-14, 3-85
Pattern matching
with LIKE 3-181
PCOMPRESS 3-87
Performance
SQL Relational Database Engine 7-1
temporary tables 7-15
Permissions
on stored procedures 3-153
on views 3-153
Permissions. See Rights
Pervasive Control Center
OEM characters and 3-304
Pervasive ODBC Engine interface
data types supported A-2
SQL support 2-17
PI 5-7
Plan pane
query plan viewer E-3
Plans
query E-1
POSITION 5-3
positional-argument SQL grammar element
definition 3-283
POWER 5-7

Index 13

Precedence
TOP vs. SET ROWCOUNT 3-223, 3-249
Precision
SUM result on DECIMAL data 3-207
precision SQL grammar element definition 3-283
Predicate
in stored procedures 3-288
predicate (grammar element defined) 3-203
predicate SQL grammar element definition 3-284
PRIMARY KEY 3-187
cannot ALTER column 3-17
grammar supported 3-187
PRINT 3-189
grammar supported 3-189
PROC.DDF C-3
Procedure
cached_procedures setting 3-231
caching of stored procedure 3-231, 3-245
exclusions to caching of stored procedure 3-233,
3-247
procedures_cache setting 3-245
procedure-name (grammar element defined) 3-66
procedure-name SQL grammar element definition
3-285
Procedures
creating 3-78
Procedures_cache setting 3-245
proc-expr (grammar element defined) 3-66
proc-expr SQL grammar element definition 3-284
proc-search-condition (grammar element defined)
3-68
proc-search-condition SQL grammar element
definition 3-284
proc-stmt (grammar element defined) 3-66
proc-stmt SQL grammar element definition 3-284
psp_column_attributes 6-6
psp_column_rights 6-9
psp_columns 6-3
psp_fkeys 6-13
psp_groups 6-15
psp_help_sp 6-17
psp_help_trigger 6-19
psp_help_udf 6-21
psp_help_view 6-23
psp_indexes 6-25
psp_pkeys 6-28

14 Index

psp_stored_procedures 6-33
psp_table_rights 6-39
psp_tables 6-36
psp_triggers 6-41
psp_udfs 6-43
psp_users 6-45
psp_view_rights 6-29, 6-47
psp_views 6-50
PUBLIC 3-190
grammar supported 3-190
public-or-user-group-name SQL grammar element
definition 3-285
Push down filter
See table filter
PVATTRIB.DDF C-3
PVDEPEND.DDF C-3
PVFIELD.DDF C-3
PVFILE.DDF C-3
PVINDEX.DDF C-3
PVPROC.DDF C-3
PVRELATE.DDF C-3
PVRIGHTS.DDF C-3
PVTRIG.DDF C-3
PVUSER.DDF C-3
PVVIEW.DDF C-3

Q
QUARTER 5-14
Queries
examining query plans E-1
optimizing E-1
settings for query plans E-2
Query
examining query plans E-1
optimizing E-1
Query pane
query plan viewer E-3
Query plan
nodes in query plan viewer E-4
outputfile E-2
settings for E-2
Query plan viewer E-1
how to start E-7
nodes E-4
panes E-3
settings E-2

Query plans E-1

query-specification (grammar element defined) 3202
query-specification SQL grammar element
definition 3-285
Quotation mark, representing single 2-4
Quoted string in SQL statement
maximum size 2-5
Quotes
matching data that contains 3-181

R
RADIANS 5-7
RAND 5-7
Ranges
data types A-5
REAL data type A-2, A-34
Real Infinity
representation A-19
Record
compression 3-87
referencing-alias (grammar element defined) 3-103
referencing-alias SQL grammar element definition
3-285
Referential integrity
delete rules 3-84
update rules 3-84
X$Relate system table C-12, C-28
referential-actions (grammar element defined) 3-81,
3-94
referential-actions SQL grammar element definition
3-286
referential-delete-action (grammar element defined)
3-81, 3-94
referential-delete-action SQL grammar element
definition 3-286
referential-update-action (grammar element
defined) 3-81, 3-94
referential-update-action SQL grammar element
definition 3-286
Regional settings
comma as decimal separator
data display 3-228, 3-235
data entry 3-300
RELATE.DDF C-3
Relational index definitions

Btrieve indexes and 3-14, 3-59, 3-86

Relational interface
data types not supported A-4
limits 2-2
object sizes 2-2
Relational security 3-152
RELEASE SAVEPOINT 3-191
grammar supported 3-191
release-statement SQL grammar element definition
3-286
REPLACE 5-3
Replacing data files 3-16, 3-86
REPLICATE 5-3
Replication
SET TIME ZONE and 3-252
Reserved words B-1
~See also Words to avoid
ABORT B-2
ACCELERATED B-2
ADD B-2
AFTER B-2
ALL B-2
ALTER B-2
AND B-2
ANY B-2
AS B-2
ASC B-2
ATOMIC B-2
AVG B-2
BEFORE B-2
BEGIN/BEGINS B-2
BETWEEN B-2
BORDER B-2
BY B-2
CALL B-2
CASCADE B-2
CASE B-2
CAST B-2
CHECk B-2
CLOSE B-2
COALESCE B-2
COLLATE B-2
COLUMN B-2
COMMIT B-2
COMMITTED B-2
CONSTRAINT B-2

Index 15

CONVERT B-2
COUNT B-2
CREATE B-2
CREATESP B-2
CREATETAB B-2
CREATEVIEW B-2
CROSS B-2
CS B-2
CURDATE B-2
CURRENT B-2
CURSOR B-2
CURTIME B-2
DATABASE B-3
DCOMPRESS B-3
DDF B-3
DECIMALSEPARATORCOMMA B-3
DECLARE B-3
DEFAULT B-3
DEFAULTCOLLATE B-3
DELETE B-3
DENY B-3
DESC B-3
DIAGNOSTICS B-3
DICTIONARY B-3
DISTINCT B-3
DO B-3
DROP B-3
DSN B-3
EACH B-3
ELSE B-3
END B-3
ENFORCED B-3
EX B-3
EXCLUSIVE B-3
EXEC B-3
EXECUTE B-3
EXISTING B-3
EXISTS B-3
FETCH B-3
FN B-3
FOR B-3
FOREIGN B-3
FROM B-3
FULL B-3
FUNCTION B-3
GRANT B-3

16 Index

GROUP B-3
HANDLER B-3
HAVING B-3
IF B-4
IN B-4
INDEX B-4
INNER B-4
INOUT B-4
INSERT B-4
INTEGRITY B-4
INTERNAL B-4
INTO B-4
IS B-4
ISOLATION B-4
JOIN B-4
KEY B-4
LEAVE B-4
LEFT B-4
LEGACYOWNERNAME B-4
LEVEL B-4
LIKE B-4
LOGIN B-4
LOOP B-4
MAX B-4
MIN B-4
MODE B-4
MODIFIABLE B-4
MODIFY B-4
NEW B-4
NEXT B-4
NO B-4
NORMAL B-4
NOT B-4
NOW B-4
NULL B-4
OF B-5
OFF B-5
OLD B-5
ON B-5
ONLY B-5
OPEN B-5
OR B-5
ORDER B-5
OUT B-5
OUTER B-5
OWNER B-5

PAGESIZE B-5
PARTIAL B-5
PRIMARY B-5
PRINT B-5
PROCEDURE B-5
PUBLIC B-5
READ B-5
REFERENCES B-5
REFERENCING B-5
RELATIONAL B-5
RELEASE B-5
REPEAT B-5
REPEATABLE B-5
REPLACE B-5
RESTRICT B-5
RETURN B-5
RETURNS B-5
REVOKE B-5
RIGHT B-5
ROLLBACK B-5
ROW B-5
ROWCOUNT B-5
SAVEPOINT B-5
SECURITY B-5
SELECT B-5
SERIALIZABLE B-5
SET B-5
SIGNAL B-5
SIZE B-5
SQLSTATE B-5
SSP_EXPR B-5
SSP_PRED B-5
START B-5
SUM B-5
SVBEGIN B-5
SVEND B-5
T B-6
TABLE B-6
THEN B-6
TO B-6
TOP B-6
TRANSACTION B-6
TRIGGER B-6
TRIGGERSTAMPMISC B-6
TRUEBITCREATE B-6
TRUENULLCREATE B-6

TS B-6
UNCOMMITTED B-6
UNION B-6
UNIQUE B-6
UNIQUEIDENTIFER B-6
UNTIL B-6
UPDATE B-6
USER B-6
USING B-6
VALUES B-6
VIEW B-6
WHEN B-6
WHERE B-6
WHILE B-6
WITH B-6
WORK B-6
WRITE B-6
RESTRICT 3-193
grammar supported 3-193
ON DELETE 3-84
result SQL grammar element definition 3-286
Results
returning partial set 3-222, 3-249
Retrieving data
about 1-7
RETURNS
example of in CREATE PROCEDURE 3-73
REVOKE 3-194
grammar supported 3-194
Revoking rights 1-11
RI. See Referential integrity
RIGHT 5-3
Rights
granting 1-11
revoking 1-11
RIGHTS.DDF C-3
ROLLBACK 3-197
ROLLBACK WORK
grammar supported 3-197
rollback-statement SQL grammar element definition
3-286
ROUND 5-7
ROWCOUNT (SET) 3-249
ROWCOUNT global variable. See @@ROWCOUNT

Index 17

Rows
limiting number returned 3-222, 3-249
limits 2-5
Rowset size
specifying 3-249
RTRIM 5-3

S
SAVEPOINT 3-199
grammar supported 3-199
savepoint-name SQL grammar element definition 3286
Scalar functions
ABS 5-6
ACOS 5-6
ASCII 5-2
ASIN 5-6
ATAN 5-6
ATAN2 5-6
BIT_LENGTH 5-2
CAST 5-21
categories
conversion 5-20
date 5-9
numeric 5-6
string 5-2
system 5-16
time 5-9
CEILING 5-6
CHAR 5-2
CHAR_LENGTH 5-2
CHARACTER_LENGTH 5-2
COALESCE 5-17
CONCAT 5-2
CONVERT 5-21
truncating DATETIME milliseconds 5-22
COS 5-6
COT 5-6
CURDATE 5-9
CURRENT_DATE 5-9
CURRENT_TIME 5-9
CURRENT_TIMESTAMP 5-9
CURTIME 5-9
DATABASE 5-16
DATEADD 5-10
DATEDIFF 5-11

18 Index

DATENAME 5-12
DATEPART 5-12
DAYNAME 5-13
DAYOFMONTH 5-13
DAYOFYEAR 5-13
DEGREES 5-6
EXP 5-6
EXTRACT 5-13
FLOOR 5-6
HOUR 5-13
IF 5-17
IFNULL 5-17
ignore fractional seconds in TIMESTAMP A-35
ISNULL 5-17
LCASE or LOWER 5-2
LEFT 5-2
LENGTH 5-2
LOCATE 5-3
LOG 5-6
LOG10 5-7
LTRIM 5-3
MINUTE 5-13
MOD 5-7
MONTH 5-13
MONTHNAME 5-13
NEWID 5-16
NOW 5-14
NULL 5-17
NULLIF 5-17
OCTET_LENGTH 5-3
PI 5-7
POSITION 5-3
POWER 5-7
QUARTER 5-14
RADIANS 5-7
RAND 5-7
REPLACE 5-3
REPLICATE 5-3
RIGHT 5-3
ROUND 5-7
RTRIM 5-3
SECOND 5-14
SIGN 5-7
SIN 5-7
SPACE 5-3
SQRT 5-7

STUFF 5-3
SUBSTRING 5-3
TAN 5-7
TIMESTAMPADD 5-14
TIMESTAMPDIFF 5-14
TRUNCATE 5-7
UCASE or UPPER 5-3
USER 5-16
WEEK 5-14
YEAR 5-14
scalar-function (grammar element defined) 3-204
scalar-function SQL grammar element definition 3286
scale SQL grammar element definition 3-286
Schema Executor D-4, D-8
example usage D-9
executing sample XML file D-13
log messages D-10
table filters used with D-14
SchemaExec
See Schema Executor
search-condition (grammar element defined) 3-203
search-condition SQL grammar element definition
3-286
SECOND 5-14
Secured databases
with Btrieve Owner Names 1-10
Security
enabling and disabling 1-10
owner names 3-153, 3-240
password of Master user 3-152
relational 3-152
SET OWNER 3-240
setting 3-250
system tables
rights (X$Rights) C-13, C-29
users (X$User) C-16, C-33
SELECT 3-202
grammar supported 3-202
maximum number of columns 2-5
TOP clause 3-222
SELECT (with INTO)
grammar supported 3-201
SELECT (with into) 3-201
select-item (grammar element defined) 3-202
select-item SQL grammar element definition 3-286

select-list (grammar element defined) 3-202

select-list SQL grammar element definition 3-286
Separator
comma as decimal
data display 3-228, 3-235
data entry 3-300
SESSIONID global variable. See @@SESSIONID
SET 3-260
SET ANSI_PADDING 3-228
SET CACHED_PROCEDURES 3-231
Set cached_procedures 3-231
SET DECIMALSEPARATORCOMMA 3-228, 3-235
SET DEFAULTCOLLATE 3-237
Set Function
grammar supported in SELECT statements 3216
SET OWNER 3-240
SET PASSWORD 3-242
grammar supported 3-242
SET PROCEDURES_CACHE 3-245
Set procedures_cache 3-245
SET QRYPLAN statement E-2
SET QRYPLANOUTPUT statement E-2
SET ROWCOUNT 3-249
SET SECURITY 3-250
grammar supported 3-250
SET TIME ZONE 3-252
SET TRUEBITCREATE 3-258
SET TRUENULLCREATE 3-259
grammar supported 3-259
SET VARIABLE
grammar supported 3-260
set-function (grammar element defined) 3-204
set-function SQL grammar element definition 3-286
Settings
for query plan viewer E-2
Shift
sign value for positive NUMERIC data types A31
SIGN 5-7
Sign value
for positive NUMERIC data types A-31
SIGNAL 3-261
grammar supported 3-261
SIN 5-7

Index 19

Single quote
matching data that contains a 3-181
Single quote, representing 2-4
Size
of data page, specifying 3-87
of objects for relational interface 2-2
SMALLIDENTITY data type A-2
SMALLINT data type A-2
Sort order in keys
string A-21
SPACE 5-3
Spacing
in BINARY columns A-11
in CHAR columns A-11
in LONGVARBINARY columns A-11
in LONGVARCHAR columns A-11
in VARCHAR columns A-11
Special characters 3-181
SPID global variable. See @@SPID
SQL
ADD 3-3
ALL 3-4
ALTER (rename) 3-5
ALTER GROUP 3-8
ALTER TABLE 3-10
ALTER USER 3-26
ANY 3-28
AS 3-29
CALL 3-32
CASCADE 3-33
CASE (expression) 3-34
CASE (string) 3-39
CLOSE 3-40
COALESCE 3-41
COMMIT 3-44
CREATE (temporary) TABLE 3-93
CREATE DATABASE 3-46
CREATE FUNCTION 3-51
CREATE GROUP 3-58
CREATE INDEX 3-59
CREATE PROCEDURE 3-66
CREATE TABLE 3-80
CREATE TRIGGER 3-103
CREATE USER 3-106
CREATE VIEW 3-108
DECLARE 3-113

20 Index

DECLARE CURSOR 3-114

DEFAULT 3-116
DELETE 3-125
DELETE (positioned) 3-123
description and purpose 1-1
DISTINCT 3-128
DROP DATABASE 3-129
DROP FUNCTION 3-131
DROP GROUP 3-132
DROP INDEX 3-133
DROP PROCEDURE 3-135
DROP TABLE 3-136
DROP TRIGGER 3-137
DROP USER 3-138
DROP VIEW 3-139
END 3-140
enhanced access for COBOL
components D-4
using D-6
EXECUTE 3-141
EXISTS 3-143
extensions to standards B-1
FETCH 3-145
FOREIGN KEY 3-147
Grammar Element Definitions 3-281
GRANT 3-149
GROUP BY 3-160
HAVING 3-162
IF 3-163
IN 3-165
INSERT 3-166
JOIN 3-173
LEAVE 3-180
LIKE 3-181
list of statements 3-288
LOOP 3-183
maximum length of statement 2-5
maximum size of quoted string in statement 2-5
NOT 3-184
OPEN 3-185
ORDER BY 3-109
PARTIAL 3-186
PRIMARY KEY 3-187
PRINT 3-189
PUBLIC 3-190
RELEASE SAVEPOINT 3-191

reserved words B-1

RESTRICT 3-193
REVOKE 3-194
ROLLBACK 3-197
SAVEPOINT 3-199
security 3-152
SELECT 3-202
SELECT (with into) 3-201
SET 3-260
SET ANSI_PADDING 3-228
SET CACHED_PROCEDURES 3-231
SET DECIMALSEPARATORCOMMA 3-235
SET DEFAULTCOLLATE 3-237
SET OWNER 3-240
SET PASSWORD 3-242
SET PROCEDURES_CACHE 3-245
SET ROWCOUNT 3-249
SET SECURITY 3-250
SET TIME ZONE 3-252
SET TRUEBITCREATE 3-258
SET TRUENULLCREATE 3-259
SIGNAL 3-261
SQLSTATE 3-263
START TRANSACTION 3-264
statement delimiter
changing in PCC 3-2
statements
data control 1-10
data definition 1-3
data manipulation 1-5, 1-7
delimited identifiers 2-19
types of 1-1
system tables. See System tables
UNION 3-266
UNIQUE 3-268
UPDATE 3-269
UPDATE (positioned) 3-277
use of statements with COBOL data constructs
D-3
USER 3-279
variables
limits 3-79
parameters 3-79
WHILE 3-280
SQL Editor
OEM characters and 3-304

SQL grammar element definition

as-or-semicolon 3-281
before-or-after 3-281
call-arguments 3-281
col-constraint 3-281
collation-name 3-281
column-constraint 3-281
column-definition 3-281
column-name 3-281
commit-statement 3-281
comparison-operator 3-281
constraint-name 3-282
correlation-name 3-282
cursor-name 3-282
data-type 3-282
data-type-name 3-282
db-name 3-282
expression-or-subquery 3-282
fetch-orientation 3-282
group-name 3-282
index-definition 3-282
index-name 3-202, 3-283
index-segment-definition 3-282
insert-values 3-283
ins-upd-del 3-283
join-definition 3-283
label-name 3-283
literal 3-283
order-by-expression 3-283
outer-join-definition 3-283
outer-join-type 3-283
parameter 3-283
parameter-name 3-283
parameter-type 3-283
parameter-type-name 3-283
password 3-283
positional-argument 3-283
precision 3-283
predicate 3-284
procedure-name 3-285
proc-expr 3-284
proc-search-condition 3-284
proc-stmt 3-284
public-or-user-group-name 3-285
query-specification 3-285
referencing-alias 3-285

Index 21

referential-actions 3-286
referential-delete-action 3-286
referential-update-action 3-286
release-statement 3-286
result 3-286
rollback-statement 3-286
savepoint-name 3-286
scalar-function 3-286
scale 3-286
search-condition 3-286
select-item 3-286
select-list 3-286
set-function 3-286
sqlstate-value 3-286
table-constraint 3-286
table-constraint-definition 3-286
table-element 3-287
table-expression 3-287
table-name 3-287
table-privilege 3-287
table-reference 3-287
transaction-statement 3-287
trigger-name 3-287
user-group-name 3-287
user-name 3-287
user-password 3-287
value 3-287
value-list 3-288
values-clause 3-288
variable-name 3-288
view-name 3-288
SQL Grammar Elements 3-2
SQL Relational Database Engine
optimizations 7-1
performance 7-1
restriction optimization 7-4
temporary files, location 3-294
SQL session
setting a collating default 3-237
SQL_BINARY(-2) data type A-3
SQL_BIT(-7) data type A-4
SQL_CHAR(1) data type A-3
SQL_DATE(9) data type A-2
SQL_DECIMAL(3) data type A-2, A-3
SQL_DOUBLE(8) data type A-2
SQL_FLOAT A-4

22 Index

SQL_GUID(-11) data type A-2

SQL_INTEGER(4) data type A-2, A-3
SQL_LONGVARBINARY(-4) data type A-2
SQL_LONGVARCHAR(-1) data type A-2
SQL_NUMERIC(2) data type A-3
SQL_REAL(7) data type A-2
SQL_SMALLINT(5) data type A-2, A-3, A-4
SQL_TIME(10) data type A-3
SQL_TIMESTAMP(11) data type A-3
SQL_TINYINT(-6) data type A-2, A-3
SQL_VARBINARY A-4
SQL_VARCHAR(12) data type A-4
SQLAllocHandle 2-9
SQLBindCol 2-9
SQLBindParameter 2-9
SQLBrowseConnect 2-9
SQLBulkOperations 2-9
SQLCancel 2-9
SQLCloseCursor 2-10
SQLColAttributes 2-10
SQLColumnPrivileges 2-10
SQLColumns 2-10
SQLConnect 2-10
SQLCopyDesc 2-10
SQLDataSources 2-10
SQLDescribeCol 2-10
SQLDescribeParam 2-10
SQLDisconnect 2-10
SQLDriverConnect 2-10
SQLDrivers 2-10
SQLEndTran 2-10
SQLExecDirect 2-10
SQLExecute 2-10
SQLExtendedFetch 2-10
SQLFetch 2-10
SQLFetchScroll 2-10
SQLForeignKeys 2-10
SQLFreeHandle 2-10
SQLFreeStmt 2-10, 3-299
SQLGetConnectAttr 2-10
SQLGetCursorName 2-10
SQLGetData 2-10
exception to ODBC API 2-12
with LONGVARBINARY A-12
with LONGVARCHAR A-12
SQLGetDescField 2-10

SQLGetDescRec 2-11
SQLGetDiagField 2-11
SQLGetDiagRec 2-11
SQLGetEnvAttr 2-11
SQLGetFunctions 2-11
SQLGetInfo 2-11, 2-13
exception to ODBC API 2-12
SQLGetStmtAttr 2-11
SQLGetTypeInfo 2-11, 2-12
exception to ODBC API 2-12
SQLMoreResults 2-11, 2-12
SQLNativeSql 2-11
SQLNumParams 2-11
SQLNumResultCols 2-11
SQLParamData 2-11
SQLPrepare 2-11
SQLPrimaryKeys 2-11
SQLProcedureColumns 2-11
SQLProcedures 2-11
SQLPutData 2-11
SQLRowCount 2-11
SQLSetConnectAttr 2-11
SQLSetCursorName 2-11
SQLSetDescField 2-11
SQLSetDescRec 2-11
SQLSetEnvAttr 2-11
SQLSetPos 2-11
SQLSetStmtAttr 2-12
SQLSpecialColumns 2-12
exception to ODBC API 2-12
SQLSTATE 3-263
grammar supported 3-263
sqlstate-value (grammar element defined) 3-68
sqlstate-value SQL grammar element definition 3286
SQLStatistics 2-12
SQLTablePrivileges 2-12
SQLTables 2-12
SQRT 5-7
START TRANSACTION 3-264
grammar supported 3-264
Statement delimiter, changing 3-2
Statements
maximum per connection 2-5
Static cursor
type changed by TOP 3-223

Stored procedure
cached_procedures setting 3-231
caching of 3-231, 3-245
exclusion to caching of temporary table 3-233, 3247
exclusion to caching with DDL 3-233, 3-247
exclusion to caching with EXEC 3-233, 3-247
exclusions to caching of 3-233, 3-247
procedures_cache setting 3-245
Stored procedures
calling 1-9
creating 1-4, 1-5
data type limitations 3-70
dropping 1-4, 1-5, 3-135
executing 1-9
expressions 3-289
limits 3-78
max. number of columns 2-3, 3-70
number of arguments in a parameter list 2-3,
3-70
total size 2-5, 3-70
permissions on 3-153
predicates 3-288
system table (X$Proc) C-11, C-27
use of variables as select items 3-69
using 3-78
String
functions supported 5-2
literal values 3-296
Maximum size of quoted string in SQL statement
2-5
STRING data type A-3, A-26
Structured Query Language. See SQL
STUFF 5-3
Subquery
correlated 3-208, 3-270
eliminating duplicate rows with DISTINCT 3274
grammar supported 3-207
improved performance of 3-208
non-correlated 3-270
subquery-expression (grammar element defined) 3204
SUBSTRING 5-3
SUM aggregate function 3-204
and precision of DECIMAL type 3-207

Index 23

Supported data types A-2

Supported ODBC APIs
in Pervasive PSQL 2-9
Syntax
for creating temporary tables 3-93
System
clock 3-252
locale setting 3-252
SQL functions supported 5-16
time 3-252
System databases
TempDB 3-97
System stored procedures
calling 1-9
psp_column_attributes 6-6
arguments 6-7
error conditions 6-9
permissions 6-7
returned result set 6-7
psp_column_rights 6-9
Arguments 6-10
error conditions 6-13
returned result set 6-10
psp_columns 6-3
arguments 6-3
error conditions 6-6
returned result set 6-3
psp_fkeys 6-13
arguments 6-13
error conditions 6-15
returned result set 6-14
psp_groups 6-15
arguments 6-16
error conditions 6-17
returned result set 6-16
psp_help_sp 6-17
arguments 6-17
error conditions 6-19
returned result set 6-18
psp_help_trigger 6-19
arguments 6-20
error conditions 6-21
returned result set 6-20
psp_help_udf 6-21
arguments 6-21
error conditions 6-23

24 Index

returned result set 6-22

psp_help_view 6-23
arguments 6-24
error conditions 6-25
permissions 6-24
returned result set 6-24
psp_indexes 6-25
arguments 6-25
error conditions 6-28
returned result set 6-26
psp_pkeys 6-28
arguments 6-28
error conditions 6-29
returned result set 6-28
psp_stored_procedures 6-33
arguments 6-33
error conditions 6-36
returned result set 6-34
psp_table_rights 6-39
arguments 6-30, 6-39, 6-47
error conditions 6-31, 6-41, 6-49
returned result set 6-30, 6-40, 6-48
psp_tables 6-36
arguments 6-36
error conditions 6-38
returned result set 6-37
psp_triggers 6-41
arguments 6-42
error conditions 6-43
returned result set 6-42
psp_udfs 6-43
arguments 6-44
error conditions 6-45
returned result set 6-44
psp_users 6-45
arguments 6-45
error conditions 6-47
returned result set 6-46
psp_views 6-50
arguments 6-50
error conditions 6-51
returned result set 6-50
System table
for version 2 metadata C-2

System tables C-1

updating C-2
V1 metadata C-4
V2 metadata C-19
X$Attrib C-4, C-19
X$Depend C-5, C-20
X$Field C-6, C-21
X$File C-8, C-23
X$Index C-9, C-24
X$Proc C-11, C-27
X$Relate C-12, C-28
X$Rights C-13, C-29
X$Trigger C-15, C-32
X$User C-16, C-33
X$View C-17, C-35

T
Table
closing in an SQL statement 3-299
creating 1-3
creating with legacy null support 3-259
deleting 1-3
maximum number of columns 2-3
maximum number of rows 2-5
modifying 1-3
system tables C-1
updating system tables C-2
Table filter D-14
Table name
maximum length 2-5
table-constraint (grammar element defined) 3-81,
3-94
table-constraint SQL grammar element definition 3286
table-constraint-definition (grammar element
defined) 3-81, 3-94
table-constraint-definition SQL grammar element
definition 3-286
table-element (grammar element defined) 3-80, 393
table-element SQL grammar element definition 3287
table-expression SQL grammar element definition
3-287
table-name (grammar element defined) 3-80, 3-93
table-name SQL grammar element definition 3-287

table-privilege SQL grammar element definition 3287

table-reference (grammar element defined) 3-202
table-reference SQL grammar element definition 3287
Tables
system tables for version 2 metadata C-2
TAN 5-7
TEMP environment variable
SQL Relational Database Engine
temporary files and 3-294
TempDB
system database 3-97
Temporary files
SQL Relational Database Engine
location of 3-294
types of 3-295
when created 3-295
Temporary table
CREATE TABLE statement 3-93
CREATE TABLE statement syntax 3-93
exclusion to caching in stored procedure 3-233,
3-247
TempDB database 3-97
Temporary tables
performance 7-15
Time
adding in INSERT statements 3-167, 5-9
format supported 3-217, 3-297
functions supported 5-9
inserting current 3-167, 5-9
inserting or updating column values 3-217, 3297
literal format 3-217, 3-297
literal values 3-297
local vs UTC 3-252
TIMESTAMP type, why not to use A-36
TIME data type A-3, A-34
Time zone
setting 3-252
Time-literal
grammar supported 3-217, 3-297

Index 25

Timestamp
adding to an INSERT statement 3-167, 3-169
format supported 3-217, 3-297
inserting current 3-167
inserting or updating column values 3-217, 3297
literal format 3-217, 3-297
literal values 3-297
TIMESTAMP data type A-3, A-35
inappropriate for many purposes A-36
interpretation of literal values 3-253
TIMESTAMPADD 5-14
TIMESTAMPDIFF 5-14
Timestamp-literal
grammar supported 3-217, 3-297
TINYINT data type A-2
TMP environment variable
SQL Relational Database Engine
temporary files and 3-294
TOP
with SELECT 3-222
top-clause (grammar element defined) 3-202
Transactions
defining 1-8
transaction-statement (grammar element defined)
3-67
transaction-statement SQL grammar element
definition 3-287
TRANSLATIONDLL connection string 3-304
TRIGGER.DDF C-3
trigger-name (grammar element defined) 3-103
trigger-name SQL grammar element definition 3287
Triggers
calling 1-9
creating 1-4
data type limitations 3-104
dependencies
system table (X$Depend) C-5, C-20
dropping 1-4
executing 1-9
number of columns allowed 2-3, 3-70
system table (X$Trigger) C-15, C-32
TRUEBITCREATE 3-258
TRUENULLCREATE 3-259
TRUNCATE 5-7

26 Index

Truncate
milliseconds from DATETIME 5-22
Trusted objects 3-153
Truth table for bitwise operations 4-9
Type conversion 5-20

U
UBIGINT data type A-3
UCASE 5-3
UINTEGER data type A-3
Unicode data types A-37
Unicode key types A-22
UNION 3-266
grammar supported 3-266
limitations 3-266
UNIQUE 3-268
grammar supported 3-268
UNIQUEIDENTIFIER
data type A-17
UNIQUEIDENTIFIER data type 3-118, 5-16, A-2
Universal Time See Time
UNSIGNED BINARY data type A-37
UNSIGNED(1) BINARY data type A-3
UNSIGNED(2) BINARY data type A-3
UNSIGNED(4) BINARY data type A-3
UNSIGNED(8) BINARY data type A-3
UPDATE 3-269
fails if subquery returns multiple rows 3-271
grammar supported 3-269
use with COBOL D-3
Update
rule 3-84
UPDATE (positioned) 3-277
grammar supported 3-277
Updating
system tables C-2
UPPER 5-3
USER 3-279, 5-16
grammar supported 3-279
User
creating using CREATE USER 3-106
creating using GRANT LOGIN 3-149
Master 3-152
User name
maximum length 2-5
USER.DDF C-3

User-Defined Functions
creating 1-5
dropping 1-5
Invoking 3-54
limits 3-52
user-group-name SQL grammar element definition
3-287
user-name SQL grammar element definition 3-287
user-password SQL grammar element definition 3287
Users and user groups. See Security
USING keyword 3-14, 3-84
length of path name 3-14, 3-85
USMALLINT data type A-3
UTC Time See Time
Utilities
query plan viewer E-1
UTINYINT data type A-3

V
V1 metadata 2-2
system tables C-4
V2 metadata 2-2
system tables C-19
Valid Value Range
data types A-5
Value
default 3-166
value (grammar element defined) 3-203
value SQL grammar element definition 3-287
value-list SQL grammar element definition 3-288
Values
default
not supported for BLOB, CLOB, or BINARY
3-168
values-clause SQL grammar element definition 3288
VARCHAR data type A-4
notes about A-11
Variable
for adding current date 3-167
for adding current time 3-167
for adding timestamp 3-167
variable-name SQL grammar element definition 3288
Variables

Global. See Global variables

use as select item in stored procedure 3-69
Variant DDF C-3
Variant.DDF C-3
Vendor Strings
embedded 3-173
in LEFT OUTER JOIN statements 3-174
View
containing ORDER BY clause 3-109
TOP clause in a 3-109, 3-223
VIEW.DDF C-3
view-name SQL grammar element definition 3-288
Views
containing ORDER BY clause 3-109
creating 1-9
database 3-108
deleting 1-9
permissions on 3-153
psp_view_rights 6-29, 6-47
system table (X$View) C-17, C-35

W
WEEK 5-14
WHERE
clause 3-202
WHILE 3-280
grammar supported 3-280
Wildcard characters
any number of characters 3-181
escape character 3-181
single character 3-181
WITH REPLACE keyword 3-16, 3-86
Words to avoid B-7
ABSOLUTE B-7
ACTION B-7
ADD B-7
ALL B-7
ALLOCATE B-7
ALTER B-7
AND B-7
ANY B-7
ARE B-7
AS B-7
ASC B-7
ASSERTION B-7
AT B-7

Index 27

AUTHORIZATION B-7
AVG B-7
BEGIN B-7
BETWEEN B-7
BIT B-7
BIT_LENGTH B-7
BOTH B-7
BY B-7
CASCADE B-7
CASCADED B-7
CASE B-7
CAST B-7
CATALOG B-7
CHAR B-7
CHAR_LENGTH B-7
CHARACTER B-7
CHARACTER_LENGTH B-7
CHECK B-7
CLOSE B-7
COALESCE B-7
COLLATE B-7
COLLATION B-7
COLUMN B-7
COMMIT B-7
CONNECT B-7
CONNECTION B-7
CONSTRAINT B-7
CONSTRAINTS B-7
CONTINUE B-7
CONVERT B-7
CORRESPONDING B-7
COUNT B-7
CREATE B-7
CROSS B-7
CURRENT B-7
CURRENT_DATE B-8
CURRENT_TIME B-8
CURRENT_TIMESTAMP B-8
CURRENT_USER B-8
CURSOR B-8
DATE B-8
DAY B-8
DEALLOCATE B-8
DEC B-8
DECIMAL B-8
DECLARE B-8

28 Index

DEFAULT B-8
DEFERRABLE B-8
DEFERRED B-8
DELETE B-8
DESC B-8
DESCRIBE B-8
DESCRIPTOR B-8
DIAGNOSTICS B-8
DISCONNECT B-8
DISTINCT B-8
DOMAIN B-8
DOUBLE B-8
DROP B-8
ELSE B-8
END B-8
END-EXEC B-8
ESCAPE B-8
EXCEPT B-8
EXCEPTION B-8
EXEC B-8
EXECUTE B-8
EXISTS B-8
EXTERNAL B-8
EXTRACT B-8
FALSE B-8
FETCH B-8
FIRST B-8
FLOAT B-8
FOR B-8
FOREIGN B-8
FOUND B-8
FROM B-8
FULL B-8
FUNCTION B-8
GET B-8
GLOBAL B-8
GO B-8
GOTO B-8
GRANT B-8
GROUP B-8
HOUR B-8
IDENTITY B-8
IMMEDIATE B-8
IN B-8
INDICATOR B-8
INITIALLY B-8

INNER B-8
INPUT B-8
INSENSITIVE B-8
INSERT B-8
INT B-8
INTEGER B-8
INTERSECT B-8
INTERVAL B-8
INTO B-8
IS B-8
ISOLATION B-8
JOIN B-8
KEY B-8
LANGUAGE B-8
LAST B-8
LEADING B-8
LEFT B-8
LEVEL B-8
LIKE B-8
LOCAL B-8
LOWER B-9
MASK B-9
MATCH B-9
MAX B-9
MIN B-9
MINUTE B-9
MODULE B-9
MONTH B-9
NAMES B-9
NATIONAL B-9
NATURAL B-9
NCHAR B-9
NEXT B-9
NO B-9
NOT B-9
NULL B-9
NULLIF B-9
NUMERIC B-9
OCTET_LENGTH B-9
OF B-9
ON B-9
ONLY B-9
OPEN B-9
OPTION B-9
OR B-9
ORDER B-9

OUTER B-9
OUTPUT B-9
OVERLAPS B-9
PAD B-9
PARTIAL B-9
POSITION B-9
PRECISION B-9
PREPARE B-9
PRESERVE B-9
PRIMARY B-9
PRIOR B-9
PRIVILEGES B-9
PROCEDURE B-9
PUBLIC B-9
READ B-9
REAL B-9
REFERENCES B-9
RELATIVE B-9
RESTRICT B-9
REVOKE B-9
RIGHT B-9
ROLLBACK B-9
ROWS B-9
SCHEMA B-9
SCROLL B-9
SECOND B-9
SECTION B-9
SELECT B-9
SESSION B-9
SESSION_USER B-9
SET B-9
SIZE B-9
SMALLINT B-9
SOME B-9
SPACE B-9
SQL B-9
SQLCODE B-9
SQLERROR B-9
SQLSTATE B-9
SUBSTRING B-9
SUM B-9
SYSTEM_USER B-9
TABLE B-9
TEMPORARY B-9
THEN B-9
TIME B-9

Index 29

TIMESTAMP B-9
TIMEZONE_HOUR B-9
TIMEZONE_MINUTE B-9
TO B-9
TRAILING B-9
TRANSACTION B-9
TRANSLATE B-10
TRANSLATION B-10
TRIM B-10
TRUE B-10
UNION B-10
UNIQUE B-10
UNKNOWN B-10
UPDATE B-10
UPPER B-10
USAGE B-10
USER B-10
USING B-10
VALUE B-10
VALUES B-10
VARCHAR B-10
VARYING B-10
VIEW B-10
WHEN B-10
WHENEVER B-10
WHERE B-10
WITH B-10
WORK B-10
WRITE B-10
YEAR B-10
ZONE B-10
Words, reserved B-1
WSTRING data type A-3
WSTRING data type (Unicode) A-37
WSZSTRING data type A-3
WZSTRING data type (Unicode) A-37

X
X$Attrib C-3
X$Attrib system table C-4, C-19
X$Depend C-3
X$Depend system table C-5, C-20
X$Field C-3
X$Field system table C-6, C-21
X$File C-3
X$File system table C-8, C-23

30 Index

X$Index C-3
X$Index system table 3-64, C-9, C-24
X$Proc C-3
X$Proc system table C-11, C-27
X$Relate C-3
X$Relate system table C-12, C-28
X$Rights C-3
X$Rights system table C-13, C-29
X$Trigger C-3
X$Trigger system table C-15, C-32
X$User C-3
X$User system table C-16, C-33
X$View C-3
X$View system table C-17, C-35
XML
used with Schema Executor utility D-13

Y
YEAR 5-14

Z
Zone
setting time 3-252
ZSTRING data type A-4, A-37

4 Valses Venezolanos - Antonio Lauro - Revised by Alirio Diaz
100% (15)
4 Valses Venezolanos - Antonio Lauro - Revised by Alirio Diaz
9 pages
I Puc Computer Science Lab Manual 2024-2025 - With - Flowcharts
88% (8)
I Puc Computer Science Lab Manual 2024-2025 - With - Flowcharts
61 pages
VisualATE Users Guide
100% (2)
VisualATE Users Guide
340 pages
Cisug
No ratings yet
Cisug
294 pages
RSSQL Users Guide
No ratings yet
RSSQL Users Guide
110 pages
Progress Webspeed
No ratings yet
Progress Webspeed
142 pages
Programming FPGAs: Getting Started with Verilog
From Everand
Programming FPGAs: Getting Started with Verilog
Simon Monk
3.5/5 (2)
PSQLv11SP3 Users Guide
No ratings yet
PSQLv11SP3 Users Guide
374 pages
Cisug
No ratings yet
Cisug
306 pages
Openedge Abl
No ratings yet
Openedge Abl
228 pages
115hradm HR UG
No ratings yet
115hradm HR UG
498 pages
Iir
No ratings yet
Iir
29 pages
Progress OpenEdge Database Administration
No ratings yet
Progress OpenEdge Database Administration
812 pages
DataBase - Management DataBase - Administration
No ratings yet
DataBase - Management DataBase - Administration
848 pages
Gs Abl Progress
No ratings yet
Gs Abl Progress
226 pages
Iq Query
0% (2)
Iq Query
172 pages
OpenDeploy 7.2 Administration Guide Rev1 en
0% (1)
OpenDeploy 7.2 Administration Guide Rev1 en
332 pages
Actuate Glossary
No ratings yet
Actuate Glossary
240 pages
SQL Dba
No ratings yet
SQL Dba
275 pages
PSQLv11SP3 Users Guide
No ratings yet
PSQLv11SP3 Users Guide
374 pages
Integrating Novell Edirectory With Freeradius: F E B R U A R Y 1 4, 2 0 0 5
No ratings yet
Integrating Novell Edirectory With Freeradius: F E B R U A R Y 1 4, 2 0 0 5
44 pages
Herctut
No ratings yet
Herctut
502 pages
8_0_IdentityIQ_Installation_Guide
No ratings yet
8_0_IdentityIQ_Installation_Guide
30 pages
Xw8600 Workstation
No ratings yet
Xw8600 Workstation
52 pages
Bioinformatics Toolbox™ User's Guide
No ratings yet
Bioinformatics Toolbox™ User's Guide
351 pages
Dotnetref
No ratings yet
Dotnetref
130 pages
8-0fcs WebMethods Installation Guide
No ratings yet
8-0fcs WebMethods Installation Guide
164 pages
Sqabasic PDF
No ratings yet
Sqabasic PDF
890 pages
Clear Quest Administration
No ratings yet
Clear Quest Administration
434 pages
Oracle Workflow Administrators's Guide
No ratings yet
Oracle Workflow Administrators's Guide
316 pages
Pervasive Sync
No ratings yet
Pervasive Sync
338 pages
NetBackup105_ProgrammersGuide_XSBA
No ratings yet
NetBackup105_ProgrammersGuide_XSBA
145 pages
Progress Manual SQL
100% (1)
Progress Manual SQL
86 pages
Transact-SQL User-Defined Functions For MSSQL Server
100% (1)
Transact-SQL User-Defined Functions For MSSQL Server
479 pages
Installing Solaris On Sparc
No ratings yet
Installing Solaris On Sparc
229 pages
OpenEdge Development Basic Development Tools PDF
No ratings yet
OpenEdge Development Basic Development Tools PDF
86 pages
115 Devg
No ratings yet
115 Devg
848 pages
Reporting and Data Analysis With HP Openview Network Node Manager
No ratings yet
Reporting and Data Analysis With HP Openview Network Node Manager
244 pages
Progress Dataserver For Odbc Guide
No ratings yet
Progress Dataserver For Odbc Guide
252 pages
EV Exchange PDF
No ratings yet
EV Exchange PDF
617 pages
Gsins
No ratings yet
Gsins
510 pages
Manualfsp 3000r7 em PDF
0% (1)
Manualfsp 3000r7 em PDF
500 pages
ProgressDataServerforMSQL 1768.Sds
No ratings yet
ProgressDataServerforMSQL 1768.Sds
238 pages
Autodesk Navisworks Freedom 2012 User Guide
No ratings yet
Autodesk Navisworks Freedom 2012 User Guide
324 pages
Allbase/Sql Reference Manual: HP 3000 MPE/iX Computer Systems
No ratings yet
Allbase/Sql Reference Manual: HP 3000 MPE/iX Computer Systems
694 pages
Installation and Licensing Guide - IsE PDF
No ratings yet
Installation and Licensing Guide - IsE PDF
74 pages
WISE Online Reference
No ratings yet
WISE Online Reference
444 pages
Monitor Pro Tuto2
No ratings yet
Monitor Pro Tuto2
254 pages
Users Guide
No ratings yet
Users Guide
312 pages
UareU para Linux
No ratings yet
UareU para Linux
46 pages
Bzware In001 - en P
No ratings yet
Bzware In001 - en P
144 pages
Basicref v11r1
No ratings yet
Basicref v11r1
1,108 pages
U.are.U SDK: Platform Guide For Windows
No ratings yet
U.are.U SDK: Platform Guide For Windows
33 pages
RSView User Manual Eng
No ratings yet
RSView User Manual Eng
920 pages
CSS Hacks and Filters: Making Cascading Stylesheets Work
From Everand
CSS Hacks and Filters: Making Cascading Stylesheets Work
Joseph Lowery
3/5 (5)
Microsoft SQL Server 2005: A Beginner''s Guide
From Everand
Microsoft SQL Server 2005: A Beginner''s Guide
Dusan Petkovic
No ratings yet
OCP Oracle Database 11g Administration II Exam Guide: Exam 1Z0-053
From Everand
OCP Oracle Database 11g Administration II Exam Guide: Exam 1Z0-053
Bob Bryla
No ratings yet
Programming the Photon: Getting Started with the Internet of Things
From Everand
Programming the Photon: Getting Started with the Internet of Things
Christopher Rush
5/5 (1)
Programming the Intel Galileo: Getting Started with the Arduino -Compatible Development Board
From Everand
Programming the Intel Galileo: Getting Started with the Arduino -Compatible Development Board
Christopher Rush
5/5 (1)
Programming Arduino Next Steps: Going Further with Sketches
From Everand
Programming Arduino Next Steps: Going Further with Sketches
Simon Monk
3/5 (3)
Internet Technologies Handbook: Optimizing the IP Network
From Everand
Internet Technologies Handbook: Optimizing the IP Network
Mark A. Miller
No ratings yet
Software Patterns Made Easy
From Everand
Software Patterns Made Easy
Justice Nanhou
No ratings yet
A Different Kind of Family
No ratings yet
A Different Kind of Family
53 pages
Sutta Numbering PDF
No ratings yet
Sutta Numbering PDF
218 pages
Becak Fantasy - Jubing
No ratings yet
Becak Fantasy - Jubing
5 pages
49.8b Mahapadana S d14 Sutta Notes Piya
No ratings yet
49.8b Mahapadana S d14 Sutta Notes Piya
91 pages
Sungha Jung-Twilight PDF
0% (1)
Sungha Jung-Twilight PDF
6 pages
Any DAC
100% (1)
Any DAC
907 pages
Money Rule
No ratings yet
Money Rule
16 pages
Full Chapter Murach S SQL Server 2019 For Developers 1St Edition Joel Murach PDF
100% (21)
Full Chapter Murach S SQL Server 2019 For Developers 1St Edition Joel Murach PDF
53 pages
SQL-Server-Online-Training
No ratings yet
SQL-Server-Online-Training
2 pages
SSMA For Oracle
No ratings yet
SSMA For Oracle
15 pages
Database SQL Programming
No ratings yet
Database SQL Programming
416 pages
Iso8583 UDF Manual
No ratings yet
Iso8583 UDF Manual
2 pages
WBP Model Answer Paper
100% (2)
WBP Model Answer Paper
30 pages
Installing and Using Impala
No ratings yet
Installing and Using Impala
248 pages
Note 2620830 - How to Record SAP HANA Memory Allocator Traces to Analyze Memory Leaks
No ratings yet
Note 2620830 - How to Record SAP HANA Memory Allocator Traces to Analyze Memory Leaks
4 pages
Download Full SQL Server MVP Deep Dives Volume 2 Kalen Delaney PDF All Chapters
100% (14)
Download Full SQL Server MVP Deep Dives Volume 2 Kalen Delaney PDF All Chapters
60 pages
Snowflake Mastering
No ratings yet
Snowflake Mastering
6 pages
Board Practical 2023 - 24
No ratings yet
Board Practical 2023 - 24
5 pages
AWS Machine Learning Specialty
100% (1)
AWS Machine Learning Specialty
67 pages
User Defined Field Oracle FLEXCUBE Universal Banking Release 12
No ratings yet
User Defined Field Oracle FLEXCUBE Universal Banking Release 12
36 pages
Transact-SQL User-Defined Functions For MSSQL Server PDF
100% (1)
Transact-SQL User-Defined Functions For MSSQL Server PDF
479 pages
solved questions matric 2024(theory)
No ratings yet
solved questions matric 2024(theory)
8 pages
SECJ1013 Test 2 (Practical) 1-20232024 Question
No ratings yet
SECJ1013 Test 2 (Practical) 1-20232024 Question
8 pages
SQL Server Query Optimization Techniques PDF
No ratings yet
SQL Server Query Optimization Techniques PDF
9 pages
Firebird Isql
No ratings yet
Firebird Isql
43 pages
Lab Task #7 Functions
No ratings yet
Lab Task #7 Functions
6 pages
SQL Get
100% (1)
SQL Get
213 pages
Kendriya Vidyalaya Sangathan, Chennai Region Practice Test 2020 - 21 Class Xii
No ratings yet
Kendriya Vidyalaya Sangathan, Chennai Region Practice Test 2020 - 21 Class Xii
9 pages
HCM - IUH - INTE - NET - HCM20 - 005 - Training Plan
No ratings yet
HCM - IUH - INTE - NET - HCM20 - 005 - Training Plan
49 pages
SQL Server 2016
No ratings yet
SQL Server 2016
169 pages
Top SQL Interview Questions
No ratings yet
Top SQL Interview Questions
35 pages
Logo System Manual en-US en-US
No ratings yet
Logo System Manual en-US en-US
388 pages
Data Mesh Architecture
No ratings yet
Data Mesh Architecture
27 pages
DB2 V8 Application Programming and SQL Guide
No ratings yet
DB2 V8 Application Programming and SQL Guide
1,141 pages
SQL Lab Manual 2
No ratings yet
SQL Lab Manual 2
8 pages