Navigation:  Advantage Concepts > Advantage Functionality >

Root Dictionary

Advantage Database Server

Previous pageReturn to chapter overviewNext page

The concept of a root dictionary was introduced in v11 of Advantage. The root dictionary was primarily added in this release to help support the Advantage Web Administrator utility and some functionality in the Advantage Web Platform. But it may also provide functionality that you may find useful in other situations. Initially, the root dictionary functionality is limited to providing some additional security enhancements.


Two new database roles SERVER:Admin and SERVER:Monitor have been added.  These apply to users with membership in these roles only when the user is connected to the root dictionary.
Some new system procedures such as sp_mgGetCrashDumpInfo, sp_mgGetErrorLog, sp_GetLinks, and sp_mgSetConfigValue can only be called when connected to the root dictionary.
sp_mgKillUser now requires DB:Admin or SERVER:Admin membership. If a user is a member of SERVER:Admin and is connected to the root dictionary, then the user can use sp_mgKillUser to disconnect any user on the server. Otherwise, sp_mgKillUser now only allows users to be disconnected by members of DB:Admin and only if the user is in the same dictionary as the DB:Admin user.
sp_mgKillUser allows wild card (an asterisk) to be given as the user name when run by SERVER:Admin members on the root dictionary.
With the Web Administrator Utility, it is possible to run queries against other dictionaries when connected to the root dictionary. Note that this requires the __Query service to be enabled on the root dictionary and pass-through queries to be enabled on the target dictionary (see sp_ModifyDatabase and AdsDDSetDatabaseProperty and the ADS_DD_QUERY_VIA_ROOT property). This pass-through query capability means it is possible to expose a single dictionary through the Advantage Web Platform but be able to perform some administration on other databases on the same server. To enable pass-through queries, you can use Advantage Data Architect to modify the settings under the Advanced tab of the data dictionary properties dialog. Or you can modify them directly with the system procedure.  For example, "EXECUTE PROCEDURE sp_ModifyDatabase( 'Query_Via_Root', '3' )" will enable pass-through queries and pass-through procedure requests.
For security reasons, system procedures can only be executed against the root dictionary through the Advantage Web Platform. To execute system procedures through the web platform against non-root dictionaries, it would be necessary to enable the __Query service and use an SQL statement.


A single installation of Advantage Database Server can have only one root dictionary. It is specified by the ROOT_DICTIONARY configuration parameter. This configuration parameter can be set on the Windows platform by using the Advantage configuration utility (ads_cfg.exe) under the file locations tab. Note that the path supplied in the configuration value must match exactly the path of the dictionary when it is opened.  You can use the system variable ::Conn.IsRoot to determine if a dictionary is the root dictionary. For example, after setting the ROOT_DICTIONARY configuration parameter and restarting Advantage Database Server for it to be recognized, you can run the query:


SELECT ::Conn.IsRoot FROM system.iota;


when connected to the root dictionary to verify that it is indeed recognized as the root dictionary.


You can specify an existing dictionary as the root.  However, you can also create a new empty dictionary as the root dictionary for use with the Advantage Web Administrator Utility for management purposes. This might be desirable if you do not want to expose an existing dictionary through the Advantage Web Platform.


__rootdd System Alias

A system alias named __rootdd is available that resolves to the path of the configured root dictionary.  Applications can then connect to the root dictionary using a path like \\server\__rootdd.