Navigating the TCB for VB and BASIC Programmers

LA Solutions

The BASIC and VBA Programmer's Guide to Navigating the TCB describes access mechanisms for MicroStation's Terminal Control Block (TCB). It attempts to answer questions that are posted occasionally to the Bentley Discussion Groups.

The terminology TCB has been traced by archeologists to the days when minicomputers connected to graphic terminals by cable and were controlled by dedicated software. The TCB held the terminal settings. Why its use has persisted in MicroStation is a mystery.

Q It seems unfortunate that there are so many development languages, each with its own special syntax

A Languages are provided to suit different circumstances. Bear in mind that every computer language exists solely to distance the programmer from machine code: no-one wants to write in assembly code (if you do, please don't e-mail me). MicroStation BASIC is relatively easy to learn, but has limitations. Visual Basic for Applications (VBA) in MicroStation V8 is a leap forward in capability, but to take advantage of that capability you must be prepared to learn a whole lot more.

Q I'm in for a struggle with syntax. What is dot notation?

A Many languages, including BASIC and VBA, have the concept of a user-defined-type (UDT). A UDT that you can't live without in icroStation VBA is a Point3d (in MicroStation BASIC this is MbePoint). MbePoint is pre-defined in BASIC …

Type MbePoint
  x As Double
  y As Double
  z AS Double
End Type

The definition of a Point3d is similar. In your code, you declare a Point3d like this …

Dim point As Point3d

You can read and write the X, Y, Z data members of a Point3d like this:

Dim length As Double, width As Double, height As Double
length = point.x
width = point.y
height = point.z

The dot notation illustrated here instructs the VBA interpreter to look inside the Point3d to get at its X, Y and Z data members. The dot notation is used in most programming languages these days. You'll encounter it in VB, C, C++, Java and Perl and, of course, MicroStation VBA.

Q I've seen postings about the TCB, which use arrow notation. My head hurts.

A Arrow notation (->) is a syntax used by C and C++. It's similar to dot notation, but if you want to know more then you should take a 'C' programming course. It's sufficient, for the purposes of navigating the TCB, to know that you should use the syntax tcb->xxx to get at TCB member data.

Q Enough of this flim-flam: what about the TCB contents?

A The terminal control block (TCB) holds many of MicroStation's global settings. By global, I mean settings that belong to the design file rather than any individual model or element. An example is units-of-resolution. Commonly-used components of the TCB are available through VBA or BASIC calls. For example …

Dim masterUnitName As String
masterUnitName = MbeDgnInfo.masterUnitName

Here, MbeDgnInfo.masterUnitName is extracting the masterUnitName member of the TCB. However, the TCB is huge, and not all its members are exposed in VBA and BASIC (i.e. there is no MbeDgnInfo.xxxx function for each and every piece of data in the TCB).

If you're coding MicroStation VBA , you should know that the way units are expressed and labelled is quite different to MicroStation BASIC. With VBA, the ModelReference embeds its units in properties MasterUnit and SubUnit. The MasterUnit and SubUnit types each has a Label member. To get a model's master unit label with VBA you would write something like this …

Dim masterUnit As MeasurementUnit

masterUnit = ActiveModelReference.MasterUnit
Debug.Print "Master Unit label=" & masterUnit.Label

Q How do I get the active Text Style settings?

A The active Text Style settings are stored in the textStyle member of the TCB. This information is available directly in VBA, but with BASIC you have to use a C Expression. Here's an example …

' Shows how to obtain active Text Style settings from the TCB

Sub Main
  Dim interCharSpacing As Double
  Dim textHeight As Double
  Dim textWidth As Double
  Dim strCExpression As String
  ' Get interCharSpacing from the active TextStyle
  strCExpression = "tcb->textStyle.interCharSpacing"
  interCharSpacing = MbeCExpressionDouble (strCExpression)
  ' Get text width
  strCExpression = "tcb->textStyle.width"
  textWidth = MbeCExpressionDouble (strCExpression)
  ' Get text height
  strCExpression = "tcb->textStyle.height"
  textHeight = MbeCExpressionDouble (strCExpression)
End Sub

Q Where can one find a list of TCB arguments?

A The TCB is formally documented as a 'C' header file in …\MicroStation\mdl\include\tcb.h. This file is delivered with a full MicroStation installation. It is a text file, so you can browse it with your favourite text editor (however, it doesn't make good bedtime reading). There is no friendly description or help file about the TCB. If you want to get at data not exposed by an MbeDgnInfo.xxxx function, you must be prepared to dig deep. Alternatively, post a question to the Bentley Discussion Groups. For example, the 'C' equivalent of MbeDgnInfo.masterUnitName is tcb->mastname, which looks like this in tcb.h for MicroStation/J …

char	    mastname[2];/* master units name   606 */

In MicroStation V8, this member is not present in the TCB. Instead, it's available to a BASIC programmer as MbeDgnInfo.masterUnitName and to a VBA programmer as ModelReference.MasterUnit.Label. Notes …

char indicates that it's character data
square brackets [] are C's way of specifying an array
Thus, mastname is an array of two characters in MicroStation/J
In MicroStation/J the master unit name may never have more than two letters (e.g. ft is OK, foot is too long)
anything between /* and */ is a comment

Q What is a C expression?

A MicroStation includes an elegant engine called the C expression interpreter. This allows you to evaluate 'C' statements at run-time. You can see this in action with the Calculator MDL (see MicroStation documentation). If you've ever designed a BASIC dialog box, then you've been using the C expression parser to obtain the value of an access string. The user types something in your dialog, and the C expression interpreter evaluates what she types and passes it to your program variable. A simple C expression is 4 * 2 (the answer is eight). You could include this in a BASIC program like this …

Dim answer As Integer
answer = MbeCExpressionLong ("4 * 2")

With VBA you can use a similar method GetCExpressionValue …

Dim savePlaceArcMode
savePlaceArcMode = GetCExpressionValue( _
  "tcb->msToolSettings.igen.placeArcMode", "IGEN")

You can evaluate TCB member data in a similar way …

Dim UORs As Long
'  Get the number of units-of-resolution per master unit
'  in MicroStation/J
UORs = MbeCExpressionLong ("tcb->subpermast * tcb->uorpersub")

This snitch of MicroStation/J code shows that MbeDgnInfo and C expressions are equivalent …

Dim masterUnitsName1 As String, masterUnitsName2 As String
masterUnitsName1 = MbeDgnInfo.masterUnitName
masterUnitsName2 = MbeCExpressionString ("tcb->mastname")
MbeMessageBox "MbeDgnInfo.masterUnitName=" & masterUnitsName1 & _
  " MbeDgnInfo.masterUnitName=" & masterUnitsName2

The above doesn't work in MicroStation V8 because tcb->mastname no longer exists. VBA provides more information via the ModelReference.MasterUnit property.

The BASIC and VBA Programmer's Guide to Navigating the TCB is copyright (c) 2003...2008 LA Solutions Ltd. You may freely use and distribute at no cost the information here provided that you retain this copyright notice.

Trademarks

All trademarks are acknowledged. Trademarks may be registered in some jurisdictions.

Home

Updated on 22-Dec-2008