Collections

A collection is a set of objects.

The model is the root object and the other objects can be reached by browsing the corresponding collection. The objects are grouped together within collections that can be compared to the category nodes appearing in the Browser tree view of the Workspace.

If an object CUSTOMER has a collection, it means the collection contains the list of objects with which the object CUSTOMER is in relation.

Some functions are available on collections. You can:

Browse a collection
Get the number of objects a collection contains
Create a new object inside a collection, if it is a composition collection

Collections can be of the following types:

Read-only collections are collections that can only be browsed
Unordered collections are collections for which objects order in the list is not significant. For example the Relationships collection of a CDM Entity object is an unordered collection
Ordered collections are collections for which object order is set by the user and must be respected. For example the Columns collection of the PDM Table object is an ordered collection
Composition collections are collections for which objects belong to the collection owner. They are usually displayed in the Browser. Non composition collections can also be accessed using scripting and can be for example the list of business rules attached to a table or a class and displayed in the Rules tab of its property sheet or the list of objects displayed in the Dependencies tab of an object property sheet.

Read-only Collections

Models (global collection for opened models) is an example of read-only collection.

The property and method available for read-only collections are the following:

Property or Method	Use
Count As Long	Retrieves the number of objects in collection
Item(idx As Long = 0) As BaseObject	Retrieves the item in collection for a given index. Item(0) is the first object
MetaCollection As BaseObject	Retrieves the MetaCollection object that defines this collection
Kind As Long	Retrieves the kind of objects the collection can contain. It returns a predefined constant such as cls_
Source As BaseObject	Retrieves the object that owns the collection

Example:

'How to get the number of open models and display it 
'in the output window
output Models.count

Unordered Collections

All methods and properties for read-only collections are also available for unordered collections.

Properties and methods available for unordered collections are the following:

Property or Method	Use
Add(obj As BaseObject)	Adds object as the last object of the collection
Remove(obj As BaseObject, delete As Boolean = False)	Removes the given object from collection and optionally delete the object
CreateNew(kind As Long = 0) As BaseObject	Creates an object of a given kind, and adds it at the end of collection. If no object kind is specified the value 0 is used which means that the Kind property of the collection will be used. See the Metamodel Objects Help file for restrictions on using this method
Clear(delete As Boolean = False)	Removes all objects from collection and optionally delete them

Example:

'remove table TEST from the active model
Set MyModel = ActiveModel
For each T in Mymodel.Tables
 If T.code = "TEST" then
   set MyTable = T
 End if
next
ActiveModel.Tables.Remove MyTable, true

Ordered Collections

All methods and properties for read-only and unordered collections are also available for ordered collections.

Properties and methods available for ordered collections are the following:

Property or Method	Use
Insert(idx As Long = -1, obj As BaseObject)	Inserts objects in collection. If no index is provided, the index -1 is used, which means the object is simply added as the last object of the collection
RemoveAt(idx As Long = -1, delete As Boolean = False)	Removes object at given index from collection. If no index is provided the index -1 is used, which means the removed object is the last object in collection (if any). Optionally deletes the object
Move(source As Long, dest As Long)	Moves object from source index to destination index
CreateNewAt( idx As Long = -1, kind As Long = 0) As BaseObject	Creates an object of a given kind, and inserts it at given position. If no index is provided the index -1 is used which means the object is simply added as the last object of the collection. If no object kind is specified the value 0 is used which means that the Kind property will be used. See the Metamodel Objects Help file for restrictions on using this method

Example:

'Move first column in last position
'Assuming the variable MyTable contains a table
MyTable.Columns.move(0,-1)

Composition Collections

Composition collections can be ordered or unordered.

All methods and properties for unordered collections are also available for unordered compositions.

Properties and methods available for unordered composition collections are the following:

Property or Method	Use
CreateNew(kind As Long = 0) As BaseObject	Creates an object of a given kind, and adds it at the end of collection. If no object kind is specified the value 0 is used, which means the Kind property of the collection will be used

All methods and properties for ordered collections are also available for ordered compositions.

All methods and properties for unordered compositions are also available for ordered compositions.

Properties and methods available for ordered composition collections are the following:

Property or Method	Use
CreateNewAt( idx As Long = -1, kind As Long = 0) As BaseObject	Creates an object of a given kind, and inserts it at a given position. If no index is provided the index -1 is used, which means the object is simply added as the last object of the collection. If no object kind is specified the value 0 is used which means that the Kind property of the collection will be used

These methods can be called with no object kind specified, but this is only possible when the collection is strongly typed. That is, the collection is designed to contain objects of a precise non-abstract object kind. In such cases, the Kind property of the collection corresponds to an instantiable class and the short description of the collection states the object kind name.

Example:

The Columns collection of a table is a composition collection as you can create columns from it. But the Columns collection of a key is not a composition collection as you cannot create objects (columns) from it, but only list them.

'Create a new table in a model
'Assuming the variable MyModel contains a PDM
'Declare a new variable object MyTable
Dim MyTable
'Create a new table in MyModel
Set MyTable = MyModel.Tables.Createnew

'Create a new column in a table
'Declare a new variable object MyColumn
Dim MyColumn
'Create a new column in MyTable in 3rd position
Set MyTable = MyTable.Columns.CreateNewAt(2)
' the column is created with a default name and code

Note: When you browse the collections of a model and want to retrieve its objects, be aware that you will also retrieve the shortcuts of objects of the same type.