This document contains the following topics:
Distributed Tuning Objects are the COM wrapper for the Pervasive Distributed Tuning Interface. DTO is a collection of objects encapsulating DTI. DTO enables developers to develop a range of useful, customized server administration tools and interfaces quickly and easily. The power and flexibility of DTO can be applied to the full range of database management and database definition tasks such as production, performance tuning, and metadata administration. DTO is implemented as a dual interface, in-process server.
This update provides support for DTI features added in Pervasive PSQL v9 and Pervasive.SQL V8 (8.5).
DtoDatabasethat enable manipulation of secured databases and the ability to copy a database while preserving referential integrity.
Reveals whether a database has security enabled.
This release of DTO has updates that reflect the changes that were
implemented in the DTI interface for Pervasive PSQL v9. The
DtoDictionary object is deprecated in this release. You can still
open a dictionary using a path, but no longer using the DB name. The new
preferred way is to instantiate a
DtoDatabase object and invoke the
Open method to authenticate to the database. You can then access
Tables collection from the
DtoDatabase object. You
should invoke the
Open method whether or not the database has
security enabled. If security is not enabled, pass empty strings for the
database username and password.
If you obtain a
DtoDatabase object from the
DtoDatabases collection, you cannot use the
Close methods or obtain the
Tables collection. You
must specifically instantiate any
DtoDatabase object for which you
want to obtain the
Tables collection. The sample in this readme
shows examples of working with secured databases.
You cannot have an open connection to the database when invoking the
The following code is a Visual Basic sample of connecting to a secure
database and obtaining the
Tables collection. This sample has two
parts that demonstrate the new security features of the Distributed Tuning
Objects. Part 1 displays information about each database on the current machine,
including whether it is secured. An attempt is made to connect to the database
without credentials. If successful, the tables in that database are listed. Part
2 focuses on the DEMODATA database included with Pervasive PSQL The database is
secured, and then opened with the security credentials. Assuming success, the
tables are listed as in Part 1 and then DEMODATA is closed and then unsecured.
' START OF DTO VISUAL BASIC SCRIPT ' Save as dtosample.vbs and run from ' a command prompt by entering: ' Cscript dtosample.vbs Set m_session = CreateObject("DTO.DtoSession.2") server = "127.0.0.1" ' local machine username = "" password = "" result = m_session.Connect(server, username, password) if not(result = 0) then result_text = m_session.Error(result) Wscript.Echo "ERROR DURING CONNECT - result was " & result & " - " & result_text else Wscript.Echo "Distributed Tuning Objects - Pervasive PSQL v9 SDK Sample" Wscript.Echo "========================================================" & vbcrlf ' PART 1: New DtoDatabase Property and Methods Wscript.Echo "Part 1: Information about Databases" & vbcrlf Set m_databases = m_session.Databases ' Important - if you access Tables collection, or use Open and Close methods, ' you must instantiate the DtoDatabase object Set m_dtodatabase = CreateObject("DTO.DtoDatabase.2") m_dtodatabase.Session = m_session Wscript.Echo "Number of databases = " & m_databases.Count & vbcrlf for each database in m_databases Wscript.Echo "DB Name : " & database.Name Wscript.Echo "Secured : " & Cbool(database.Secured) Wscript.Echo "Data Path : " & database.DataPath Wscript.Echo "Dict Path : " & database.DdfPath m_dtodatabase.Name = database.Name ' database is variant, m_dtodatabase ' is needed to Open/Close, access Tables result = m_dtodatabase.Open("","") ' Try to open with no credentials if (result = 0) then set tables_collection = m_dtodatabase.Tables Wscript.Echo "Tables in " & m_dtodatabase.Name & ": " & tables_collection.Count for each table in tables_collection Wscript.Echo vbtab & table.Name next Wscript.Echo m_dtodatabase.Close ' Close any database you open else Wscript.Echo "Could not display " & m_dtodatabase.Name & " tables - error " & result Wscript.Echo m_session.Error(result) & vbcrlf ' display error text end if next ' PART 2: New Security methods applied to DEMODATA database Wscript.Echo "Part 2: New DtoDatabase Methods: Secure, Open, Close, UnSecure" & vbcrlf m_dtodatabase.Name = "DEMODATA" m_dtodatabase.Session = m_session Wscript.Echo "Demodata secured = " & CBool(m_dtodatabase.Secured) ' SECURE METHOD Wscript.Echo vbcrlf & "Secure method" Wscript.Echo "name = " & m_dtodatabase.Name & ", data path = " & m_dtodatabase.DataPath result = m_dtodatabase.Secure("Master", "123") ' Wscript.Echo "result of SECURE db = " & result & ": " & m_session.Error(result) Wscript.Echo "Demodata secured = " & CBool(m_dtodatabase.Secured) ' OPEN METHOD Wscript.Echo vbcrlf & "Open method" Wscript.Echo "name = " & m_dtodatabase.Name & ", data path = " & m_dtodatabase.DataPath result = m_dtodatabase.Open("Master","123") Wscript.Echo "result of open database = " & result & ": " & m_session.Error(result) ' TABLES COLLECTION FROM DTODATABASE Wscript.Echo vbcrlf & "Database Tables collection" if (result = 0) then Set my_tables = m_dtodatabase.Tables Wscript.Echo vbcrlf & "number of Tables in demodata = " & my_tables.Count For each table in my_tables Wscript.Echo table.Name Next else Wscript.Echo "Could not obtain Tables collection because Open method did not succeed" end if ' CLOSE METHOD Wscript.Echo vbcrlf & "Close method" result = m_dtodatabase.Close Wscript.Echo "Result of close database = " & result & ": " & m_session.Error(result) ' UNSECURE METHOD Wscript.Echo vbcrlf & "Unsecure" Wscript.Echo "name = " & m_dtodatabase.Name & ", data path = " & m_dtodatabase.DataPath result = m_dtodatabase.UnSecure("Master", "123") Wscript.Echo "Result of UNSECURE db = " & result & ": " & m_session.Error(result) Wscript.Echo "Demodata secured = " & CBool(m_dtodatabase.Secured) end if ' If session connected = OK Set m_dtodatabase = Nothing Set m_session = Nothing ' END OF DTO SAMPLE SCRIPT
The following code segment demonstrates the use of the
DtoDatabase Copy method.
result = m_session.Connect(server, username, password) ' Copying a Database ' result = m_database.Copy("username","password","newDBname","newDictionaryPath","NewDataPath") Set m_databases = m_session.Databases Set m_dtodatabase = CreateObject("DTO.DtoDatabase.2") m_dtodatabase.Session = m_session m_dtodatabase.Name = "DEMODATA" ' New dictionary path must already exist. If data path is empty, it will be set to ' the same value as the dictionary path. ' Copy an unsecure database result = m_dtodatabase.Copy("","", "DEMODATA2", "c:\pvsw\demodata2", "c:\pvsw\demodata2") ' Copy a secure database ' Database does not need to be opened. New database copy will also be secure. result = m_dtodatabase.Copy("Master","123", "DEMODATA3", "c:\pvsw\demodata3", "c:\pvsw\demodata3")
DtoLicenseMgr - DTO2 only
DtoMkdeVersion - DTO2 only
DtoEngineInformation - DTO2 only
DtoDictionary - deprecated in favor of DtoDatabase
There is no separate install for DTO. The DTO runtime binaries listed under the Components List are installed by the PSQL engine installation. PSQL v9 SP2 DTO SDK is available for download at http://www.pervasive.com/developerzone/access_methods/dtidto.asp.
Use if you utilize Pervasive PSQL secure database or need the
Use if you want compatibility with older DTO applications.
The following are known issues with this release.
|52546||DtoSession.Property(dtoAccessRights), DtoSession.Property(dtoConnectionType), DtoLicenseMgr.Licenses collection appear in object browser but are not implemented in this release.|
|52548||DTO does not have the following DTI functionality:
|53074||Many possible DTO errors are not in the enumerated type DtoResult nor are descriptions returnable from the Error function. Error codes are returned but there are no corresponding error messages.|
|53113||The Databases.Remove method returns Dto_Success even when it fails or when it fails to delete the "in-use" DDF files|
|54010||The updated |
Discuss all your Pervasive development issues at DevTalk at http://www.pervasive.com/devtalk.
See some creative applications and code snippets and share your own at Pervasive ComponentZone at http://www.pervasive.com/componentzone.
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
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.