DtoDatabase Object
Properties
 
Gets or sets the database code page. This property is an enumeration. See Database Code Page for a list of values. The value zero specifies the server encoding (the code page of the server running the database engine).
Collections
DtoTables Collection
Methods
AddUserToGroup
AlterUserName
AlterUserPassword
Close
Copy
CreateGroup
CreateUser
DropGroup
DropUser
Open
RemoveUserFromGroup
Secure
UnSecure
Remarks
The Secure and UnSecure methods can only be used when the database is closed.
Examples
The following example shows how to instantiate the session object and connect to the server.
’ instantiate session object and connect to server
Dim my_session as New DtoSession
Dim result as DtoResult
result = my_session.Connect("myserver", "username", "password")
 
’ now use your session object to obtain db collection
Dim my_databases as DtoDatabases
Set my_databases = my_session.Databases
 
’ get first database and query its dictionary path
Dim first_database as DtoDatabase
Dim dictionarypath as string
Set first_database = my_databases(1)
dictionarypath = first_database.DdfPath
 
The following example shows how to retrieve and set a code page using the DBCodePage property with the “Demodata” sample database.
Dim m_dtoSession1 As New DtoSession
Dim result As dtoResult
result = m_dtoSession1.Connect("localhost", "", "")
Dim sCodePage As String
sCodePage = m_dtoSession1.Databases("DEMODATA").DBCodePage
MsgBox "Code Page for database (before change): " & CStr(sCodePage)
If result = Dto_Success Then
Rem Set the code page for the database by passing in
Rem the code page number (for example, 0, 932, 1252,
Rem and so forth).
m_dtoSession1.Databases("DEMODATA").DBCodePage = 0
End If
MsgBox "Code Page for database: " & CStr(m_dtoSession1.Databases("DEMODATA").DBCodePage)
m_dtoSession1.Disconnect
See Also
DtoDatabases Collection
Methods Detail
AddUserToGroup
Adds an existing user to an existing group in the database.
Syntax
result = Object.AddUserToGroup(username, groupname)
Arguments
Return Values
Remarks
This function fails if the specified group or user do not already exist in the database, or if the user is a member of another group.
The following preconditions must be met:
You must first create a session then Open a database successfully as user “Master.”
The following post condition must be met:
Close the database to free the resources.
Example
Function AddUserToGroup(sUserName As String, sGroupName As String) As Boolean
Dim res As dtoResult
Dim m_dbn As New DtoDatabase
Dim m_dbn.Session = m_dto
Dim m_dbn.Name = "demodata"
res = m_dbn.Open("Master", "1234")
If res = Dto_Success Then
'Open worked, let's add the user to the group
res = m_dbn.AddUserToGroup(sUserName, sGroupName)
If res <> Dto_Success Then
LogResult ("Error on Add User to Group: " & CStr(res))
Else
LogResult ("User " & sUserName & " added to group " & sGroupName & ".")
End If
End If
m_dbn.Close
End Function
AlterUserName
Alters an existing user's name in the specified database.
Syntax
result = Object.AlterUserName(username, new_username)
Arguments
Return Values
Remarks
You must first create a session then Open a database successfully as user “Master.”
The following post condition must be met:
Close the database to free the resources.
Example
Function AlterUserName(sUserName As String, sNewUserName As String) As Boolean
Dim res As dtoResult
Dim m_dbn As New DtoDatabase
Dim m_dbn.Session = m_dto
Dim m_dbn.Name = "demodata"
res = m_dbn.Open("Master", "1234")
If res = Dto_Success Then
'Open worked, let's alter the username
res = m_dbn.AlterUserName(sUserName, sNewUserName)
If res <> Dto_Success Then
LogResult ("Error on Alter Username: " & CStr(res))
Else
LogResult ("Alter Username completed. New user name is " & sNewUserName)
End If
End If
m_dbn.Close
End Function
AlterUserPassword
Alters an existing user's password.
Syntax
result = Object.AlterUserPassword(username, new_password)
Arguments
Return Values
Remarks
You must first create a session then Open a database successfully as user “Master.”
The following post condition must be met:
Close the database to free the resources.
Example
Function AlterUserPassword(sUser As String, sNewPassword As String) As Boolean
Dim res As dtoResult
Dim m_dbn As New DtoDatabase
Dim m_dbn.Session = m_dto
Dim m_dbn.Name = "demodata"
res = m_dbn.Open("Master", "1234")
If res = Dto_Success Then
'Open worked, let's alter the user's password
res = m_dbn.AlterUserPassword(sUser, sNewPassword)
If res <> Dto_Success Then
LogResult ("Error on Alter User Password: " & CStr(res))
Else
LogResult ("Alter User Password successful.")
End If
End If
m_dbn.Close
End Function
Close
Closes a set of data dictionary files that were opened using the Open method.
Syntax
result = Object.Close
Arguments
Return Values
 
Remarks
Call this method after the database has been opened using Open method. Error information can be obtained using Error property.
Example
Dim m_database as new DtoDatabase
Dim result as DtoResult
 
result = m_database.Open(“dbuser”,”pwd”)
 
’ perform operations here
result = m_database.Close
Copy
Creates a new database based on the current one.
Syntax
result = Object.Copy(username, password, newDBname, newDictionaryPath, newDataPath)
Arguments
Return Values
Remarks
Referential integrity is preserved in the copied database.
More information on the errors returned by the method can be obtained using the Error property.
Example
Dim Database As New DtoDatabase
Dim result as DtoResult
Database.Session = my_session ‘ assume session exists
Database.Name = “DEMODATA”
‘ no user name or password, unsecure database
result = Database.Copy("", "", "DEMODATA2", "D:\DEMODATA2", "D:\DEMODATA2")
 
If NOT result = Dto_Success Then
MsgBox "Error"+ Session.Error(result)
End If
CreateGroup
Creates a new user group in the existing database.
Syntax
result = Object.CreateGroup(groupname)
Arguments
Return Values
Remarks
You must first create a session then Open a database successfully as user “Master.”
The following post condition must be met:
Close the database to free the resources.
Example
Function CreateGroup(sGroupName As String) As Boolean
Dim res As dtoResult
Dim m_dbn As New DtoDatabase
Dim m_dbn.Session = m_dto
Dim m_dbn.Name = "demodata"
res = m_dbn.Open("Master", "1234")
If res = Dto_Success Then
'Open worked, let's create the user.
res = m_dbn.CreateGroup(sGroupName)
If res <> Dto_Success Then
LogResult ("Error on Create Group: " & CStr(res))
Else
LogResult ("Group " & sGroupName & " created.")
End If
End If
m_dbn.Close
End Function
CreateUser
Creates a new user in an existing database. Optionally sets a password and assign the new user to an existing group.
Syntax
result = Object.CreateUser(username, [password], [groupname])
Arguments
Return Values
Remarks
The following preconditions must be met:
You must first create a session then Open a database successfully as user “Master.”
The following post condition must be met:
Close the database to free the resources.
Example
Function CreateUser(sUserName As String, sPassword As String, sGroupName As String) As Boolean
Dim res As dtoResult
Dim m_dbn As New DtoDatabase
Dim m_dbn.Session = m_dto
Dim m_dbn.Name = "demodata"
res = m_dbn.Open("Master", "1234")
If res = Dto_Success Then
'Open worked, let's create the user.
res = m_dbn.CreateUser(sUserName, sPassword, sGroupName)
If res <> Dto_Success Then
LogResult ("Error on Create User: " & CStr(res))
Else
LogResult ("User " & sUserName & " created in group " & sGroupName & ".")
End If
End If
m_dbn.Close
End Function
DropGroup
Removes an existing group from the database.
Syntax
result = Object.DropGroup(groupname)
Arguments
Return Values
Remarks
You must first create a session then Open a database successfully as user “Master.”
The following post condition must be met:
Close the database to free the resources.
Example
Function DropGroup(sGroupName As String) As Boolean
Dim res As dtoResult
Dim m_dbn As New DtoDatabase
Dim m_dbn.Session = m_dto
Dim m_dbn.Name = "demodata"
res = m_dbn.Open("Master", "1234")
If res = Dto_Success Then
'Open worked, let's drop the group.
res = m_dbn.DropGroup(sGroupName)
If res <> Dto_Success Then
LogResult ("Error on Drop Group: " & CStr(res))
Else
LogResult ("Group " & sGroupName & " dropped.")
End If
End If
m_dbn.Close
End Function
DropUser
Removes an existing user from the database.
Syntax
result = Object.DropUser(username)
Arguments
Return Values
Remarks
You must first create a session then Open a database successfully as user “Master.”
The following post condition must be met:
Close the database to free the resources.
Example
Function DropUser(sUserName As String) As Boolean
Dim res As dtoResult
Dim m_dbn As New DtoDatabase
Dim m_dbn.Session = m_dto
Dim m_dbn.Name = "demodata"
res = m_dbn.Open("Master", "1234")
If res = Dto_Success Then
'Open worked, let's drop the user.
res = m_dbn.DropUser(sUserName)
If res <> Dto_Success Then
LogResult ("Error on Drop User: " & CStr(res))
Else
LogResult ("Drop User for " & sUserName & " completed.")
End If
End If
m_dbn.Close
End Function
Open
Opens a connection to the database with the given username and password.
Syntax
result = Object.Open(username, password)
Arguments
Return Values
Remarks
This operation is used in order to open a set of dictionary files. This set must contain FILE.DDF, INDEX.DDF and FIELD.DDF. It may also contain a number of optional DDF files. Remember to call the Close method to free memory. Once the database is opened, no one else can make changes to it until the Close method is called.
You cannot issue the Secure or UnSecure methods while the database is open.
More information on the errors returned by the method can be obtained using the Error property of the DtoSession Object.
Example
Dim m_session as new DtoSession
Dim m_database as new DtoDatabase
Dim result as DtoResult
result = m_session.Connect(“myserver”,“user”,”pwd”)
m_database.Session = m_session
m_database.Name = “DEMODATA”
result = m_database.Open(“dbuser”,”pwd”)
RemoveUserFromGroup
Removes an existing user from an existing group.
Syntax
result = Object.RemoveUserFromGroup(groupnamem username)
Arguments
Return Values
Remarks
You must first create a session then Open a database successfully as user “Master.”
The following post condition must be met:
Close the database to free the resources.
Example
Function RemoveUserFromGroup(sUserName As String, sGroupName As String) As Boolean
Dim res As dtoResult
Dim m_dbn As New DtoDatabase
Dim m_dbn.Session = m_dto
Dim m_dbn.Name = "demodata"
res = m_dbn.Open("Master", "1234")
If res = Dto_Success Then
'Open worked, let's remove the user from the group
res = m_dbn.RemoveUserFromGroup(sGroupName, sUserName)
If res <> Dto_Success Then
LogResult ("Error on Remove User From Group: " & CStr(res))
Else
LogResult ("Remove user " & sUserName & " from group " & sGroupName & " completed.")
End If
End If
m_dbn.Close
End Function
Secure
Enables security for a database.
Syntax
result = Object.Secure(user, password)
Arguments
Return Values
Remarks
When you enable database security, you must specify Master as the database user name and choose a password. Security for the database is enforced based on the access rights defined for the database, and should match behavior seen in SQL or ODBC access methods.
Ensure that the database is closed when attempting to enable security.
More information on the errors returned by the method can be obtained using the Error property of the DtoSession Object.
Example
Dim m_database as new DtoDatabase
Dim result as DtoResult
m_database.Name = “DEMODATA”
m_database.Session = my_session ‘ assume session exists
result = m_database.Secure(“Master”, “password”)
UnSecure
Disables security for a database.
Syntax
result = Object.UnSecure(user, password)
Arguments
Return Values
Remarks
When you disable database security, you must specify Master as the database user name and provide the Master user password.
Ensure that the database is closed when attempting to disable security.
More information on the errors returned by the method can be obtained using the Error property of the DtoSession Object.
Example
Dim m_database as new DtoDatabase
Dim result as DtoResult
m_database.Name = “DEMODATA”
m_database.Session = my_session ‘ assume session exists
result = m_database.UnSecure(“Master”, “password”)