Pervasive PSQL v9 SP2 SDK -- Pervasive Direct Access Components (PDAC)
Readme -- October 2006 Release


Overview

Pervasive Direct Access Components (PDAC) are a set of Visual Component Library (VCL) components that allow direct access to Pervasive Database Engines from within the Borland Delphi and C++ Builder Environments. These components provide a replacement for the functionality of the Borland Database Engine (BDE). PDAC dramatically extends the database development options available to Delphi and C++ Builder developers.

Note: Please review the Pervasive Developer Center for the most recent information and updates for PDAC: http://www.pervasive.com/developerzone/access_methods/pdac.asp.

The Pervasive Direct Access Components are provided in versions fully integrated with the following development environments:

Compatibility with later versions of the Delphi and C++ Builder development tools will be made available after those products are released by Borland.

No support is provided or planned for the following:

This update to the PDAC package provides fixes for a number of issues discovered in the components as well as providing a new dynamic cursor feature.

You may also find informative the master readme file for the SDK. The master SDK readme, readsdk.htm, is installed with the Pervasive PSQL database engine and is located by default in the folder PVSW\bin\plugins\com.pervasive.help.docs.psql.enus.


Installation

To install the PDAC components for Delphi and C++ Builder, download the setup program from http://www.pervasive.com/developerzone/access_methods/pdac.asp

Note: If you have an existing version of PDAC, you should uninstall it before installing the updated PDAC components. Otherwise, the PDAC installation will not succeed.


October 2006 Release (Support for Delphi 2006)

This release includes the following updates:

Please see the known issues with this release.


May 2006 release (Pervasive PSQL SDK - v9 SP2)

This release includes the following updates:

Please see the known issues with this release.


July 2005 release (Pervasive PSQL SDK - v9.0)

This release includes the following updates:

Please see the known issues with this release.


March 2004 release (Pervasive.SQL SDK - V8.5)

This release includes the following updates:

BookMarksEnabled Property Added to TPvQuery

A new Boolean property "BookmarksEnabled" was added to TPvQuery. If you do not use Bookmarks in your application, set this property to False in order to increase TPvQuery performance. The default value is True.

PvQuery.BookmarksEnabled :=False

Secure Databases and PDAC

If you are connecting to a secured database, PDAC prompts you for the user name and password. If you do not want the user to be prompted for the user name and password, you can set up the connection parameters in TPvDatabase and TPvSQLDatabase.

For example:

   PvSession.ServerName:='ServerName';
   PvSession.SessionName:='session1';
   PvSession.Active:=True;

   PvDatabase.AliasName:= 'DatabaseName';
   PvDatabase.DatabaseName:='DB';
   PvDatabase.SessionName:='session1';
   PvDatabase.Params.Clear();

// here you specify user name and password to connect to remote database.

   PvDatabase.Params.Add('User Name=UserName');
   PvDatabase.Params.Add('password=Password');
   PvDatabase.Connected:=True;
   PvTable.DatabaseName:=dB;
   PvTable.SessionName:='session1';
   PvTable.TableName:='person';
   PvTable.Active:=True;
   

July 2003 release (PDAC Security Beta)

This release adds PDAC compatibility for the Pervasive.SQL V8.5 release. For information about the Pervasive.SQL v8.5 release, see http://www.pervasive.com/support/updates/v8_85.asp. The PDAC components are enhanced in the following ways in support of the new security features:

To use this release, follow these steps:

  1. Install this PDAC security beta and the Pervasive PSQL security release, which can be obtained at http://www.pervasive.com/support/updates/v8_85.asp.
  2. Copy the new PDAC DRM component to the application environment.
  3. Recompile your PDAC application

    Note: You can choose not to recompile your PDAC application. However, the following limitations will then apply:

Issues Addressed Since Last Release

In addition to the new functionality, the following issues have been corrected in this release.
Issue Description
45424 After using TParam Clear() method in a stored procedure, default value for datatype is received instead of null value.

For example, consider a stored procedure that has a parameter called :x and the value is set to NULL via TParam's clear() method. When the procedure is executed, the stored procedure receives a default value for the datatype of x instead of an actual null value. In this example, since parameter x is of type ftDate, it receives a value of '1899' (the default date) instead of an actual null, when the Clear() method is used.

45719 When using a UNC paths to make a remote connection using the PvDatabase component, status code 11 is returned.
45463 When using the TPvStoredProc component, dataType parameter values of date, time, and dateTime values appear with defaults of ftUnknown.
45557 When the TPvTable component is in insert mode (dsInsert), the TMemoField does not accept a new value. In Edit mode, the TMemoField does accept new values.
45309 Status 43 when attempting to change the index. This issue would occur given the following sequence:
  1. You use a TPvQuery component to delete all the records from a table
  2. You then use a TPvTable to change to a different index on that table either by using the IndexName or IndexFieldNames property
45090 Using a TPvQuery component to execute a SQL statement containing "SELECT DISTINCT .." may produce the error "More than one row updated or deleted".
44880 Memory leak occurs using PvTable each time database name is changed.
44750 Bookmark with setRange works incorrectly. Setting a bookmark prior to setting a range that should exclude the bookmark produces unexpected results. The bookmark then finds the record when it should throw an exception.
43846 'Invalid Bookmark' error is received when attempting to delete a cached record and then saving the changes to the database.
44638 REAL (FLOAT(4)) data type is cloned as BFLOAT (FLOAT(8)).

The REAL data type is ignored by the PDAC PvCreateTable function and is interpreted as a DOUBLE instead. As a result, cloning a TPvTable in code results in a table with a DOUBLE field that should be a REAL field.

43213 Package builds are not optimized for performance. When using Delphi 7, you may see a window asking for source code when you single step into the code in debug mode.
44618 PDAC Locate returns True even if a key value does not exist in the table.

This occurs if the Locate's key fields are a superset of the table's current index fields. Locate incorrectly returns True that it found the record.

44532 A EPvSqlEngineError bookmark error message can result when using a clientDataSet that is attached to a TPvQuery component.
44534 When using an AUTOINC field, '0' is not automatically sent if no value is provided by the application.
44581 Some queries can produce an editable field in a grid when the data in the field is not persistant . When saving the changes, the non persistant data is not saved.
44607 Changing the index of a table resets the current row to the first row when viewing the table through a grid.
43659 String fields can be truncated after an Update. For example, this error can occur during the following sequence:
  1. You update a varchar field and move the cursor
  2. You then update a second field and move the cursor back to the first field The updated value on the first field is missing.
53598 PDAC should not work for the changed datatypes such as Bigint, UBingint SDKs of PDAC (that use an 8 byte integer) prior to Pervasive PSQL v9 SP2.


April 2003 release

This release incorporates a number of fixes for reported issues since the December 2002 release.

Notes about Data Types in this Release

If you need to store and handle very large values in your columns then, you should always use float and double datatypes. If you do not use float and double datatypes you will receive inconsistent results with rounding and overflow conditions with very large values from the following data types

With regards to the rounding errors, it is possible that any of the types in the following table could be displayed or filtered incorrectly when nearer the outer ends of the range.

The maximum number of digits and values that can be handled in the different datatypes is documented in the following table:

Pervasive PSQL Data Type PDAC Lower Range PDAC Upper Range
BIGINT -281474976710655 281474976710655
CURRENCY -28147497671.0655 28147497671.0655
DECIMAL -281474976710655 281474976710655
MONEY -281474976710655 281474976710655
NUMERIC -281474976710655 281474976710655
NUMERICSA -281474976710655 281474976710655
NUMERICSTS -99999999999999 99999999999999
UBIGINT 0 281474976710655

Note on DECIMAL, MONEY, and Numerics:

You have to move the decimal place over the number of places defined in the creation. For example:

Applications Linked to PDAC as Runtime Library

Pervasive recommends that you re-link your application when you obtain a new version of BPLs (with accompanying DCPs). This is particularly important with releases of PDAC shipped in 2002 or later. When you receive an updated version, new properties and methods can cause incompatibility with previous BPLs. To address this issue, replace the original DCP files and rebuild your application before utilizing the latest release.

Detail: BPLs export all properties and methods within a class. Each property and method becomes an ordinal entry in the export table. Any changes in the interface of the class causes a shift of ordinals, which in turn causes the consuming application to access incorrect addresses of the functions.

Documentation Issue When Using 2000i Engine

The Pervasive.SQL V8 SDK documentation that is included with this latest PDAC release assumes that a V8 engine is installed. When using the latest PDAC update with a 2000i engine, the documentation shortcut in the Start Menu (Start | Programs | Pervasive.SQL SDK | Documentation | Pervasive.SQL V8) will not function correctly.

To work around this issue, you can either


December 2002 release

This release incorporates a number of fixes for reported issues, and introduces new functionality with regards to cursors.

Other than the issues discussed in this section, PDAC should operate as it did in prior releases. However, it will exhibit faster relational performance. If you have existing PDAC applications that have issues with this new release, please contact Pervasive Software with this information.

Support for newer Borland releases

This release now supports the following:

TPvTable & other Btrieve components

There are no functional changes to these components, but there are several issues resolved.

TPvQuery

TPvQuery has a new property CursorType. This property can be set to ctCached or ctDynamic. The following table describes the behavior of this property in more detail:

Cursor type Behavior
ctCached This setting corresponds to the previously-available fully-cached, fully-static Cursor Manager. It reads every record in the ResultSet before returning, which can be very slow for large tables, yet fast after it has opened for operations such as LookUps.
ctDynamic This setting is the new default; it uses the Pervasive PSQL Engine's dynamic cursors, and offers much improved performance for most operations when compared with ctCached, especially with regard to large tables.

Note: The Dynamic cursors can see the Inserts/Updates/Deletes of their own or other clients.

You can change CursorType on a PvQuery by changing the Property, but only (at runtime) if Active is False. If you change it in Design mode, and the query is Active, it will de-activate the query and change the cursortype (but not reactivate). At Runtime, changing CursorType on an Active PvQuery will throw an exception ("Cannot perform this operation on an open dataset").

Case Where Dynamic Cursors Change to Static

If you request a Dynamic cursor (ctDynamic), but your SQL statement contains a construct that a Dynamic cursor cannot process, the engine will connect and return data, but with a Static cursor. For example, such a construct could be:

In the event the cursor is transformed into a static one, this static cursor will be engine-based one that cannot see inserts, updates, or deletes made by other clients. It will perform better than the static cursors on previous releases (that is, ones using ctCached as the cursor type.).

When the dynamic to static transformation occurs, the Pervasive PSQL engine notifies the PDAC component, and sets a read-only Public Property named EngineCursor.

This EngineCursor property is not published, so it is not visible in the Object Inspector during design. It can have two values:

You cannot modify this property, but you can check its value after opening a query. You might want to check this property for example if it is important that your application know whether your cursor includes updates made by other clients.

Engine Version Checking

When opening a query or table, PDAC now checks for an adequate Pervasive PSQL engine version (version 7.94, build 253.057 or higher) to ensure that engine dependency-related errors do not occur. If the engine version is not sufficient, an exception is thrown with a message indicating the required version.


"Redist" Subdirectory

There is a "redist" directory for each Borland compiler. This directory contains the libraries that must be distributed with an application compiled with "Build with runtime packages."


Adding PDAC to C++ Builder's "Include" and "Library" paths

Although the Pervasive Direct Access Component libraries are installed into all Delphi and C++ Builder IDEs found on your system, it is necessary to set C++ Builder's "Project Options" to reflect the INCLUDE and LIBRARY paths for PDAC. These can be added to the default options, so the steps are unnecessary for every project using the Pervasive components. To add Pervasive Direct Access Components to the INCLUDE and LIBRARY paths in C++ Builder:

  1. Select Project | Options, and choose the "Directories/Conditionals" tab.

  2. Add "\sdk\pdac\BCB?\include" to the Include Path, where represents the directory where you installed the SDK (C:\PVSW is the default). Replace the "?" with the version of C++ Builder you are using.

  3. Also add "\SDK\pdac\BCB?\lib\" and "\SDK\pdac\BCB?\lib\dcu" to the "Library Path", separated by a semicolon (;). Replace the "?" with the version of C++ Builder you are using.

  4. Check the Default box (if you want these to be the defaults for all projects you create), then click OK to save these options.

After the Include and Library paths are set properly, use the Direct Access components exactly the same way as the corresponding Borland components.


Information on Additional Programs Included with PDAC

PDAC2IDE.exe

PDAC2IDE.exe, installed in the SDK\PDAC subdirectory, will configure the Borland Delphi 5/6/7 and C++ Builder 5/6 Integrated Development Environments (Ides) for the PDAC components. This utility is run automatically when the SDK is installed, but can be used at a DOS command line if new Ides are installed or if problems occur.

When installing, there is no need to uninstall first -- any old entries are automatically deleted prior to installation. Note that no files are deleted, copied, or installed; the program simply updates the Ides for PDAC.

The command is used as follows:

To install PDAC to all Borland Ides found on a system

    pdac2ide 

This will find all supported Borland environments and make the appropriate Registry entries for the components to appear on the Palette and be available for use.

To uninstall PDAC from all Borland Ides found on a system

    pdac2ide -u 

To install or uninstall to/from specific Ides

   pdac2ide [-u]  [D5] [D6] [D7] [C5] [C6]

One or more Ides can be listed on the command line.

The -u parameter runs the uninstall only; if it is not given, PDAC will first be uninstalled, then re-installed into each listed IDE.

PDAC2IDE also accepts a -q parameter, for "quiet" mode, that does not write to the console; this is useful for inclusion in batch files.

FixBPR.exe

This is a utility to "fix" the C++ Builder .bpr (project) files. It replaces references to the old (original PDAC release> library names with the correct filenames for the new libraries. The original BPR file is saved as .bpr.old.

FixBPR is installed into the PDAC installation directory (c:\pvsw\SDK\pdac, by default). It can be run from a DOS or CMD box as follows:

    FixBPR 

This utility should be run against all C++ Builder projects developed using the original release of PDAC, so they will build with the correct libraries. It is only useful with projects developed with the earlier PDAC libraries; nothing is added to the BPR files if the old library names are not found. It is not necessary to run this utility on the "default.bpr" files located in the compilers' "bin" directories, as PDAC2IDE.exe performs that function during installation of PDAC.


Deploying PDAC applications

See the text file "pdacdepl.txt," located in the ...\SDK\DOC subdirectory for complete information on deploying applications developed with the Pervasive Direct Access Components.


Known Issues

The following are known issues with this release.

Issue Number Description
52067

Data not displayed for some PDAC properties in Delphi 2005 IDE

The following properties are displayed incorrectly in the Delphi 2005 IDE

TpvSession: servername 
TpvDatabase: Aliasname 
TpvTable: Database 

TpvBatchmove: changetablename, KeyvoilTablename

pvsqlsession: servername 
pvsqldatabase: Aliasname 
Tpvquery: database 
Tpvstoredprocedure: database 

wwpvTable1: Database 
wwpvquery:  Database 
wwpvstoreprocedure: Database 

This issue does not occur when using Delphi 5,6, or 7.

None

Documentation for PDAC in CHM format not updated

Documentation for PDAC in Javahelp and PDF formats will be provided in a subsequent update.


Useful Links


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.

Copyright 1999-2006 Pervasive Software Inc. All Rights Reserved.