Functions for Configuration Data

The functions in this chapter read configuration data from he Digas registry. They may be unavailable if the logged on user doesn’t have read access to the respective registries.

Terminology

This documentation page uses the following terms with you should understand.

• Hive – This describes the registry or sequence of registries to use for the operation. Valid values are USER, LOCAL, GLOBAL, or CORPORATE, which denote a specific registry each, or PREFER_USER, PREFER_LOCAL, PREFER_GLOBAL, or PREFER_CORPORATE, which describe that the search should start in one place, and if no entry is found, it should continue through a sequence of registries.

• Key -- A key works like the directory portion of a file name. Like a directory in a file system, a key in the Digas registry can contain an arbitrary number of subkeys and an arbitrary number of entries. A key is describes as a sequence of names, separated by backslashes (\), like "DBM\UISchemes\UISCheme_dark",

• Entry – An entry consists of a name, a type, and a value. To completely describe an entry, the key and name must be known. The type and value then come from the registry.

• Type – An entry’s type is one of STRING INTEGER BINARY. The type limits the range of data which can be stored in the entry.

When used as parameters to these functions, hive, key, name, and type are case insensitive.

GetConfigValue function

Retrieves a configuration value from the Digas registry.

Synopsis

%decay_rate = GetConfigValue("user", "dbm\loudness", "LVC_TP_DecayRate")

Parameters

Returns

The value which was found in the registry, possibly as a number; or the default value if no entry was found.

Remarks

If an entry with the name is not found in the specified key of the specified registry or registries, and a default is given, then the function returns default; otherwise, it returns an empty string.

If type is specified, and the entry's type does not match the type parameter, an empty string is returned.

If the entry has a value of type INTEGER, then the function returns a number; otherwise, it returns a string.

If the entry has a value of type BINARY, the function returns a string which contains a JSON array of bytes in decimal notation.

The type can also be specified as BOOL, in which case the return value is either 0 or 1. It is 1 if the value is of type INTEGER other than 0, STRING value "1" or "TRUE", or a BINARY value which contains at least one nonzero byte.

GetConfigValueType function

Retrieves the type of a configuration value from the Digas registry. This function can also be used to find out whether a specific entry exists.

Synopsis

%type = GetConfigValueType(prefer_user, dbm\accel, desel)

Parameters

Returns

• If the entry exists, the function returns one of STRING INTEGER BINARY, indicating the type of the entry.

• Otherwise, it returns an empty string.

ExistsConfigKey function

Finds out whether a configuration key in the Digas registry exists.

Synopsis

%has_user_masks = ExistsConfigKey(prefer_user, dbm\usermasks)

Parameters

Returns

• 1 if the key exists, regardless of whether it contains any subkeys or entries.

• 0 otherwise.

GetConfigTree function

Returns alls entries and subkeys of a configuration key recursively, as XML or JSON structure.

This information is preliminary and may change

Synopsis

%tree = GetConfigTree(global, DBM, 2, json)

Parameters

Returns

A string either in XML or in JSON format with the configuration data. The actual format depends on the format parameter.

Remarks

• The format can be XML or JSON or JSON_COMPACT.

• A negative value for levels means unlimited recursion.

XML Example

<?xml version="1.0" encoding="UTF-16"?>
<Config base="DBM">
 <Key name="Window">
  <Value name="LoadColumnPos" type="integer">1</Value>
  <Value name="SaveColumnPos" type="integer">1</Value>
  <Value name="LoadFonts" type="integer">0</Value>
...
 </Key>
 <Key name="Selection">
  <Key name="Duration"></Key>
  <Value name="SearchText" type="integer">65535</Value>
  <Value name="AddJokers" type="integer">1</Value>
 </Key>
 <Key name="WinPos">
  <Value name="Main" type="string">155 57 1897 934 0</Value>
  <Value name="OnAIRTrackMixer" type="string">939,891</Value>
  <Value name="LinkDlg" type="string">703,353</Value>
 </Key>
 <Key name="MainScreen">
  <Value name="Content0" type="integer">0</Value>
  <Value name="Content1" type="integer">16</Value>
...
 </Key>
...
</Config>

JSON Example

{
  "base": "DBM",
  "Keys":
  [
    {
      "name": "Window",
      "Values":
      [
        {
          "name": "LoadColumnPos",
          "type": "integer",
          "data": 1
        },
        {
          "name": "SaveColumnPos",
          "type": "integer",
          "data": 1
        },
        {
          "name": "LoadFonts",
          "type": "integer",
          "data": 0
        },
...
      ]
    },
    {
      "name": "Selection",
      "Keys":
      [
        {
          "name": "Duration"
        }
      ],
      "Values":
      [
        {
          "name": "SearchText",
          "type": "integer",
          "data": 65535
        },
        {
          "name": "AddJokers",
          "type": "integer",
          "data": 1
        },
        {
          "name": "_MaxMainLines",
          "type": "string",
          "data": "10"
        }
      ]
    },
...
  ]
}

JSON_COMPACT Example

$body