Reading and Writing MicroStation Tag Data

The Bentley VBA newsgroup (see Bentley Discussion Groups) regularly receives postings asking some question about Tag data.

Q This article answers some common questions, such as …

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?

A Those questions are answered here …

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

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. in a tag element. Tag set definitions belong to a DGN file, not a single model within that file. In other words, 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

Tag 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 it's value exists 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 a hangover 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 file, but the host element is not affected.

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.

Defining Tag Sets using FlexiTable

An alternative way to define Tag Sets is through FlexiTable™. FlexiTable provides a Tag Set definition editor. It saves a Tag Set definition to an XML file. The benefit of this approach is that XML files, being plain text, can be viewed an edited through other means. For example, it's easy to transform an XML tag definition into HTML for documentation purposes.

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 Reporting using FlexiTable

An alternative way to acquire data about tagged elements is FlexiTable™. FlexiTable can also create CSV and XML reports, and in addition HTML and Microsoft Excel^® files.

Tag Sets

Because 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 models that are part of that 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

Tagging Multiple Objects with VBA

ShapeTagger is a VBA project bundled with AreaAnnotator™. ShapeTagger shows how to …

Scan a DGN model for shape elements on a designated level
Attach tags to each shape element
Invoke AreaAnnotator to measure each shape's area and update the tags attached to it

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.

Reading and Writing Tag Data