DtoSession Object

Object DtoSession is the root object for most DTO operations. It represents and manages a connection to a Pervasive.SQL database engine.

Properties


Connected	Returns a Boolean indicating whether the Session object is connected to the Pervasive.SQL 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 setings, explore databases and DSNs, and to monitor Pervasive.SQL 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 Pervasive.SQL 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) 
  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

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 my_session as New DtoSession 
Dim result as DtoResult 
result = my_session.Connect("myserver", "username", 
"pw"); 
' stored_id is a variable representing a setting id 
' that your program previously stored 
Dim my_setting as DtoSetting  
Set my_setting = my_session.GetSetting(stored_id);  
If my_setting is Nothing  
then MsgBox "Invalid setting" 
End If