DtoDatabase Object
Properties
DataPath | Gets or sets the location of the data for a database. |
DbCodePage | 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). |
DbFlags | Gets or sets the database flags for a database. This property is an enumeration. See
Database Flags for a list of values. |
DdfPath | Gets or sets the dictionary path for a database. |
Name | Gets or sets the name of the database. |
Secured | Returns whether the database has security enabled. (0=unsecure, 1=secure) |
Session | Gets or sets the Session object associated with this DtoDatabase object. |
Collections
Methods
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.
Dim my_session as New DtoSession
Dim result as DtoResult
result = my_session.Connect("myserver", "username", "password")
Dim my_databases as DtoDatabases
Set my_databases = my_session.Databases
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
Methods Detail
AddUserToGroup
Adds an existing user to an existing group in the database.
Syntax
result = Object.AddUserToGroup(username, groupname)
Arguments
Object | Dtodatabase object |
username | User name to add to the group |
groupname | Group name to which the user is added |
Return Values
result | DtoResult long value indicating the result of the method call. |
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 associated database has database-level security enabled.
•The user and group already exist in the specified database.
•The user is not a member of another group.
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
Object | Dtodatabase object |
username | Name of existing database user |
new_username | New name for the database user. If set to NULL, the function fails. |
Return Values
result | DtoResult long value indicating the result of the method call. |
Remarks
•You must first create a session then
Open a database successfully as user “Master.”
•The associated database has database-level security enabled.
•The user name must already exist in the specified database.
•The new user name cannot already exist in the specified database.
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
Object | Dtodatabase object |
username | Name of the database user whose password is to be changed |
new_password | New password for the user. If set to NULL, the password is cleared. |
Return Values
result | DtoResult long value indicating the result of the method call. |
Remarks
•You must first create a session then
Open a database successfully as user “Master.”
•The associated database has database-level security enabled.
•The user name must already exist in the specified database.
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
result | DtoResult long value indicating the result of the method call. Use the Error property of the
DtoSession Object to obtain a description for the result. |
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”)
result = m_database.Close
Copy
Creates a new database based on the current one.
Syntax
result = Object.Copy(username, password, newDBname, newDictionaryPath, newDataPath)
Arguments
Object | DtoDatabase object |
username | Database user name for the database. If the database does not have security enabled, set to an empty string. |
password | Password for database user. If the database does not have security enabled, set to an empty string. |
newDBname | Database name for the copied database. |
newDictionaryPath | Absolute path to the directory in which the dictionary files are to be created. This directory must already exist. |
newDataPath | Data path for the database. Pass an empty string to use the default data path (that is, the same as the dictionary path) |
Return Values
result | DtoResult long value indicating the result of the method call. Use the Error property of the
DtoSession Object to obtain a description for the result. |
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
Object | Dtodatabase object |
groupname | Name of the group that you want to add to the database |
Return Values
result | DtoResult long value indicating the result of the method call. |
Remarks
•You must first create a session then
Open a database successfully as user “Master.”
•The associated database has database-level security enabled.
•A group with the same name cannot already exist in the specified database.
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
Object | Dtodatabase object |
username | Name of the user to add to the database |
password | User password. If set to NULL, no password is set. |
groupname | Database group name to which to assign the user. If set to NULL, user is not assigned to a group. |
Return Values
result | DtoResult long value indicating the result of the method call. |
Remarks
The following preconditions must be met:
•You must first create a session then
Open a database successfully as user “Master.”
•The associated database has database-level security enabled.
•A user with the same name cannot already exist in the specified database.
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
Object | Dtodatabase object |
groupname | Name of the group that you want to remove from the database |
Return Values
result | DtoResult long value indicating the result of the method call. |
Remarks
•You must first create a session then
Open a database successfully as user “Master.”
•The associated database has database-level security enabled.
•A group with the same name cannot already exist in the specified database.
•The group cannot contain any members.
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
Object | Dtodatabase object |
username | Name of the user that you want to remove from the database |
Return Values
result | DtoResult long value indicating the result of the method call. |
Remarks
•You must first create a session then
Open a database successfully as user “Master.”
•The associated database has database-level security enabled.
•A user with the same name must already exist in the specified database.
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
Object | DtoDatabase object |
username | User name for the database. If database is not secured, set to an empty string. |
password | Password for the database. If database is not secured, set to an empty string |
Return Values
result | DtoResult long value indicating the result of the method call. Use the Error property of the
DtoSession Object to obtain a description for the result. |
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
Object | Dtodatabase object |
groupname | Database group name |
username | Database user name |
Return Values
result | DtoResult long value indicating the result of the method call. |
Remarks
•You must first create a session then
Open a database successfully as user “Master.”
•The associated database has database-level security enabled.
•The user and group already exist in the specified database.
•The user is not a member of another group.
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
Object | DtoDatabase object |
user | User should be set to “Master” for securing the database. |
password | Password for the Master user. |
Return Values
result | DtoResult long value indicating the result of the method call. Use the Error property of the
DtoSession Object to obtain a description for the result. |
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
Object | DtoDatabase object |
user | User should be set to “Master” to unsecure the database. |
password | Password for the Master user. |
Return Values
result | DtoResult long value indicating the result of the method call. Use the Error property of the
DtoSession Object to obtain a description for the result. |
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”)