<html>
<head>
<title>Dictionary Object</title>
</head>
<body bgcolor="#FFFFFF" text="#000000">
<div id="Description">
<table cellpadding="0" cellspacing="0" border="0" width="100%" class="main">
<tr>
<td valign="top" class="NAME">Dictionary Object</td>
<td valign="top" class="COMPATIBILITY">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"></td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="TITLE">Createable</td>
</tr>
<tr>
<td colspan="2" class="description">

<p>Yes</p>

</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="TITLE">Library</td>
</tr>
<tr>
<td colspan="2" class="description">

<p>Microsoft Scripting Runtime</p>

</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="TITLE">Description</td>
</tr>
<tr>
<td colspan="2" class="description">

<p>The Dictionary object is similar to a Collection object, except that
it's loosely based on the Perl associative array.
Like an array or a Collection object, the Dictionary object holds
elements, called <em>items</em> or
<em>members</em>, containing data. A Dictionary object
can contain any data whatsoever, including objects and other
Dictionary objects. Access the value of these dictionary items by
using unique <em>keys</em> (or named values) that are
stored along with the data, rather than by using an
item's ordinal position as you do with an array.
This makes the Dictionary object ideal when you need to access data
that is associated with a unique named value.
</p>

<p>You can access each item stored to a Dictionary object by using the
<span class="LITERAL">For</span> <span class="LITERAL">Each ...Next</span> construct.
However, rather than returning a variant containing the data value
stored to the Dictionary object as you would expect, it returns a
variant containing the key associated with the member. You then have
to pass this key to the Item method to retrieve the member, as the
following example shows:
</p>

<span class="PROGRAMLISTING"><pre>Dim vKey 
Dim sItem, sMsg 
Dim oDict 
    
Set oDict =  CreateObject("Scripting.Dictionary")
oDict.Add "One", "Engine"
oDict.Add "Two", "Wheel"
oDict.Add "Three", "Tire"
oDict.Add "Four", "Spanner"
        
For Each vKey In oDict
   sItem = oDict.Item(vKey)
   sMsg = sMsg &amp; sItem &amp; vbCrLf
Next
   
MsgBox sMsg</pre></span>

</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="TITLE">Dictionary Object Properties</td>
</tr>
<tr>
<td colspan="2" class="description">


<p>The Dictionary object includes the following four properties:</p>

<table border="1">



<thead>
<tr valign="top">
<td>
<p>Property</p>
</td>
<td>
<p>Description</p>
</td>
</tr>
</thead>
<tbody>
<tr valign="top">
<td>
<p>CompareMode</p>
</td>
<td>
<p>Determines the order of text comparisons in the Item property</p>
</td>
</tr>
<tr valign="top">
<td>
<p>Count</p>
</td>
<td>
<p>Indicates the total number of items in the dictionary</p>
</td>
</tr>
<tr valign="top">
<td>
<p>Item</p>
</td>
<td>
<p>Sets or retrieves a particular item of data in the dictionary</p>
</td>
</tr>
<tr valign="top">
<td>
<p>Key</p>
</td>
<td>
<p>Renames an existing key</p>
</td>
</tr>
</tbody>

</table>

</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="TITLE">Dictionary Object Methods</td>
</tr>
<tr>
<td colspan="2" class="description">
<p>The Dictionary object supports the following five methods:</p>

<table border="1">



<thead>
<tr valign="top">
<td>
<p>Property</p>
</td>
<td>
<p>Description</p>
</td>
</tr>
</thead>
<tbody>
<tr valign="top">
<td>
<p>Add</p>
</td>
<td>
<p>Adds an item and its associated key to the dictionary</p>
</td>
</tr>
<tr valign="top">
<td>
<p>Exists</p>
</td>
<td>
<p>Determines whether a particular key exists in the dictionary</p>
</td>
</tr>
<tr valign="top">
<td>
<p>Keys</p>
</td>
<td>
<p>Returns all keys in the dictionary</p>
</td>
</tr>
<tr valign="top">
<td>
<p>Remove</p>
</td>
<td>
<p>Removes an item from the dictionary</p>
</td>
</tr>
<tr valign="top">
<td>
<p>Remove All</p>
</td>
<td>
<p>Removes all the data from the dictionary</p>
</td>
</tr>
</tbody>

</table>

</td>
</tr>
</table>
</div>
<div id="DictionaryAddMethod">
<table border="0" cellspacing="0" cellpadding="0" width="100%">
<tr valign="top">
<td class="NAME">
Dictionary.Add Method</td>
<td class="COMPATIBILITY">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"></td>
</tr>
<tr>
<td class="usage" colspan="2">&nbsp;</td></tr>
<tr><td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Syntax</td>
</tr>
<tr>
<td colspan="2" class="description">

<span class="PROGRAMLISTING"><pre><var class="replaceable">dictionaryobject</var>.Add <var class="replaceable">key</var>, <var class="replaceable">item</var></pre></span>

<dl>
<dt><var class="replaceable">dictionaryobject</var></dt>
<dd>
<p>Use: Required</p>
<p>Data Type: Dictionary object</p>

<p>A reference to a Dictionary object.</p>

</dd>
<dt><var class="replaceable">key</var></dt>
<dd>
<p>Use: Required</p>
<p>Data Type: Any</p>

<p>A key value that's unique in the Dictionary object.</p>

</dd>
<dt><var class="replaceable">item</var></dt>
<dd>
<p>Use: Required</p>
<p>Data Type: Any</p>

<p>The item to be added to the dictionary.</p>
</dd>

</dl>
</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Description</td>
</tr>
<tr>
<td colspan="2" class="description">

<p>Adds a key and its associated item to the specified Dictionary object.</p>

</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Rules at a Glance</td>
</tr>
<tr>
<td colspan="2" class="description">

<ul><li>
<p>If the key isn't unique, runtime error 457,
"This key is already associated with an element of
this collection," is generated.
</p>
</li><li>
<p><var class="replaceable">item</var> can be of any data type, including
objects and other Dictionary objects.
</p>
</li></ul>
</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Example</td>
</tr>
<tr>
<td colspan="2" class="description">


<p>The example uses a Dictionary object to store state abbreviations and
their corresponding state names:
</p>

<span class="PROGRAMLISTING"><pre>Dim StateCode, StateName
Dim StateDict
Dim Key

Set StateDict = CreateObject("Scripting.Dictionary")

StateCode = "CA"
StateName = "California"
StateDict.Add StateCode, StateName

StateCode = "NY"
StateName = "New York"
StateDict.Add StateCode, StateName

StateCode = "MI"
StateName = "Michigan"
StateDict.Add StateCode, StateName

Key = "NY"
MsgBox StateDict.Item(Key)</pre></span>

</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Programming Tips and Gotchas</td>
</tr>
<tr>
<td colspan="2" class="description">

<ul><li>
<p>The order of members within a Dictionary object is officially
undefined. That is, you can't control the position
of individual members, nor can you retrieve individual members based
on their position within the Dictionary object. Your code, in short,
should make no assumptions about the position of individual elements
within the Dictionary objects.
</p>
</li><li>
<p>Once you add a key and its associated data item, you can change the
key by using the write-only Key property.
</p>
</li><li>
<p>Use the Dictionary object to store tables of data, and particularly
to store single items of data that can be meaningfully accessed by a
key value.
</p>
</li><li>
<p>The use of the Dictionary object to store multifield data records is
not recommended; instead, classes offer a better programmatic
alternative. Typically, you would store a record by adding an array
representing the record's field values to the
dictionary. But assigning arrays to items in the Dictionary object is
a poor programming practice, since individual elements of the array
cannot be modified directly once they are assigned to the dictionary.
</p>
</li></ul>
</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">See Also</td>
</tr>
<tr>
<td colspan="2" class="description">

<p><link linkend="ch10-38906">Dictionary.Key Property</link></p>

</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
</table>
</div>
<div id="DictionaryCompareModeProperty">
<table border="0" cellspacing="0" cellpadding="0" width="100%">
<tr valign="top">
<td class="NAME">
Dictionary.CompareMode Property</td>
<td class="COMPATIBILITY">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"></td>
</tr>
<tr>
<td class="usage" colspan="2">&nbsp;</td></tr>
<tr><td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Data Type</td>
</tr>
<tr>
<td colspan="2" class="description">


<p>Long</p>

</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Description</td>
</tr>
<tr>
<td colspan="2" class="description">

<p>Sets or returns the mode used to compare the keys in a Dictionary
object.
</p>

</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Rules at a Glance</td>
</tr>
<tr>
<td colspan="2" class="description">

<ul><li>
<p>CompareMode can be set only on a dictionary that
doesn't contain any data.</p>
</li><li>
<p>The CompareMode property can have either of the following two values:</p>

<dl>
<dt>0, Binary</dt>
<li>
<p>This is the default value. It compares the keys with a string
byte-per-byte to determine whether a match exists.</p>



<dt>1, Text</dt>
<dd>
<p>Uses a case-insensitive comparison when attempting to match keys with
a string.</p>
</dd>
</dl>

<p>In addition, the value of CompareMode can be greater than 2, in which case it defines the locale identifier (LCID) to be used in making the comparison.</p>
</ul>

</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Programming Tips and Gotchas</td>
</tr>
<tr>
<td colspan="2" class="description">

<ul><li>
<p>You need to explicitly set the CompareMode property only if you do
not wish to use the default binary comparison mode.
</p>
</li><li>
<p>The Scripting Runtime type library defines constants
(<span class="LITERAL">BinaryCompare</span> and <span class="LITERAL">TextCompare</span>)
that can be used in place of their numeric equivalents. You can do
this in one of three ways. You can define the constants yourself by
adding the following code to your script:
</p>

<span class="PROGRAMLISTING"><pre>Const BinaryCompare = 0
Const TextCompare = 1</pre></span>

<p>You can also use the equivalent
<span class="LITERAL">vbBinaryCompare</span> and
<span class="LITERAL">vbTextCompare</span> constants that are defined in the
VBScript library.</p>

<p>Finally, if you're an ASP programmer, you can use the METADATA directive to access the Scripting Runtime type library; if you're developing a Windows Script Host script, you can include the following line in a Windows Script Host (<filename>.wsf</filename> ) file in order to access the constants from the Scripting Runtime type library:</p>

<span class="PROGRAMLISTING"><pre>&lt;reference GUID="{420B2830-E718-11CF-893D-00A0C9054228}" /&gt;</pre></span></li>

<li>
<p>Practically, the CompareMode property indicates whether the
comparison between existing key names and the
<var class="replaceable">key</var> argument of the Dictionary
object's Add method, Exists method, Item property,
or Key property will be case-sensitive
(<span class="LITERAL">BinaryCompare</span>) or case-insensitive
(<span class="LITERAL">TextCompare</span>). By default, comparisons are
case-sensitive.
</p>
</li></ul>
</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
</table>
</div>
<div id="DictionaryCountProperty">
<table border="0" cellspacing="0" cellpadding="0" width="100%">
<tr valign="top">
<td class="NAME">
Dictionary.Count Property</td>
<td class="COMPATIBILITY">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"></td>
</tr>
<tr>
<td class="usage" colspan="2">&nbsp;</td></tr>
<tr><td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Data Type</td>
</tr>
<tr>
<td colspan="2" class="description">


<p>Long</p>

</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Description</td>
</tr>
<tr>
<td colspan="2" class="description">

<p>A read-only property that returns the number of key/item pairs in a
Dictionary object.
</p>

</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Rules at a Glance</td>
</tr>
<tr>
<td colspan="2" class="description">


<p>This property returns the actual number of items in the dictionary.
So if you use the Count property to iterate the items in the
dictionary, you would use code like the following:
</p>

<span class="PROGRAMLISTING"><pre>Dim ctr
For ctr = 0 to dictionary.Count - 1
   ' do something
Next</pre></span>

</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
</table>
</div>
<div id="DictionaryExistsMethod">
<table border="0" cellspacing="0" cellpadding="0" width="100%">
<tr valign="top">
<td class="NAME">
Dictionary.Exists Method</td>
<td class="COMPATIBILITY">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"></td>
</tr>
<tr>
<td class="usage" colspan="2">&nbsp;</td></tr>
<tr><td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Syntax</td>
</tr>
<tr>
<td colspan="2" class="description">

<span class="PROGRAMLISTING"><pre><var class="replaceable">dictionaryobject</var>.Exists(<var class="replaceable">key</var>) </pre></span>

<dl>
<dt><var class="replaceable">dictionaryobject</var></dt>
<dd>
<p>Use: Required</p>
<p>Data Type: Dictionary object</p>

<p>A reference to a Dictionary object.</p>

</dd>
<dt><var class="replaceable">key</var></dt>
<dd>
<p>Use: Required</p>
<p>Data Type: String</p>

<p>The key value being sought.</p>
</dd>

</dl>
</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Return Value</td>
</tr>
<tr>
<td colspan="2" class="description">

<p>Boolean</p>

</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Description</td>
</tr>
<tr>
<td colspan="2" class="description">

<p>Determines whether a given key is present in a Dictionary object.</p>

</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Rules at a Glance</td>
</tr>
<tr>
<td colspan="2" class="description">


<p>Returns <span class="LITERAL">True</span> if the specified key exists in the
Dictionary object; <span class="LITERAL">False</span> if not.
</p>

</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Programming Tips and Gotchas</td>
</tr>
<tr>
<td colspan="2" class="description">

<ul><li>
<p>If you attempt to use the Item property to return the item of a
nonexistent key, or if you assign a new key to a nonexistent key, the
nonexistent key is added to the dictionary, along with a blank item.
To prevent this, you should use the Exists property to ensure that
the Key is present in the dictionary before proceeding.
</p>
</li><li>
<p>The way in which <var class="replaceable">key</var> is compared with the
existing key values is determined by the setting of the Dictionary
object's CompareMode property.
</p>
</li></ul>
</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Example</td>
</tr>
<tr>
<td colspan="2" class="description">

<span class="PROGRAMLISTING"><pre>If oDict.Exists(strOldKey) Then
    oDict.Key(strOldKey) = strNewKey
End If   </pre></span>

</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
</table>
</div>
<div id="DictionaryItemProperty">
<table border="0" cellspacing="0" cellpadding="0" width="100%">
<tr valign="top">
<td class="NAME">
Dictionary.Item Property</td>
<td class="COMPATIBILITY">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"></td>
</tr>
<tr>
<td class="usage" colspan="2">&nbsp;</td></tr>
<tr><td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Syntax</td>
</tr>
<tr>
<td colspan="2" class="description">


<p>The syntax for setting an item is:</p>

<span class="PROGRAMLISTING"><pre><var class="replaceable">dictionaryobject</var>.Item(<var class="replaceable">key</var>) = <var class="replaceable">item</var></pre></span>


<p>The syntax for returning an item is:</p>

<span class="PROGRAMLISTING"><pre><var class="replaceable">value</var> = <var class="replaceable">dictionaryobject</var>.Item(<var class="replaceable">key</var>)</pre></span>

<dl>
<dt><var class="replaceable">dictionaryobject</var></dt>
<dd>
<p>Use: Required</p>
<p>Data Type: Dictionary object</p>

<p>A reference to a Dictionary object.</p>

</dd>
<dt><var class="replaceable">key</var></dt>
<dd>
<p>Use: Required</p>
<p>Data Type: String</p>

<p>A unique string key for this Dictionary object.</p>

</dd>
<dt><var class="replaceable">item</var></dt>
<dd>
<p>Use: Optional</p>
<p>Data Type: Any</p>

<p>The data associated with <var class="replaceable">key</var>.</p>
</dd>

</dl>
</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Data Type</td>
</tr>
<tr>
<td colspan="2" class="description">


<p>Any</p>

</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Description</td>
</tr>
<tr>
<td colspan="2" class="description">

<p>Sets or returns the data item to be linked to a specified key in a
Dictionary object.
</p>

</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Rules at a Glance</td>
</tr>
<tr>
<td colspan="2" class="description">

<ul><li>
<p>The Item property is the default member of the Dictionary object.</p>
</li><li>
<p>The data type is that of the item being returned.</p>
</li><li>
<p>Unlike the Item property of most objects, the Dictionary
object's Item property is read/write. If you try to
set <var class="replaceable">item</var> to a nonexistent key, the key is
added to the dictionary, and the item is linked to it as a sort of
"implicit add."
</p>
</li></ul>
</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Programming Tips and Gotchas</td>
</tr>
<tr>
<td colspan="2" class="description">

<ul><li>
<p>The Dictionary object doesn't allow you to retrieve
an item by its ordinal position.
</p>
</li><li>
<p>If you provide a nonexistent key when trying to retrieve an item, the
dictionary exhibits rather strange behavior: it adds
<var class="replaceable">key</var> to the Dictionary object along with a
blank item. You should therefore use the Exists method prior to
setting or returning an item, as the example shows.
</p>
</li><li>
<p>If the item to be assigned or retrieved from the Dictionary object is
itself an object, be sure to use the <span class="LITERAL">Set</span> keyword
when assigning it to a variable or to the Dictionary object.
</p>
</li><li>
<p>The comparison of <var class="replaceable">key</var> with member keys is
defined by the value of the Dictionary object's
CompareMode property.
</p>
</li><li>
<p>Although the read/write character of the Dictionary
object's Item property has its drawbacks, it also
has its advantages. In particular, it makes it easy to overwrite or
replace an existing data item, since its Item property is read/write:
simply assign the new value like you would with any other property.
</p>
</li><li>
<p>The Dictionary object should never be used to store HTML form or
query data in Session scope in an ASP application. Since the
Dictionary object is an apartment-threaded COM object, this has the
effect of locking down the application to a single thread of
execution.
</p>
</li></ul>
</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Example</td>
</tr>
<tr>
<td colspan="2" class="description">


<p>The example uses the Dictionary object as a lookup table to retrieve
the state name that corresponds to the state code entered by the
user. The HTML page that submits user information to the server is as
follows:
</p>

<span class="PROGRAMLISTING"><pre>&lt;HTML&gt;
&lt;HEAD&gt;&lt;TITLE&gt;Dictionary Object Example&lt;/TITLE&gt;&lt;/HEAD&gt;
&lt;BODY&gt;
Enter your name and location: &lt;P&gt;
&lt;FORM METHOD=POST ACTION=dictobj.asp&gt;
Your name:
&lt;INPUT TYPE="Text" NAME="VisitorName" /&gt;&lt;P&gt;
Your location:
&lt;INPUT TYPE="Text" NAME="City" /&gt;,
&lt;INPUT TYPE="Text" NAME="State" SIZE=2 /&gt; &lt;P&gt;
&lt;INPUT TYPE="Submit" VALUE="Submit" /&gt;
&lt;/FORM&gt;
&lt;BODY&gt;
&lt;/HTML&gt;</pre></span>


<p>The ASP page that retrieves the information submitted by the user,
encodes it, and uses the Dictionary object to retrieve the full state
name is as follows:
</p>

<span class="PROGRAMLISTING"><pre>&lt;HTML&gt;
&lt;HEAD&gt;
&lt;TITLE&gt;ASP Page for the Dictionary Object Example&lt;/TITLE&gt;
&lt;/HEAD&gt;
&lt;BODY&gt;

            &lt;% Show Greeting %&gt;

&lt;SCRIPT LANGUAGE="VBScript" RUNAT="Server"&gt;

Sub ShowGreeting(  )
   Dim StateDict
   Dim ClientName, ClientState

   ' Initialize dictionary
Set StateDict = Server.CreateObject("Scripting.Dictionary")
StateDict.Add "NY", "New York"
StateDict.Add "CA", "California"
StateDict.Add "FL", "Florida"
StateDict.Add "WA", "Washington"
StateDict.Add "MI", "Michigan"
StateDict.Add "MA", "Massachusetts"
StateDict.Add "MN", "Minnesota"
' add other states

ClientName = Server.HTMLEncode(Request.Form("VisitorName"))
ClientState = Server.HTMLEncode(Request.Form("State"))

Response.Write("Hello, " &amp; ClientName &amp; ". &lt;P&gt;")
Response.Write("We are pleased to have a visitor from ")
   Response.Write(StateDict.Item(ClientState) &amp; "!")
End Sub
&lt;/SCRIPT&gt;
&lt;/BODY&gt;
&lt;/HTML&gt;</pre></span>

</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
</table>
</div>
<div id="DictionaryItemsMethod">
<table border="0" cellspacing="0" cellpadding="0" width="100%">
<tr valign="top">
<td class="NAME">
Dictionary.Items Method</td>
<td class="COMPATIBILITY">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"></td>
</tr>
<tr>
<td class="usage" colspan="2">&nbsp;</td></tr>
<tr><td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Syntax</td>
</tr>
<tr>
<td colspan="2" class="description">

<span class="PROGRAMLISTING"><pre><var class="replaceable">dictionaryobject</var>.Items</pre></span>

<dl>
<dt><var class="replaceable">dictionaryobject</var></dt>
<dd>
<p>Use: Required</p>
<p>Data Type: Dictionary object</p>

<p>A reference to a Dictionary object.</p>
</dd>

</dl>
</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Return Value</td>
</tr>
<tr>
<td colspan="2" class="description">

<p>A Variant array.</p>

</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Description</td>
</tr>
<tr>
<td colspan="2" class="description">

<p>Returns an array containing all the items in the specified Dictionary
object.
</p>

</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Rules at a Glance</td>
</tr>
<tr>
<td colspan="2" class="description">


<p>The returned array is always a zero-based variant array whose data
type matches that of the items in the Dictionary object.
</p>

</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Programming Tips and Gotchas</td>
</tr>
<tr>
<td colspan="2" class="description">

<ul><li>
<p>The only way to directly access members of the Dictionary is via
their key values. However, using the Items method, you can
"dump" the data from the Dictionary
into a zero-based variant array. The data items can then be accessed
like an array in the normal way, as the following code shows:
</p>

<span class="PROGRAMLISTING"><pre>Dim vArray
vArray = DictObj.Items
For i = 0 to DictObj.Count -1
    Response.Write vArray(i) &amp; "&lt;P&gt;"
Next I</pre></span>
</li><li>
<p>The Items method retrieves only the items stored in a Dictionary
object; you can retrieve all the Dictionary object's
keys by calling its Keys method.
</p>
</li></ul>
</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">See Also</td>
</tr>
<tr>
<td colspan="2" class="description">

<p><link linkend="ch10-11583">Dictionary.Keys Method</link></p>

</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
</table>
</div>
<div id="DictionaryKeyProperty">
<table border="0" cellspacing="0" cellpadding="0" width="100%">
<tr valign="top">
<td class="NAME">
Dictionary.Key Property</td>
<td class="COMPATIBILITY">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"></td>
</tr>
<tr>
<td class="usage" colspan="2">&nbsp;</td></tr>
<tr><td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Syntax</td>
</tr>
<tr>
<td colspan="2" class="description">

<span class="PROGRAMLISTING"><pre><var class="replaceable">dictionaryobject</var>.Key(<var class="replaceable">key</var>) = <var class="replaceable">newkey</var></pre></span>

<dl>
<dt><var class="replaceable">dictionaryobject</var></dt>
<dd>
<p>Use: Required</p>
<p>Data Type: Dictionary object</p>

<p>A reference to a Dictionary object.</p>

</dd>
<dt><var class="replaceable">key</var></dt>
<dd>
<p>Use: Required</p>
<p>Data Type: String</p>

<p>The key of an existing dictionary item.</p>

</dd>
<dt><var class="replaceable">newkey</var></dt>
<dd>
<p>Use: Required</p>
<p>Data Type: String</p>

<p>A new unique key for this dictionary item.</p>
</dd>

</dl>
</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Data Type</td>
</tr>
<tr>
<td colspan="2" class="description">


<p>A String.</p>

</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Description</td>
</tr>
<tr>
<td colspan="2" class="description">

<p>Replaces an existing key with a new one.</p>

</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Rules at a Glance</td>
</tr>
<tr>
<td colspan="2" class="description">

<ul><li>
<p>The Key property is write-only.</p>
</li><li>
<p><var class="replaceable">key</var>, the existing key value, must exist in
the dictionary or an error results.
</p>
</li><li>
<p><var class="replaceable">newkey</var> must be unique and must not already
exist in the dictionary or an error results.
</p>
</li><li>
<p>The comparison of <var class="replaceable">key</var> and
<var class="replaceable">newkey</var> with existing key values is defined
by the Dictionary object's CompareMode property.
</p>
</li></ul>
</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Example</td>
</tr>
<tr>
<td colspan="2" class="description">

<span class="PROGRAMLISTING"><pre>Private Function ChangeKeyValue(sOldKey, sNewKey)
'Assumes oDictionary is a public object
    If oDictionary.Exists(sOldKey) Then
        oDictionary.Key(sOldKey) = sNewKey
        ChangeKeyValue = True
    Else
        ChangeKeyValue = False
    End If
End Function</pre></span>

</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Programming Tips and Gotchas</td>
</tr>
<tr>
<td colspan="2" class="description">

<ul><li>
<p>Use the Key property to change the name of an existing key. Use the
Add method to add a new key and its associated value to the
Dictionary object. Use the Keys method to retrieve the names of all
keys; this is especially useful when you don't know
the names or the contents of the dictionary in advance.
</p>
</li><li>
<p>Attempting to retrieve the key name (a nonsensical operation, since
this amounts to providing the key's name in order to
retrieve the key's name) generates an error, as does
attempting to modify a key name that hasn't already
been added to the dictionary.
</p>
</li><li>
<p>Using a <span class="LITERAL">For Each...Next</span> loop to iterate the
members of a Dictionary object involves an implicit call to the Key
property. In other words, each iteration of the loop returns a key,
rather than a data item. To retrieve the member's
data, you then must use its key value to access its data through the
Item property. This is illustrated in the example for the
Dictionary.Item property.
</p>
</li></ul>
</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
</table>
</div>
<div id="DictionaryKeysMethod">
<table border="0" cellspacing="0" cellpadding="0" width="100%">
<tr valign="top">
<td class="NAME">
Dictionary.Keys Method</td>
<td class="COMPATIBILITY">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"></td>
</tr>
<tr>
<td class="usage" colspan="2">&nbsp;</td></tr>
<tr><td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Syntax</td>
</tr>
<tr>
<td colspan="2" class="description">

<span class="PROGRAMLISTING"><pre><var class="replaceable">dictionaryobject</var>.Keys</pre></span>

<dl>
<dt><var class="replaceable">dictionaryobject</var></dt>
<dd>
<p>Use: Required</p>
<p>Data Type: Dictionary object</p>

<p>A reference to a Dictionary object.</p>
</dd>

</dl>
</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Return Value</td>
</tr>
<tr>
<td colspan="2" class="description">

<p>An array of strings.</p>

</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Description</td>
</tr>
<tr>
<td colspan="2" class="description">

<p>Returns an array containing all the Key values in the specified
Dictionary object.
</p>

</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Rules at a Glance</td>
</tr>
<tr>
<td colspan="2" class="description">


<p>The returned array is always a 0-based variant array whose data type
is String.
</p>

</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Programming Tips and Gotchas</td>
</tr>
<tr>
<td colspan="2" class="description">


<p>The Keys method retrieves only the keys stored in a Dictionary
object. You can retrieve all the Dictionary object's
items by calling its Items method. You can recall an individual data
item by using the Dictionary object's Item property.
</p>

</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Example</td>
</tr>
<tr>
<td colspan="2" class="description">

<span class="PROGRAMLISTING"><pre>Dim vArray
vArray = DictObj.Keys
For i = 0 to DictObj.Count -1
    Response.Write vArray(i) &amp; "&lt;BR&gt;"
Next</pre></span>

</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
</table>
</div>
<div id="DictionaryRemoveMethod">
<table border="0" cellspacing="0" cellpadding="0" width="100%">
<tr valign="top">
<td class="NAME">
Dictionary.Remove Method</td>
<td class="COMPATIBILITY">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"></td>
</tr>
<tr>
<td class="usage" colspan="2">&nbsp;</td></tr>
<tr><td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Syntax</td>
</tr>
<tr>
<td colspan="2" class="description">

<span class="PROGRAMLISTING"><pre><var class="replaceable">dictionaryobject</var>.Remove <var class="replaceable">key</var></pre></span>

<dl>
<dt><var class="replaceable">dictionaryobject</var></dt>
<dd>
<p>Use: Required</p>
<p>Data Type: Dictionary object</p>

<p>A reference to a Dictionary object.</p>

</dd>
<dt><var class="replaceable">key</var></dt>
<dd>
<p>Use: Required</p>
<p>Data Type: String</p>

<p>The key associated with the item to be removed.</p>
</dd>

</dl>
</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Description</td>
</tr>
<tr>
<td colspan="2" class="description">

<p>Removes both the specified key and its associated data (i.e., its
item) from the dictionary.
</p>

</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Rules at a Glance</td>
</tr>
<tr>
<td colspan="2" class="description">


<p>If <var class="replaceable">key</var> doesn't exist,
runtime error 32811, "Element not
found," occurs.
</p>

</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
</table>
</div>
<div id="DictionaryRemoveAllMethod">
<table border="0" cellspacing="0" cellpadding="0" width="100%">
<tr valign="top">
<td class="NAME">
Dictionary.RemoveAll Method</td>
<td class="COMPATIBILITY">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"></td>
</tr>
<tr>
<td class="usage" colspan="2">&nbsp;</td></tr>
<tr><td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Syntax</td>
</tr>
<tr>
<td colspan="2" class="description">

<span class="PROGRAMLISTING"><pre><var class="replaceable">dictionaryobject</var>.RemoveAll</pre></span>

<dl>
<dt><var class="replaceable">dictionaryobject</var></dt>
<dd>
<p>Use: Required</p>
<p>Data Type: Dictionary object</p>

<p>A reference to a Dictionary object.</p>
</dd>

</dl>
</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Description</td>
</tr>
<tr>
<td colspan="2" class="description">

<p>Clears out the dictionary; in other words, removes all keys and their
associated data from the dictionary.
</p>

</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Programming Tips and Gotchas</td>
</tr>
<tr>
<td colspan="2" class="description">


<p>If you want to remove a selected number of members rather than the
entire contents of the dictionary, use the Remove method.
</p>

</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
</table>
</div>
</body>
</html>