Pervasive PSQL v9 Distributed Tuning Objects (DTO) - May 2006

This document contains the following topics:

About DTO
Features
System Requirements
Getting Started
- Installation
- Components List
Known Issues
Useful Links
Disclaimer

About DTO

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.

Features

Pervasive PSQL v9 DTO

This update provides support for DTI features added in Pervasive PSQL v9 and Pervasive.SQL V8 (8.5).

New Methods in DtoDatabase that enable manipulation of secured databases and the ability to copy a database while preserving referential integrity.
Open, Close, Secure, UnSecure, Copy.
New Secured property in DtoDatabase
Reveals whether a database has security enabled.

Working with Secured Databases in DTO

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 the 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 Open or 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 Secure or UnSecure methods.

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

Copying a Database with DTO

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")

DTO and DTO2 Object Summary

Connection Object

DtoSession

Configuration Objects

DtoCategory

DtoSetting

DtoSelectionItem

DtoServices

DtoLicenseMgr - DTO2 only

Monitoring Objects

DtoMonitor

DtoOpenFile

DtoFileHandle

DtoMkdeClient

DtoMkdeClientHandle

DtoSqlClient

DtoCommStat

DtoProtocolStat

DtoMkdeVersion - DTO2 only

DtoEngineInformation - DTO2 only

Database and Dictionary Objects

DtoDatabase

DtoDSN

DtoDictionary - deprecated in favor of DtoDatabase

DtoTable

DtoColumn

DtoIndex

DtoSegment

System Requirements

Existing install of Pervasive PSQL v9 Engine

Getting Started

Installation

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.

Components List

Component	Description
DTO2.DLL	Use if you utilize Pervasive PSQL secure database or need the `DtoMkdeVersion` and `DtoLicenseMgr` objects.
DTO.DLL	Use if you want compatibility with older DTO applications.

Component

Description

DTO2.DLL

Use if you utilize Pervasive PSQL secure database or need the DtoMkdeVersion and DtoLicenseMgr objects.

DTO.DLL

Use if you want compatibility with older DTO applications.

Known Issues in this Release

The following are known issues with this release.

Issue Number	Description
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: `PvGetTableStat()`, database flags indicating the Btrieve security policy of the database (`P_DBFLAG_DBSEC_AUTHENTICATION`, `P_DBFLAG_DBSEC_AUTHORIZATION`).
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 `DtoDatabase` object does not contain the `AddTable` and `RemoveTable` methods found in the `DtoDictionary` object. To add or remove a table from a database with this release, you must use the deprecated `DtoDictionary` object.
54011	The `Secure` and `UnSecure` methods in `DtoDatabase` do not have errors mapped to DtoResult. Any result other than success will report as "Unknown error".

Useful Links

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.

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.