---

This BASIC Programmer's Guide to Navigating the TCB describes access mechanisms for MicroStation's Terminal Control Block (TCB). If you're using VBA rather than MicroStation BASIC, then refer to the VBA version of this page.

It attempts to answer questions that are posted occasionally to the BE Communities forums.

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 and is obsolescent. 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.

We've written a comparison of MicroStation development languages.

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 MicroStation BASIC this is MbePoint.

MbePoint is pre-defined in BASIC …

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

In your code, you declare an MbePoint like this …

Dim point As MbePoint

You can read and write the X, Y, Z data members of a MbePoint 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 BASIC interpreter to look inside the MbePoint 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 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 BASIC (i.e. there is no MbeDgnInfo.xxxx function for each and every piece of data in the TCB).

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.

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 = GetCExpressionValue (strCExpression)
  ' Get text width
  strCExpression = "tcb->textStyle.width"
  textWidth = GetCExpressionValue (strCExpression)
  ' Get text height
  strCExpression = "tcb->textStyle.height"
  textHeight = GetCExpressionValue (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 when you install the MicroStation V8i or MicroStation XM SDK, or with a full installation of MicroStation V8. 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 BE Community forums. 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.. 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 application (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 = CExpressionDouble ("4 * 2")

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
'  Note: this won't work in MicroStation V8 and later
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. Instead, VBA provides more information via the ModelReference.MasterUnit property. It's because of issues such as this that we recommend you should prefer MicroStation VBA to BASIC.

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