mime-version: 1.0 date: Fri, 25 Jun 2010 16:37:03 -0500 content-transfer-encoding: quoted-printable content-location: http://ww1.pervasive.com/developerzone/access_methods/readme_dto.html x-mimeole: Produced By Microsoft MimeOLE V6.00.2900.5931 from: subject: Pervasive PSQL DTO Interface content-type: text/html; charset="Windows-1252" Readme DTO Interfa= ce v9

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

This document contains the following topics:

About DTO

Distributed Tuning Objects are the COM wrapper for the Pervasive Distri= buted=20 Tuning Interface. DTO is a collection of objects encapsulating DTI. DTO en= ables=20 developers to develop a range of useful, customized server administration = tools=20 and interfaces quickly and easily. The power and flexibility of DTO can be= =20 applied to the full range of database management and database definition t= asks=20 such as production, performance tuning, and metadata administration. DTO i= s=20 implemented as a dual interface, in-process server.

Features

Pervasive PSQL v9 DTO

This update provides support for DTI features added in Pervasive PSQL v= 9 and=20 Pervasive.SQL V8 (8.5).=20

Working with Secured Databases in DTO

This release of DTO has updates that reflect the changes that were=20 implemented in the DTI interface for Pervasive PSQL v9. The=20 DtoDictionary object is deprecated in this release. You can s= till=20 open a dictionary using a path, but no longer using the DB name. The new=20 preferred way is to instantiate a DtoDatabase object and invo= ke the=20 Open method to authenticate to the database. You can then acc= ess=20 the Tables collection from the DtoDatabase objec= t. You=20 should invoke the Open method whether or not the database has= =20 security enabled. If security is not enabled, pass empty strings for the=20 database username and password.=20

If you obtain a DtoDatabase object from the=20 DtoDatabases collection, you cannot use the Open= or=20 Close methods or obtain the Tables collection. Y= ou=20 must specifically instantiate any DtoDatabase object for whic= h you=20 want to obtain the Tables collection. The sample in this read= me=20 shows examples of working with secured databases.=20

You cannot have an open connection to the database when invoking the=20 Secure or UnSecure methods.=20

The following code is a Visual Basic sample of connecting to a secure=20 database and obtaining the Tables collection. This sample has= two=20 parts that demonstrate the new security features of the Distributed Tuning= =20 Objects. Part 1 displays information about each database on the current ma= chine,=20 including whether it is secured. An attempt is made to connect to the data= base=20 without credentials. If successful, the tables in that database are listed= . Part=20 2 focuses on the DEMODATA database included with Pervasive PSQL The databa= se is=20 secured, and then opened with the security credentials. Assuming success, = the=20 tables are listed as in Part 1 and then DEMODATA is closed and then unsecu= red. 


' START OF DTO VISUAL BASIC SCRIPT
' Save as dtosample.vbs and run from
' a command prompt by entering:=20
' Cscript dtosample.vbs

 Set m_session =3D CreateObject("DTO.DtoSession.2")=20

   server   =3D "127.0.0.1"    ' local machine

   username =3D ""
   password =3D ""
  =20
   result =3D m_session.Connect(server, username, password)
       =20
   if not(result =3D 0) then
      result_text =3D m_session.Error(result)
      Wscript.Echo "ERROR DURING CONNECT - result was " & result &=
 " - " & result_text =20
    =20
   else=20

     Wscript.Echo "Distributed Tuning Objects - Pervasive PSQL v9 SDK Samp=
le"=20
     Wscript.Echo "=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D" & vbcrlf
           =20
           =20
     ' PART 1: New DtoDatabase Property and Methods

     Wscript.Echo "Part 1: Information about Databases" & vbcrlf

       Set m_databases =3D m_session.Databases
           =20
     ' Important - if you access Tables collection, or use Open and Close =
methods,
     '             you must instantiate the DtoDatabase object
       Set m_dtodatabase =3D CreateObject("DTO.DtoDatabase.2")

       m_dtodatabase.Session =3D m_session

       Wscript.Echo "Number of databases =3D " & m_databases.Count &am=
p; vbcrlf

       for each database in m_databases

         Wscript.Echo "DB Name   : " & database.Name=20
         Wscript.Echo "Secured   : " & Cbool(database.Secured)
         Wscript.Echo "Data Path : " & database.DataPath
         Wscript.Echo "Dict Path : " & database.DdfPath

         m_dtodatabase.Name =3D database.Name  '=
  database is variant, m_dtodatabase
                                             '  is needed to Open/Close, a=
ccess Tables

         result =3D m_dtodatabase.Open("","")  '=
  Try to open with no credentials

         if (result =3D 0) then
             set tables_collection =3D m_dtodatabase.Tables
             Wscript.Echo "Tables in " & m_dtodatabase.Name & ": "=
 & tables_collection.Count

             for each table in tables_collection
                Wscript.Echo vbtab & table.Name=20
             next
             Wscript.Echo
             m_dtodatabase.Close   '  Close any =
database you open

         else=20
              Wscript.Echo "Could not display " & m_dtodatabase.Name &=
amp; " tables - error " & result =20
              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 =3D "DEMODATA"
       m_dtodatabase.Session =3D m_session
       Wscript.Echo "Demodata secured =3D " & CBool(m_dtodatabase.Secu=
red)
 =20
      
     ' SECURE METHOD
       Wscript.Echo vbcrlf & "Secure method"
       Wscript.Echo "name =3D " & m_dtodatabase.Name & ", data pat=
h =3D " & m_dtodatabase.DataPath
       result =3D m_dtodatabase.Secure("Master", "123")  ' =20
       Wscript.Echo "result of SECURE db =3D " & result & ": " &am=
p; m_session.Error(result)
       Wscript.Echo "Demodata secured =3D " & CBool(m_dtodatabase.Secu=
red)

      
     ' OPEN METHOD
       Wscript.Echo vbcrlf & "Open method"
       Wscript.Echo "name =3D " & m_dtodatabase.Name & ", data pat=
h =3D " & m_dtodatabase.DataPath
       result =3D m_dtodatabase.Open("Master","123")
       Wscript.Echo "result of open database =3D " & result & ": "=
  & m_session.Error(result)
     =20
      
     ' TABLES COLLECTION FROM DTODATABASE

       Wscript.Echo vbcrlf & "Database Tables collection"

       if (result =3D 0) then
           Set my_tables =3D m_dtodatabase.Tables  =20
           Wscript.Echo vbcrlf & "number of Tables in demodata =3D " &=
amp; my_tables.Count

           For each table in my_tables
             Wscript.Echo table.Name=20
           Next

       else
          Wscript.Echo "Could not obtain Tables collection because Open me=
thod did not succeed"=20
       end if   =20
  =20
      
     ' CLOSE METHOD
       Wscript.Echo vbcrlf & "Close method"
       result =3D m_dtodatabase.Close
       Wscript.Echo "Result of close database =3D " & result & ": =
"  & m_session.Error(result)

      
     ' UNSECURE METHOD
       Wscript.Echo vbcrlf & "Unsecure"
       Wscript.Echo "name =3D " & m_dtodatabase.Name & ", data pat=
h =3D " & m_dtodatabase.DataPath
       result =3D m_dtodatabase.UnSecure("Master", "123")
       Wscript.Echo "Result of UNSECURE db =3D " & result & ": " &=
amp; m_session.Error(result)
       Wscript.Echo "Demodata secured =3D " & CBool(m_dtodatabase.Secu=
red)

 end if ' If session connected =3D OK



 Set m_dtodatabase =3D Nothing
 Set m_session =3D Nothing


' END OF DTO SAMPLE SCRIPT

Copying a Database with DTO

The following code segment demonstrates the use of the=20 DtoDatabase Copy method. 

  =20
   result =3D m_session.Connect(server, username, password)
           =20
 ' Copying a Database
 ' result =3D m_database.Copy("username","password","newD=
Bname","newDictionaryPath","NewDataPath")

   Set m_databases =3D m_session.Databases
   Set m_dtodatabase =3D CreateObject("DTO.DtoDatabase.2")
   m_dtodatabase.Session =3D m_session
   m_dtodatabase.Name =3D "DEMODATA"
           =20
 ' 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 =3D m_dtodatabase.Copy("","", "DEMODATA2", "c:\pvsw\demodata2", =
"c:\pvsw\demodata2")=20
           =20
 ' Copy a secure database
 ' Database does not need to be opened.  New database copy will also be se=
cure.
   result =3D m_dtodatabase.Copy("Master","123", "DEMODATA3", "c:\pvsw\dem=
odata3", "c:\pvsw\demodata3") =20

DTO and DTO2 Object Summary

System Requirements

Getting Started

Installation

There is no separate install for DTO. The DTO runtime binaries listed u= nder=20 the Components List are installed by the PSQL engine installation. PSQL v9= SP2=20 DTO SDK is available for download at=20 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=20 DtoMkdeVersion and DtoLicenseMgr objects.

DTO.DLL

 

Use if you want compatibility with older DTO=20 applications.

Known Issues in this Release

The following are known issues with this release.

Issue Number Description
52546 DtoSession.Property(dtoAccessRights),=20 DtoSession.Property(dtoConnectionType), DtoLicenseMgr.Licenses colle= ction=20 appear in object browser but are not implemented in this release.
52548 DTO does not have the following DTI functionality:=20 PvGetTableStat(), database flags= =20 indicating the Btrieve security policy of the database (P_DBFLAG_DBSEC_AUTHENTICATION,=20 P_DBFLAG_DBSEC_AUTHORIZATION).
53074 Many possible DTO errors are not in the enumerated t= ype=20 DtoResult nor are descriptions returnable from the Error function. E= rror=20 codes are returned but there are no corresponding error messages.
53113 The Databases.Remove me= thod=20 returns Dto_Success even when it fails = or when=20 it fails to delete the "in-use" DDF files
54010 The updated DtoDatabase= =20 object does not contain the AddTable and=20 RemoveTable methods found in the= =20 DtoDictionary object. To add or = remove a=20 table from a database with this release, you must use the deprecated= =20 DtoDictionary object.
54011 The Secure and=20 UnSecure methods in DtoDatabase do not have errors mapped to Dto= Result.=20 Any result other than success will report as "Unknown error".=20

Useful Links

Discuss all your Pervasive development issues at DevTalk at http://www.pervasive.com/devtalk= .=20

See some creative applications and code snippets and share your own at= =20 Pervasive ComponentZone at http://www.pervasive.com/c= omponentzone.=20

Disclaimer

PERVASIVE SOFTWARE INC. LICENSES THE SOFTWARE AND DOCUME= NTATION=20 PRODUCT TO YOU OR YOUR COMPANY SOLELY ON AN "AS IS" BASIS AND SOLELY IN=20 ACCORDANCE WITH THE TERMS AND CONDITIONS OF THE ACCOMPANYING LICENSE=20 AGREEMENT.
PERVASIVE SOFTWARE INC. MAKES NO OTHER WARRANTIES WHATSOEVER= ,=20 EITHER EXPRESS OR IMPLIED, REGARDING THE SOFTWARE OR THE CONTENT OF THE=20 DOCUMENTATION; PERVASIVE SOFTWARE INC. HEREBY EXPRESSLY STATES AND YOU OR = YOUR=20 COMPANY ACKNOWLEDGES THAT PERVASIVE SOFTWARE INC. DOES NOT MAKE ANY WARRAN= TIES,=20 INCLUDING, FOR EXAMPLE, WITH RESPECT TO MERCHANTABILITY, TITLE, OR FITNESS= FOR=20 ANY PARTICULAR PURPOSE OR ARISING FROM COURSE OF DEALING OR USAGE OF TRADE= ,=20 AMONG OTHERS.

Copyright =A9 1999-2006 Pervasive Software Inc. All Rig= hts=20 Reserved.