Establishing a DTO Session
This topic provides information about establishing a session using the Distributed Tuning Objects:
DtoSession Object
Object DtoSession is the root object for most DTO operations. It represents and manages a connection to a Zen database engine.
Properties
Collections
Objects
Methods
Remarks
A DtoSession object is the starting point for all operations except dictionaries. You use DtoSession to make connection to servers, obtain configuration information such as categories and settings, explore databases and DSNs, and to monitor Zen usage information.
To use DtoSession, first instantiate your object and use the Connect method to specify a server for the session object.
The user name and password you use for the session connect is for the machine only. This does not authenticate you to any Zen database.
Note: If instantiating this object using ASP or if you use the CreateObject method in Visual Basic, the progid of DtoSession is "DTO.DtoSession.2" (DTO version 2) or “DTO.DtoSession.1” (DTO version 1). See
DTO2 for information on the differences between the two versions.
Example
' instantiate session object
Dim my_session as New DtoSession
' connect to a server
result = my_session.Connect("myserver", "username", "password")
' check for good connection using the Error property
if Not (result = Dto_Success)
Then Msgbox"Could not connect to the server. Error was "+ my_session.Error(result)
' now use your session object to obtain
' category and database collections
Dim my_categories as DtoCategories
Dim my_databases as DtoDatabases
Set my_categories = my_session.Categories
Set my_databases = my_session.Databases
See Also
Methods Detail
Connect method
Open a connection to a server.
Syntax
Dim result as DtoResult
result = Object.Connect([server], [username], [password])
Arguments
Return Values
Remarks
Since connections to servers can fail for a variety of reasons, be sure to check the return value for this method and take appropriate action programmatically.
If user name and password are not specified, an attempt will be made to login as a guest. If such an attempt is successful, some functionality will not be available.
Check the isConnected property in order to see whether the session is currently connected.
Examples
Dim result as DtoResult
Dim my_session as New DtoSession
result = my_session.Connect("myserver", "smook", "1234")
Dim result as DtoResult
Dim my_session as New DtoSession
my_session.UserName="smook"
my_session.Password="1234"
my_session.ServerName="myserver"
result = my_session.Connect
Disconnect method
End a connection to a server.
Syntax
result = Object.Disconnect
Arguments
Return Values
Remarks
This method should be called for every server to which you are connected prior to using the session object to connect to another server, or exiting the application.
Example
Dim result as DtoResult
Dim my_session as New DtoSession
result = my_session.Connect("myserver", "username", "pw")
'
' perform operations here
'
result = my_session.Disconnect
GetSetting method
Obtains a DtoSetting object using a setting id.
Syntax
Set my_setting = Object.GetSetting(setting_id)
Arguments
Return Values
Remarks
This method is useful for obtaining a specific setting without having to first obtain a category and then searching through a DtoSettings collection.
Example
Dim oSession As New DtoSession
Dim Result As dtoResult
Result = oSession.Connect("localhost", "", "")
Dim oSetting As DtoSetting
Dim settingFileversion As Integer
settingFileversion = 97
Set oSetting = oSession.GetSetting(settingFileversion)
If oSetting Is Nothing Then
MsgBox "Invalid setting"
Else
Dim new_selections As New DtoSelectionItems
'0 = 9.5 '1 = 9.0 '2 = 8.x '3 = 7.x '4 = 6.x '5 = 13.0
'These are file format values
new_selections.Add oSetting.AllPossibleSelections.GetByID(0)
oSetting.Value = new_selections
End If