Developer Reference : Platform Management : Distributed Tuning Objects (DTO) Guide : Establishing a DTO Session : DtoSession Object
 
DtoSession Object
Object DtoSession is the root object for most DTO operations. It represents and manages a connection to a Zen database engine.
Properties
 
Connected
Returns a Boolean indicating whether the Session object is connected to the Zen engine.
True = connected
False = not connected
Error
Returns the error of the last method call. Pass the result of the method call and a dtoResult string will be returned that explains the error.
See DtoResult for a listing of these error codes.
ServerName
Gets or sets the server name of a DtoSession object.
UserName
Sets the user name for an object.
Password
Sets the password for a session.
Collections
DtoCategories Collection
DtoDatabases Collection
DtoDSNs Collection
Objects
DtoMonitor Object
DtoServices Object
DtoLicenseMgr Object
DtoEngineInformation Object
Methods
Connect method
Disconnect method
GetSetting method
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
DtoCategories Collection
DtoServices Object
DtoMonitor Object
DtoDatabases Collection
DtoDSNs Collection
Methods Detail
Connect method
Open a connection to a server.
Syntax
Dim result as DtoResult
result = Object.Connect([server], [username], [password])
Arguments
Object
DtoSession object
server
(optional) Name of the server to which you want to connect. If omitted, an attempt to connect to the local server is made. You can also first set the ServerName property and call the method without specifying this parameter.
username
(optional) User name for the server. You can also first set the UserName property and call the method without specifying this parameter.
password
(optional) Password for the user. You can also first set the Password property and call the method without specifying this parameter.
Return Values
 
result
DtoResult long value indicating the result of the method call. Use the Error property to obtain a description for the result.
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 username 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
Object
DtoSession object
Return Values
 
result
DtoResult long value indicating the result of the method call. Use the Error property to obtain a description for the result.
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
Object
DtoSession object
setting_id
A valid setting id. Each DtoSetting object has a property SettingID that uniquely identifies it. If you are trying to obtain all settings for a particular category, use the Settings property of the DtoCategory Object. This method is useful if you already know a particular setting you wish to obtain and you have previously stored its setting_id.
Return Values
 
my_setting
DtoSetting object. If the given setting cannot be found, NULL is returned.
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