Configuring Zen Servers with DTO
The following topics provide information about the objects that comprise the configuration group of the Distributed Tuning Objects:
DtoCategories Collection
This object is a collection of DtoCategory objects representing all the setting categories available for a particular DtoSession object.
Properties
Count | Returns number of members in a collection. |
Item | Returns a specific member of a collection. |
Methods
None
Remarks
This collection allows retrieving individual items by passing a 1-based ordinal.
Use the Count property to find the number of members in the collection.
num_categories = my_categories.Count
Use the Item property to retrieve the one-based index of a collection.
Set first_item = my_categories(1)
Example
' 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 obtain categories collection
Dim my_categories as DtoCategories
Set my_categories = my_session.Categories
See Also
DtoCategory Object
This object allows you to perform operations on a particular category from a DtoCategories collection.
Properties
CategoryID | Returns unique category ID for a DtoCategory. |
Name | Returns name of the category |
Session | Returns session of the category |
Collections
Methods
None
Remarks
To get a list of settings for a category, use the Settings property to return a DtoSettings collection. You can then use the DtoSetting objects contained therein to obtain information relating to a particular setting.
Example
' instantiate session object and connect to server
Dim my_session as new DtoSession
Dim result as DtoResult
Dim category as DtoCategory
Dim my_categories as DtoCategories
Dim settings as DtoSettings
result = my_session.Connect("myserver", "username", "password")
' now obtain categories collection
Set my_categories = my_session.Categories
' loop through collection
For Each category In my_categories
Set settings = category.Settings
Next
See Also
DtoLicenseMgr Object
DTO2 only: This object allows you to authorize and deauthorize product licenses, initiate a license validation action, and retrieve an XML string of product information.
Properties
None
Collections
None
Methods
Remarks
Obtain from Session object
Example
' instantiate session object and connect to server
Dim my_session as new DtoSession
Dim result as DtoResult
Dim my_licmgr as DtoLicenseMgr
result = my_session.Connect("myserver", "username", "password")
' now obtain License Manager object
Set my_licmgr = my_session.LicenseMgr
' Add a license
result = my_licmgr.AddLicense(“ERXVD3U4ZS9KR94QPDHV5BN2”)
See Also
Methods Detail
AddLicense
Authorizes a license.
Syntax
result = LicenseManager.AddLicense(License)
Arguments
LicenseManager | DtoLicenseMgr object |
License | A valid license key to authorize on the engine you are currently connected to with a DtoSession 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. |
Example
' instantiate session object and connect to server
Dim my_session as new DtoSession
Dim result as DtoResult
Dim my_licmgr as DtoLicenseMgr
result = my_session.Connect("myserver", "username", "password")
' now obtain License Manager object
Set my_licmgr = my_session.LicenseMgr
' Add a license
result = my_licmgr.AddLicense(“ERXVD3U4ZS9KR94QPDHV5BN2”)
DeleteLicense
Deauthorizes a license.
Syntax
result = LicenseManager.DeleteLicense(License)
Arguments
LicenseManager | DtoLicenseMgr object |
License | A valid license key to deauthorize from the engine you are currently connected to with a DtoSession 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
None
Example
' instantiate session object and connect to server
Dim my_session as new DtoSession
Dim result as DtoResult
Dim my_licmgr as DtoLicenseMgr
result = my_session.Connect("myserver", "username", "password")
' now obtain License Manager object
Set my_licmgr = my_session.LicenseMgr
' Delete a license
result = my_licmgr.DeleteLicense(“ERXVD3U4ZS9KR94QPDHV5BN2”)
GetProductInfo
Retrieves a list of all Zen products found by the License Manager.
Syntax
result = LicenseManager.GetProductInfo
Arguments
LicenseManager | DtoLicenseMgr object |
Return Values
result | Returns a list of products, in an XML formatted string. |
Remarks
For information about the XML formatted string, see Remarks for PvGetProductsInfo() in Distributed Tuning Interface Guide.
Example
' instantiate session object and connect to server
Dim session As New DtoSession
Set session = New DtoSession
Dim result As dtoResult
result = session.Connect("server", "user", "password")
If result <> Dto_Success Then
MsgBox "Error on connect." & CStr(result)
Exit Sub
End If
Dim xmlstring As String
xmlstring = session.LicenseMgr.GetProductInfo
RichTextBox1.TextRTF = xmlstring
ValidateLicenses
Initiates a check of the validity of all keys on the computer specified by the session connection.
Syntax
result = LicenseManager.ValidateLicenses
Arguments
LicenseManager | DtoLicenseMgr 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
ValidateLicenses returns only the result from requesting a validation check. It does not return any information about the state of the keys. You must separately call GetProductInfo to get the XML string of product information that includes information about the state of the keys.
Example
' instantiate session object and connect to server
Dim my_session as new DtoSession
Dim result as DtoResult
Dim my_licmgr as DtoLicenseMgr
result = my_session.Connect("myserver", "username", "password")
' now obtain License Manager object
Set my_licmgr = my_session.LicenseMgr
' initiate a validation check of all keys
result = my_licmgr.ValidateLicenses
DtoSettings Collection
This collection contains DtoSetting objects which represent all the settings for a particular DtoCategory object.
Properties
Count | Returns number of members in a collection. |
Item | Returns a specific member of a collection. |
Methods
None
Remarks
Use the Count property to find the number of members in the collection.
This collection allows retrieving individual items by passing a variant containing either the 1-based ordinal or the setting name.
Note: Individual settings can also be obtained using the GetSetting method of DtoSession Object, thus saving a loop through the categories and settings.
Example
Dim my_categories as DtoCategories
Set my_categories = my_session.Categories
Dim my_settings as DtoSettings
Dim first_setting as DtoSetting
Set my_settings = my_categories.Settings
Set first_setting = my_settings(1)
See Also
DtoSetting Object
This object represents a configuration setting.
Properties
AllPossibleSelections | Returns DtoSelectionItems Collection or DtoSelectionItem Object representing all the possible items in a single or multiple type setting. This property is only valid for a setting with property Type of 'dtoSingleSelection' or 'dtoMultiSelection', which corresponds to property TypeNames of 'Single Selection' and 'Multiple Selection'. |
Category | Returns DtoCategory object associated with this setting. |
DefaultValue | Returns default value for the setting. The returned value is a variant based on the Type of the setting. A Type of Single selection returns a DtoSelectionItem object. A Type of Multiple selection returns a DtoSelectionItems collection. |
Factor | Returns factor value of the setting. For example, many settings are stored by Zen in bytes, but for the purpose of changing the setting the user might input a value in kilobytes. If a setting returned 16384 for the Value property and the Factor property returned 1024, your program should divide 16384 by 1024 and return 16 to the user. Then query the FactorString property to get the new units. In this case, it would be kilobytes. Before setting the Value property , you should multiply the user-supplied value by Factor. |
FactorString | Returns units for the Value property adjusted for the Factor property. For example, if the UnitString property returns "bytes," the FactorString property will return "kbytes," and Factor property will return "1024". |
FalseString | Returns false value for a Boolean type setting. This property is only valid for a Boolean type setting. Use the Type property to determine if the setting is Boolean. |
Help | Returns help text associated with a setting. |
IsClient | Returns a Boolean of whether the setting is applicable to Zen Client or Enterprise Server. True = Client False = Server |
Max | Returns maximum value of a Long type setting. This property is only valid for a Long type setting. Use the Type property to determine if the setting is Long. If this property returns a negative number, interpret it as follows: /* Maximum valid memory or disk size */P_MAX_MEM_DISK_SIZE -129 /* Maximum size limited by available disk space */P_MAX_LIMITED_BY_DISK -2 /* Maximum size limited by available memory */P_MAX_LIMITED_BY_MEMORY -1 |
Min | Returns minimum value of a Long type setting. This property is only valid for a Long type setting. Use the Type property to determine if the setting is Long. This property returns -1 if the property is not applicable. |
Name | Returns name of the setting. |
Rank | Returns rank of a setting. The rank groups settings according to whether they apply to advanced users only. 0 = Normal 1 = Advanced |
Session | Returns session associated with this object. |
SettingID | Returns unique identifier for a setting. |
TrueString | Returns true value for a Boolean type setting. This property is only valid for a Boolean type setting. Use the Type property to determine if the setting is Boolean. |
Type | Returns setting type (Setting Type enumeration) 0 = Boolean 1 = Long 2 = String 3 = Single selection 4 = Multiple selection |
TypeName | Returns setting type in string form Boolean Long String Single selection Multiple selection |
UnitString | Returns measure of a long type setting. For example: seconds, bytes To adjust the Value for a more user-friendly range of values, use the Factor and FactorString properties. |
Value | Gets or sets the value of a setting. The returned value is a variant based on the Type of the setting. A Type of Single selection returns a DtoSelectionItem object. A Type of Multiple selection returns a DtoSelectionItems collection. When setting this property for a Long type setting, check to see that the value is within the limits for the particular setting by querying the Min and Max properties. |
Collections
Methods
None
Remarks
Use the Type property to find the type of the setting. Note that, depending on the type:
• The properties TrueString and FalseString apply to Boolean type settings (0) only.
• The properties Factor, FactorString, Max, Min, and UnitString apply to Long type settings (1) only.
Example
Set my_settings = my_category.Settings
Set first_setting = my_settings(1)
See Also
DtoSelectionItems Collection
A collection of DtoSelectionItem objects representing the possible values of a selection type setting.
Properties
Count | Returns number of members in a collection. |
Item | Returns a specific member of a collection. |
Methods
Remarks
The property AllPossibleSelections of object DtoSetting Object returns the DtoSelectionItems collection.
Use the Count property to find the number of members in the collection.
Example
Set first_setting = my_settings(1)
type = first_setting.Type
' only call this for selection type settings
' see Setting Type enumeration
' for a list of setting types
if (type = dtoSingleSel) OR (type = dtoMultiSel)
Set all_the_selections = first_setting.AllPossibleSelections
See Also
Methods Detail
Add method
Add an item to a DtoSelectionItems collection.
Syntax
result = Collection.Add(Object)
Arguments
Collection | DtoSelectionItems Collection to which to add object. |
Object | A DtoSelectionItem object that you want to add. |
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 DtoSelectionItem. 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 Session As New DtoSession
Result = Session.Connect("nik-ntws", "", "")
Dim my_setting As DtoSetting
Dim SetID As Long
SetID = 26
Set my_setting = Session.GetSetting(SetID)
If my_setting Is Nothing Then
MsgBox " Setting is wrong"
Exit Sub
End If
' Start to assign new values:
' Add Item with ItemID 1
new_selections.Add my_setting.AllPossibleSelections.Item(1)
' TCP
my_setting.Value = new_selections
GetById method
Returns a DtoSelectionItem object from a DtoSelectionItems collection given an id.
Syntax
my_selection_item = Collection.GetById(id)
Arguments
Collection | DtoSelectionItems collection |
id | The id of the item you wish to retrieve from the collection. The id for a particular selection item can be obtained with the ItemId property of the DtoSelectionItem object. |
Return Values
my_selection_item | DtoSelectionItem Object corresponding to id. |
Example
Dim Result As DtoResult
Dim Session As New DtoSession
Result = Session.Connect("nik-ntws", "", "")
Dim my_setting As DtoSetting
Dim SetID As Long
SetID = 26
Set my_setting = Session.GetSetting(SetID)
If my_setting Is Nothing Then
MsgBox " Setting is wrong"
Exit Sub
End If
Dim new_selections As New DtoSelectionItems
new_selections.Add my_setting.AllPossibleSelections.GetByID(3) 'Microsoft TCP/IP
my_setting.Value = new_selections
Remove method
Removes an item from a DtoSelectionItems collection
Syntax
result = Collection.Remove(item)
Arguments
Collection | DtoSelectionItems collection |
item | Variant that can contain the index (starting with 1) of the item you wish to remove from the collection or the name of the selection item. |
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 DtoSelectionItem
Example
Dim Result As DtoResult
Dim Session As New DtoSession
Result = Session.Connect("nik-ntws", "", "")
Dim my_setting As DtoSetting
Dim SetID As Long
SetID = 26
Set my_setting = Session.GetSetting(SetID)
If my_setting Is Nothing Then
MsgBox " Setting is wrong"
Exit Sub
End If
Dim new_selections As New DtoSelectionItems
new_selections.Add my_setting.AllPossibleSelections.GetByID(3) ''Microsoft TCP/IP
new_selections.Remove(1)
my_setting.Value = new_selections
DtoSelectionItem Object
An object representing a possible value of a selection type setting.
Properties
ItemID | Returns unique ID of a selection item. |
Setting | Returns setting to which this selection item applies. |
String | Returns value of a selection item. |
Methods
None
Remarks
The AllPossibleSelections property of the DtoSetting Object returns the DtoSelectionItems collection.
Example
Set first_setting = my_settings.Item(1)
Dim type as dtoSettingType
type = first_setting.Type
' only call this for selection type settings
' see Setting Type enumeration
' for a list of setting types
if (type = dtoSingleSel) OR (type = dtoMultiSel) then
Dim all_the_selections as DtoSelectionItems
Dim selection as DtoSelectionitem
Set all_the_selections = first_setting.AllPossibleSelections
Dim String_text as String
For each selection in all_the_selections
String_text = selection.String
Next
See Also
DtoServices Object
This object is a collection of DtoService objects, representing the Zen services running on the server.
Properties
Status | Returns status of a service. You must pass the service of which you want the status: dtoServiceTransactional dtoServiceRelational dtoServiceIDS |
StatusString | Returns string representation of the current status. |
Methods
Remarks
The methods of DtoServices control the Zen engine services running on the machine you connected to with the DtoSession object. All these methods return the enumeration DtoResult.
This object lets you start and stop the Zen engine services running on Windows platforms. Also, you can query the current status of Zen services using the Status or StatusString properties.
Security Information Regarding DtoServices Object
• This object uses the same user name and password as the DtoSession object to connect to a Windows server.
• When using the methods of this object from a web application hosted by Microsoft Internet Information Service (IIS), you must set properties on the directory where the DTO web application resides so that IIS allows DTO to run in the same process as the IIS service. Otherwise, you can obtain the current state of the services, but using the start or stop methods returns DTO error 431 (access denied). To set the IIS folder properties needed for the methods of the DTO Services object, perform the following procedure on folders where DTO web applications are located. See the Microsoft IIS documentation for more information on IIS configuration.
To configure IIS to allow starting and stopping of services from a DTO web application
1. Click Start, select Settings and point to Control Panel.
2. Double-click Administrative Tools.
3. Double-click Internet Service Manager.
4. Browse to the folder containing your DTO ASP application.
5. Right-click the folder in the left pane and select Properties.
6. Click the Directory tab.
7. Specify Low (IIS Process) in the Application Protection field in the dialog for IIS directory properties for DTO Services Methods. 
Examples
' This example connects to a server and restarts
' Zen services.
Dim my_session as new DtoSession
Dim my_services as DtoServices
Dim result as DtoResult
result = my_session.Connect("myserver", "username", "password")
Set my_services = my_session.Services
result = my_services.RestartAllServices
' This example connects to a server and starts the
' DataExchange (DX) Agent service and the DX replication
' service.
Dim my_session as new DtoSession
Dim my_services as DtoServices
Dim result1 as DtoResult
Dim result2 as DtoResult
result = my_session.Connect("myserver", "username", "password")
Set my_services = my_session.Services
result1 = my_services.StartDXReplication
result2 = my_services.StartDXAgent
See Also
Methods Detail
RestartAllServices method
Stops and then restarts the services for transactional, relational, DataExchange (DX) agent, and DX replication.
Syntax
result = Services.RestartAllServices
Arguments
Services | DtoServices 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. |
StartRelational method
Starts the Relational service. As of Zen v14, this is the same as the StartTransactional method.
Syntax
result = Services.StartRelational
Arguments
Services | DtoServices 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. |
StartTransactional method
Starts the Btrieve transactional engine service. As of Zen v14, this is the same as the StartRelational method.
Syntax
result = Services.StartTransactional
Arguments
Services | DtoServices 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. |
StopRelational method
Stops the Relational engine service. As of Zen v14, this is the same as the StopTransactional method.
Syntax
result = Services.StopRelational
Arguments
Services | DtoServices 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. |
StopTransactional method
Stops the Btrieve transactional engine service. As of Zen v14, this is the same as the StopRelational method.
Syntax
result = Services.StopTransactional
Arguments
Services | DtoServices 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. |
StartDXAgent
Starts the DataExchange (DX) agent service. The DX agent is a component that detects critical replication failures and notifies administrators by e‑mail. See DataExchange documentation for more information.
You can start the DX agent service before the DX replication service, but the agent returns a message informing you that replication is stopped. This is expected behavior because the replication service is not yet running.
Syntax
result = Services.StartDXAgent
Arguments
Services | DtoServices 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. |
StartDXReplication
Starts the DataExchange (DX) replication service (the Replication Engine). The Replication Engine captures and shares changes from one Zen database to other databases in a DataExchange replication network. See DataExchange documentation for more information.
Starting the replication service also starts the transactional and the relational services.
Syntax
result = Services.StartDXReplication
Arguments
Services | DtoServices 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. |
StopDXAgent
Stops the DataExchange (DX) agent service. The DX agent is a component that detects critical replication failures and notifies administrators by email. See DataExchange documentation for more information.
Syntax
result = Services.StopDXAgent
Arguments
Services | DtoServices 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. |
StopDXReplication
Stops the DataExchange (DX) Replication Engine. The Replication Engine captures and shares changes from one Zen database to other databases in a DataExchange replication network. See DataExchange documentation for more information.
Syntax
result = Services.StopDXReplication
Arguments
Services | DtoServices 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. |
Last modified date: 10/31/2023