Scripting dictionaries — Legacy
This documentation is for legacy Kiwi Syslog Server versions 9.8.3 and older.
When you write scripts, you can use the dictionaries collection to create named dictionaries that store data key and item pairs. The data stored in these dictionaries exists for the lifetime of the application. Dictionaries have the same scope as the VarGlobal
variables in the Fields namespace.
A named Dictionary is the equivalent of a PERL associative array. Dictionaries store items (data) in the array and each item is associated with a unique key.
The key is used to retrieve an individual item and can be anything except an array, such as an integer or string.
Find dictionary methods and properties through the dictionaries namespace.
Built in functions of the Dictionaries object
StoreItem(dicName As String, dicKey As String, dicItem As Variant)
The StoreItem
function stores a key and item pair to a named dictionary.
dicName | Required | The name of the dictionary. If dicName does not exist, it is created. |
dicKey | Required |
The key associated with the stored item. If created. |
dicItem | Required | The item associated with the stored key. |
Example syntax: Call Dictionaries.StoreItem("MyDictionary", "MyKeyName", "MyItemValue")
AddItem(dicName As String, dicKey As String, dicItem As Variant)
The AddItem
function stores a key and item pair to a named dictionary. A script error occurs if the key dicKey
already exists in the dictionary dicName
.
dicName |
Required |
The name of the dictionary. If dicName does not exist, it is created. |
dicKey | Required | The key associated with the item added. |
dicItem | Required | The item associated with the key added. |
Example syntax: Call Dictionaries.AddItem("MyDictionary", "MyKeyName", "MyItemValue")
The .AddItem()
and .UpdateItem()
have been supplanted by the .StoreItem()
function as of Kiwi Syslog Server version 8.1.4. However, to ensure backwards compatibility the usage of .AddItem()
and .UpdateItem()
will continue to be supported.
UpdateItem(dicName As String, dicKey As String, dicItem As Variant)
The UpdateItem
function updates the item associated with key dicKey
to the value in dicItem
. Only the dictionary dicName
is affected. A script error occurs if the dictionary dicName
does not exist, or if the key dicKey
does not exist.
dicName | Required | The name of the dictionary. |
dicKey | Required | The key associated with the item updated. |
dicItem | Required | The new item to be updated. |
Example syntax: Call Dictionaries.UpdateItem("MyDictionary", "MyKeyName", "MyNewItemValue")
RemoveItem(dicName As String, dicKey As String)
The RemoveItem
function removes a key and item pair from the dictionary dicName
. A script error occurs if the dictionary dicName
does not exist, or if the key dicKey
does not exist.
dicName | Required | The name of the dictionary. |
dicKey | Required | The key associated with the item removed. |
Example syntax: Call Dictionaries.RemoveItem("MyDictionary", "MyKeyName")
RemoveAll(dicName As String)
The RemoveAll
function removes all key and item pairs from the dictionary dicName
. A script error occurs if the dictionary dicName
does not exist.
dicName | Required | The name of the dictionary removed. |
Example syntax: Call Dictionaries.RemoveAll("MyDictionary")
Delete(dicName As String)
The Delete
function deletes the entire dictionary dicName
. A script error occurs if the dictionary dicName
does not exist.
dicName | Required |
The name of the dictionary being deleted. |
Example syntax: Call Dictionaries.RemoveItem("MyDictionary", "MyKeyName")
DeleteAll
The DeleteAll
function deletes all dictionaries.
Example syntax: Call Dictionaries.DeleteAll()
GetItemCount(dicName As String) As Long
The GetItemCount
function returns the number of items in the dictionary dicName
. A script error occurs if the dictionary dicName
does not exist.
dicName | Required | The name of the dictionary. |
Example syntax: ItemCount = Dictionaries.GetItemCount("MyDictionary")
GetItem(dicName As String, dicKey As String) As Variant
The GetItem
function returns an item for a specified key dicKey
in the dictionary dicName
. An error occurs if the dictionary dicName
does not exist, or if the key dicKey
does not exist.
dicName | Required | The name of the dictionary. |
dicKey | Required |
The key associated with the item fetched. |
Example syntax: MyItem = Dictionaries.GetItem("MyDictionary", "MyKeyName")
ItemExists(dicName As String, dicKey As String) As Boolean
The ItemExists
property returns True if the specified key dicKey
exists in the dictionary dicName
. An error occurs if the dictionary dicName
does not exist.
dicName | Required | The name of the dictionary. |
dicKey | Required | The key associated with the item fetched. |
Example syntax: If Dictionaries.ItemExists("MyDictionary", "MyKeyName") Then
...
End If
GetKeys(dicName As String) As Variant
The GetKeys
property returns an array containing the keys in the dictionary dicName
. An error occurs if the dictionary dicName
does not exist.
dicName | Required | The name of the dictionary. |
Example syntax: MyKeyArray = Dictionaries.GetKeys("MyDictionary")
For i = 0 to UBound(MyKeyArray)
ThisKey = MyKeyArray(i)
...
Next
GetItems(dicName As String) As Variant
The GetItems
property returns an array containing the items in the dictionary dicName
. An error occurs if the dictionary dicName
does not exist.
dicName | Required | The name of the dictionary. |
Example syntax: MyItemArray = Dictionaries.GetItems("MyDictionary")
For i = 0 to UBound(MyItemArray)
ThisItem = MyItemArray(i)
...
Next
Error Reference
The following table lists and provides a brief explanation of some of the common errors you may receive when attempting to execute each function.
Function Name | Error Description |
---|---|
GetName() | Script Error executing .GetName() - Dictionary does not exist |
Delete() | Script Error executing .Delete() - Dictionary [x] does not exist |
AddItem() | Script Error executing .AddItem() - Dictionary Key [x] already exists in dictionary [y] |
UpdateItem() |
Script Error executing .UpdateItem() - Dictionary Key [x] does not exist in dictionary [y] Script Error executing .UpdateItem() - Dictionary [x] does not exist |
RemoveItem() |
Script Error executing .RemoveItem() - Dictionary Key [x] does not exist in dictionary [y] Script Error executing .RemoveItem() - Dictionary [x] does not exist |
RemoveAllItems() | Script Error executing .RemoveAllItems() - Dictionary [x] does not exist |
GetItemCount() | Script Error executing .GetItemCount() - Dictionary [x] does not exist |
GetItems() | Script Error executing .GetItems() - Dictionary [x] does not exist |
GetKeys() | Script Error executing .GetKeys() - Dictionary [x] does not exist |
GetItem() |
Script Error executing .GetItem() - Dictionary Key [x] does not exist in dictionary [y] Script Error executing .GetItem() - Dictionary [x] does not exist |
ItemExists() | Script Error executing .ItemExists() - Dictionary [x] does not exist |