Submit a ticketCall us

Get a crash course on Network Monitoring delivered right to your inbox
This free 7-day email course provides a primer to the philosophy, theory, and fundamental concepts involved in IT monitoring. Lessons will explain not only how to perform various monitoring tasks, but why and when you should use them. Sign up now.

Home > Success Center > Kiwi Syslog Server > Kiwi Syslog Server Administrator Guide > Scripting resources > Scripting dictionaries

Scripting dictionaries

When you are writing scripts, the dictionaries collection allows for the creation of (named) dictionaries that store data key and item pairs. The data stored in these dictionaries is persistent, in that it exists for the lifetime of the application. Dictionaries have essentially the same scope as the VarGlobal variables in the Fields namespace.

A named Dictionary is the equivalent of a PERL associative array. Items, which can be any form of data, are stored in the array. Each item is associated with a unique key. The key is used to retrieve an individual item and is usually a integer or a string, but can be anything except an array.

All dictionary methods and properties are accessible through the "dictionaries" namespace.

Built in functions of the "Dictionaries" object

StoreItem

StoreItem(dicName As String, dicKey As String, dicItem As Variant)

The StoreItem method stores a key, item pair to a named dictionary.

dicName Required The name of the dictionary. I.f dicName does not exist, it will be created.
dicKey Required

The key associated with the item being stored. If dicKey does not exist, it will

be created.

dicItem Required The item associated with the key being stored.

Example: Call Dictionaries.StoreItem("MyDictionary", "MyKeyName", "MyItemValue")

AddItem

The .AddItem() and .UpdateItem() methods have been supplanted as of version 8.1.4 of Kiwi Syslog Server, by the .StoreItem() method. However, to ensure backwards compatibility the usage of .AddItem() and .UpdateItem() will continue to be supported.

AddItem(dicName As String, dicKey As String, dicItem As Variant)

The AddItem method adds a key, item pair to a named dictionary. An error will occur if the key dicKey already exists in the dictionary dicName.

dicName

Required

The name of the dictionary. If dicName does not exist, it will be created.
dicKey Required The key associated with the item being added.
dicItem Required The item associated with the key being added.

Example: Call Dictionaries.AddItem("MyDictionary", "MyKeyName", "MyItemValue")

UpdateItem

UpdateItem(dicName As String, dicKey As String, dicItem As Variant)

The UpdateItem method updates the item associated with key dicKey to the value in dicItem. Only the dictionary dicName is affected. An error will occur if dictionary dicName does not exist, or if key dicKey does not exist.

dicName Required The name of the dictionary.
dicKey Required The key associated with the item being updated.
dicItem Required The new item to be updated.

Example: Call Dictionaries.UpdateItem("MyDictionary", "MyKeyName", "MyNewItemValue")

RemoveItem

RemoveItem(dicName As String, dicKey As String)

The RemoveItem method removes a key, item pair from the dictionary dicName. An error will occur if dictionary dicName does not exist, or if key dicKey does not exist.

dicName Required The name of the dictionary
dicKey Required The key associated with the item being removed.

Example: Call Dictionaries.RemoveItem("MyDictionary", "MyKeyName")

RemoveAll

RemoveAll(dicName As String)

The RemoveAll method removes all key, item pairs from the dictionary dicName. An error will occur if dictionary dicName does not exist.

dicName Required The name of the dictionary

Example: Call Dictionaries.RemoveAll("MyDictionary"

Delete

Delete(dicName As String)

The Delete method deletes the entire dictionary dicName. An error will occur if dictionary dicName does not exist.

dicName Required

The name of the dictionary being deleted.

Example: Call Dictionaries.RemoveItem("MyDictionary", "MyKeyName")

DeleteAll

DeleteAll()

The DeleteAll method deletes all dictionaries.

Example: Call Dictionaries.DeleteAll()

GetItemCount

GetItemCount(dicName As String) As Long

The GetItemCount property returns the number of items in the dictionary dicName. An error will occur if dictionary dicName does not exist.

dicName Required The name of the dictionary.

Example: ItemCount = Dictionaries.GetItemCount("MyDictionary")

GetItem

GetItem(dicName As String, dicKey As String) As Variant

The GetItem property returns an item for a specified key dicKey in dictionary dicName. An error will occur if dictionary dicName does not exist, or if key dicKey does not exist.

dicName Required The name of the dictionary.
dicKey Required

The key associated with the item being fetched.

Example: MyItem = Dictionaries.GetItem("MyDictionary", "MyKeyName")

ItemExists

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 will occur if dictionary dicName does not exist.

dicName Required The name of the dictionary.
dicKey Required The key associated with the item being fetched.

Example: If Dictionaries.ItemExists("MyDictionary", "MyKeyName") Then
...
End If

GetKeys

GetKeys(dicName As String) As Variant

The GetKeys property returns an array containing all the keys in the dictionary dicName. An error will occur if dictionary dicName does not exist.

dicName Required The name of the dictionary

Example: MyKeyArray = Dictionaries.GetKeys("MyDictionary")
For i = 0 to UBound(MyKeyArray)
ThisKey = MyKeyArray(i)
...
Next

GetItems

GetItems(dicName As String) As Variant

The GetItems property returns an array containing all the items in the dictionary dicName. An error will occur if dictionary dicName does not exist.

dicName Required The name of the dictionary

Example:
MyItemArray = Dictionaries.GetItems("MyDictionary")
For i = 0 to UBound(MyItemArray)
ThisItem = MyItemArray(i)
...
Next

Error Reference

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
Last modified
12:39, 2 Mar 2017

Tags

Classifications

Public