PDAC Classes, Properties, Events, and Methods

PDAC Classes, Properties, Events, and Methods

This section contains a listing of all the classes, properties, events, and methods present in the Pervasive Direct Access Components. All are listed in Pascal notation and show differences with their Embarcadero counterpart components.

•

Exception Classes

•

Supporting Classes

•

General Differences from VCL

•

Specific Class Differences from VCL

•

Pervasive PSQL and Embarcadero Data Type Mappings

•

Btrieve and Embarcadero Data Type Mappings

Exception Classes

Class EPvDatabaseError

This class is an ancestor for all exception classes in PDAC. It has the property Owner that contains a reference to the class that generated the exception.

Class EPvDBEngineError

This is an abstract base class for all DB engine error related classes. Property Errors lists the errors (in classes, derived from the TPvDBError class) and property ErrorCount indicates the total number of errors contained in the Errors property.

Class TPvDBError

TPvDBError is an abstract base class for all classes that represent database engine errors for the EPvDBEngineError exception class. It contains follow properties:

•

Property Message specifies the text of the error message.

•

Property NativeError indicates the status code returned from the engine (the Btrieve status code).

Class EPvDrmEngineError

Exceptions of this class are raised by the Btrieve subset of PDAC. Property ErrorCode is a DRM error code. The Errors array of EPvDrmEngineError contains objects with type TPvDrmError.

Class TPvDrmError

Class TPvDrmError describes a DRM error. In ErrorCode it contains a DRM error code, and in NativeError it contains a Btrieve status code.

Class EPvSqlEngineError

Exceptions of this class are raised by the SQL (relational) subset of PDAC. Property ErrorCode is the return value of the last ODBC call. The Errors array of EPvSqlEngineError contains objects with type TPvSqlError.

Class TPvSqlError

Class TPvSqlError describes ODBC errors.

Class EPvDbAdminEngineError

Exceptions of this class are raised during execution of DBNames and DSN management functions, such as TPvSqlSession.AddAlias, on local and remote servers. It has an additional property ErrorType: TPvDbAdminEngineErrorTypes. If ErrorType = dbmeDTI then NativeError contains a DTI (Distributed Tuning Interface) error code, otherwise NativeError contains local error codes of DBNames and DSN related function (see EPvSqlInstallerEngineError and EPvOwnSqlInstallerEngineError).

Class EPvSqlInstallerEngineError

Exceptions of this class are raised during execution of DNSs management functions, such as TPvSqlSession.AddAlias, on local servers, i.e. if TPvSqlSession.ServerName property is empty or has name of the local server. Errors contains the value, returned by SQLInstallerError() function.

Class EPvOwnSqlInstallerEngineError

Because DSN management functions in some cases lack meaningful errors, exceptions of this class are provided to raised in order to introduce new types of errors. In the NativeError the following values are possible:

•

cPvOwnSqlInstallerEngineErrorDsnAlreadyExist – user tried to create a preexisting DSN.

•

cPvOwnSqlInstallerEngineErrorDsnNotFound – user tried to delete non-existent DSN.

•

cPvOwnSqlInstallerEngineErrorInvalidOpenMode – value of prmOPEN_MODE ('OPEN_MODE') parameter is invalid. See ‘prmOPEN_MODE’ description below for details.

•

cPvOwnSqlInstallerEngineErrorClientDSNsAreNotSupported – client DSNs are not supported in remote server mode (TPvSqlSession.ServerName is not empty).

Supporting Classes

Supporting classes are required by the higher-level components and encapsulate BDE-specific functionality. These classes are “cloned” in PDAC with as few changes as possible.

Class TPvSessionList/TPvSqlSessionList

Classes TPvSessionList and TPvSqlSessionList manage session components in applications that provide multiple sessions. In this class only the types of contained objects (TSession to TPvSession or TPvSqlSession) have been changed.

Class TPvBlobStream/TPvSQLBlobStream

Classes TPvBlobStream and TPvSQLBlobStream are stream objects that let applications read from or write to field objects that represent Binary large object (BLOB) fields. They function in the same way as the TBlobStream VCL class.

Classes TParam/TParams

Class TParam represents a field parameter. Properties of a TParam are used to set the value of a parameter that represents the value of a field. TParams is list of the TParam objects. TParam and TParams in PDAC have no changes in their interface sections; they are only moved to the new file.

Class TMasterDataLink

Note: For Delphi/C++Builder 3 and 4 only

TMasterDataLink allows a dataset to establish a master/detail relationship. It has no changes in its interface section, and is only moved to a new file.

General Differences from VCL

Interfaces exposed by PDAC components correspond almost exactly to the appropriate VCL components, which work via the BDE. More detailed info about related VCL components is contained in the Delphi/C++Builder help system (file del?vcl.hlp or bcbvcl?.hlp, where ? is ‘3’ or ‘4’ or ‘5’). However, since some BDE features do not exist in Pervasive PSQL and some Pervasive PSQL features do not exist in the BDE, Pervasive has corrected these interfaces (dropped or added properties/methods/events). The listing below enumerates only those interfaces that have been changed. All other interfaces are cloned as-is.

Global Variables

Instead of the BDE’s ‘Session’ and ‘Sessions’ global variables, PDAC has its own global variables ‘BtvSession: TPvSession’ and ‘BtvSessions: TPvSessionList’ for the Btrieve subset and ‘PvSqlSession: TPvSqlSession’ and ‘PvSqlSessions: TPvSqlSessionList’ for the relational subset. They behave the same as the Session and Sessions variables and are created automatically on application startup and destroyed automatically on application shutdown.

In the Transactional subset, PDAC uses Pervasive PSQL ‘Named Databases’ as aliases.

In the Relational subset, PDAC uses Data Source Names (DSNs) as aliases.

Specific Class Differences from VCL

The following sections contain specific differences from the Embarcadero VCL.

•

TPvSession and TPvSqlSession

•

TPvSession Specific

•

TPvSqlSession Specific

•

TPvDatabase and TPvSqlDatabase

•

TPvDatabase Specific

•

TPvSqlDatabase Specific

•

TPvTable, TPvQuery, and TPvStoredProc

•

TPvQuery and TPvStoredProc Specific

•

TPvQuery Specific

•

TPvStoredProc Specific

•

•

TPvSession and TPvSqlSession

•

‘TraceFlags’ property was dropped, since tracing of Pervasive PSQL API calls is carried out via an external utility or the Distributed Tuning Interface.

•

Pervasive PSQL does not use the following properties (for compatibility purposes they are present only as storage for strings):

•

•

•

‘Locale’ property was dropped, as there is no analog in Pervasive PSQL for this BDE-specific feature.

•

Pervasive PSQL has no ‘driver’. All interfaces items relating to drivers were dropped (methods ‘AddDriver’, ‘DeleteDriver’, ‘GetAliasDriverName’, ‘GetDriverNames’, ‘GetDriverParams’ and ‘ModifyDriver’).

•

Password-related interfaces only store and retrieve strings (‘AddPassword’, ‘RemovePassword’ and ‘RemoveAllPasswords’). Event ‘OnPassword’ never fires, except in ‘GetPassword’ method.

•

‘GetConfigParams’ method does nothing.

•

New published properties have been added: ‘ServerName’, ‘ServerAdminUser’, ‘ServerAdminPassword’ and ‘ServerAdminLoginPrompt’. They provide the way to connect to remote servers. ‘ServerAdminUser’ and ‘ServerAdminPassword’ are DTI (Distributed Tuning Interface) user name and password.

Tip: For more information see DTI documentation.

•

Property ‘ServerAdminLoginPrompt’ is analog to TPv(Sql)Database.LoginPrompt, except that in design time if ServerAdminLoginPrompt=false and there are problems to get list of DBNames from server, you will be prompted for user name/password after unsuccessful attempt to login.

Tip: DTI is supported only by Pervasive.SQL 2000 and above.

•

‘LocalSystem’ public property.
For remote servers LocalSystem=false, for local – true.

TPvSession Specific

•

All alias management functions perform Named Database management in PDAC. TPvSession allows creating local and remote DBNames and getting parameters for local and remote DBNames. To establish a connection with a database on the server, the user should create a DBName using the path to the database on the server. The developer can use the following values on entrance:

•

prmDDF_PATH ('DDF_PATH') – path to data dictionary files.

•

prmPATH ('PATH') – path to data files.

•

prmBOUND ('BOUND') – is database bound? Default is false.

•

prmINTEGRITY ('INTEGRITY') – is database has integrity constraints? Default is true.

•

prmCREATE_DDF ('CREATE_DDF') – if this parameter is true, then empty database will be created.

•

‘AddStandardAlias’ method adds DB name with standard settings: INTEGRITY – True, BOUND – False.

•

‘Handle’ property type was changed to DRM_SESID.

•

Example: Create DBName.

var MyList: TStringList;

MyList := TStringList.Create;

Add('DDF_PATH=D:\MyDemoData');

Add('PATH=D:\MyDemodata');

Add('BOUND=False');

Add('INTEGRITY=False');

Add('Create_DDF=False');

PvSession1.AddAlias('TestAlias', MyList);

TPvSqlSession Specific

•

All alias management functions do DSN management. User can use follow values on entrance

•

prmDB_NAME (‘DB’) – DB name for database. Engine DSN specific.

•

prmDSN_DESCRIPTION (‘DESCRIPTION’) – description for DSN.

•

prmIS_ENGINE_DSN ('IS_ENGINE_DSN') – determines, is the given DSN Engine DSN (True) or Client DSN (False).

•

prmIS_SYSTEM_DSN ('IS_SYSTEM_DSN') – determines, if the given DSN is System DSN (True) or User DSN (False).

•

prmOPEN_MODE (‘OPEN_MODE’) – determines open mode for DSN. Possible values are: prmOPEN_MODE_normal (‘Normal’), prmOPEN_MODE_accelerated (‘Accelerated’), prmOPEN_MODE_readonly (‘ReadOnly’) and prmOPEN_MODE_exclusive (‘Exclusive’). Engine DSN specific.

•

prmSERVER_NAME ('SERVER_NAME') – the address of the server or host name and the port number where the data resides. Client DSN specific.

•

prmTCP_PORT ('TCP_PORT') – TCP port on server. Client DSN specific.

•

prmSERVER_DSN ('SERVER_DSN') – the name of an Engine DSN on server. Client DSN specific.

•

prmTRANSPORT_HINT ('TRANSPORT_HINT') – contains transport hint. Client DSN specific. Possible values: ‘TCP’, ‘SPX’, ‘TCP:SPX’ or ‘SPX:TCP’.

•

prmARRAY_FETCH_ON ('ARRAY_FETCH_ON') – enables array fetching (True/False). Client DSN specific.

•

prmARRAY_BUFFER_SIZE ('ARRAY_BUFFER_SIZE') – size of the array buffer. Values between 1 and 64KB are acceptable. Client DSN specific.

•

‘Handle’ property type was changed to SQLHENV.

•

Remote DSNs management is supported only by Pervasive.SQL 2000 SP2a or above. Remote client and user DSNs are not supported.

•

‘AddStandardAlias’ method adds a Engine DSN with default settings. Second parameter is DB name.

•

‘UpdateDsnType: TDsnTypes’ property has been added. ‘TDsnTypes = (dsnSystem, dsnUser)’. ‘UpdateDsnType’ means:

•

In case of ‘DeleteAlias’ function – which DSN user is going to delete: System or User DSN.

•

In case of ‘AddAlias’ and ‘GetAliasParameters’ functions – hints which DSN type we prefer.

•

Sample program how to create system client DSN:

var MyStringList: TStringList;

MyStringList := TStringList.Create;

MyStringList.Clear();

MyStringList.Add('IS_ENGINE_DSN=False');

MyStringList.Add('IS_SYSTEM_DSN=True');

MyStringList.Add('SERVER_NAME=ServerName');

MyStringList.Add('SERVER_DSN=DEMO1');

// DSN on the Server

PvSqlSession1.AddAlias('ATest', MyStringList);

MyStringList.Free;

TPvDatabase and TPvSqlDatabase

•

ODBCPacketSize property is an SQLUINTEGER value that specifies the network packet size in bytes. It is used in SQLSetConnectAttr() to set the SQL_ATTR_PACKET_SIZE attribute that governs aspects of connections.

Tip: For more information on SQLSetConnectAttr(), please refer to Microsoft ODBC Programmer's Reference.

•

The following properties were dropped:

•

•

•

•

‘TransIsolation’ property has only 1 value (‘tiReadCommitted’), because Pervasive PSQL does not support other isolation levels.

•

‘Tables’ property was added. It contains list of tables in database.

•

‘StoredProcs’ property was added. It contains list of stored procedures in database.

•

‘LoginPromptOnlyIfNecessary’ was added. Following situations are possible:

•

If LoginPrompt=true, LoginPromptIfNecessary=true. Login dialog is displayed only for secured database (after unsuccessful login attempt). This is the default behavior.

•

If LoginPrompt=true, LoginPromptIfNecessary=false. Login dialog is displayed always before login attempt. This is VCL's TDatabase behavior. The most suitable for secured databases. Provides fastest way to login.

•

If LoginPrompt=false, LoginPromptIfNecessary=true/false (not matter). Login dialog is never displayed. User can implement own login dialog.

TPvDatabase Specific

•

‘Handle’ property has been changed to DRM_DBID.

•

‘IsSQLBased’ property is always false.

•

‘Directory’ property on local servers (that is, if TPvSession.ServerName property is empty or has name of the local server) contains path to database's data dictionary files. For remote servers it is always empty. In both cases attempt to set it will cause exception. You could know if you work with local or remote server by examining property TPvSession.LocalSystem.

•

The following properties have type ‘TDRMTableCollection’:

•

•

•

‘IsSecured property added ‘boolean’. It is read-only property. IsSecured = True if database has security turned on. In this case the transactional database engine owner name in property ‘TPvTable.Owner’ is ignored, and user must authorize in order to login in the DB.

•

’OEMConversion’ property are added.

This property indicates that the database contains characters encoded according to the OEM (DOS) code page, and that these characters should be converted to the ANSI (Windows) code page before use. The database remains in the OEM code page, but all reads and writes of character data are translated by PDAC.

This conversion uses the mapping provided by the Windows OemToCharBuff and CharToOemBuff functions. It is important to note that not all characters are round-trip convertible. Only the characters present in both the OEM and ANSI code pages will be preserved in an update. As a rule of thumb, most of the alphabetic characters are preserved, but other types of characters, such as the box-drawing characters, may not be. For characters that cannot be preserved exactly, the closest look-alike character is chosen. For example, the box-drawing characters are replaced by plus (+), minus (-), and pipe (|).

Currently, only characters stored in user tables are converted. Metadata (stored in DDF files) such as table, column, and file names are not.

TPvSqlDatabase Specific

•

‘Handle’ property type was changed to SQLHDBC.

•

‘IsSQLBased’ property is always true.

•

'Directory' property is always empty. Attempt to set it will cause an exception.

•

The following properties have type ‘TSqlTablesInfoCollection’ and ‘TSqlStoredProcInfoCollection’ correspondingly.

•

•

•

‘Exclusive’ property means nothing. It is provided for VCL compatibility only.

•

‘AliasNameIsConnectionString’ property was added. This property provides possibility for DSN-less connections. If AliasNameIsConnectionString=true, then AliasName (or DatabaseName, if AliasName is empty) is connection string.

TPvTable, TPvQuery, and TPvStoredProc

•

TDBDataSet properties/methods/events types have changed to TPvDataSet or derived.

•

TSession properties/methods/events type have changed to TPvAbsSession or derived.

•

TDatabase properties/methods/events type have changed to TPvAbsDatabase or derived.

•

‘ExpIndex’ property is always false.

•

The following properties were dropped.

•

•

•

•

‘Database’ property with type TPvDatabase or TPvSqlDatabase was added.

•

‘ConstraintCallBack’ was dropped.

•

‘CheckOpen’ method’s parameter type was changed to DRM_ERR.

TPvTable Specific

•

‘Handle’ property type was changed to DRM_TABLEID.

•

T‘DBHandle’ property type was changed to DRM_DBID.

•

‘Owner’ property was added, representing the Btrieve Owner Name for the table.

•

‘BtrHandle property: TBtrieveInfo’ has been added. This is helper property for function DirectBtrCall. TBtrieveInfo contains the following fields:

•

pKeyBuf – pointer to key buffer;

•

KeyLen – key length;

•

KeyNum – key number;

•

CurFilter – pointer to formed input data buffer structure for extended operations (see GetNextExtended in the Btrieve Programmer’s Reference). This buffer also contains the current filter.

•

CurFilterLen – length of CurFilter buffer. CurFilterLen is useful when developer want to copy CurFilter data from the buffer to another location in memory.

•

‘DirectBtrCall(Op: Smallint function; pDataBuf: Pointer; var DataLen: Word; pKeyBuf: Pointer; KeyLen: Byte; KeyNum: Shortint): integer’ has been added. It allows developers to call Btrieve directly, using the TpvTable’s ‘Position Block’. It has the following parameters:

•

Op – Btrieve operation. See Btrieve Programmer’s Reference;

•

pDataBuf – analog for the data buffer parameter of BTRCALL;

•

DataLen – analog for the data buffer length parameter of BTRCALL;

•

pKeyBuf – analog for the key buffer parameter of BTRCALL;

•

KeyLen –length of the key buffer;

•

KeyNum – analog for the key number parameter of BTRCALL.

DirectBtrCall returns the Btrieve status code. pKeyBuf, KeyLen and KeyNum parameters should be taken from PvTable.BtrHandle property.

Small samples below demonstrate how to lock and unlock the current record via direct calls to Btrieve:

procedure TForm1.Lock(Sender: TObject);

var b: TBookmark;

b := PvTable1.GetBookmark();

Res := PvTable1.DirectBtrCall(B_GET_DIRECT + 300, b, DataLen, PvTable1.BtrHandle.pKeyBuf, PvTable1.BtrHandle.KeyLen, PvTable1.BtrHandle.KeyNum);

PvTable1.FreeBookmark(b);

procedure TForm1.Unlock(Sender: TObject);

var Res: integer;

Res := PvTable1.DirectBtrCall(B_UNLOCK, @vr, vr, @vr, vr, -2);

•

‘IndexFiles’ property has been dropped.

•

‘TableType’ property has been dropped.

•

‘TableLevel’ property is ignored.

•

‘UpdateObject’ property has been dropped.

•

The following methods have been dropped.

•

‘CloseIndexFile’

•

‘OpenIndexFile’

•

‘LockTable’

•

‘UnlockTable’

•

‘PvCreateTable(PvFieldDefs: TPvFieldDefs)’ method has been added. It allows the developer to tune the table creation process somewhat. See the appropriate section for additional details.

•

‘SetOwnerOnTable(AOwner: string; AccessMode: integer)’ method has been added. It allows the developer to set the Btrieve owner name on a table. ‘AccessMode’ can be:

•

B_ACCESS_RWOWNER – requires an owner name for any access mode (no data encryption).

•

B_ACCESS_WOWNER – permits read-only access without an owner name (no data encryption).

•

B_ACCESS_RWOWNERENCRYPT – requires an owner name for any access mode (with data encryption).

•

B_ACCESS_WOWNERENCRYPT – permits read-only access without an owner name (with data encryption).

TPvQuery and TPvStoredProc Specific

•

‘Handle’ property type was changed to SQLHSTMT.

•

‘DBHandle’ property type was changed to SQLHDBC.

•

‘StmtHandle’ was dropped.

•

‘Text’ property always returns text from property ‘SQL’.

•

‘CheckOpen’ method was dropped.

•

All index and key related properties and methods (like ‘GetIndexInfo’) were dropped.

TPvQuery Specific

The following properties were added:

•

‘LoadBlobOnOpen’

If ‘LoadBlobOnOpen’ is true, then all BLOBs will be cached in memory on query open. If ‘LoadBlobOnOpen’ is false, then BLOBs will be read as required.

•

’PassThrough’

Setting this property true will force PDAC to pass the SQL Text directly to the engine, without the pre-parsing that is ordinarily done to bind parameters. This is necessary when, for instance, creating Stored Procedures with parameters. Use the property as follows:

procedure TForm1.Button1Click(Sender: TObject);

PvQuery1.SQL.Clear;

PvQuery1.SQL.Add('CREATE PROCEDURE TestPr(IN :A INTEGER) AS');

PvQuery1.SQL.Add('BEGIN');

PvQuery1.SQL.Add('PRINT :A;');

PvQuery1.SQL.Add('END');

PvQuery1.PassThrough := True;

PvQuery1.ExecSQL;

PvQuery1.PassThrough := False;

The PassThrough Property is available at Design Time in the IDE, as well.

TPvStoredProc Specific

•

‘Overload’ property was dropped.

•

TQuery property type (for all properties) has been changed on TPvQuery.

•

‘Transliterate’ property was dropped.

•

‘Destination’ property type was changed to TPvTable.