PDAC Classes, Properties, Events, and Methods
Show this topic in Library frames
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 Borland counterpart components.
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. `NativeError' 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
Note
for Delphi/C++Builder 3 only
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.SQL and some Pervasive.SQL 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.
Btrieve subset
In the Transactional subset, PDAC uses Pervasive.SQL `Named Databases' as aliases.
SQL subset
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 Borland VCL.
TPvSession and TPvSqlSession
- Property `TraceFlags' has been dropped, since tracing of Pervasive.SQL API calls is carried out via an external utility or the Distributed Tuning Interface.
- Pervasive.SQL does not use properties 'NetFileDir' and 'PrivateDir'. For compatibility purposes they are present only as storage for strings.
- Property `Locale' has been dropped, as there is no analog in Pervasive.SQL for this BDE-specific feature.
- Pervasive.SQL has no `driver'. All interfaces items relating to drivers have been 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.
- Method `GetConfigParams' 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. 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. DTI is supported only by Pervasive.SQL 2000 and above.
- New public property `LocalSystem' has been added. For remote servers LocalSystem=false, for local - true.
TPvSession specifics
- 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.
- Method `AddStandardAlias' adds DB name with standard settings: INTEGRITY - True, BOUND - False.
- The type of Property `Handle' has been changed to DRM_SESID.
- Example: Create DBName.
var MyList: TStringList;
begin
MyList := TStringList.Create;
try
with MyList do
begin
Add('DDF_PATH=C:\PVSW\DemoData');
Add('PATH=C:\PVSW\Demodata');
Add('BOUND=False');
Add('INTEGRITY=False');
Add('Create_DDF=False');
end;
PvSession1.AddAlias('TestAlias', MyList);
finally
MyList.Free;
end;
TPvSqlSession specifics
- 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 (`Accelarated'), 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.
- The type of Property `Handle' has been changed to SQLHENV.
- Remote DSNs management is supported only by Pervasive.SQL 2000 SP2a or above. Remote client and user DSNs are not supported.
- Method `AddStandardAlias' adds a Engine DSN with default settings. Second parameter is DB name.
- Property `UpdateDsnType: TDsnTypes' 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;
begin
MyStringList := TStringList.Create;
try
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);
finally
MyStringList.Free;
end;
TPvDatabase and TPvSqlDatabase
- Property `DriverName' has been dropped.
- Properties `Locale' and `TraceFlags' has been dropped (see above).
- Property `TransIsolation' has only 1 value (`tiReadCommitted'), because Pervasive.SQL does not support other isolation levels.
- Property `Tables' has been added. It contains list of tables in database.
- Property `StoredProcs' has been added. It contains list of stored procedures in database.
- Property `LoginPromptOnlyIfNecessary' has been added. Following situations are possible:
- If LoginPrompt=true, LoginPromptIfNecessary=true. Login dialog is displayed only for secured database (after unsuccessful login attempt). This is 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
- The type of Property `Handle' has been changed to DRM_DBID.
- Property `IsSQLBased' is always false.
- Property `Directory' on local servers, i.e. 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 (see above).
- Properties `Tables' and `StoredProcs' have type `TDRMTableCollection'.
- Property `IsSecured: boolean' has been added. It is read only property. IsSecured = True if database has security turned on. In this case Btrieve's owner name in property `TPvTable.Owner' is ignored, and user must authorize in order to login in the DB.
- Property 'OEMConversion' has been 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
- The type of Property `Handle' has been changed to SQLHDBC.
- Property `IsSQLBased' is always true.
- Property 'Directory' always empty. Attempt to set it will cause exception.
- Properties `Tables' and `StoredProcs' have type `TSqlTablesInfoCollection' and `TSqlStoredProcInfoCollection' correspondingly.
- Property `Exclusive' means nothing. It is provided for VCL compatibility only.
- Property `AliasNameIsConnectionString' has been 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
- In all properties/methods/events type TDBDataSet has changed to TPvDataSet or derived.
- In all properties/methods/events type TSession has changed to TPvAbsSession or derived.
- In all properties/methods/events type TDatabase has changed to TPvAbsDatabase or derived.
- Property `ExpIndex' is always false.
- Properties `Locale' and `DBLocale' have been dropped.
- Property `ObjectView' has been dropped.
- Property `Database' with type TPvDatabase or TPvSqlDatabase has been added.
- Method `ConstraintCallBack' has been dropped.
- Method `CheckOpen' parameter type changed to DRM_ERR.
TPvTable specific
- The type of Property `Handle' has been changed to DRM_TABLEID.
- The type of Property `DBHandle' has been changed to DRM_DBID.
- Property `Owner' has been added, representing the Btrieve Owner Name for the table.
- Property `BtrHandle: 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 API 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.
- Function `DirectBtrCall(Op: Smallint; 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 API 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 (see above).
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;
DataLen: word;
Res: integer;
begin
b := PvTable1.GetBookmark();
try
DataLen := 4;
Res := PvTable1.DirectBtrCall(B_GET_DIRECT + 300,
b, DataLen, PvTable1.BtrHandle.pKeyBuf,
PvTable1.BtrHandle.KeyLen,
PvTable1.BtrHandle.KeyNum);
finally
PvTable1.FreeBookmark(b);
end;
end
procedure TForm1.Unlock(Sender: TObject);
var Res: integer;
vr: Word;
begin
vr := 0;
Res := PvTable1.DirectBtrCall(B_UNLOCK, @vr, vr,
@vr, vr, -2);
end
- Property `IndexFiles' has been dropped.
- Property `TableType' has been dropped.
- Property `TableLevel' is ignored.
- Property `UpdateObject' has been dropped.
- Method `CloseIndexFile' has been dropped.
- Methods `OpenIndexFile' has been dropped.
- Methods `LockTable' and `UnlockTable' have been dropped.
- Method `PvCreateTable(PvFieldDefs: TPvFieldDefs)' has been added. It allows the developer to `tune' the table creation process somewhat. See the appropriate section for additional details.
- Method `SetOwnerOnTable(AOwner: string; AccessMode: integer)' 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
- The type of Property `Handle' has been changed to SQLHSTMT.
- The type of Property `DBHandle' has been changed to SQLHDBC.
- Property `StmtHandle' has been dropped.
- Property `Text' always returns text from property `SQL'.
- Method `CheckOpen' has been dropped.
- All index and key related properties and methods (like `GetIndexInfo') have been dropped.
TPvQuery specific
- A new property `LoadBlobOnOpen' has been added. 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.
- A new property 'PassThrough' has been added.
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);
begin
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;
end;
The PassThrough Property is available at Design Time in the IDE, as well.
TPvStoredProc specific
TPvUpdateSQL
TPvBatchMove
- Property `Transliterate' has been dropped.
- Type of property `Destination' has been changed to TPvTable.
