Your VM Perplexities Called, and They Need You to Read This.
Virtualization can give you enormous flexibility with future workloads and can be a key enabler for other areas, like cloud computing and disaster recovery. So, how can you get a handle on the performance challenges in your virtual environment and manage deployments without erasing the potential upside? Learn the four key areas you need to be focusing on to help deliver a healthy and well-performing data center.
Get your free white paper.
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.
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")
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(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(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(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(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()
The DeleteAll method deletes all dictionaries.
Example: Call Dictionaries.DeleteAll()
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(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(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(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(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
| 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 |