Creating a VBA Macro - Part 4 of 11

This tip is the fourth of a series of tips that describe System Architect's VBA and show you how to build a simple macro that gets information from the repository. In this series, you create a macro, use System Architect's object model to access an encyclopedia, access diagrams in the encyclopedia, get symbols on a diagram, and get information from the definition of a symbol.

In the last tip, we got information about the active encyclopedia. This tip focuses on getting information on diagrams in an encyclopedia, and using the Encyclopedia object, the Diagram object, and a special set of collection objects, to do so. It's a long tip, but you'll learn some crucial information about using SA's object model.

If you have closed the work you did in the last tip, reopen it by performing the following steps:

1. In System Architect, with the Samples encyclopedia open, select Tools, Macros, VBA Editor to open the VBA IDE.
2. Within the IDE, open the Example module that we created in last week's tip. Your code should look as follows:

Getting the diagram

In the previous tips, we dimensioned the Application object, created an active instance of it, and then from it, got the Encyclopedia object's name. Take another look at the object model. The Encyclopedia object is the aggregate of the Dagram object, the Symbol object, and of the Definition object. The Encyclopedia object contains zero or many Diagrams, zero or many Symbols, and zero or many Definitions. Also, a Diagram is the aggregate of the Symbol object; it contains zero or more Symbols (ie, a symbol cannot exist outside of a diagram). Each symbol is defined by zero or one Definition (ie, some symbols exist that have not been defined). A Definition may or may not have a Symbol associated with it (for example, a Class Method definition is not represented by a particular symbol of its own). We will use these relationships to get information about the encyclopedia's diagrams, symbols, and definitions.

Collection objects in the object model

Before we continue, let's discuss three important collection objects in System Architect's object model:

• SAObjects,
• SACollection, and
• OfCollection

Normally, a collection is a list of objects at a particular point in time. Because System Architect is a network tool, it is harder to get a collection because it could take hours, in some cases, with large encyclopedias. For example, if you have a large network encyclopedia with 10,000 diagrams, and you ask for all diagrams in the encyclopedia, your code will start walking the encyclopedia, locking diagrams up, and take hours to complete. Because of this, System Architect's object model presents the three special collection objects mentioned above. All System Architect objects are stored in these special collections and are immediately available. Let's take a look at each one.

SAObjects:

SAObjects contains Diagrams, Symbols, and Definitions. SAObjects is a special collection that you have control over - you can decide how many items to count into that collection, when it starts, when it stops, etc. You can use it, for example, to say "give me a count of all diagrams in an encyclopedia right now".

OfCollection:

OfCollection contains a list of properties inside a definition. For example, you can use this object to quickly get a list of elementary business processes that have roles associated with them.

Using SAObjects to get diagrams

So far in our macro, we have gone from the Application object to the Encyclopedia object; now we want to go from the Encyclopedia object to the Diagram object. We will use the SAObjects collection object to reduce the effort to do so.

First let's dimension a variable that will hold the diagrams.

1. Type the following:

‘get a list of all diagrams in the encyclopedia
Dim myDiagrams as sa2001.SaObjects

We have **_dimensioned_** the variable <span class="path">myDiagrams</span> as an SAObjects container that can contain all of the diagrams. Now we want to set the variable <span class="path">myDiagrams</span> as a list of all the diagram objects.

Before we do this, take another look at the object model. Notice that the Encyclopedia object contains a method called <span class="path">GetAllDiagrams</span>. Note - and this is important - that you wouldn’t use a method to get the diagram name from the <span class="path">Diagram</span> object, since this would only return a single diagram’s name. To get a collection of diagrams, you must go to the encyclopedia that the diagrams are contained in.

2. Type in the following (selecting where appropriate using the drop-down lists of IntelliSense):

   Set myDiagrams = SA2001.Application.Encyclopedia.GetAllDiagrams

3. Following good programming practice, we'll set the end of the loop. Hit your Enter key a few times to open up space in the code, and type in the following to end the object:

   Set myDiagrams = Nothing

   Your code should look as follows:

In any normal collection that would do it – you would get all of your diagrams via the encyclopedia. But in System Architect, as we mentioned before, you don't want to we want to walk a network encyclopedia and potentially lock everybody up. We'll use the facilities of the SAObjects collection object to get the diagrams quickly.

Using methods and attributes of SAObject

Since we have dimensioned myDiagrams as an object of SAObject, when we type in ‘myDiagrams.’, we get a list of all properties and methods of SAObject.

The ReadAll method:

4. In the code, above the line Set myDiagrams = Nothing, type in:

   myDiagrams.ReadAll

   We are saying go away and consciously read all the diagrams and add them to the collection. Let’s try it by stepping through the code:

5. Place your cursor in the code, and press the Step Into button to walk through the code.

6. Step to the point where myDiagrams=ReadAll is selected, then step again and count the seconds it takes to read all of the diagrams.

   Diagram is now an object in the SAObject collection called myDiagrams. Let's now use some SAObjects attributes to get further information:

The count attribute:

7. When the Set myDiagrams = Nothing command is highlighted, place your cursor in the Immediate window and type in:

   ? myDiagrams.Count

   and hit Enter.

   You will receive a number of the diagrams in the currently open encyclopedia. It will give you an answer rather quickly.

Now let’s get a particular item in the SAObject collection. Let’s get the 10th diagram in the list, and get its name. The name of a diagram is actually one of its attributes. To get a complete list of a diagram object's attributes, take another look at the object model – all the available properties (or attributes) of the Diagram class are listed.

The item attribute:

The item attribute enables us to get at a particular item in the list. It takes a number as a parameter - the number acts as an index.

8. In the Immediate window, type in:

   ? myDiagrams.Item(10).Name

   and hit Enter.

   You receive the 10^th diagram in the Samples encyclopedia. Now let’s get the 16^th diagram in the list, and get its type.

9. Type the following in the Immediate window:

   ? myDiagrams.Item(16).Typename

   and hit Enter.

   The type of the 16^th diagram is garnered. Now let's get the person who last touched the 16th diagram.

10. Type the following in the Immediate window:

    ? myDiagrams.Item(16).auditID

    and hit Enter.

    You get the person’s name, in this example someone named Dave Rice.

Adding code to the subroutine

We've been using the Immediate window to play around with various methods and attributes. Now let's add a statement to the code to get the diagram's name.

We'll first dimension a new variable called myDiagram (previously we got myDiagrams, plural).

1. Delete everything in the Immediate window, and place your cursor back into the code, in the blank area under myDiagrams.ReadAll.

2. Type the following in the Immediate window:

   Dim myDiagram as SA2001.Diagram
    Set myDiagram = myDiagrams.Item(16)

   Notice that after typing a period after myDiagrams, you get a drop-down list of all properties and methods of the collection.

3. Alternatively, because Item is the default property of a collection, you can replace the .Item(16) with simply (16). Change the line above so that it reads:

   Set myDiagram = myDiagrams(16)

   We now have a diagram object. We can use Intellisense to get all the properties and methods available for the diagram.

4. Type in: Debug.

   Debug.print myDiagram.Name

5. Reset the project (click the Reset button) and step through the code (clicking the Step Into button). When you step to the above line, the name of the 16^th diagram is printed to the Immediate window.

Next tip

We've done a lot in this tip; we examined collection objects and the three special ones provided in System Architect's object model. We journeyed from the Encyclopedia object to the Diagram object, getting information from both, using the SAObjects collection object as an aide. We played a lot in the Immediate window, and even found out that Dave Rice created the 16th diagram in the Samples encyclopedia. In the next tip we'll create a loop in our code to get information on a bunch of diagrams.

6. Continue with the next tip, or select File, Save Example and close the VBA environment by selecting File, Close and Return to SA2001.