Dictionary Object
Use this object to support the creation, storage, and retrieval of name/value pairs in memory. Every value in a Dictionary object is a Variant, which means you can create a Dictionary object that consists of almost any kind of value (including other Dictionary objects), and that you can store any combination of Variant types in the same Dictionary object.
ProgID: |
Commerce.Dictionary (Externally creatable) |
COM Class Name: |
CDictionary |
Type Library Name: |
Microsoft Commerce Server Core Components Type Library |
DLL Name: |
MscsCore.dll |
Threading Model: |
Both |
[C++]
COM Interface Name: |
IDictionary |
Interface ID Constant: |
IID_IDictionary |
Header File: |
commerce.h |
In C++, use the IDictionary interface to access the properties and methods of the Dictionary object.
Properties
Property |
Description |
|---|---|
Returns the number of elements in the Dictionary object. This property is read-only. |
|
Stores the string that acts as a filter when the contents of the Dictionary object are saved (usually to a database). When the name of a name/value pair begins with the specified prefix, that name/value pair is not saved. This property is read/write. |
|
Stores the value of a given Dictionary key. This property is read/write. |
Remarks
Because a Dictionary object is designed to be a general-purpose collection, you can use it for almost anything that its internal structure supports.
When you need to create a Dictionary object explicitly (that is, when the object is not created for you by some other Commerce Server object), use the CreateObject method of the Active Server Pages (ASP) object, as follows:
Set dictUser = Server.CreateObject("Commerce.Dictionary")
After creating the object, you can add elements to it, as follows:
dictUser.first_name = "Steve"
In this example, first_name is a Dictionary key, and Steve becomes the assigned value of this key. Each statement actually accomplishes three functions: declaring the Dictionary key, adding that key to the Dictionary object, and setting the key to a value.
You can extract values from a Dictionary object in several ways. You can simply place the object.key identifier on the right side of the assignment statement. Such an assignment returns the value of the referenced key:
my_first_name = dictUser.first_name
Or you can use the Value method to get the value of a given key:
my_first_name = dictUser.Value("first_name")
You can also use the For Each statement in Microsoft Visual Basic Scripting Edition (VBScript) to enumerate through the keys or the values of a Dictionary object as follows (this example assumes that every value in the dictionary contains text):
' Get the key names
For Each element In dictUser
Response.Write element
Next
' Get the values
For Each element In dictUser
Response.Write dictUser.Value(element)
Next
Commerce Server sites use implementations of the Dictionary object to store sets of data that are required by various other objects and pipeline components.
Unlike previous versions of the dictionary, the dictionary in Commerce Server is implemented as a hash of name value pairs. This enables the dictionary to perform fast lookups even when a large number of key/value pairs are stored. It also has the side effect that enumerations of dictionary keys may not be returned in the same order they are stored.
The dictionary object aggregates the Free Threaded Marshaller (FTM) for performance reasons (so that calls to the dictionary will never go through a proxy, no matter what COM apartment it is called from). Because of this, you may not store a reference to an apartment-threaded object in a dictionary. Doing so may result in errors such as RPC_E_WRONGTHREAD when the object pointer is retrieved and used.
The Dictionary object supports the ICloneable and IPersistXML interfaces. Use the ICloneable interface to deep copy all name/value pairs into a new dictionary. Use the IPersistXML interface to convert the Dictionary entries into an XML string and back again.