Reading and Writing Tag Data with MicroStation VBA

• Products
• Services
• Publications
• Links
• WishList
• LA Solutions
• Home

The Be Communities MicroStation Programming Forum regularly receives postings asking some question about Tag data.

Q This article answers some common questions, such as …

• Will future versions of MicroStation support tags?
• How does VBA retrieve Tags?
• How do I get or set a Tag's value?
• How do I write back Tag data?
• When I rewrite an element, why aren't the Tags updated?
• How do I locate an object with tags?
• How do I attach tags to multiple objects?
• How do I delete all tag set definitions?
• How do I copy tag elements from one file to another?
• What happens when I place a cell with tags?

A Those questions are answered here …

• The Future of Tags
• Tag Overview
• Review of Tag Sets
• Working with Tags in VBA
• Locating Tagged Objects with VBA
• Attaching Tags to Multiple Objects with VBA

Tags Future

MicroStation CONNECT

Tags are deprecated in MicroStation CONNECT. They are superseded by Item Types in MicroStation V10 (MicroStation CONNECT) and later. For more details, consult Bentley Systems.

However, at the time of writing (MicroStation CONNECT Update 1) there is no VBA API for Item Types. If you want to automate, say, title block updating, then you must remain with tags because you can't write VBA code for Item Types.

Deprecated does not mean obsolete. You can continue to use tags in your DGN models, and MicroStation's APIs continue to support tags.

Item Types provide most of what tags provide. They separate form and function: Item Types are data stored independently of graphic elements, but can be associated with a graphic element. Item Types can be referenced by certain elements, such as text elements that contain text fields.

For more information about Item Types read the MicroStation CONNECT help document.

Tags Overview

Tags are MicroStation type 37 elements. A Tag's primary purpose is to store a data value. The Tag may or may not be displayed, but its internal value persists whether or not you can see it. In many ways, tags behave like any other graphic element: you can move, rotate, scale, symbolize, and delete a Tag. The primary difference between Tags and most other graphic element types is their association with a host element (subsequently called the Host in this article). The Host element can be almost any type of MicroStation graphic element: there is nothing special about it.

A Tag's association with a Host is through the Host's Element ID (the unique 64-bit ID assigned automatically to each and every element in a DGN file). Use MicroStation's Analyse Element tool to examine a Tag element and see this association. The screen-shot below shows a green shape element (the host) and a couple of Tag elements …

I used the Analyse Element tool to see information about the Tag that displays Stephan 3 …

Note the Type Specific Details relating to a Tag element, and the clumsy and inaccurate phrase Assoc id of element attached to. The Assoc id is legacy terminology from earlier generations of MicroStation: it should more properly read Element ID of Host Element. In this case, the host element is the green rectangle, whose Element ID is 192.

The most obvious property of Tags is that they 'belong' to a host element: when you move the host, the Tags move with it; when you delete a host, its Tags are also deleted. MicroStation maintains this relationship host-owns-tag through its dependency logic. That is, the tag is dependent on its host.

Occasionally, confusion sets in: some people get the impression that tag data are somehow a part of the host. Let's get this straight: when you tag an element, the element becomes the host for one or more tags. But, the host itself is not changed. It already has an Element ID, and each Tag is associated with the host by referencing that ID. The process of tagging adds new Tag elements to your DGN model, but the host element is not affected.

Q Here's the answer to a question posted to the Be Communities web site …

• How can I get the tag set definitions in a DGN file?

A Tag set definitions are meta-data: that is, they define how tag data should be stored. Tag set definitions belong to a DGN file, not a single model within that file. When you define a tag set that definition can be seen in all models contained in that DGN file. Likewise, each tag definition in that tag set belongs to the file rather than a particular model.

• Viewing Tag Set Definitions

Place a Cell with Tags

Q I can define a cell, in a cell library, that contains tag elements. What happens when I place such a cell?

A  When you create a cell instance (i.e. place a cell), MicroStation copies the cell contents to the location you indicate. That's the normal process of placing a cell.

However, when a cell definition contains tag elements, MicroStation treats those tags differently. At the point where you create a new cell instance, MicroStation removes the tag definitions from the cell and creates new tag elements attached to the cell.

The result is as if you had copied all the graphic elements, except the tags, from the cell, then used MicroStation's tag tools to attach those tags to your new cell instance.

MicroStation Tag Tools

Tag Set Definitions & Libraries

MicroStation provides tools for Tag Set definition, for attaching, editing, and viewing tags, and for tag reporting. You can find the Tag Set definition and reporting tools on MicroStation menu Elements|Tags. You can find the tag attaching, editing, and viewing tools on MicroStation's Tag Tools palette.

In addition to defining a Tag Set in a DGN file, you can save that definition to a Tag Library (.tlb) file. A Tag Library is a binary file, readable only by MicroStation. Its purpose is to let you save and load a Tag Set definition; it saves time when you want to duplicate a Tag Set definition in multiple DGN files, or give your definition to a third party.

Tag Reports

Tags hold alpha-numeric data about an element. MicroStation provides tag reporting capabilities: the data content of a Tag Set can be exported to a CSV or XML report file. Reporting tools are found in MicroStation's Elements|Tags menu.

Tag Sets

Tag elements can store & display different data types. Their definition is stored in a Tag Set. You define and review Tag Set definitions through the MicroStation menu Element|Tags|Define, which opens the Tag Sets dialog …

In this example, we have a Tag Set named stephan. This Tag Set contains three Tag definitions named IntTag, RealTag, and StringTag. Those names are arbitrary: you would probably choose a set of names appropriate to your organisation's needs. Select a Tag definition and press the Edit button to pop the Define Tag dialog …

Here, the Tag named IntTag is defined to hold an integer number with a default value of zero. A Tag may also be defined as a container for a real (floating-point) number or a character string. Tag Set Definitions and their Tag Definitions are stored as non-graphic elements in the design file. The definitions are available to all DGN models that are part of that DGN file. You can create the definitions in a project seed file to ensure that the same Tag Sets are always defined in your design files.

Tags and VBA

MicroStation VBA provides properties and methods to create, manipulate, and read Tag data. A common requirement is to read tag data and render it in a report. You might want to export tag data in a CSV or XML file, for example.

To read tag data, first identify a host having associated tags …

Dim oHost As Element
 …' Read oHost element from file
If (oHost.HasAnyTags) Then
  ' process tags
End If

Once you've found a Host, get an array of tag elements …

Dim oHost As Element
 …' Read oHost element from file
If (oHost.HasAnyTags) Then
  Dim oTags() As TagElement
    oTags = oHost.GetTags ()
    ' process tag array
End If

For each tag element, extract its value …

Dim oHost As Element
 …' Read oHost element from file
If (oHost.HasAnyTags) Then
  Dim oTags() As TagElement
    Dim nTags As Integer
    Dim i As Integer
    Dim vtValue As Variant
    oTags = oHost.GetTags ()
    ' process tag array
    For i = Lbound (oTags) To Ubound (oTags)
      vtValue = oTags(i).Value
      Debug.Print "Tag [" & CStr(i) & "]" = " & CStr(vtValue)
    Next i
End If

Update a tag's value …

Dim oHost As Element
 …' Read oHost element from file
If (oHost. HasAnyTags) Then
  Dim oTags() As TagElement
    Dim  nTags As Integer
    Dim i As Integer
    Dim vtValue As Variant
    oTags = oHost.GetTags ()
    ' process tag array
    For i = Lbound (oTags) To Ubound (oTags)
      oTags(i).Value = i ' assign some value
      oTags(i).Redraw msdDrawingModeNormal ' display the new value
      oTags(i).Rewrite ' update the tag in the DGN file
    Next i
End If

Note how we update individual tag elements. We don't need to update the host element. In other words, modifying a tag element doesn't affect its host.

You can find more examples in the VBA documentation. Search for TagElement and related methods and properties.

---

Viewing Tag Set Definitions

The code below shows how to enumerate each Tag Set Definition in a DGN file. For each Tag Set Definition, it enumerates that set's Tag Definitions …

Option Explicit

' ---------------------------------------------------------------------
'   EnumerateTagSets
'   Shows information about each Tag Set definition in the active DGN file
' ---------------------------------------------------------------------
Sub EnumerateTagSets()
    Dim oTagSets                            As TagSets
    Set oTagSets = ActiveDesignFile.TagSets
    Dim terse                               As String
    Dim verbose                             As String
    terse = "Found " & CStr(oTagSets.count) & " tag sets "
    verbose = terse & "in DGN file" & ActiveDesignFile.name
    ShowMessage terse, verbose, msdMessageCenterPriorityInfo

    Dim oTagSet                             As TagSet
    For Each oTagSet In oTagSets
        terse = "Tag set '" & oTagSet.name & "' has " & CStr(oTagSet.TagDefinitions.count) & " tag definitions"
        ShowMessage terse, terse, msdMessageCenterPriorityInfo
        EnumerateTagDefinitions oTagSet
    Next oTagSet
End Sub
' ---------------------------------------------------------------------
'   EnumerateTagDefinitions
'   Shows information about each Tag Definition in a given Tag Set
' ---------------------------------------------------------------------
Sub EnumerateTagDefinitions(ByVal oTagSet As TagSet)
    Dim oTagDefinition                      As TagDefinition
    Dim terse                               As String
    Dim verbose                             As String
    Dim count                               As Integer
    count = 1
    For Each oTagDefinition In oTagSet.TagDefinitions
        terse = "Tag definition [" & CStr(count) & "] Name '" & oTagDefinition.name & "'"
        verbose = terse & " Type " & CStr(oTagDefinition.TagType) & " Default '" & oTagDefinition.DefaultValue & "'"
        ShowMessage terse, terse, msdMessageCenterPriorityInfo
        count = 1 + count
    Next oTagDefinition
End Sub

---

Locating Tagged Objects with VBA

We've created a sample VBA project to illustrate how to locate a tagged object and display its tag values. The project includes a regular code module, modTags that includes a function TraceTags. TraceTags gets an array of tags from a host element and prints their values to the VBA IDE Immediate window. The code to locate a tagged object is contained in the clsTaggedObjectLocator module.

clsTaggedObjectLocator is a class that Implements ILocateCommandEvents. The key procedure of this class is the ILocateCommandEvents_LocateFilter subroutine, which tests an element to see if it has any tags …

Private Sub ILocateCommandEvents_LocateFilter(ByVal oElement As Element, Point As Point3d, accepted As Boolean)
  If (oElement.HasAnyTags) Then
    accepted = True
  Else
    accepted = False
  End If
End Sub

---

Download TagsLocator Project

You can download a complete MicroStation VBA project that implements a tag location and tracing tool. The TagLocator Project is in a ZIP archive. Unpack the archive to a suitable location, such as C:\Program Files\Bentley\Workspace\Standards\VBA, then start MicroStation and load TagsLocator with the VBA project manager.

Some portions of this article were first published by LA Solutions Ltd in MicroStation Manager magazine online, on Bentley Systems, Inc. website.

Copy Tag Elements across Files

A VBA developer wanted to write code to merge a reference model with the active model. The source file (the reference) contains tagged elements. The question asked how to handle tag elements when merging two DGN models.

Tags are graphic elements, but have particular properties that mean you have to be careful when copying tags from one file to another.  Note that I wrote 'copying tags from one file to another', not 'copying tags from one model to another in the same file'.

A tag element is dependent on a host element.  That dependency relies on the host's Element ID.  As you probably know, an Element ID is a unique 64-bit identifier within a given DGN file.  Each and every element in a DGN file, irrespective of which model, has a unique Element ID.  Part of a tag element's data is its host Element ID (you can see the host ID if you use the Analyze Element tool)

Tag Set Definition

If the destination file does not contain the tag set definition in your source file, then you'll need to create that tag set definition in the destination file before you start copying tag elements.

Copy Hosts before you Copy Tags

If you want to copy tag elements from one file to another, copy the host elements first.  Each host will be assigned a new Element ID in the destination DGN file. MicroStation assigns the Element ID for you: as a programmer, you don't need to do anything. Next, create a new set of tags for the destination host, using as templates the existing tags on the source host.  The new tags are dependent on the new host ID.

Copy Tags by Model Scan

If you're copying by file scan, then a good approach is to scan-and-copy all graphic elements that are not tags, and store the Element ID of each tagged host in a list.  Once the non-tag elements have been copied, iterate your host list and get the tags from the source model for each host.  Create a new set of tags on the destination host from those source tags.  The new tags are dependent on the new host ID.

Delete Tag Set Definitionss

Sometimes you find that a DGN file is swamped with tag set definitions. Some definitions may not be used, but there's just too many to make any sense. A common cause for that plethora of tag set definitions is when you import an AutoCAD file into MicroStation.

Here's how to delete all tag set definitions in a DGN file. The code is straighforward: iterate the definitions and delete each one. The documented side effect of deleting a tag set definition is to delete all tag elements in that set.

Run this macro using the key-in
vba run RemoveAllTagSets …

Public Sub RemoveAllTagSets ()
Dim oSet As TagSet
For Each oSet In ActiveDesignFile.TagSets
  ' The following line deletes each tag set definition.  The side effect of
  ' removing the definition is to delete all tag elements belonging to that set
  ActiveDesignFile.TagSets.Remove oSet.Name
Next oSet
End Sub

Questions

Post questions about MicroStation programming to the MicroStation Programming Forum.