Collections

An Automation object features the same structure as any other JScript object. It exposes various methods and properties that we can work with. If you've never worked with Visual Basic, you probably aren't familiar with the Collection object. A collection is a way of grouping a set of related items. Collections are used in Visual Basic to keep track of many things, such as the loaded forms in your program (the Forms collection), or all the controls on a form (the Controls collection).

Visual Basic provides the Collection class so you can create your own collections. Each item in a Collection object is declared as a Variant, Visual Basic's generic 16-byte data type. OLE Automation collections are collections that are exposed through a standard OLE interface. A collection object features four standard elements:

colObj.Add(item[, key][, before]);

The Add() method adds an item to the collection. Along with the data itself, you can specify a key value by which the member can retrieved from the collection. Note that the last argument cannot be specified via JScript.

colObj.Count

The Count property returns the number of items in the collection.

colObj.Item(index);

The Item() method retrieves an item from the collection by its index, which can be either the position in the collection, or the item's key.

colObj.Remove(index);

The Remove() method deletes an item from the collection by its index, which can be either the position in the collection, or the item's key.

Collections are very similar to arrays, but in some cases they are a better choice:

• It is awkward to remove items from the middle of an array. The Remove() method makes it easy to remove any item from a collection based on either its position in the collection, or the item's key.
• You never have to redim a Collection object (a way of changing a dynamic array's length in Visual Basic), which results in much cleaner, more maintainable code.
• Collection objects have extremely fast look-ups by key, which arrays do not. Even if you don't know the exact position of an item, you can retrieve it easily by specifying its key.

Now back to our own story. No, Doc JS isn't going to become Doc VB. Since we're dealing with Automation objects, it's important to be familiar with collections. You'll find yourself handling them in your scripts. In particular, you will notice the importance of the Item() method in statements like:

colWorkOrders.Item("W050580").Priority = 4;

JavaScript's main problem with collections, is that it doesn't have any function that loops through a collection's items. In Visual Basic (or VBScript) this can be done with the For Each...Next construct, but it is not possible with JScript. You will have to overcome this problem in your scripts.