Developer Reference > Platform Management > Distributed Tuning Objects (DTO) Guide > Creating and Maintaining Catalogs and Dictionaries with DTO
Creating and Maintaining Catalogs and Dictionaries with DTO
The following topics provide information about the objects that comprise the Catalog group of the Distributed Tuning Objects:
DtoDatabases Collection
Properties
Count
Returns number of members in a collection.
Item
Returns a specific member of a DtoDatabases collection.
Methods
Add
Remove
Remarks
Use the Count property to find the number of members in the collection.
Example
' instantiate session object and connect to a 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
See Also
DtoDatabase Object
DtoSession Object
Methods Detail
Add
Add an item to a DtoDatabases collection.
Syntax
result = Collection.Add(Object,[dsnName])
Arguments
Collection
DtoDatabases collection to which to add object.
Object
A new DtoDatabase object
dsnName
Optional. Will create a standard server DSN for the new database
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 method takes a parameter of type object. Therefore, you are responsible for first instantiating the object and setting its properties before adding it to the collection.
This method will add the given database to the collection and to the underlying DBNAMES.CFG file on the server.
Example
Dim result As dtoResult
Dim database As DtoDatabase
 
Set database = New DtoDatabase
' Set properties for new database
database.Name = "MyDemodata"
database.DdfPath = "C:\test"
database.DataPath = "C:\test"
database.Flags = dtoDbFlagCreateDDF + dtoDbFlagRI
 
result = my_session.Databases.Add(database)
If NOT result = Dto_Success Then
MsgBox "Error"+ Session.Error(result)
End If
Remove
Removes an item from a DtoDatabases collection.
Syntax
Collection.Remove(database,[deleteDDF])
Arguments
Collection
Collection from which to remove object.
database
A variant that can contain the index (starting with 1) or the database name of the item you wish to remove from the collection
deleteDDF
Set to True to delete dictionary files.
Set to False to leave dictionary files intact.
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 method removes the item from the databases collection and from the underlying DBNAMES.CFG file.
Example
Dim result As dtoResult
result = my_session.Databases.Remove("MyDemodata",1)
If NOT result = Dto_Success Then
MsgBox "Error"+ my_session.Error(result)
End If
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
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
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
Object
DtoDatabase object
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”)
 
' 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
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(groupname, 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")
DtoDSNs Collection
A collection of DtoDSN objects.
Properties
Count
Returns number of members in a collection.
Item
Returns a specific member of a DtoDSNs collection.
Methods
Add
Remove
Remarks
Use the Count property to find the number of members in the collection.
Example
' instantiate session object
Dim my_session as New DtoSession
Dim result as DtoResult
 
' connect to a server
result = my_session.Connect("myserver", "username", "password")
 
' now get DSNs collection
Dim my_dsns as DtoDSNs
Set my_dsns = my_session.DSNs
See Also
DtoDSN Object
DtoSession Object
Methods Detail
Add
Add an item to a DtoDSNs collection and creates a DSN on the server.
Syntax
result = Collection.Add(Object)
Arguments
Collection
DtoDSNs collection to which to add object.
Object
A new DtoDSN object
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 method takes a parameter of type object. Therefore, you are responsible for first instantiating the object and setting its properties before adding it to the collection.
Example
Dim result As dtoResult
Dim DSNs As DtoDSNs
Dim dsn As DtoDSN
 
Set dsn = New DtoDSN
 
' Set properties for new dsn
dsn.Name = "MyDemodata_DSN"
dsn.Description = "a sample DSN"
dsn.Dbname = "MyDemodata"
dsn.Openmode = dtoNormalDSNOpenMode
 
result = my_session.DSNs.Add(dsn)
If NOT result = Dto_Success Then
MsgBox "Error"+ my_session.Error(result)
End If
Remove
Removes a DSN item from a DtoDSNs collection and deletes it from the server.
Syntax
result = Collection.Remove(dsn)
Arguments
Collection
Collection from which to remove object.
dsn
A variant containing either the index (starting with 1) or the name of the item you wish to remove from the collection
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 method does not remove the associated database or database name.
Example
Dim result As dtoResult
Dim DSNs As DtoDSNs
result = my_session.DSNs.Remove("MYDSN")
If NOT result = Dto_Success Then
MsgBox "Error"+ my_session.Error(result)
End If
DtoDSN Object
An object representing a Zen DSN.
Properties
DbName
Gets or sets the Dbname associated with the DSN.
Description
Gets or sets the description of the DSN.
Name
Gets or sets the name of the DSN.
OpenMode
Gets or sets the open mode enumeration of the DSN.
See DSN Open Mode for possible values.
Session
Gets or sets the DtoSession object associated with this DtoDSN object.
Translate
Gets or set the encoding translation, which specifies how character data is translated between the database engine and a client application. This property is an enumeration. See DSN Translate Option for a list of values.
Methods
None
Remarks
To obtain information about a particular database, use the DtoDatabase Object.
Examples
To Query the DbName Associated with a DSN
' instantiate session object
Dim my_session as New DtoSession
' connect to a server
my_session.Connect("myserver", "username", "password")
' now use your session object to obtain db collection
my_dsns = my_session.DSNs
first_dsn = my_dsns.Item(1)
dsn_dbname = first_dsn.DbName
To Add a New DSN
' instantiate session object
Dim my_session as New DtoSession
Dim result as dtoResult
 
' connect to a server
result = my_session.Connect("myserver", "username", "password")
' now use your session object to obtain DSN collection
Dim my_dsns as DtoDSNs
Set my_dsns = my_session.DSNs
 
' Populate new DtoDSN object
Dim NewDSN as New DtoDSN
NewDSN.DbName = "DEMODATA"
NewDSN.Description = "A DSN for the DEMODATA db"
NewDSN.Name = "Demodata_DSN"
 
' now add the new DSN to the collection
result = my_dsns.Add(NewDSN)
To Get or Set the Encoding Translation
Dim m_dtoSession1 As New DtoSession
Dim result As dtoResult
result = m_dtoSession1.Connect("localhost", "", "")
Dim sTranslate As String
Dim iTranslate As Integer
iTranslate = m_dtoSession1.DSNs("DEMODATA").Translate
If iTranslate = 0 Then sTranslate = "None"
If iTranslate = 1 Then sTranslate = "OEM/ANSI Conversion"
If iTranslate = 2 Then sTranslate = "Automatic"
 
MsgBox "DSN Translate Setting (before change): " & sTranslate
If result = Dto_Success Then
Rem set the encoding translation.
m_dtoSession1.DSNs("DEMODATA").Translate = 1
End If
iTranslate = m_dtoSession1.DSNs("DEMODATA").Translate
If iTranslate = 0 Then sTranslate = "None"
If iTranslate = 1 Then sTranslate = "OEM/ANSI Conversion"
If iTranslate = 2 Then sTranslate = "Automatic"
 
MsgBox "DSN Translate Setting (after change): " & sTranslate
m_dtoSession1.Disconnect
See Also
DtoDSNs Collection
DtoSession Object
DtoDictionary Object
An object representing a Zen dictionary. This object is deprecated in favor of DtoDatabase Object. DtoDictionary can still be used only if you can specify the path to the dictionary on the Open method.
Properties
Path
Returns path of the dictionary object.
Collections
DtoTables Collection
Methods
Open
Create
Close
AddTable
DropTable
Reload
Delete
Remarks
All of the operations affecting dictionary files have to be done through this object. The user can open a dictionary, create a dictionary, get table information add a table or drop a table using this object.
Note:  If instantiating this object using ASP or if you use the CreateObject method in Visual Basic, the progid of DtoDictionary is "DTO.DtoDictionary.2" for DTO2, or “DTO.DtoDictionary.1” for DTO version 1. See DTO2 for more information on the differences between the two versions.
Example
Dim result as DtoResult
Dim dictionary as New DtoDictionary
result = dictionary.Open("d:\MyDemodata")
See Also
DtoTables Collection
DtoTable Object
Methods Detail
Open
Opens a set of data dictionary files using either a database name or a dictionary path.
Syntax
result = Object.Open(path, [user], [password])
Arguments
Object
DtoDictionary object
path
Absolute path to the directory containing dictionary files or name of the named database if local.
You cannot use a named database for this argument if you are connected to a remote server.
user
Optional user name for the DDF set
password
Optional password for the DDF set
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
Note:  The path argument may either contain a path to the directory containing the DDF files or it can use a name of the database contained in the local DBNAMES.CFG. See DtoDatabases Collection in order to create and maintain database names.
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 dictionary set is opened no one else can make changes to it until the Close method is called.
More information on the errors returned by the method can be obtained using the Error property of the DtoSession Object.
Example
Dim dictionary as new DtoDictionary
Dim result as DtoResult
 
result = dictionary.Open("d:\MyDemodata")
Create
Creates an empty set of data dictionary files.
Syntax
result = Object.Create(path, [user], [password])
Arguments
Object
DtoDictionary object
path
The absolute path to the directory in which the dictionary files to be created.
user
Optional user name for the DDF set.
password
Optional password for the DDF set.
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
If the directory contained in path argument does not exist, an attempt will be made to create it. If operation is successful a set containing file.ddf, field.ddf, index.ddf will be created.
Remember to call Close method to free memory. Once the dictionary set is created other clients cannot open it or make changes to it until Close method is called.
More information on the errors returned by the method can be obtained using the Error property. Unlike Open method the path parameter can only contain an absolute path.
Example
Dim Dictionary As New DtoDictionary
Dim result as DtoResult
 
result = Dictionary.Create("C:\TEST", "login", "password")
If NOT result = Dto_Success Then
MsgBox "Error"+ Session.Error(result)
End If
Close
Closes a set of data dictionary files. Opened using Open method or created using Create method.
Syntax
result = Object.Close
Arguments
Object
DtoDictionary object
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 dictionary has been opened using Open method or created using Create method. Error information can be obtained using Error property.
Example
Dim dictionary as new DtoDictionary
Dim result as DtoResult
 
result = dictionary.Open("d:\MyDemodata")
'
' perform operations here
'
result = dictionary.Close
AddTable
Adds table information to data dictionary files and creates a data file to match the definition.
Note:  In the same directory, no two files should share the same file name and differ only in their file name extension. For example, do not create a data file Invoice.btr and another one Invoice.mkd in the same directory. This restriction applies because the database engine uses the file name for various areas of functionality while ignoring the file name extension. Since only the file name is used to differentiate files, files that differ only in their file name extension look identical to the database engine.
Syntax
result = Object.AddTable(table)
Arguments
Object
DtoDictionary object
table
DtoTable object
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 method adds the table definition to the ddf files and attempts to create the data file specified in Location property of table. If Location property is left blank then this method will attempt to create a data file named tableName.mkd. If a table with such name already exists a number will be appended to the name and another attempt will be made.
In order for this operation to complete successfully at least one column must be defined.
Example
The following example shows how to create a dictionary object and then add a table to it.
Dim Dictionary As New DtoDictionary
Dim Table As DtoTable
Dim Tables As DtoTables
Dim result As dtoResult
Dim Columns As DtoColumns
Dim Indexes As DtoIndexes
Dim Column As DtoColumn
Dim Index As DtoIndex
Dim Segments As DtoSegments
Dim Segment As DtoSegment
 
result = Dictionary.Create("C:\TEST", "login", "password")
If NOT result = Dto_Success Then
MsgBox "Error"+ Session.Error(result)
End If
 
' ******* Begin AddTable *******************
 
Set Table = New DtoTable
 
Set Column = New DtoColumn
With Column
.Decimal = 0
.Flags = dtoColumnNullable
.ISR = ""
.Name = "F_Int"
.Number = 0
.Size = 4
.Type = dtoTypeInteger
End With
Table.Columns.Add Column
 
Set Column = New DtoColumn
With Column
.Decimal = 4
.Flags = dtoColumnNullable + dtoColumnCaseInsensitive
.ISR = ""
.Name = "F_Str"
.Number = 1
.Size = 55
.Type = dtoTypeLString
End With
Table.Columns.Add Column
 
Set Column = New DtoColumn
With Column
.Decimal = 4
.Flags = dtoColumnCaseInsensitive
.ISR = ""
.Name = "F_Str_Second"
.Number = 2
.Size = 100
.Type = dtoTypeLString
End With
Table.Columns.Add Column
 
Set Column = New DtoColumn
With Column
.Decimal = 10
.Flags = dtoColumnDefault
.ISR = ""
.Name = "F_Float"
.Number = 3
.Size = 8
.Type = dtoTypeBFloat
End With
Table.Columns.Add Column
 
'Add Indexes
Set Index = New DtoIndex
result = Index.AddSegment("F_Int", 0)
Set Segment = New DtoSegment
Segment.Number = 0
Segment.ColumnName = "F_Int"
Segment.Flags = dtoSegmentAscending
Index.Segments.Add Segment
 
Index.Name = "FintInd"
Index.Number = 0
Index.Flags = dtoIndexModifiable
Table.Indexes.Add Index
'Add second Index:
Set Index = New DtoIndex
Set Segment = New DtoSegment
Segment.Number = 0
Segment.ColumnName = "F_Str"
Segment.Flags = dtoSegmentAscending
Index.Segments.Add Segment
Set Segment = New DtoSegment
Segment.Number = 1
Segment.ColumnName = "F_Str_Second"
Segment.Flags = dtoSegmentAscending
Index.Segments.Add Segment
Index.Name = "FStrTagInd"
Index.Number = 1
Index.Flags = dtoIndexModifiable
Table.Indexes.Add Index
Table.Overwrite = true
Table.Flags = dtoTableTrueNullable
Table.Name = "Table3"
 
result = Dictionary.AddTable(Table)
 
If NOT result = Dto_Success Then
MsgBox "Error"+ Session.Error(result)
End If
DropTable
Remove a table from the current dictionary.
Syntax
result = Object.DropTable(tableName, [deleteFile])
Arguments
Object
DtoDictionary object.
tableName
Name of the table to be dropped.
deleteFile
A boolean value indicating whether the underlying data file should be deleted.
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
Note that the dictionary has to be opened successfully for this operation to succeed.
Example
result = Dictionary.DropTable("Table3", true)
If NOT result = Dto_Success Then
MsgBox "Error"+ Session.Error(result)
End If
Reload
Refreshes a dictionary object.
Syntax
result = Object.Reload
Arguments
Object
DtoDictionary object
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.
Delete
Deletes dictionary object and the corresponding DDF files.
Syntax
result = Object.Delete
Arguments
Object
DtoDictionary object
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.
DtoTables Collection
Returns a collection of DtoTable objects.
Properties
Count
Returns number of members in a collection.
Item
Returns a specific member of a collection. You can pass an ordinal value or a table name.
Methods
None
Remarks
This collection only includes the user defined tables and does not include system tables. The dictionary has to be successfully opened. In order to add or drop tables from the collection use AddTable and DropTable.
Use the Count property to find the number of members in the DtoTables collection.
Example
Using DtoDatabase
Before obtaining the Tables collection, you must first invoke the Open method on the database object, even if the database is not secured.
Dim m_session as new DtoSession
Dim m_database as new DtoDatabase
Dim table as new DtoTable
Dim result as DtoResult
 
result = m_session.Connect("server","user","password")
m_database.Name = "demodata"
m_database.Session = m_session
' Open database, assuming database not secured
result = m_database.Open("","")
 
For each table in m_database.Tables
if table.Name = “Billing” then
' found the billing table
End If
next
m_database.Close ' close the db if you open it
Using DtoDictionary
Dim dictionary as new DtoDictionary
Dim table as new DtoTable
Dim result as DtoResult
Dim location as string
 
'find location of Mytable table
result = dictionary.Open("d:\MyDemodata")
 
For Each table In dictionary.Tables
If table.Name = "Mytable" Then
location = table.Location
exit For
End If
next
See Also
DtoDatabase Object
AddTable
DropTable
DtoTable Object
DtoTable Object
An object representing a table in a database.
Properties
Flags
Gets or sets the flags associated with this table. See Table Flags for possible values.
Location
Gets the file name of the table. To determine the path of this file, use the properties of the DtoDatabase Object.
Name
Gets or sets the name of the table.
Overwrite
If True, this table can overwrite a table with the same name during an AddTable call.
True = overwrite table
False = do not overwrite table and return an error
Collections
DtoColumns Collection
DtoIndexes Collection
Methods
None
Remarks
DtoTable object contains two collection objects: Columns and Indexes. All operations involving columns and indexes are accomplished using these objects.
To add a new table to a dictionary, use the AddTable.
To remove a table from a dictionary, use the DropTable.
Example
For an example of creating a new DtoTable object, see AddTable.
Dim dictionary as new DtoDictionary
Dim table as new DtoTable
Dim result as DtoResult
Dim location as string
 
'determine file name of Mytable table
result = dictionary.Open("d:\MyDemodata")
 
For Each table In dictionary.Tables
If table.Name = "Mytable" Then
location = table.Location
End If
next
See Also
DtoTables Collection
DtoColumn Object
DtoIndex Object
DtoColumns Collection
A collection of DtoColumn objects representing all the columns in a table.
Properties
Count
Returns number of members in a collection.
Item
Returns a specific member of a DtoColumns collection.
Methods
Add
Remove
Clear
Remarks
You obtain this collection from a property of the DtoTable Object object.
Use the Count property to find the number of members in the collection.
Example
Dim dictionary as new DtoDictionary
dictionary.Open("d:\MyDemodata")
students_table = dictionary.GetTable("STUDENT")
students_cols = students_table.Columns
See Also
DtoIndexes Collection
DtoColumn Object
DtoTable Object
Methods Detail
Add
Add an item to a DtoColumns collection.
Syntax
result = Collection.Add(Object)
Arguments
Collection
DtoColumns collection to which to add object.
Object
A new DtoColumn object.
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 method takes a parameter of type DtoColumn. Therefore, you are responsible for first instantiating the object and setting its properties before adding it to the collection.
Note:  You cannot use this method to add columns to preexisting Zen tables. This method does not alter data or DDF files, and can only be used to add columns in memory before a table is created. See the example for AddTable as a reference.
Remove
Removes an item from a DtoColumns collection.
Syntax
Collection.Remove(column)
Arguments
Collection
DtoColumns collection from which to remove object.
column
A variant containing either the index (starting with 1) or the name of the item you wish to remove from the DtoColumns collection
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
You can pass either a column name or the 1-based ordinal of the item in the DtoColumns collection.
Note:  You cannot use this method to remove columns from preexisting Zen tables. This method does not alter data or DDF files, and can only be used to remove columns in memory before a table is created. See the example for AddTable as a reference.
Clear
Removes all items from a DtoColumns collection.
Syntax
result = Collection.Clear
Arguments
In
Collection
DtoColumns or DtoIndexes collection obtained from a DtoTable object
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 method removes all the columns from a table in memory.
Note:  You cannot use this method to remove columns from preexisting Zen tables. This method does not alter data or DDF files, and can only be used to remove all columns in memory before a table is created. See the example for AddTable as a reference.
DtoColumn Object
This object represents a table column.
Properties
Decimal
Gets or sets the decimal places for a column
Flags
Gets or sets the flags for a column
ISR
Gets or sets the ISR for a column
Name
Gets or sets the Name for a column
Number
Gets or sets the ordinal of a column
Size
Gets or sets the size of the column
Type
Gets or sets column type. An enumerated value. See Btrieve Types for possible values.
TypeName
Returns a string value containing the type name.
Methods
None
Remarks
This object allows you to display properties of a specific table column.
Example
' Instantiate and open dictionary
Dim dictionary as new DtoDictionary
Dim result as DtoResult
result = dictionary.Open("d:\MyDemodata")
 
' Get STUDENT table from MyDemodata database
Dim students_table as DtoTable
Set students_table = dictionary.Tables("STUDENTS")
 
' Get columns collection from STUDENT table
Dim students_cols as DtoColumns
Set students_cols = students_table.Columns
 
' Retrieve first column and get its name
Dim first_col as DtoColumn
Set first_col = students_cols(1)
name = first_col.Name
See Also
DtoColumns Collection
DtoTable Object
DtoIndexes Collection
A collection of DtoIndex objects representing the indexes of a table.
Properties
Count
Returns number of members in a collection.
Item
Returns a specific member of a DtoIndexes collection. You can pass either a 1-based ordinal or the name of the Index.
Methods
Add
Remove
Clear
Remarks
Use the Count property to find the number of members in the collection.
Example
' Instantiate and open dictionary
Dim dictionary as new DtoDictionary
Dim result as DtoResult
result = dictionary.Open("d:\mydemodata")
 
' Get STUDENT table from MYDEMODATA database
Dim students_table as DtoTable
Set students_table = dictionary.Tables("STUDENT")
 
' Retrieve DEMODATA indexes collection
Dim students_idx as DtoIndexes
Set students_idx = students_table.Indexes
See Also
DtoIndex Object
DtoTable Object
Methods Detail
Add
Add an item to a collection.
Syntax
result = Collection.Add(Object)
Arguments
Collection
Collection to add object to.
Object
A new DtoIndex object to add to the DtoIndexes collection.
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 method takes a parameter of type DtoIndex. Therefore, you are responsible for first instantiating the object and setting its properties before adding it to the collection.
Note:  You cannot use this method to add indexes to preexisting Zen tables. This method does not alter data or DDF files, and can only be used to add indexes in memory before a table is created. See the example for AddTable as a reference.
Remove
Removes an item from a collection.
Syntax
result = Collection.Remove(index)
Arguments
Collection
Collection from which to remove object.
index
A variant containing either the index (starting with 1) or the name of the item you wish to remove from the DtoIndexes collection
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
You can pass either a name or a 1-based ordinal to the Remove method.
Note:  You cannot use this method to remove indexes from preexisting Zen tables. This method does not alter data or DDF files, and can only be used to remove indexes in memory before a table is created. See the example for AddTable as a reference.
Clear
Removes all items from a DtoColumns or DtoIndexes collection.
Syntax
result = Collection.Clear
Arguments
Collection
DtoIndexes collection obtained from a DtoTable object
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 method removes all the indexes from a table in memory.
Note:  You cannot use this method to remove indexes from preexisting Zen tables. This method does not alter data or DDF files, and can only be used to remove all indexes in memory before a table is created. See the example for AddTable as a reference.
DtoIndex Object
This object represents an index for a table.
Properties
Flags
Gets or sets the column name for the index segment. This is an enumerated value. See Index Flags for possible values.
Name
Gets or sets the name of the index.
Number
Gets or sets the 0-based number of the index.
Tag
Gets the index tag. It contains the names of all the columns that comprise the index.
Collections
DtoSegments Collection
Methods
None
Remarks
Only 119 segments are allowed per index. Note that the combined size of all the columns in segments of an index cannot be more then 255 bytes for 13.0 format files and earlier, or 1024 bytes for 16.0 format files.
Only the last column in an index segment can have a partial index flag. Index segments that are not the last segment in the index and that use the partial index flag will have the partial flag ignored.
Example
' Instantiate and open dictionary
Dim dictionary as new DtoDictionary
Dim result as DtoResult
result = dictionary.Open("d:\mydemodata")
 
' Get STUDENT table from MYDEMODATA database
Dim students_table as DtoTable
Set students_table = dictionary.Tables("STUDENT")
 
' Retrieve DEMODATA indexes collection
Dim students_idx as DtoIndexes
Set students_idx = students_table.Indexes
 
' Get first index and determine its name
Dim first_idx as DtoIndex
Set first_idx = students_idx(1)
Dim index_name as String
index_name = first_idx.Name
See Also
DtoIndexes Collection
DtoSegments Collection
DtoSegments Collection
A collection of DtoSegment objects representing the segments of an index.
Properties
Count
Returns number of members in a collection.
Item
Returns a specific member of a collection.
Methods
Add
Remove
Clear
Remarks
Use the Count property to find the number of members in the collection.
Example
' Open dictionary
Dim dictionary as new DtoDictionary
Dim result as DtoResult
result = dictionary.Open("d:\mydemodata")
 
' Get Students table
Dim students_table as DtoTable
Set students_table = dictionary.GetTable("Student")
 
' Obtain indexes collection from students table
Dim students_idx as DtoIndexes
Set students_idx = students_table.Indexes
 
' Delete all the indexes
Dim first_idx as DtoIndex
Set first_idx = students_idx(1)
 
' Get DtoSegments collection from first_idx
Dim my_segments as DtoSegments
Set my_segments as first_idx.Segments
See Also
DtoSegment Object
DtoTable Object
Methods Detail
Add
Add an item to a collection.
Syntax
result = Collection.Add(Object)
Arguments
Collection
DtoSegments collection to which to add object.
Object
A new DtoSegment object
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 method takes a parameter of type DtoSegment. Therefore, you are responsible for first instantiating the object and setting its properties before adding it to the collection.
Note:  You cannot use this method to add segments to preexisting Zen tables. This method does not alter data or DDF files, and can only be used to add segments in memory before a table is created. See the example for AddTable as a reference.
Remove
Removes an item from a collection.
Syntax
result = Collection.Remove(segment)
Arguments
Collection
DtoSegments collection from which to remove object.
segment
A variant containing either the index (starting with 1) or the name of the item you wish to remove from the collection
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
You can pass either the 1-based ordinal or the name of the segment.
Note:  You cannot use this method to remove segments from preexisting Zen tables. This method does not alter data or DDF files, and can only be used to remove segments in memory before a table is created. See the example for AddTable as a reference.
Clear
Removes all items from a DtoSegments collection.
Syntax
result = Collection.Clear
Arguments
Collection
DtoSegments collection obtained from a DtoIndex object
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 method removes all the segments from an index in memory.
Note:  You cannot use this method to remove segments from preexisting Zen tables. This method does not alter data or DDF files, and can only be used to remove segments in memory before a table is created. See the example for AddTable as a reference.
DtoSegment Object
This object represents a segment in an index.
Properties
ColumnName
Gets or sets the column name associated with this segment.
Flags
Gets or sets segment flags. An enumerated value. See Segment Flags for values.
Number
Gets or sets the 0-based segment number.
Methods
None
Remarks
One or more of these comprise an index. Only 119 segments are allowed per index. Note that the combined size of all the columns in segments of an index cannot be more then 255 bytes for 13.0 format files and earlier, or 1024 bytes for 16.0 format files.
Example
' Open dictionary
Dim dictionary as new DtoDictionary
Dim result as DtoResult
result = dictionary.Open("d:\mydemodata")
 
' Get Students table
Dim students_table as DtoTable
Set students_table = dictionary.GetTable("Student")
 
' Obtain indexes collection from students table
Dim students_idx as DtoIndexes
Set students_idx = students_table.Indexes
 
' Delete all the indexes
Dim first_idx as DtoIndex
Set first_idx = students_idx(1)
 
' Get DtoSegments collection from first_idx
Dim my_segments as DtoSegments
Set my_segments as first_idx.Segments
 
' Get first segment and query column name
Dim first_seg as DtoSegment
Set first_seg = my_segments(1)
Dim colname as String
colname = first_seg.ColumnName
See Also
DtoSegments Collection
DtoTable Object
DtoIndexes Collection
 
Last modified date: 11/04/2024