You are on page 1of 120

15 User Commands

ucmlang.pdf User Commands (UCMs) are macros that follow the logic and syntax rules of the UCM language described in this chapter. However, MicroStation 95s increased flexibility and ease of use now enable you to perform many simple functions for which you may have used UCMs in the past. For this reason, no future enhancements to the UCM functionality are planned. The information in this chapter is provided to enable you to convert existing UCMs to current analogs. You can use UCMs to: Automate common sequences of tool usage and key-ins. Simulate input to MicroStation. Test and loop for various conditions.

UCMs differ from MicroStation commands. In MicroStation, every tool, view control, or key-in activates a command. For example, the Place Helix tool activates the PLACE HELIX command. A UCM can be thought of as a sequence of MicroStation commands (although this is an oversimplification). You need to know about commands only if you are customizing MicroStation. The UCM language and registers are essentially the same for MicroStation and the VAX-based IGDS system. See Adapting IGDS UCMs for MicroStation on page 15-33 for a list of the differences. User Command Macros are unrelated to MicroStation BASIC programs (which are occasionally referred to as Macros).

UCM Statements
A UCM consists of a series of statements. Each statement has one and only one operator, which directs MicroStation to take action. There are many types of operators, and the name of each operator indicates the action to be taken by MicroStation.

MicroStation 95 Reference Guide

15-1

UCM Statements
Many operators have associated operands, which further specify the action, and a label, which identifies the statement for branching operations. A statement without a label must be indented with spaces, tabs, or both. Some elementary operators and the kind of action they direct are listed here, grouped by type.

Elementary program flow operators


For a complete list, see Program Flow (Branching) Statements on page 15-37.
Operator:
TST GO END PAUSE

Description:
Conditionally branch to another statement. Unconditionally branch to a label. Exit from the UCM. Temporarily stop the UCM.

Elementary user interface operators


For a complete list, see User Interface Operators on page 15-41.
Operator:
MSG GET

Description:
Display message in status bar. Get input from user.

Elementary MicroStation interface operators


For a complete list, see MicroStation Interface Statements on page 15-44.
Operator:
CMD PNT RST KEY SLI

Description:
Activate MicroStation command. Send data point to MicroStation. Send Reset to MicroStation. Send key-in to MicroStation. Send last input to MicroStation.

15-2

MicroStation 95 Reference Guide

UCM Statements Elementary design file input/output operators


For a complete list, see Design File Input/Output Statements on page 15-49.
Operator:
RED WRT STO

Description:
Read element from design file at a specific location. Write element to design file. Save setting.

Mathematical, Conversion, and Assignment Statements on page 15-52 are used to set up mathematical expressions.

Elementary database interface operators


For complete list, see Database Interface Statements on page 15-58.
Operator:
DBREAD DBWRITE DBADD DBDELETE

Description:
Read column(s) from linked database row. Write column(s) to linked database row. Add row to connected non-graphic database. Delete row from connected non-graphic database.

General statement syntax


The general syntax of a statement is:
[label:] [OPERATOR][, operand1,, operandN] [; comment]

The UCM language is flexible enough to accommodate personal preferences in the way UCMs are created and in the way they operate. Operators and operands can be in either upper or lower case, and most commands can either be activated through a CMD statement or KEY statement.

MicroStation 95 Reference Guide

15-3

15

User Commands

Elementary assignment operator The SET (page 15-52) statement assigns the value of an expression to a variable. Other statements listed in

Introduction to UCM Programming

Lesson: Introduction to UCM Programming


This lesson is an introduction to programming UCMs.

Exercise: Creating and activating a simple UCM


Suppose you are responsible for a building design, and you want all the elements that represent electrical wiring to be placed on the same level with the same symbology. If more than one person is drawing the wiring, or if more than one design file is involved, it would be efficient to create a UCM to simulate the key-ins that change the active settings for these attributes. Once created, the UCM could be activated right before any of the wiring is drawn. To get a feel for the process of creating a UCM, type the UCM using an ASCII text editor. Press <Return> at the end of each line. Any text following a semi-colon is treated as a comment. Note that when operands are literal strings, as are the element attributes in this example, they are enclosed in single quotation marks ('). When you finish typing, save the UCM as setelec.ucm in MicroStations ucm directory.
; SETELEC.UCM ; ; Simulate key-ins to change element attributes prior to ; drawing electrical wiring ; KEY 'ACTIVE LEVEL 4'; Set active level to level 4 KEY 'ACTIVE COLOR 3'; Set active color to color 3 KEY 'ACTIVE STYLE 1'; Set active line style to 1 KEY 'ACTIVE WEIGHT 0'; Set active line weight to 0 END ; All done

Now start MicroStation and activate the UCM:


1. From the Utilities menu, choose User Command > Run.

The Run User Command dialog box opens.


2. In the list box, select setelec.ucm. 3. Click the OK button.

OR
x Key in UC=SETELEC

This UCM sets the element attributes by using the KEY operator to send the key-ins to MicroStation to process. The last statement is the END operator. Every UCM must have an END operator to signal

15-4

MicroStation 95 Reference Guide

Introduction to UCM Programming


the end of the UCM. As the UCM runs, watch the status bar to see the settings change.

Exercise: Prompting from UCMs


The MSG operator is used to display messages and prompts in the status bar. The first two characters in the string that follows the operator in an MSG statement indicate the status bar field in which the message is displayed:
Status Key-in Arrangement of fields on the screen. Message Prompt Error

Field:
Status (st) Command (cf) Message (ms) Prompt (pr) Error (er)

Used to display:
Status (usually lock status). The name of the selected tool or view control. Messages (usually active element attribute settings). Prompts. Error messages.a

a. These should assist the user with resolving the problem, and in general should not contain the word Error.

Each field is about 40 characters wide. This example demonstrates the use of each message field. To get a feel for messaging, create and activate this UCM just as you did setelec.ucm, but name it message.ucm.
MSG MSG MSG MSG MSG END 'stThis 'cfThis 'msThis 'prThis 'erThis is is is is is the the the the the Status Field' Command Field' Message Field' Prompt Field' Error Field'

MicroStation frequently displays messages, prompts, and errors in the status bar. It is sometimes better to have MicroStation process the commands in a UCM without displaying the messages and prompts so that the UCM can display its own prompts. This is done by simulating the NOECHO key-in with the statement:
key 'noecho'

MicroStation 95 Reference Guide

15-5

15

User Commands

Introduction to UCM Programming


NOECHO is one of a group of MicroStation commands that are designed to be activated by UCMs. For more information about these commands, see Commands for Applications on page 15-116. If a UCM disables MicroStation messages and prompts, before the UCM exits it should reactivate them by simulating the ECHO keyin:
KEY 'ECHO'

If prompts are not reactivated when the UCM exits, MicroStation does not display any status bar prompts and the user cannot tell what has happened. If this does occur, prompts can manually be reactivated by keying in ECHO. Here is a modified version of setelec.ucm. It displays custom messages with the NOECHO and ECHO commands. This version also uses the special label, EXITUC. This label identifies the statement to which the UCM branches in the event of an error in its execution. Use the statements after the EXITUC label to do any cleaning-up needed before the UCM terminates. For example, if the UCM activates the NOECHO command and then aborts before it activates the ECHO command, MicroStation does not display any of its prompts and appears to be inoperative. To avoid that problem, it is good programming practice to simulate the ECHO key-in after the EXITUC label.

Edit your copy of setelec.ucm as follows and run the


modified version of the UCM:
KEY MSG KEY KEY KEY KEY MSG MSG MSG MSG EXITUC: KEY END 'NOECHO' 'cfCustom messages.' 'ACTIVE LEVEL 4' 'ACTIVE COLOR 3' 'ACTIVE STYLE 1' 'ACTIVE WEIGHT 0' 'stWiring Attributes set.' 'msLEVEL=4, COLOR=RED, STYLE=1, WEIGHT=0' 'prYou are now ready to place the wiring.' 'er ' 'ECHO'

15-6

MicroStation 95 Reference Guide

Introduction to UCM Programming

You can disable MicroStation messages and prompts with the following statement, which should be used if you also want to use the UCM with IGDS . The IGDS-compatible statement to reactivate messages and prompts is:

SET CONTRL=CONTRL ! 768

SET CONTRL=CONTRL & -769

Exercise: Receiving input, registers, and branching in UCMs


User Commands
The GET (page 15-42) operator is used to receive a data point, a key-in, or a Reset from the user and to branch to a specific label based on the type of input. The next example, branch.ucm, delivered in MicroStations ucm directory, uses GET as well as the GO and TST operators, which also control program flow. Also note the use of the variables C0, K0 and KEY. (Do not confuse the variable, KEY, with the KEY operator.) UCMs cannot declare their own variables, but a number of MicroStation system variables are allocated for general use by UCMs. These variables are known as UCM registers. For more information about variables in UCMs, see UCM Variables on page 15-20. This example also introduces the SET operator, which is used to assign the value of an expression to a UCM register.

MicroStation 95 Reference Guide

15-7

15

Introduction to UCM Programming


; BRANCH.UCM KEY 'NOECHO' ; Disable messages MSG 'st ' ; Clear Status field MSG 'cfBranch.ucm' ; Display UCM name in Command field MSG 'er ' ; Clear Error field START: MSG 'msEnter some characters'; Prompt MSG 'prReset to exit' ; Reminder GET K,KEYIN, R,EXITUC ; If key-in, jump to KEYIN ; Else if Reset, jump to EXITUC GO START ; Else return to START KEYIN: MSG 'er ' ; Clear fields MSG 'pr ' MSG 'ms ' TST K0 GT 20, LONG ; If input > 20 chars, jump to LONG SET C0='cfYou keyed in: '+KEY; Build message MSG C0 ; that echoes your input GO START ; Jump to START LONG: MSG 'erInput > 20 characters, please re-enter' GO START ; Return to START EXITUC: MSG 'er ' ; Clear Error field MSG 'ms ' ; Clear Message field MSG 'cf ' ; Clear Command field MSG 'st ' ; Clear Status field MSG 'prBranch.ucm exited' ; Display exit status KEY 'ECHO' ; Enable messages END

To summarize, this UCM prompts the user for a key-in. If a key-in is entered the UCM branches to the label KEYIN where it tests the length of the key-in. If the key-in is longer than 20 characters, it displays an error message and loops to the label START. Otherwise, it concatenates a literal string (You keyed in ) and the users input, which is the content of the KEY register, and stores the string in the register C0. Finally, it displays the user input in the Command field and again loops to the label START. Pressing the Reset button while at the GET statement allows the user to exit the UCM.

15-8

MicroStation 95 Reference Guide

Introduction to UCM Programming

Exercise: Locating elements and DGNBUF


Much of the interaction between MicroStation and the user relates to identifying or locating existing elements for construction, manipulation, or modification. A UCM can control this interaction by simulating a LOCELE or FENCE LOCATE key-in. When the LOCELE command is activated and the UCM sends a data point to MicroStation with a PNT statement, MicroStation searches the design file for an element. If MicroStation locates an element, it loads the element into a buffer called DGNBUF. Attributes of the element in DGNBUF can then be extracted through special DGNBUF variables. It is even possible to manipulate the element and then write it back to the design file. A list of DGNBUF and other system variables can be downloaded from MIC. After an element is loaded into DGNBUF, the MicroStation system variables CUREBL and CUREBY are pointers to the elements location (in block and byte offset) in the design file. Two other pointer variables, WWSECT and WWBYTE, are pointers to the design file location at which the element search starts. These latter two pointers should be initialized by the UCM to point to the beginning of the design file and should be restored to that location before the UCM exits. Before MicroStation Version 5.0, the Change Element to Active Symbology and Change Element to Active Level tools let you change the color, line style, line weight, and level of existing elements to the active settings. It would have been convenient to have a single tool that does the work of both tools. A UCM, chgattr.ucm, in MicroStations ucm directory, is just such a tool. Here is the listing:

MicroStation 95 Reference Guide

15-9

15

User Commands

Introduction to UCM Programming


; ; ; ; ; ; ; ; ; ; ; ; ; CHGATTR.UCM DESCRIPTION :Change element symbology (color, line style, and line weight) and level to active settings. Prompt user to identify an element. If element is found, prompt user to accept or reject element. If user accepts, change the element's symbology and level. Repeat until user Resets or activates another command. Initialize ---------SET WWSECT=0 SET WWBYTE=0 KEY 'NOECHO' MSG 'stChgAttr.ucm' MSG 'ms ' MSG 'er '

; ; ; ; ; ;

Make sure to start searching from beginning of design file Disable messages Display UCM name Clear Message field Clear Error field

; ; ; Main Routine ; -----------START: KEY 'LOCELE' ; MSG 'cfChange Element Symbology GETELE: GET P,FNDELE, R,EXITUC ; ; GO GETELE ; FNDELE: PNT ; TSTELE: TST RELERR NE 0, START ; MSG 'prAccept/Reject' ; GET P,CHANGE, R,REJECT ; ; GO GETELE ; REJECT: RST ; GO TSTELE ; CHANGE: SET XYZLEV = ACTLEV ; SET SY.DSP = IDSYMB ; WRT CUREBL, CUREBY ; GO START ; ;

Locate element and Level'; Display "tool" name If data point, jump to FNDELE Else if Reset, jump to EXITUC Else return to GETELE Send data point If element not found, return to START Prompt If data point, jump to CHANGE Else if Reset, jump to REJECT Else return to GETELE Send Reset Return to TSTELE Change level Change symbology Write element back to design file Return to START

15-10

MicroStation 95 Reference Guide

Introduction to UCM Programming


; Exit ; ---EXITUC: KEY 'NULL' MSG 'prChgAttr.ucm exited' SET WWSECT=0 SET WWBYTE=0 KEY 'ECHO' END

; Clear MicroStation state ; Display status ; Restore search position ; Enable messages

 

The WRT operator does not check the validity of the element being written to the file. A UCM cannot test whether elements are selected (with the Element Selection tool). MicroStation ignores the selection set when LOCELE is active.

Exercise: Using the RED operator


The RED operator reads elements at specific block and byte offsets. This operator not only locates an element, but also loads the element into DGNBUF, where it can be manipulated or tested. The next element pointers, the ELEBLK and ELECNT variables, contain the pointers to the next element in the file. The example that follows, dispchng.ucm, in MicroStations ucm directory uses both the RED operator and the next element pointer variables to step through the design file. As each element is loaded into DGNBUF, it is tested with the logical AND operator (&) to determine whether the element is new or has been modified. If the test is successful, the element is highlighted. Otherwise the next element is read.

MicroStation 95 Reference Guide

15-11

15

Be sure you understand how LOCELE lets the user identify each element whose attributes are to be modified. The key is the TST statement. This statement tests the MicroStation system variable RELERR to determine whether MicroStation found an element within the area specified by the Locate Tolerance user preference. If the element is successfully located, the element is then loaded into DGNBUF. There, the DGNBUF variable XYZLEV (the level of the located element) is set to ACTLEV (the active level), and the variable SY.DSP (the symbology of the element) is set to IDSYMB (the active symbology). Finally, the modified element is written back to the design file at the same location, overwriting the old element.

User Commands

Introduction to UCM Programming


; DISPCHNG.UCM -- Sequentially highlight all that have been modified in ; a design file. ; Initialize ; ---------KEY 'NOECHO' CMD NULCMD ; Clear MicroStation state MSG 'cfDisplay Changes' SET WWSECT = 0 SET WWBYTE = 0 SET CUREBL = WWSECT SET CUREBY = WWBYTE ; ; Main Routine ; -----------TOP: RED CUREBL, CUREBY TST UELETY EQ 34, SKIP TST RELERR NE 0, EXITUC SET R0 = LH.PRO & 1536 TST R0 EQ 0, SKIP KEY 'DISPLAY HILITE' PNT SKIP: SET CUREBL = ELEBLK SET CUREBY = ELECNT GO TOP ; point to next element ; Set search to the beginning of the file

; Find first element ; Skip shared cell definition element ; Exit when at the EOF ; Test modify bit ; in properties word

; highlight element

; Exit ; ---EXITUC: SET WWSECT = 0 ; reset file pointers SET WWBYTE = 0 KEY 'ECHO' CMD NULCMD MSG 'stDisplay Changes Completed' END

Exercise: Locating new elements


It is often convenient to manipulate elements as they are placed in the design file. This simple example, which is delivered as blockpat.ucm in MicroStations ucm directory, prompts the

15-12

MicroStation 95 Reference Guide

Introduction to UCM Programming


user to define the two corners of a block that will then be hatched at a 45 angle. This is accomplished through the use of the endof-design pointer variables, DFSECT and DFBYTE. These pointers contain the current end-of-design location and should not be set by the UCM. This UCM first saves the current position of the end-of-design markers and then prompts the user for the corners of the block. The search position is then set to the old location of the end-ofdesign marker, which is also the position of the new block that was just placed. Therefore, when the HATCH command is started and a data point is sent to identify the element to be hatched, the first and only element that can be located is the new block (the only element beyond the current search position.) The point that is sent to locate the element for hatching and to accept the element defaults to the last point that the user entered the second point that defined the block. For more information about the operands for the PNT operator, see PNT on page 15-44.

MicroStation 95 Reference Guide

15-13

15

User Commands

Introduction to UCM Programming


; ; ; ; BLOCKPAT.UCM Initialize ---------KEY 'NOECHO' MSG 'st ' MSG 'cfBlockpat.ucm' MSG 'er ' Place a block and then hatch it.

; ; ; ;

Disable messages Clear Status field Display UCM name in Command field Clear Error field

; ; Main Routine ; -----------START: SET R0 = DFSECT ; Save current end-of-design pointers SET R1 = DFBYTE CMD PBLOCK ; Activate the PLACE BLOCK command GETDP1: MSG 'msPlace a block' ; Prompt MSG 'prEnter first data point-Reset to exit' GET P,DP1,R,EXITUC ; If data point, jump to DP1 KEY 'BEEP' ; Else if Reset, jump to EXITUC GO GETDP1 ; Else sound warning and return to GETDP1 DP1: PNT ; Send along the data point just received GETDP2: MSG 'prEnter second data point-Reset to exit' GET P,DP2,R,EXITUC ; If data point, jump to DP2 KEY 'BEEP' ; Else if Reset, jump to EXITUC GO GETDP2 ; Else sound warning and return to GETDP2 DP2: PNT ; Send along second data pt to close the block SET WWSECT = R0 ; Set the search pointers to start SET WWBYTE = R1 ; at the old end-of-design location KEY 'PA=45' KEY 'PD=:1' KEY 'HATCH' PNT PNT GO START ; ; Exit ; ; ; ; Set pattern angle 45 Set pattern spacing to 1 sub-unit Simulate the HATCH key-in Send a data point to locate the new element ; Send a data point to accept the new element

15-14

MicroStation 95 Reference Guide

Using a UCM Template


; ---EXITUC: CMD NULCMD SET WWSECT = 0 SET WWBYTE = 0 MSG MSG MSG MSG MSG 'er ' 'ms ' 'cf ' 'st ' 'prBlockpat.ucm exited'

; Clear MicroStation state ; Restore search position

; ; ; ;

Clear Error field Clear Message field Clear Command field Clear Status field ; Display exit status ; Enable messages

Using a UCM Template


A UCM template is a UCM that has all the necessary and recommended labels and statements, all but ensuring normal initialization and termination. The UCM template template.ucm is supplied in MicroStations ucm directory.

MicroStation 95 Reference Guide

15-15

15

User Commands

KEY 'ECHO' END

Using a UCM Template


; ; ; ; ; ; ; ; ; ; TEMPLATE.UCM DESCRIPTION: VARIABLES: CALLS: CALLED BY: Initialize ---------KEY 'NOECHO' SET WWSECT=0 SET WWBYTE=0 SET A0=ACTANG SET A10=XAXSCL SET A11=YAXSCL SET A12=ZAXSCL SET UCASC=ACTAB SET R1=UCWRD(1) SET R2=UCWRD(2) SET R3=UCWRD(3)

; ; ; ; ;

Disable messages Make sure to start searching from beginning of design file Save active angle Save active scale factors

; Save active cell name ; in R1,R2,R3

; ; Main Routine ; -----------START: ; * ; * ; * ; ; Error Messages ; -------------ERR1: SET MSG='erError in last operation. RELERR='+RELERR MSG MSG ; Display error message in Error field GO EXITUC ; Exit ; ---FINISH: KEY 'NULL' MSG 'er ' MSG 'cf ' EXITUC: MSG 'st ' MSG 'prUCM exited';

; Clear MicroStation state ; Clear Error field ; Clear Command field ; Clear Status field ; Display status

15-16

MicroStation 95 Reference Guide

UCM Format
KEY SET SET SET SET SET SET SET SET SET SET END 'ECHO' WWSECT=0 WWBYTE=0 ACTANG=A0 XAXSCL=A10 YAXSCL=A11 ZAXSCL=A12 UCWRD(1)=R1 UCWRD(2)=R2 UCWRD(3)=R3 ACTAB=UCASC ; Enable messages ; Restore search position ; Restore active angle ; Restore active scale factors

; Restore active cell

UCM Format
A UCM is stored in an ASCII file and can contain any number of statements, each of which must be of the general form:
[label:] [OPERATOR][, operand1,, operandN] [; comment]

Labels
Labels are a means of identifying a statement for branching operations. Any statement can begin with a label, and a statement can consist of a label alone. Labels must be six characters or less and must start with an alphabetic character and be followed by a colon (:). There is no distinction between upper and lower case. If a label is longer than six characters, only the first six are used. For example, the following labels are treated identically:
LOCATION: Locating:

MicroStation 95 Reference Guide

15-17

15

Before you begin to develop your own UCMs, examine the sample UCMs supplied with MicroStation in the ucm directory and check the large selection of UCMs available through Intergraph user groups and third-party developers.

User Commands

The sample UCMs in this lesson include all necessary statements from this UCM template. Some statements are unnecessary in particular UCMs. For example, the statements that save and restore the active angle, active scale factors, and active cell are omitted from examples that do not change these settings. You should delete unnecessary statements in your UCMs to release variables for other uses and to minimize UCM size.

UCM Format
Any character other than a space or a tab is valid in a label; however, for compatibility with IGDS it is recommended that you use only alphanumeric characters (A-Z, 0-9). The label EXITUC has special significance; see the description of EXITUC under UCM Execution on page 15-19.

Operators
Operators, in conjunction with operands, direct MicroStation to take action. Types of action include activation of MicroStation commands, computation, and interaction with the user. Only one operator can be in a statement. There is no distinction between upper and lower case. Operands are specific to operators and, in fact, are optional for some operators. Operands can be separated by blanks, tabs, or commas.

For complete information on UCM operators and operands, see UCM Statement Syntax on page 15-36.

Comments
Comments are preceded by a semi-colon (;) and continue to the end of the statement.

Rules
Each UCM must conform to the following rules: The last statement must be an END statement: Any line other than those starting with a label can be indented with tabs or spaces or both. Literal strings must be enclosed in single quotation marks ('). Special characters can be included in literal strings by specifying the at symbol (@) and the 3-digit octal code for the ASCII value of the character. For example, to put a line feed in a text string (such as when creating a text node for placement), include @012 (octal 12 is the ASCII value for a line feed):
SET C0='This is@012a multi-line text@012string.'

Constants can be represented either as decimal integer values, floating point values, hexadecimal or octal values (the latter by

15-18

MicroStation 95 Reference Guide

UCM Execution
preceding the number with the at symbol@). For example, all of the following are valid:
12.345 -235 @100 (decimal 64)+34234234 12e-10 0x24

A statement can be continued on the next line by placing a comma (,) at the end of the line as a continuation character. For example:
SET C0='|UPDATE AE SET NAME=', +C1; Construct key-in

UCM Execution
For information about activating UCMs, see Activating a UCM in Chapter 8 in the Users Guide. After a UCM is loaded, MicroStation checks its syntax. If the syntax is correct, the UCM is run starting with its first executable statement. MicroStation steps through the statements until it encounters an END statement. When MicroStation encounters a GET (page 15-42), it pauses to allow user input: key-in, data point, Reset, or activation of a new command. If the user activates a new command, either from a tool box, menu, or from a function key, the UCM automatically branches to the EXITUC label. Thus, UCMs function similarly to built-in MicroStation commands in that at any point the user can exit. (It is possible to inhibit automatic branching.)

To stop a runaway UCM, press <Ctrl-C>.

MicroStation 95 Reference Guide

15-19

15

User Commands

UCM Variables

Error handling
If an error occurs during the processing of a UCM, MicroStation branches to the special label EXITUC, if it exists. This is a means for a UCM to restore variables that have been changed before exiting or to correct errors and continue. Any statement is legal after the EXITUC label except a call to another UCM.

Errors that are the result of improper user input


Some errors are the result of improper user input rather than an error in the UCM itself. For example, if the UCM is waiting for numeric input and the user keys in a character string, an error is generated and MicroStation branches to the EXITUC label (if it exists). When this happens, MicroStation sets the ERR register to a non-zero value prior to branching to EXITUC. If processing is to continue, the UCM must clear the ERR register before branching back. For example:
EXITUC: tst err eq 0, norm; Test for normal exit set err = 0 ; Clear error status go start ; Back for more NORM:

The UCM template.ucm, (see Using a UCM Template on page 15-15) supplied with MicroStation in the ucm directory, has labels and statements for initialization, error handling, and termination.

UCM Variables
There are three types of variables that can be used in UCMs: UCM registers TCB variables DGNBUF variables Any variable type can be used anywhere in a UCM and the distinction is only in the way MicroStation handles them internally. There is no distinction between upper and lower case.

15-20

MicroStation 95 Reference Guide

UCM Variables

UCM registers
UCM registers are variables that can be used by UCMs for general purposes. MicroStation initializes all UCM registers when it loads UCMs. UCM registers are listed below.
Register(s):
R0-R31 ERR

Size:
16 bits 16 bits

Description:
integer scratch registers. MicroStation sets ERR to indicate errors before branching to EXITUC. set to the number of characters input from the keyboard. double precision integer scratch registers. tablet coordinates for last data point. UOR coordinates for last data point. low byte view for last data point high byte multiview spot flag 1 = multi-view 0 = single view double precision floating point scratch registers. register where MicroStation puts user key-ins. Can also be used as a scratch register. number of characters in KEY. character scratch register (generally used for prompts and messages to user). number of characters in MSG.

NUM

16 bits

I0-I15

32 bits

XDT, YDT XUR, YUR, ZUR VNO

16 bits 32 bits 16 bits

A0-A15

64 bits

KEY

42 characters

K0 MSG

16 bits 42 characters

M0

16 bits

MicroStation 95 Reference Guide

15-21

15

User Commands

UCM Variables
Register(s):
C0-C15

Size:
42 characters

Description:
character scratch registers (can be combined for strings of up to 252 characters). Arguments are stored in these registers, beginning with C0. number of characters in C0-C15. If value is 1, the C# register is combined with the next one. register for identifying menu and tutorial command selection.

N0-N15

16 bits

FNO

16 bits

TCB variables
The TCB (Terminal Control Block) is a global data area of memory in which MicroStation stores all settings. A TCB variable is a variable in the TCB in which a setting is stored. A complete list of TCB variables can be downloaded from MIC.

UCMs can modify TCB variables directly with the UCM SET operator, but there isnt any error checking, and improper values can cause unpredictable results. For this reason, it is recommended that UCMs modify TCB variables by simulating MicroStation key-ins with the KEY operator whenever possible. For example, the active level is stored in the TCB variable

ACTLEV and can be set from a UCM with a SET statement. This
can cause problems for two reasons. First, it is possible to set the active level to a level that is turned off (not displayed) or to 0 (which is an error). However, by simulating the MicroStation ACTIVE LEVEL (LV=) key-in in a KEY statement, you ensure that MicroStation checks for a valid level and that this level is turned on.

Savable settings
The settings associated with Type 9 and Type 66 TCB variables can be saved in the design file by activating the FILEDESIGN command with a CMD or KEY statement. (This is equivalent to

15-22

MicroStation 95 Reference Guide

UCM Variables
choosing Save Settings from the File menu.) Settings associated with non-Type 9 TCB variables cannot be saved. Some TCB variables are assigned several names by MicroStation so that they can be accessed in different formats. For example, UCWRD, UCINT, UCDFP, UCDPV, UCASC, UCRAD, and UCBYT all refer to the same buffer, but allow it to be referred to in word, integer, double precision floating point, double precision VAX, ASCII, Radix-50, and byte format, respectively. This is useful for converting from one data format to another. For example, a 16-bit word stored in R0 can be broken into two bytes and stored in R1 and R2 with the following statements:

There is no MicroStation setting associated with the buffer described above, but the TCB variables are Type 9. This means the buffer can be used to store UCM-specific data that in turn can be saved in the design file itself.

Pointers
Among TCB variables are several pairs of 16-bit integer pointers that are used by MicroStation to place, locate, and process elements. UCMs can use these pointers. There are two types of pointers: file pointers and element pointers. Each pair of file pointers points to a specific location in the design file. Each pair of element pointers points to a specific element in the design file. The common file pointers are listed below:
DFSECT, DFBYTE WWSECT, WWBYTE

Sector and byte pointers to the end of the design file. Sector and byte pointers to the starting element search position.

of the design file, directly W To prevent corruptionDFBYTE. These fileUCMs should not be used pointers should modify DFSECT and only to locate new elements or to check whether elements have been added or moved to the end of the design file.

MicroStation 95 Reference Guide

15-23

15

User Commands

SET UCWRD(1) = R0 SET R1 = UCBYT(1) SET R2 = UCBYT(2)

UCM Variables
The common element pointers are listed below:
CUREBL, CUREBY ELEBLK, ELECNT

Block and offset of current element. Block and offset of next element.

Blocks are a mechanism of segmenting information on computer disks (each block is 512 bytes). On VAX-based systems, design files are arranged as contiguous blocks. Neither DOS, UNIX, nor the Macintosh OS use contiguous blocks, but MicroStation preserves pointers for compatibility with VAX-based applications. The second number of an element pointer is the byte offset into the block. Offsets are never larger than 512 bytes and are always even (because all elements have an even number of bytes). UCM registers are a special subset of TCB variables.
Header Elements Type 8. 9. 10 Element 1
ELEBLK, ELECNT WWSECT, WWBYTE CUREBL, CUREBY

Element n -1 End of File

DFSECT, DFBYTE

Pointers upon opening of design file.

DGNBUF variables
DGNBUF is a data area within the TCB that MicroStation uses to
store elements when they are operated upon. The pointers

CUREBL and CUREBY point to the element in DGNBUF. UCMs can refer to DGNBUF variables directly using their variable names. By changing values in DGNBUF, UCMs can directly modify
elements in the design.

DGNBUF variable names all start with a two character prefix that
defines the element type for which the variable applies. For

15-24

MicroStation 95 Reference Guide

UCM Variables
example, any variable that starts with TX. is only valid if DGNBUF contains a text element (type 17). Furthermore, some variables are defined only for 3D designs. This means that before accessing DGNBUF, a UCM must test the TCB variable NDICES in a TST statement to determine the files dimensionality and therefore whether to use the 2D or 3D DGNBUF variables. For example:
TST NDICES NE 2, THREED SET I1=EL.ORG(1) GO NEXT THREED: SET I1=EL.OG3(1) next: ; Test dimensionality ; Set 2D DGNBUF variable ; Branch past 3D code

Array variables
Various UCM registers, TCB variables, and DGNBUF variables refer to an array of elements rather than just a single element see Terminal Control Block (TCB) on page 15-60. Elements of an array variable can be addressed individually with subscripts or the entire array can be addressed by omitting subscripts. For example, the variable UCASC is a 32-character array. This UCM fragment searches a string in UCASC for a comma:
SET R0 = 1 START: TST UCASC(R0) EQ ',' ,FOUND SET R0 = R0+1 TST R0 EQ 33, NONE GO START FOUND: : NONE: ; Initialize counter ; If character is ",", branch ; to FOUND ; Else increment counter ; If counter = 33, branch to NONE ; Else test next character

This statement copies the entire contents of UCASCall 32 charactersto a register:


SET C0 = UCASC

If the registers KEY, MSG, or C# are referred to without a subscript, the applicable number of characters is determined by the contents of the K0, M0, and N# registers, respectively.

MicroStation 95 Reference Guide

15-25

15

User Commands

; Set 3D DGNBUF variable

File Naming

File Naming
The CAL (page 15-39), CLS (page 15-39), TSK (page 15-57), and UCM (page 15-38) statements refer to files. Because file naming conventions vary between operating systems and types of computers, a UCM developer should be aware of the conventions for the system they are using. When a UCM filename is specified alone in a CAL, CLS, or UCM statement that is, without a path, MicroStation checks the definition of the MS_UCM configuration variable and searches for the file in the specified path. If any part of the file is not specified after substitution of the MS_UCM definition, MicroStation searches the directory in which the calling UCM resides. Likewise, when an application filename is specified alone in a TSK statement, MicroStation searches the path assigned to the MS_APP configuration variable. For example, if MS_UCM is set to its as delivered default and you specify a filename in a UCM that does not include a path specification, MicroStation searches for that UCM in MicroStations ucm directory. If you specify either the disk or the directory in the filename, the specification is used in place of the MS_UCM definition.

 

MicroStation ignores leading underbars (_) in filenames (for compatibility with IGDS applications). MicroStation ignores VAX disk and directory names in file specifications.

Using configuration variables


You can define Configuration Variables (see Chapter 4 in the Users Guide) to simulate VAX logical names. Suppose you define the configuration variable MYFILES in the Configuration Variables dialog box as /projects/city/ on any UNIX platform. For example, this statement directs MicroStation to search for the file /projects/city/findef.ucm. :
UCM 'MYFILES:findef'

Furthermore, if you were to analogously define MYFILES on other systems, the UCM could be activated, and the above UCM statement would direct MicroStation to search for C:\PROJECTS\CITY\FINDEF.UCM on the PC or HD:Projects:City:Findef.ucm on the Macintosh.

15-26

MicroStation 95 Reference Guide

Error Messages
Thus, the use of configuration variables helps to: Ensure portability of UCMs to MicroStation on other computer systems. Segment UCMs by user or application.

Configuration variables can also be used to enable MicroStation to locate UCMs that are referenced in custom menus.

Error Messages
The following error messages can be generated while a UCM is active:
Error message:
Bad array Bad destination variable Bad message field Bad string operation Bad subscript Bad value Bad variable name Divide by zero File too large Label [ ] undefined Math error String overflow String too long Subscript out of range Symbol table overflow Syntax error TCB file missing UCM nesting error

Meaning:
Array sizes do not match. Destination is not a variable. Must be either pr, er, cf, st, or ms. Only + is valid for strings. Variable is not an array. Value conversion error. Variable is undefined. Illegal operation (result is undefined). File does not fit in UCM buffer. Label not found in UCM. Usually indicates overflow. File contains too many strings. Maximum string length is 80 characters. Subscript is too large. There can be a maximum of 100 labels. Line contains invalid syntax. MicroStation cannot find tcbvars.dat. Cannot open temporary file. (MicroStation cannot write to directory assigned to MS_DATA.)

MicroStation 95 Reference Guide

15-27

15

User Commands

Servicing Tutorials with UCMs

Servicing Tutorials with UCMs


A UCM can be designated as the servicing application for a tutorial. The designated UCM is automatically activated when the tutorial activates. When the UCM exits, the tutorial deactivates. Several useful techniques for servicing tutorials with UCMs are described in the following sections.

Allowing menu operation


The servicing UCM can let the user activate commands from menus while the tutorial is active. To do so, the UCM cannot alter any of the TCB buffers used by MicroStation commands (e.g., DGNBUF). One technique for allowing menu command activation is shown in the following example:
SET RO=OUTFLG SET OUTFLG=OUTFLG ! @10 NEXT: GET I,KEYENT,T,GRASEL SLI GO NEXT KEYENT: . . . GRASEL: . . . EXITUC: SET OUTFLG=RO ; Get tutorial input ; Send other inputs to File Builder ; Save OUTFLG ; Allow menu command selections

; Service key entry field input

; Service graphic selection field input

; Restore OUTFLG

In this example, bit 3 in OUTFLG is set to prevent menu command activation from terminating the UCM. Next, a GET statement is used to get all user inputs. Tutorial-related inputs are routed to UCM labels KEYENT and GRASEL. Menu command selections, keyboard inputs, and data point inputs are relayed to File Builder using the SLI statement.

15-28

MicroStation 95 Reference Guide

Servicing Tutorials with UCMs

Servicing key entry field input


Because a tutorial can contain multiple key entry fields, it can be necessary for a UCM to be able to identify the key entry field where the input originated. The following example shows this.
KEYENT: TST FNO EQ 1, FIELD1; Input from field 1 TST FNO EQ 2, FIELD2; Input from field 2 GO NEXT ; Unrecognized field FIELD1: . ; Field 1 processing . . FIELD2: . ; Field 2 processing . .

In this example, the UCM FNO register is tested to determine whether a key entry field input originated from field 1 or field 2. Key entry field input read by the GET statement with the I keyword is stored in the KEY register, as shown in the following example.
FIELD1: TST KEY EQ ' ',NEXT; Skip blank input SET RO=1 ; Parse function code = 1 TSK '_PRO_DD_UTIL:PARSE.EXE',RO,NUM,KEY; Request parser . . .

The number of characters in KEY is stored in the NUM register.

Key-in Window input is handled by the GET statement K keyword.

Servicing graphic selection field input


A graphic selection field can be used to select any one of several commands or inputs, as determined by the field (action) type (A, C, D, E, K, M, P, R, S, T, U, or Z). The field type determines how the graphic selection field operates. The UCM GET operator is used to access graphic selection field inputs. Field types A, C, D, K, P, S, T, and U are routed to the GET statement label associated with the T keyword. To distinguish different types of fields,

MicroStation 95 Reference Guide

15-29

15

User Commands

Servicing Tutorials with UCMs


information is provided to the UCM in the FNO, NUM, and KEY registers. This information is described below.
Field Type:
P C R S U D A

FNO:
1,2 3 4 5 6 7 8

NUM:
char. count char. count char. count char. count UC slot # char. count field #

KEY:
primitive command name cell name cell name symbol character N/A tutorial cell name N/A

For field type P, FNO is 1 for intermediate commands and 2 for non-intermediate commands. Graphic selection fields containing K (Non-terminated key-in) and T (Terminated Command key-in) field types are routed to the label associated with the GET statement K keyword. This information is described below.
Field Type:
K T

FNO:
N/A N/A

NUM:
char. count char. count

KEY:
ASCII characters ASCII characters

MicroStation automatically converts precision input key-in text (XY=, DX=, DI=, etc.) to data point input, which can be obtained using the GET statement P keyword.

15-30

MicroStation 95 Reference Guide

Servicing Tutorials with UCMs


The following example shows how graphic selection field inputs can be detected.
SET RO=OUTFLG SET OUTFLG=OUTFLG ! @10 NEXT: GET M,MENU,T,GRASEL,K,KEYIN; Get graphic selection input GO NEXT ; Ignore all else KEYIN: . ; Process text in KEY, # of ; characters in NUM . GO NEXT GRASEL: . ; Service graphic selection ; field input . . GO NEXT MENU: SLI ; Select primitive commands EXITUC: SET OUTFLG=RO ; Restore OUTFLG . . . END ; Tutorial deactivates ; Save OUTFLG ; Allow menu command activation

The above example shows how the servicing UCM can distinguish graphic selection field inputs (primitive commands, text input, and application commands). In this example, text and application commands are processed locally in the UCM. Menu commands are processed so that the tutorial automatically deactivates.

MicroStation 95 Reference Guide

15-31

15

User Commands

Servicing Tutorials with UCMs


In many cases, a tutorial contains two or more application commands. The following example shows how different application commands can be distinguished.
GRASEL: TST FNO NE 8, NEXT TST NUM EQ 1, APCMD1 TST NUM EQ 2, APCMD2 GO NEXT APCMD1: . . . GO NEXT APCMD2: . . . GO NEXT ; ; ; ; Service graphic selection field input Application command 1? Application command 2? Unrecognized field

; Command 1 processing

; Command 2 processing

In the example above, FNO is examined to determine if an application command field type was selected. Also, NUM is examined to determine which application field (1 or 2) was selected.

Outputting text to a tutorial


Text can be output to tutorials through output fields and key entry fields. Output field numbers and key entry field numbers must be different for fields to be identified. For example, when building a tutorial you might specify output field numbers in the 1-10 range and key entry field numbers in the 11-20 range.

Output fields
Text can be output to an output field using a UCM TOT statement, as shown in the following example.
TOT 1,'TUTORIAL NAME=',16; Display "TUTORIAL NAME" in field 1 SET MSG=TUTNAM ; Get tutorial name TOT 2,MSG ; Display name in field 2

In the above example, the text string TUTORIAL NAME= is output to output field 1. The string is set to contain 16 characters. The active tutorial name is output to field 2.

15-32

MicroStation 95 Reference Guide

Adapting IGDS UCMs for MicroStation


Each output field in a newly created tutorial has a maximum number of displayable characters. Text strings exceeding the allotted field width are truncated for display.

Key entry fields TOT statements are also used for outputting text to key entry
fields. The following is an example of text output to key entry fields:
TOT 11, 'INCHES',6 TOT 12, ' ',1 ; Display default units in key entry ; field 11 ; Erase key entry field 12

Each key entry field in a newly created tutorial has a maximum number of displayable characters. Text strings exceeding the allotted field width are truncated for display.

Positioning the insertion cursor in key entry fields


The insertion cursor that appears in the tutorial can be positioned at the beginning of a key entry field by issuing a TOT statement with only the field number specified. The positioning of the cursor does not erase the field.
TOT 12 ; Position cursor in key entry field 12

In this example, the cursor is positioned at the beginning of field 12. Any characters previously displayed in the field remain.

Adapting IGDS UCMs for MicroStation


Because the MicroStation UCM syntax is nearly identical to that of IGDS on the VAX, it is fairly simple to adapt UCMs from IGDS to MicroStation. However, you should keep in mind the following constraints: MicroStation maintains all IGDS TCB variables whose associated settings can be saved. However, if the UCM references variables whose associated settings cannot be saved, those variables may or may not be supported in MicroStation. MicroStation flags references to these variables as errors when the UCM is executed.

MicroStation 95 Reference Guide

15-33

15

User Commands

In the above example, the text string INCHES displays in key entry field 11. A single blank character output to field 12 erases that field.

Adapting IGDS UCMs for MicroStation


The following IGDS TCB variables are not supported in MicroStation.
CMDTYP IGOTO LOPTNO REJIGT AUXXOR SCANER DCTCHS
a

FSPCnn DLVLnn DFLGnn RFFILn AUXZOR

RFFEXn RFUICn RFLDSn RFVERn

DGNSIZ FSPNnn AUXYOR

a. MicroStations terminal type is 15.

Probably the most common source of incompatibility is the following fragment:


SET CMDTYP=0 SET IGOTO=0

This fragment is often used to leave the IGDS File Builder in a known state after exiting a UCM. Any UCM that tests for specific values of CMDTYP or IGOTO must be modified to run in MicroStation. For MicroStation substitute:
KEY 'NULL'

or
CMD NULCMD

Either works in MicroStation or IGDS. The only difference is that the NULL command also clears the Key-in Window fields. Due to differences in directory structure between the VAX and the systems on which MicroStation runs, it is necessary to replace certain IGDS TCB variables.
IGDS TCB variables:
DGNFIL, DGNFEX, DGNVER, DGNUIC, DGNLDS CELFIL, CELFEX, CELVER, CELUIC, CELLDS DMRSFL, DMRSEX, DMRVER, DMRUIC, DMRLDS UCXLIB, UCXEXT, UCXVER, UCXUIC, UCXLDS

MicroStation replacement:
DGNNAM CELNAM SCHEMA UCINAM

The syntax of the STO (page 15-51) statement differs. For MicroStation, it is necessary to add the TCB offset to each STO statement.

15-34

MicroStation 95 Reference Guide

Compiling UCMs
The following UCM operators are not supported in MicroStation:
DC (substitute KEY 'BEEP') RUN (use TSK) CAN (use TSK)

Compiling UCMs
You can compile UCMs. Compiled UCMs execute exactly the same as normal UCMs, but load much faster. When activating a UCM with the USERCOMMAND (UC=) key-in, if you do not include a . extension on the UCM name, MicroStation first searches for a compiled UCM (with the extension .ucc). If no such file exists, MicroStation searches for the UCM with the standard .ucm extension. If you want to ensure activation of either the original UCM or the compiled version, you should explicitly specify the extension in the USERCOMMAND (UC=) key-in.

To compile a UCM:
1. Key in UCC <filename>.

This creates a file with the same name except that the extension .ucc replaces .ucm.

To compile several UCMs at the same time:


1. Create a text file that contains a list of the names of the UCMs. 2. Key in UCC @<filelist>.

MicroStation 95 Reference Guide

15-35

15

User Commands

UCM Statement Syntax

UCM Statement Syntax


A UCM consists of a sequence of statements, each of which (other than a comment or label) contains one and only one operator (see Operators on page 15-18). An operator directs MicroStation to perform some operation using any operands that follow in the statement. This chapter discusses each type of UCM statement. In each syntax description: Optional operands are shown in [ ]. [] denotes a variable number of operands.

15-36

MicroStation 95 Reference Guide

Program Flow (Branching) Statements

Program Flow (Branching) Statements


The following statements control UCM flow:
To:
Conditionally branch to another statement. Unconditionally branch to another statement. Exit from the UCM. Activate another UCM. Activate another UCM as a subroutine; save and restore registers. Activate another UCM as a subroutine, without saving registers. Temporarily stop the UCM.

Use this statement:


TST (page 15-37) GO (page 15-38) END (page 15-38) UCM (page 15-38) CLS (page 15-39)

CAL (page 15-39)

PAUSE (page 15-40)

TST
[label:] TST operand1, keyword, operand2, destination

Descr. Branches to destination, if the relationship between operand1 and operand2 satisfies the keyword condition. If the comparison is negative, the next statement is processed. Possible values for keyword are:
LT GT EQ NE LE GE MT
less than (<) greater than (>) equal to (=) not equal to () less than or equal to () greater than or equal to () matches

If operand1 is a string variable, operand2 is automatically converted to a string before the comparison is made, and the only valid keyword values are EQ, NE, and MT.

MicroStation 95 Reference Guide

15-37

15

User Commands

Program Flow (Branching) Statements


Examples:
TST KEY EQ 'NEXT', AGAIN "NEXT"
TST KEY MT 'NEXT', AGAIN TST r0,GT,0,LOOP TST RELERR NE 0 EXIT TST KEY(1) EQ 'A', CONT is "A"

; Branch to AGAIN if user keyed in


; Branch if any string starting with ; "NEXT" is keyed in ; Branch to LOOP if R0 > 0 ; Exit if there was an error ; Branch if first character of KEY ;

GO
[label:] GO destination

Descr. Unconditionally branches to destination. Example GO HELLO; Branch to HELLO


GO FINISH ; Branch to FINISH

END
[label:] END

Descr. Stops execution of the UCM. A UCM must have an END statement its only such statement as its last executable statement. Examples:
END ; All done

UCM
[label:] UCM filename

Descr. Activates the UCM specified by filename. The UCM is found as described in File Naming on page 15-26. When the new UCM is activated, the UCM registers are not changed. This means that the registers can be used to pass parameters from one UCM to the next.

The UCM statement can also be useful if a UCM becomes too large to fit in memory. By splitting the UCM into smaller UCMs and chaining them together with UCM statements, this limitation can be effectively circumvented.

15-38

MicroStation 95 Reference Guide

Program Flow (Branching) Statements


Examples:
UCM 'new'
UCM 'C:\USR\HANK\NEW.UCM' UCM 'HD:Usr:Hank:New.Ucm' UCM '/usr/hank/new.ucm' UCM 'PROD:new.ucm' UCM C0;

; Activate NEW.UCM
; Directory specified with filename ; (DOS systems) ; Folder specified with filename ; (Mac OS) ; Directory specified with filename ; (UNIX systems) ; Directory specified by configuration ; variable "PROD" ; Filename specified in C0

CLS
[label:] CLS filename

Descr. Calls the UCM specified by filename as a subroutine. The UCM is found as described in File Naming on page 15-26. Before MicroStation activates the called UCM, it saves and initializes all UCM registers in the calling UCM. This means that the called UCM operates exactly as if it were activated with a USERCOMMAND (UC=) key-in. When the called UCM exits (via an END statement), the original contents of the UCM registers are restored and processing of the calling UCM continues with the next statement after the CLS statement. The CLS statement is generally used to call UCMs that do not require parameters. Since the called UCM does not affect the contents of the UCM registers, in many cases UCMs that were not specifically written as subroutines can be called using the CLS statement. The calling UCM should add statements that allow for the possibility of changes to the TCB and the Key-in Window fields by the called UCM. Examples:
(DOS) CLS 'HD:Usr:Hank:New.Ucm' CLS '/usr/hank/new.ucm' (UNIX) CLS 'PROD:new.ucm' CLS C0 ; Folder specified with filename (Mac) ; Directory specified with filename ; Directory specified by environment ; variable "PROD" ; Filename specified in C0

CLS 'new'
CLS 'C:\usr\hank\new.ucm'

; Activate NEW.UCM
; Directory specified with filename

CAL
[label:] CAL filename

Descr. Call the UCM specified by filename as a subroutine. The contents of the UCM registers are not saved and restored. This means that the registers can be used as subroutine arguments. Therefore, the calling UCM should add statements that allow for the

MicroStation 95 Reference Guide

15-39

15

User Commands

Program Flow (Branching) Statements


possibility of changes to the contents of the UCM registers by the called UCM, as well as changes in the TCB and the Key-in Window fields. Examples:
CAL 'new'
CAL 'C:\usr\hank\new.ucm' CAL 'HD:Usr:Hank:New.Ucm' CAL '/usr/hank/new.ucm' CAL 'PROD:new.ucm'

; Activate NEW.UCM
; Directory specified with filename ; (DOS systems) ; Folder specified with filename ; (Mac OS) ; Directory specified with filename ; (UNIX systems) ; Directory specified by environment ; ; variable "PROD" ; Filename specified in C0

CAL C0

PAUSE
[label:] PAUSE [message, [timeout]]

Descr. In DOS, suspends the UCM for timeout seconds or until the user presses a key, whichever occurs first. If timeout is omitted, the UCM is suspended until the user presses a key. The message operand specifies a string to display in the status bar (in the same format as MSG (page 15-41). No UCM registers are affected by the PAUSE statement. Examples:
PAUSE
PAUSE 'prHello World', 10

; Pause until user presses a key


; Display "Hello World" in the Command ; Window Prompt field and pause for ; no more than 10 seconds

15-40

MicroStation 95 Reference Guide

User Interface Operators

User Interface Operators


These statements interface with the user (through MicroStation):
To:
Display message in status bar. Get input from user. Display information in tutorial.

Use:
MSG (page 15-41) GET (page 15-42) TOT (page 15-43)

MSG
Descr. Displays message in a status bar field. The first two characters of message specify the field. See Prompting from UCMs on page 15-5 for information about the arrangement of status bar fields.
pr er cf st ms

Prompt field Error field Command field Status field Message field

Example MSG 'erThis is an error message'


MSG 'prThis is a prompt' MSG 'cf ' ; Clear the Command field MSG MSG ; Message is in MSG register

MicroStation 95 Reference Guide

15-41

15

User Commands

[label:] MSG message

User Interface Operators

GET
[label:] GET [keyword1,label1,,keywordN,labelN]

Descr. Suspends the UCM until the user provides input.


If the input:
Is of a type that corresponds to a specified keyword Is not of a specified type

Then:
Branches to the corresponding label.

The next statement is processed.

There must be a one to one correspondence between keywords and labels (every keyword must have a label). The possible keywords, the input type they represent, and where the input is stored are as follows:
Keyword:
P K R C M

Input type:
Data point Key-in Reset Unattached cursor button Menu or function keya

Data stored in:


XDT, YDT, XUR, YUR, ZUR, VNO KEY (text string), NUM (number of characters) (No data is stored.) XDT, YDT, XUR, YUR, ZUR, VNO, NUM (button number) FNO (type of command), NUM (number of characters), KEY (key-in string for command) FNO (type of command), NUM (number of characters), KEY (key-in string for command) FNO (field number), NUM (number of characters), KEY (key-in string)

Tutorial graphic selection field

Tutorial key entry field

a. When the user chooses a new command from a menu, MicroStation automatically branches to the EXITUC label. To prevent this from occurring so that branching can be determined by the M keyword, the UCM must first SET bit 3 in the TCB variable OUTFLG. Having done so, the UCM should provide an exit path through EXITUC.

MicroStation sets the following TCB variables when the user chooses a new command from a menu to help the UCM distinguish between commands:
GETCMD

number that uniquely identifies the command.

15-42

MicroStation 95 Reference Guide

User Interface Operators


GETCLSa GETSRC
a

number that identifies the command class. number that identifies the source of the command.

a. For a list of the possible values for GETCLS and GETSRC, see Terminal Control Block (TCB) on page 15-60.

Examples: GET K, KEYIN


GET K,KY12, P,POINT, R,EXITUC

; Branch to KEYIN if user


; input is a key-in ; Branch on key-in, data point, ; or Reset

[label:] TOT field_number[, output_string[, num]]

Descr. Displays num characters of output_string in the tutorial field specified by field_number, after first clearing the field. The field can be either an output field or a key entry field. If num is omitted or is greater than the length of output_string, the full output_string is displayed. If the specified field is a key entry field, MicroStation positions the input pointer in that field after it displays output_string. If output_string is omitted, the input pointer is positioned without affecting the contents of the field. One way to show a default value in a tutorial key entry field is to use a TOT statement. Examples: TOT 2, 'Hello', 5
TOT 3 TOT 11, ' ', 1 TOT R0, KEY, NUM

; Display "Hello" in field 2


; Position pointer in field 3 ; Clear field 11 ; Display last key-in in field identified by R0

MicroStation 95 Reference Guide

15-43

15

User Commands

TOT

MicroStation Interface Statements

MicroStation Interface Statements


These statements let UCMs send inputs to MicroStation as if they had been input from the keyboard, mouse, or digitizing tablet:
To:
Activate a command. Send a data point to MicroStation. Send a Reset to MicroStation. Send a key-in to MicroStation. Send last input to MicroStation.

Use:
CMD (page 15-44) PNT (page 15-44) RST (page 15-49) KEY (page 15-49) SLI (page 15-49)

These statements can be used to automate sequences of commands. When MicroStation executes an interface statement, it posts the error value in the TCB variable RELERR. A value of zero indicates success. Any other value indicates an error. For more information, see RELERR Messages on page 15-110.

CMD
[label:] CMD primitive

Descr. Activate the command that corresponds to the IGDS primitive specified by primitive. There is a primitive for most drawing and viewing commands.

To simulate a key-in to change a MicroStation setting, use a KEY (page 15-49) statement.

Example CMD PLINE; Select Place Line tool (PLACE LINE command)
CMD UPDATE; UPDATE VIEW

PNT
[label:] PNT [operand1, , operand13]

Descr. Sends a data point to MicroStation. Operand1-operand6 are generally used to position points in the design plane for element placement. Operand7-operand13 are used only for locating elements with the LOCELE and FENCE LOCATE commands. These operands let UCMs specify element attributes as search criteria.

15-44

MicroStation 95 Reference Guide

MicroStation Interface Statements


If any of these operands is omitted, its default is used.
operand number:
1 2 3 4 5 6 7, 8 9

Definition:
X UOR value Y UOR value Z UOR value view number X Tablet coordinate Y Tablet coordinate Type Level

Default:
XUR register YUR register ZUR register VNO register XDT register YDT register all types active level or displayed levels (depending on Level Lock) 1 SYSCL TCB variable (not checked)

10 11 12, 13

complex element modea class properties

Examples:

PNT
PNT ,,,,,,68,1 PNT ,,,,,,,,20 PNT ,,,,,,,,,,12 PNT,,,,,,32,,10,,,512,8704

; Send data point with defaults


; Send data point with search for ; lines, text nodes, and text. ; Search on level 20 ; Search for construction and ; dimension class elements ; Search level 10 for shapes (type 6) ; that are new and planar

The element search criteria specified in operand7-operand13 are described as follows:

Type
(operand7, operand8) UCMs can specify that elements be located regardless of type or that only elements of specific types be located. If both operand7 and operand8 are omitted (or zero), all element types are located. To let UCMs specify element type as a search criterion, operand7 and operand8 are masks. These type masks work on the principle that if a bit is set that is, it is on (its value is 1) then the search is for the corresponding type. The operands hold

MicroStation 95 Reference Guide

15-45

15

a. 1=ignore components, 0=treat components as simple.

User Commands

MicroStation Interface Statements


decimal values equivalent to 2n where n is the identifying number of a set bit, counting from the least significant bit. Element types are covered in Intergraph Standard File Formats (Element Structure) on page 18-1. Following is the mapping between element type and bit numbers:
operand7 type:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16

operand8 type:
17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32

Bit number:
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15

Suppose, for example, the search is to be limited to the following element types: lines (type 3), text nodes (7), and text (17) elements. According to the above table, this means bits 2 and 6 in operand7 and bit 0 in operand8 must be set. The decimal value of operand7 is 68 (22 + 26), and operand8, 1 (20).

Level
(operand9) UCMs can specify that elements on all displayed levels, the Active Level, or the level (1-63) specified in operand9 be located. If Level Lock is off and operand9 is omitted (or zero), only currently displayed elements can be located. On the other hand, if Level Lock is on and operand9 is omitted (or zero), only elements on the Active Level can be located.

Complex element mode


(operand10) UCMs can specify one of two search modes for complex elements specifically, the relationship of complex

15-46

MicroStation 95 Reference Guide

MicroStation Interface Statements


element headers to their component elements. Nest mode (the default) ignores components of complex elements, so that only the headers of complex elements are located. Unnest mode treats component elements as if they are simple elements (not part of a complex element). The primary application of unnest mode is for UCMs to retrieve data from component elements. In either mode, simple elements are treated identically. prevent corruption of not W Tocomponent element of the design file, UCMs shouldalso modify a a complex element without modifying the complex header and the remaining components. Therefore, PNT statements should normally specify nest mode (the default), particularly when locating elements for modification.

Class
(operand11) UCMs can specify that elements be located regardless of class or that only elements of specific classes be located. To let UCMs specify class as a search criterion, operand11 is a mask. The operand holds a decimal value equivalent to 2n where n is the identifying number of a set bit, counting from the least significant bit. The table shows the correspondence between element class and bit number:
Class:
Primary Pattern Component Construction Dimension Primary Rule Linear Pattern Construction Rule

Bit No./Class Value:


0 1 2 3 4 5 6

If operand11 is omitted (or zero), the applicability of class as a search criterion is determined by the TCB variable SYSCL. This variable is a class mask.

Properties
(operand12, operand13) Properties are a subset of element attributes; each element in the design file has a properties word

MicroStation 95 Reference Guide

15-47

15

User Commands

MicroStation Interface Statements


in which its properties are stored. UCMs can specify that elements be located regardless of properties or that only elements with specific properties be located. If both operand12 and operand13 are omitted (or zero), elements are located regardless of properties. To let UCMs specify properties as search criteria, operand12 and operand13 are masks. The operands hold decimal values equivalent to 2n where n is the identifying number of a set bit, counting from the least significant bit. Operand13 identifies the properties to be searched, with each bit corresponding to the same bit in the properties word. Operand12 indicates the desired value of each property identified in operand13. For every bit that is set in operand13, the corresponding bit in operand12 should have the desired value (1 or 0). The table lists the single letter bit names by which properties that can be defined as search criteria are commonly referred and their corresponding bit numbers (bits 0-7 do not correspond to allowable property search criteria):
Bit name:
L N M A R P S H

Number:
8 9 10 11 12 13 14 15

Suppose, for example, the search is to be limited to elements that are both new and planar. These properties are stored in the N-bit and P-bit, respectively, of the properties word. According to the above table, this means bits 9 and 13 in operand13 must be set. Only bit 9 of operand12 must be set, however, because MicroStation sets the N-bit of each new element and stores planar elements with their P-bit clear. Thus, the decimal value of operand12 is 512 (29), and operand13, 8704 (29 + 213).

15-48

MicroStation 95 Reference Guide

Design File Input/Output Statements

RST
[label:] RST

Descr. Sends a Reset to MicroStation.

KEY
[label:] KEY [string [, operand2]]

Descr. Sends string to MicroStation as a key-in. Operand2 specifies the number of characters to be sent, counting from the beginning of string. If operand2 is omitted, the entire string is sent. If string is omitted, the contents of the KEY register are sent.

Examples:

KEY
KEY C0, 4 KEY 'locele' KEY 'LV=4' KEY 'AA={asin(1)}

; Send string in KEY


; Send first 4 characters in C0 ; Activate LOCELE command ; Set active level to 4 ; Set active angle to arcsine(1)

KEY 'MDL LOAD calculat'; Load Calculator/Preprocessor

SLI
[label:] SLI

Descr. Sends the last input from a GET (page 15-42) statement to MicroStation for processing.

Design File Input/Output Statements


These statements directly read and write design files:
To:
Read element from design file at a specific location. Read element from design file without transforming reference file coordinates. Write element to design file. Save setting in design file.

Use:
RED

(page 15-50)
RDF

(page 15-50)
WRT

(page 15-50)
STO

(page 15-51)

MicroStation 95 Reference Guide

15-49

15

User Commands

String can include a mathematical calculation performed by the Calculator/Preprocessor. For example, the last two example lines load Calculator/Preprocessor and set the active angle to arcsine(1).

Design File Input/Output Statements


Pointers (see page 15-23) are often used with design file I/O statements.

RED
[label:] RED [file,] block, offset

Descr. Reads an element from a design file at a specific location into DGNBUF. file specifies the file from which to read. Zero specifies the active design file. Reference files are numbered 1-255. If file is omitted, the active design file is specified. block specifies the block number (relative to 0). offset specifies the byte offset (relative to 0) into the specified block. If the element is read from a reference file, it is transformed from the reference file coordinate system to the active design file coordinate system. The RED statement cannot be used to read deleted elements. If the element pointed to by block and offset is deleted, MicroStation reads subsequent elements until it reads an active element or reaches the end-of-file mark. Examples:
RED 0 CUREBL, CUREBY
RED 2, 4, 0

; Read current element


; Read element from reference file #2 ; at block 4 offset 0

RDF
[label:] RDF [file,] block, offset

Descr. Reads an element from a design file at a specific location into DGNBUF (is identical to the RED statement except that elements read from reference files are not transformed to the coordinate system of the active design file). See RED (page 15-50) for a description of the operands and other information. Example RDF 0 CUREBL, CUREBY; Read current element

WRT
[label:] WRT block, offset

Descr. Writes the element in DGNBUF to the active design file at the block (relative to 0), and byte offset (relative to 0) in the block, specified by block and offset, respectively. If block is 1, the element in DGNBUF is written at the end-of-file (it is added to the file) and the end-of-file pointers (DFSECT, DFBYTE) are updated.

WRT with care W Useelement format because MicroStation does not validate either the or the block and byte offset. Writing invalid
elements or writing elements to the wrong location can corrupt the design file.

15-50

MicroStation 95 Reference Guide

Design File Input/Output Statements


Example WRT CUREBL, CUREBY; Write element in DGNBUF to current
; block and byte offset

STO
[label:] STO TCB_var offset

Descr. Writes the contents of the TCB variable specified in TCB_var to the design files type 9 element. offset specifies the byte offset within the type 9 element. In effect, STO is a way to save a specific setting in the design file. To determine the byte offset, see Terminal Control Block (TCB) on page 15-60. Examples:
STO CAFONT 1158
STO ACTLEV 1176

; Save Active Font


; Save Active Level

MicroStation 95 Reference Guide

15-51

15

User Commands

Mathematical, Conversion, and Assignment Statements

Mathematical, Conversion, and Assignment Statements


These statements perform mathematical calculations or logical operations, convert between character and numeric variables, and assign values to variables:
To:
Assign value of expression to variable. Convert character string (in working units) to/from integer (in UORs). Compute square root. Compute sine and cosine. Compute arc tangent.

Use:
SET (page 15-52) CVT (page 15-53) SQR (page 15-54) SCS (page 15-54) ATN (page 15-54)

SET
[label:] SET var1 = var2 [keyword var3]

Assigns to var1 the value of the expression following the equal sign (=). Possible keywords are as follows:
Keyword:
+

Meaning:
addition, if var1 is numeric; concatenation, if var1 is a character string subtraction multiplication division logical OR logical AND

Keyword:
$

Meaning:
logical XOR

* / ! &

| ^ % << >>

logical ORa logical XORa modulus operatora left bit shifta right bit shifta

a. Not supported in IGDS.

If var1 is numeric, MicroStation automatically converts var2 or var3 (if present) to numeric if either is a character string. This conversion is performed before the operation specified by keyword is performed. All arithmetic operations are performed in double precision floating point. If var1 is a character string, concatenation is the only possible operation (+ is the only valid keyword). MicroStation automatically converts var2 and var3 (if present) to a string if either is numeric. If var1 is a character register (C#), its associated character count register (N#) is also updated.

15-52

MicroStation 95 Reference Guide

Mathematical, Conversion, and Assignment Statements


If a concatenation operation is performed on a character register (C#), and the result is a string that is longer than 42 characters, its contents are combined with the next register, C#+1, such that C#+1 is undefined and its character count register (N#+1) contains 1 to indicate the combined status. Up to six C# registers can be concatenated to store a string of up to 252 characters. Examples:
SET IO=XUR
SET I1=YUR SET I1= R0 bit SET A1 = i0sm*2 SET FBFDCN=FBFDCN & -17 SET I1 = I3 % I4 SET I1 = I3 << 3 SET I1 = I3 >> 3 ; Multiply by 2 and save ; as floating point ; Turn off Snap Lock ; Remainder of I3/I4 ; Left shift I3 by 3 bits ; Right shift I3 by 3 bits

; Store input point


; Convert from 16 bit to 32

SET C1 = 'This ASCII string was 40 characters long' ; N1=40 SET C1 = C1 + ' but is now 54' SET N1 = 16 ; N1=54. C2 is undefined. ; N2=-1. ; C1="This ASCII string"

CVT
[label:] CVT var1 = var2[, var3, var4]

Descr. Converts between working units and UORs and stores the result in var1. If var1 is a character string, the conversion is from UORs to working units, and var2, var3, and var4 must be numeric. If var1 is numeric, the conversion is from working units to UORs, and var2 must be a character string. When specifying a working units (MU:SU:PU) string for conversion to UORs, the following statements are equivalent:
CVT A0 = '200:5,5000:22,800:8' CVT A0 = '200:5', '5000:22', '800:8'

The UOR values are stored in the next sequential variables after var1. For example, either of the above statements is a short form of the following fragment:
CVT A0 = '200.5' CVT A1 = '5000:22' CVT A2 = '800:8'

To convert a working units string to design plane coordinates, store the UOR results of the CVT statement in A# double precision, floating point registers. Then use SET statements to add the global origin to the UOR result. (Floating point registers are

MicroStation 95 Reference Guide

15-53

15

User Commands

Mathematical, Conversion, and Assignment Statements


recommended to handle the case of a UOR value that is not a 32-bit integerthat is, a value that refers to a point off the design plane.) Likewise, to convert design plane coordinates to a working units string for display, first use SET statements to subtract the global origin. See Examples below. Examples: ; Convert working units to design cube coordinates
CVT SET SET SET ; Convert SET SET SET CVT A0 I0 I1 I2 = = = = '200:5,5000:22,800:8' A0 + GOXUOR A1 + GOYUOR A2 + GOZUOR ; Convert to UORs ; Add global origin

design cube coordinates to working units for display A0 = I0 GOXUOR ; Subtract global origin A1 = I1 GOYUOR A2 = I2 GOZUOR KEY = A0, A1, A2 ; Convert to working units

SQR
[label:] SQR root, var

Descr. Computes the square root of var and stores the result in root. Example SQR A0, I0; Compute square root of I0

SCS
[label:] SCS sine, cosine, angle

Descr. Computes the sine and cosine of angle, where angle is specified in degrees (0-360), and stores the results in sine and cosine, respectively. Example SCS A0, A1, 45; A0=sin(45), A1=cos(45)

ATN
[label:] ATN angle, sine, cosine

Descr. Computes an angle (in degrees, 0-360), given its sine and cosine, and stores the result in angle. The UCM fragment in the example shows the use of an ATN statement to determine the angle of a line. I0, I1 contain the first endpoint, and I2, I3 contain the second endpoint. The angle between the horizontal line passing through the first endpoint and the line is computed and stored in A0. Examples:
SET A1=I2 - I0
SET A2=I3 - I1 ATN A0, A2, A1

; A1 = delta X
; A2 = delta Y ; A0 = angle

15-54

MicroStation 95 Reference Guide

Matrix Statements

Matrix Statements
These statements perform mathematical operations or conversions on matrices:
To:
Perform matrix multiplication or transform series of points. Transpose matrix. Convert rotation matrix to double precision, floating point format. Convert cell transformation matrix to double precision, floating point format.

Use:
MML (page 15-55) MTN (page 15-56) CQM (page 15-56) CCM (page 15-56)

The dimensions of the matrices are determined by the dimensions of the design file. All variables in these statements are arrays that are filled row by row. MicroStation does not verify array size it is the UCMs responsibility to ensure that all arrays are large enough to contain the expected data.

MML
[label:] MML var1, var2, var3, var4

Descr. Performs matrix multiplication (var2 var3) or transforms a series of points and stores the result in var1. If var4 equates to zero, MicroStation is directed to multiply two square matrices. Otherwise, var4 specifies the number of points in the series for transformation. Regardless of the operation, var2 is a double precision floating point array containing a square matrix stored by rows. It is 2 2 (4 values) for a 2D design file or 3 3 (9 values) for a 3D file. For matrix multiplication, var1 and var3 are also double precision floating point arrays containing square matrices and can be the same array. For point transformation, var1 and var3 are double precision integer arrays containing the point coordinates (X1, Y1, X2, Y2, etc. for 2D design files; X1, Y1, Z1, X2, Y2, Z2, etc. for 3D files) and can be the same array. Examples:
MML TMATRX,SMOBUF,TMATRX,0
MML LS.VER(1),TMATRX,LS.VER(1),LS.NVR TMATRX

; Multiply matrices
; Transform line string ; vertices through

MicroStation 95 Reference Guide

15-55

15

User Commands

Matrix Statements

MTN
[label:] MTN var1, var2

Descr. Transposes the matrix in var2 and stores the result in var1. The arrays var1 and var2 contain square matrices (2 2 for a 2D design file and 3 3 for a 3D file) and can be the same. Example MTN TMATRX,TMATRX; Transpose TMATRX

CQM
[label:] CQM var1, var2

Descr. Converts the rotation matrix in var2 to double precision, floating point format and stores the result in var1.
If design file is:
2D 3D

var2 is:
Element rotation angle Quaternion rotation

var1 contains:
2 2 matrix 3 3 matrix

CCM
[label:] CCM var1, var2

Descr. Converts the cell transformation matrix in var2 to double precision, floating point format and stores the result in var1. For a 2D design file, var1 contains a 2 2 matrix. For a 3D file, var1 contains a 3 3 matrix. Example CCM TMATRX,CL.ROT; Convert 2D cell transformation matrix
CCM TMATRX,CL.RT3; Convert 3D cell transformation matrix

15-56

MicroStation 95 Reference Guide

MicroCSL Application Interface Statements

MicroCSL Application Interface Statements


These statements interface UCMs to programs developed with the optional MicroStation Customer Support Library (MicroCSL), that supplements the functionality of MicroStation. A UCM can exchange data with an application. The application uses the MicroCSL routines gr_ucmrcv and gr_ucmsnd to receive and send data.
To:
Start an application with specified parameters. Wait for data from an application.

Use:
TSK (page 15-57) WT (page 15-57)

TSK
[label:] TSK application [, var1varN]

Descr. Starts application with the parameters specified in vars. The parameters are sent to the application as if they are command line arguments. The application calls the MicroCSL routine gr_ucmrcv to receive the data. (See File Naming on page 15-26 for information about how to specify the application.) A WT (page 15-57) statement should follow each TSK statement.

WT
[label:] WT application [,var1varN]

Descr. Waits for data from application. The data is returned in vars. The application calls the MicroCSL routine gr_ucmsnd to send the data. See File Naming on page 15-26 for information about how to specify the application. A WT statement should follow each TSK (page 15-57) statement. Example TSK 'APPS:CALC.EXE', A0, I0, R0; Start "Calc" application
WT 'APPS:CALC.EXE', A1, C0 ; Wait for "Calc" output

MicroStation 95 Reference Guide

15-57

15

User Commands

Database Interface Statements

Database Interface Statements


These statements let UCMs interface to a non-graphic database to which MicroStation is connected:
To:
Read column(s) from linked database row. Write column(s) to linked database row. Add row to database. Delete row from database.

Use:
DBREAD (page 15-58) DBWRITE (page 15-59) DBADD (page 15-59) DBDELETE (page 15-60)

UCMs can access only character and numeric columns. For instance, a UCM might use a DBREAD statement to annotate a drawing with text read from a database or a DBWRITE statement to update a database row with the computed area of a shape. The sample statements in this section refer to the Oracle table Pumps (entity: 1)
Column name:
vendor type flowrate cost mslink

Type:
Char (30) Char (10) Number (10,2) Number (6,2) Number (10)

For more information about database interfaces, see MicroStation and Non-graphical Data in Chapter 11 in the Administrators Guide. Database operators and statements are not supported in VAXbased IGDS.

DBREAD
[label:] DBREAD entity mslink_key column1[ column2 column3 ]

Descr. Reads one or more columns from the linked database row specified by entity and mslink_key into registers. The entity operand identifies the table by name or entity number. A maximum of 31 columns can be read at one time. Character, logical, and date columns are read into the C# character registers beginning with C0 and incrementing for successive columns. Character fields longer than 80 characters are truncated.

15-58

MicroStation 95 Reference Guide

Database Interface Statements


Numeric columns are read into the A# floating point registers beginning with A0 and incrementing for successive columns. Examples:
DBREAD 'Pumps' 4 'vendor'
DBREAD 1 2 'vendor' 'type'

; entity: 1, row: mslink = 4,


; C0=vendor ; entity: 1, row: mslink = 2, ; C0=vendor, C1=type

DBREAD 1 3 'vendor' 'flowrate' 'type' 'cost'; entity: 1, ; row: mslink = 3, C0=vendor, ; A0=flowrate, C1=type, A1=cost

[label:] DBWRITE entity mslink_key column1 value1[ column2 value2]

Descr. Writes one or more values to the specified columns in the linked database row specified by entity and mslink_key. The entity operand identifies the table by name or entity number. There must be a value for each column. A value can be a literal or the contents of a variable. A maximum of 31 columns can be written at one time. MicroStation automatically formats each value to match the data type of the specified column before writing to the column. For example, a real value in a floating point register is converted to an integer by truncation before it is written to an integer column. Refer to the sample table in Database Interface Statements on page 15-58. Examples:
DBWRITE 'Pumps' 2 'vendor' 'Hamilton' 'type' C0
; entity: 1, ; row: MSLINK = 2, vendor = ; "Hamilton", type = contents of C0 DBWRITE ENTITY mslink 'cost' A0 'type' 'reciprocal' ; row: Active ; Entity, cost = contents of A0, ; type = "reciprocal" DBWRITE 1 3 'vendor' C5 'flowrate' '12.5; entity: 1, ; row: MSLINK = 3, ; vendor = contents of C5, ; flowrate = 12.5

DBADD
[label:] DBADD entity mslink_key column1 value1[ column2 value2 ]

Descr. Adds a row to the table specified in entity. The mslink key for the new row is specified in mslink_key. If mslink_key is zero, MicroStation automatically determines

MicroStation 95 Reference Guide

15-59

15

User Commands

DBWRITE

Terminal Control Block (TCB)


the mslink key. There must be a value for each column. A value can be a literal or the contents of a variable. A maximum of 31 columns can be written at one time. MicroStation automatically formats each value to match the data type of the specified column before writing to the column. For example, a real value in a floating point register is converted to an integer by truncation before it is written to an integer column. Refer to the sample table in Database Interface Statements on page 15-58. Example DBADD 'Pumps' 0 'vendor' 'Jackson' 'type' C0 'flowrate' 14.0;
; entity: 1, vendor = "Jackson", ; type = contents of C0, ; flowrate = 14.0

DBDELETE
[label:] DBDELETE entity mslink_key

Descr. Deletes the row specified by mslink_key from the table specified in entity. Refer to the sample table in Database Interface Statements on page 15-58. Example DBDELETE 'Pumps' 7; Delete row with mslink key 7 from Pumps

Terminal Control Block (TCB)


The TCB (Terminal Control Block) is a global data area of memory in which MicroStation stores all settings and other data that describes its status. See Categories of TCB Variables on page 15-61 for a list of the types of information stored in TCB variables.

How Applications Can Modify TCB Variables


Programmers can modify TCB variables as follows: UCMs can modify TCB variables directly with SET (see page 15-52), but MicroStation does not perform error checking, and improper values can cause unpredictable results. For this reason, it is strongly recommended that UCMs modify TCB variables by simulating MicroStation key-ins with KEY (see page 15-49) whenever possible. MDL applications can access TCB variables directly by including tcb.h; tcb is an MDL built-in variable. Use of the mdlParams_getActive and mdlParams_setActive functions is

15-60

MicroStation 95 Reference Guide

Categories of TCB Variables


recommended, however, to guarantee valid values and make applications compatible across releases of MicroStation. MicroCSL applications can access TCB variables directly through the rdtcbasc and wttcbasc routines.

Categories of TCB Variables


There are TCB variables for the view configuration, active settings such as color and lock status, the last data point or tentative point entered, and UCM registers. User Command Registers (see page 15-62) General-purpose use. Type 9 Variables (see page 15-64) Saved in the type 9 element of the design file header when FILEDESIGN is executed (File menu/Save Settings). Type 66 variables (see page 15-80) Saved in the extended TCB element (type 66, level 9) in the design file when FILEDESIGN is executed (File menu/Save Settings). Miscellaneous variables (see page 15-83) Cannot be saved in the design file or otherwise stored between sessions. DGNBUF variables (see page 15-102) Information about the most recently created or located element.

Data types
These are the data types:
Type:
byte word int dpfp char rad50 unit uword

Description:
8 bits of data 2 bytes of data 4 bytes, double precision integer 8 bytes, double precision, floating point character 3 character, Radix-50 data (see below) 4 bytes, unsigned double precision integer unsigned 2 bytes

MicroStation 95 Reference Guide

15-61

15

User Commands

User Command Registers

Radix-50 Character Set


The Radix-50 character set is a special character set in which three characters can be encoded and packed into one word. MicroStation uses Radix-50 to store certain TCB variables such as file names and extensions, cell names, and tutorial names. Radix-50 is a subset of ASCII that defines only upper case letters and just three special characters, whose octal values are as follows:
Character:
space AZ $ . (Unassigned) 09

Radix-50 Value (Octal):


000 001032 033 034 035 036047

These Radix-50 characters are encoded by the formula: (a * 50 + b) * 50 + c) a, b and c represent octal code values of the three Radix-50 characters.

MDL has two built in functions (mdlCnv_fromR50ToAscii and mdlCnv_fromAsciiToR50) and MicroCSL provides two routines (rd2asc and asc2rd) to convert between ASCII and Radix-50.

User Command Registers


A set of registers is included in the TCB for general purpose use by applications, particularly UCMs:
TCB Name:
A0A15

Definition:
double precision floating point registers character scratch registers error indicator menu and tutorial field ID number

Type:
dpfp

C0C15 ERR FNO

40 char word word

15-62

MicroStation 95 Reference Guide

User Command Registers


TCB Name:
I0I15 K0 KEY M0 MSG N0N15

Definition:
double precision integer registers number of characters in KEY0 key-in number of characters in MSG message registers with number of characters in C0 C15 number of characters in KEY integer scratch registers current view number x cursor coordinate x UOR coordinate y cursor coordinate y UOR coordinate z UOR coordinate

Type:
int word 42 char word 42 char word

NUM R0R31 VNO XDT XUR YDT YUR ZUR

word word word word int word int int

MicroStation 95 Reference Guide

15-63

15

User Commands

Type 9 Variables

Type 9 Variables
A design file has one (and possibly two) type 9 header elements that contain settings specific to the file. When MicroStation opens a design file, the type 9 element(s) are extracted and used to initialize the TCBs type 9 variables. These variables can be rewritten to the header elements collectively with the FILEDESIGN command (File menu/Save Settings) or individually with the UCM STO operator or the MDL mdlParams_storeType9Variable built-in function. The TCB offset is required to save a variable individually. The offset is listed with each variable used by MicroStation. Saving individual variables is rarely necessary and is discouraged because of the potential for design file corruption.

A
TCB Name:
ACTANG ACTLEV ADPATC ADPCFO ADPCTC ADPDFO ADPDTC ADPEFA

Sets:
active angle active level active line terminator font number for origin terminator origin terminator font number for diameter terminator diameter terminator English fractional accuracy Bit Settings: None: Display decimal to nearest integer 0 & 7: Display decimal to nearest .1 1 & 7: Display decimal to nearest .01 2 & 7: Display decimal to nearest .001 3 & 7: Display decimal to nearest .0001 4 & 7: Display decimal to nearest .00001 5 & 7: Display decimal to nearest .000001 6 & 7: Display decimal to nearest .0000001 7: Display decimal to nearest .00000001 0: Display fraction to nearest 1/2 1: Display fraction to nearest 1/4 2: Display fraction to nearest 1/16 3: Display fraction to nearest 1/32 4: Display fraction to nearest 1/64

Type:
dpfp byte byte byte byte byte byte byte

Offset:
1096 1178 1413 1416 1417 1418 1419 1174

15-64

MicroStation 95 Reference Guide

Type 9 Variables
TCB Name:
ADPFMT

Sets:
angle readout specification Value: 0: Decimal degrees 1: Degrees, minutes, seconds dimension level No bits set: Active level Bits 163 set: Specific level selected metric fractional accuracy Bit Settings: None: Display decimal to nearest integer 0 & 7: Display decimal to nearest .1 1 & 7: Display decimal to nearest .01 2 & 7: Display decimal to nearest .001 3 & 7: Display decimal to nearest .0001 4 & 7: Display decimal to nearest .00001 5 & 7: Display decimal to nearest .000001 6 & 7: Display decimal to nearest .0000001 7: Display decimal to nearest .00000001 0: Display fraction to nearest 1/2 1: Display fraction to nearest 1/4 2: Display fraction to nearest 1/16 3: Display fraction to nearest 1/32 4: Display fraction to nearest 1/64 linear dimensioning modes Bit Settings: 0 & 1 clear: Parallel to view axis 0 set, 1 clear: Parallel to design plane axis 0 clear, 1 set: Parallel to element 0 & 1 set: Parallel to arbitrary axis 2 set, 3 clear: Auto placement mode 2 set, 3 set: Semi-manual placement mode 2 clear, 3 set: Manual placement mode 4 clear: Extension lines off 4 set: Extension lines on 5 set, 6 clear: Left justification 5 clear, 6 set: Center justification 7 clear: Label angular as length 7 set: Label angular as degrees font number for stroke terminator stroke terminator

Type:
byte

Offset:
1506

ADPLEV

byte

1176

ADPMFA

byte

1175

ADPMOD

byte

1177

ADPOFO ADPOTC

byte byte

1414 1415

MicroStation 95 Reference Guide

15-65

15

User Commands

Type 9 Variables
TCB Name:
ADPPAR

Sets:
dimensioning settings Bit Settings: 0 clear: Primary system: English 0 set: Primary system: metric 1 clear: Display in single mode 1 set: Display in dual mode 2 clear: Tolerance generation off 2 set: Tolerance generation on 3 clear: Plus/minus tolerancing 3 set: Limit tolerancing 4 & 5 clear: Text parallel & above dim. line 4 set, 5 clear: Text parallel & embedded in dim. line 4 & 5 set: Text horizontal & embedded in dim. line 6 clear: Mechanical 6 set: AEC dimension display format measurement (bits 02) Bit Settings: 02 clear: Master & sub-units 0 set: Master units 0 & 1 set: Working units 2 clear: Decimal display 2 set: Fraction display labeling (bits 35) Bit Settings: 3 clear: Master units only 3 set: Master & sub-units 4 clear: Label generation off 4 set: Label generation on 5 clear: Delimiter generation off 5 set: Delimiter generation on

Type:
byte

Offset:
1179

ADPREF

byte

1181

ADPRS2

coordinate readout decimal accuracy (bits 02) Bit Settings: 02 clear: 1/10,000 0 set: Integer 1 set: 1/10 0 & 1 set: 1/100 2 set: 1/1000

byte

1507

15-66

MicroStation 95 Reference Guide

Type 9 Variables
TCB Name: Sets:
fractional accuracy (bits 37) Bit Settings: 37 clear: 1/2 3 set: 1/4 3 & 4 set: 1/8 35 set: 1/16 36 set: 1/32 37 set: 1/64 ADPSFO ADPTLO ADPTSR ADPTUP ADRES2 font number for active line terminator lower tolerance text height (if ADPTSR=0, use active text height and width) upper tolerance dimension display accuracy decimal accuracy (bits 02) Bit Settings: 02 clear: 1/10,000 0 set: Integer 1 set: 1/10 0 & 1 set: 1/100 2 set: 1/1000 fractional accuracy (bits 37) Bit Settings: 37 clear: 1/2 3 set: 1/4 3 & 4 set: 1/8 35 set: 1/16 36 set: 1/32 37 set: 1/64 ANGFMT angle readout format Value: 0: Decimal degrees 1: Degrees, minutes, seconds active ACS type azimuth true north angle byte 1159 byte int int int byte 1412 1424 1420 1428 1180

Type:

Offset:

AUXTYP AZIANG

word dpfp

1508 1166

MicroStation 95 Reference Guide

15-67

15

User Commands

Type 9 Variables

CL
TCB Name:
CAFONT CANODE CELFEX

Setting:
active font number highest node number + 1 rad50 cell library extension rad50 cell library name rad50 cell library device cell library directory cell library version number cell library ending byte cell library ending sector character height in UORs character width in UORs miscellaneous flag word Bit Settings: 0: Enable user help mode 1: Boresite Locka 2 clear: Project snap modea 2 set: Keypoint snap mode 3: ACS Plane Lock

Type:
byte uword rad50

Offset:
1158 1258 1242

CELFIL CELLDS CELUIC CELVER CFBYTE CFSECT CHHGT CHWID CNTRL1

3rad50 rad50 word word word word uint uint word

1236 1246 1244 1248 1252 1250 1144 1148 1504

15-68

MicroStation 95 Reference Guide

Type 9 Variables
TCB Name:
CONTRL

Setting:
locks and mode control word Bit Settings: 0: Grid Lock 1: Unit Lock 2: Reserved 3: Point/ stream mode 4: Delayed patterning 5: Display aspect ratio 67: Reserved 8: Inhibit cf, st, and pr messages 9: Inhibit er messages except for fatal 1013: Reserved 14: Display window altered 15: Reserved contour Z high, 2D contour Z low, 2D design file low/ high range in UORs database record delete flag not used by MicroStation not used by MicroStation not used by MicroStation not used by MicroStation not used by MicroStation

Type:
word

Offset:
0

CONZHI CONZLO DFRANG

int int 6 int

992 980 1188

DMRFLG

byte

1409

DMRLDS DMRSEX DMRSFL DMRUIC DMRVER

rad50 rad50 3 rad50 word word

N/A N/A N/A N/A N/A

MicroStation 95 Reference Guide

15-69

15

User Commands

Type 9 Variables
TCB Name:
EU.MU

Setting:
number of subunits/master unit number of positional units/sub-unit not used by MicroStation miscellaneous locks and controls Bit Settings: 0: Solid/hole, set = hole 1: Scale Lock 2: Text Node Lock 3: Angle Lock 4: Snap Lock 5: Text mirroring 6: 2D/3D design file, set = 3D 7: 2D/3D cell library, set = 3D 8: Lines with width 9: Clip fence selection 10: Graphic Group Lock 11: Level Lock 12: Assign active attribute 14: Attribute search enabled (fence contents) 15: Overlap fence selection grids/ reference grid graphic group base number

Type:
int

Offset:
1084

EU.UOR

int

1088

FBFDC2 FBFDCN

word word

N/A 1186

G.RG GGBASE

word uword

14 1254

15-70

MicroStation 95 Reference Guide

Type 9 Variables
TCB Name:
GOXUOR

Setting:
global origin x of design plane in UORs global origin y of design plane in UORs global origin z of design plane in UORs highest graphic group number + 1 initial active file no. active element properties Bit Settings: 03 clear: Primary class 0, 23 clear, 1 set: Construction class 47: Reserved 8: Not locked 9: New 10: Modified 11: Database attributes present 12: Oriented relative to screen 13: Non-planar 14: Nonsnappable 15: Hole (not solid)

Type:
dpfp

Offset:
1212

GOYUOR

dpfp

1220

GOZUOR

dpfp

1228

GRAFIC

word

1160

IACTFL IDPROP

byte word

1411 1182

MicroStation 95 Reference Guide

15-71

15

User Commands

Type 9 Variables
TCB Name:
IDSYMB

Setting:
active element symbology Bit Settings: 02: Line style 37: Line weight 815: Color database linkage mode Value: 0: New Linkage Mode 1: Information Linkage Mode 2: Duplicate Linkage Mode Negative: Absolute value indicates the number of empty (null) DMRS linkages appended to newly created cell headers

Type:
word

Offset:
1184

LKGNMD:

byte

1408

a. Bit 2 of the CNTRL1 variable is ignored if TCB->snapOverride 0.

MT
TCB Name:
MAMADF MAMADV MAMAEX MAMAUC MAMAVR MU.CHR

Setting:
not used by MicroStation not used by MicroStation not used by MicroStation not used by MicroStation not used by MicroStation master unit name ASCII

Type:
3 rad50 rad50 rad50 word word 2 char

Offset:
N/A N/A N/A N/A N/A 1092

15-72

MicroStation 95 Reference Guide

Type 9 Variables
TCB Name:
MU.DF

Setting:
number of master units / design plane node number base active line length active line spacing reference file control flag not used by MicroStation not used by MicroStation not used by MicroStation not used by MicroStation not used by MicroStation not used by MicroStation not used by MicroStation Angle Lock roundoff value Scale Lock roundoff value Unit Lock roundoff UORs sub-unit name ASCII system class bit map

Type:
uint

Offset:
1080

NNBASE NODLLN NODSPA RFCNTL RFFEX1 RFFEX3 RFFIL1 RFFIL3 RFLDS1 RFLDS3 RFLEV1 RFLEV3 RFSCT1 RFSCT3 RFUIC1 RFUIC3 RFVER1 RFVER3 RNDANG RNDSCL RNDUNT SU.CHR SYSCL

uword byte int byte rad50 3 rad50 rad50 3 word word word word dpfp dpfp dpfp 2 char word

1256 1156 1152 1163 N/A N/A N/A N/A N/A N/A N/A 1104 1136 2 1094 1274

MicroStation 95 Reference Guide

15-73

15

User Commands

Type 9 Variables
TCB Name:
TNJUST

Setting:
text node justification Value: 0: Left/top 1: Left/center 2: Left/bottom 3: Left margin/ top 4: Left margin/ center 5: Left margin/ bottom 6: Center/top 7: Center/ center 8: Center/ bottom 9: Right margin/top 10: Right margin/center 11: Right margin/bottom 12: Right/top 13: Right/ center 14: Right/ bottom tentative point mode Value: 0: Locate mode 1: Measure delta 2: Measure angle (3 points) 3: Measure angle (2 points) 4: Measure view delta 5: Locate mode with aux coordinate 6: Measure delta with aux coordinate

Type:
byte

Offset:
1157

TPMODE

byte

1164

15-74

MicroStation 95 Reference Guide

Type 9 Variables
TCB Name:
TPSMDE

Setting:
tentative point sub-mode angle mode value (bits 0-3) Value: 0: Conventional 1: Azimuth 2: Bearing bits 47: Not used by MicroStation not used by MicroStation text justification Value: 0: Left/top 1: Left/center 2: Left/bottom 35: Unused 6: Center/top 7: Center/ center 8: Center/ bottom 911: Unused 12: Right/top 13: Right/ center 14: Right/ bottom

Type:
byte

Offset:
1165

TXJUST

byte

1162

UZ

TCB Name:
U.G UCASC UCBYT UCDPF

Setting:
UORs/grid UCM ASCII array UCM byte array UCM dpfp array

Type:
int 32 char 32 byte 4 dpfp

Offset:
10 1290 1290 1290

MicroStation 95 Reference Guide

15-75

15

User Commands

TUTVW:

byte

N/A

Type 9 Variables
TCB Name:
UCDPV

Setting:
UCM VAX format double precision array UCM integer array UCM Rad50 array UCM word array Rad50 UCM index file extension UCM index file disk Rad50 UCM index file name UCM index file directory UCM index file version view 1view 8 active Z view 1view 8 conversion factor DITS/ UORs view 1view 8 extents

Type:
4 dpfp

Offset:
1290

UCINT UCRAD UCWRD UCXEXT

8 int rad50 16 word rad50

1290 1290 1290 1282

UCXLDS UCXLIB UCXUIC UCXVER VT1ACZ VT8ACZ VT1CNV VT8CNV

rad50 3 rad50 word word int dpfp

1286 1276 1284 1288 132, 250, 368 124, 242, 360

VT1EXT VT8EXT

3 uint

40, 158, 276

15-76

MicroStation 95 Reference Guide

Type 9 Variables
TCB Name:
VT1FLG VT8FLG

Setting:
view 18 display flags Bit Settings: 0: Fast curve, arc ellipse 1: Fast text 2: Fast font 3: Line weight 4: Patterns 5: Text nodes 6: Enter data underlines 7: On/off (open/closed) 8: Delay/ update 9: Grid 10: Level symbology 11: Points 12: Line constructs 13: Dimensioning 14: Fast cell 15: Def/undef view 1view 8 level bit maps view 1view 8 origins view 1view 8 transformation matrices not used by MicroStation not used by MicroStation not used by MicroStation not used by MicroStation not used by MicroStation ACS origin ACS transformation matrices

Type:
word

Offset:
18, 136, 254

VT1LEV VT8LEV VT1ORG VT8ORG VT1TRN VT8TRN VTAACZ VTACNV VTAEXT VTAFLG VTALEV VTAORG VTATRN

4 word 3 int 9 dpfp

20, 138, 256 28, 146, 264 52, 170, 288

int dpfp 3 uint word 4 word 3 int 9 dpfp

N/A N/A N/A N/A N/A 1090 1114

MicroStation 95 Reference Guide

15-77

15

User Commands

Type 9 Variables
TCB Name:
VTDACZ VTDCNV VTDEXT VTDFLG VTDLEV VTDORG VTDTRN VWFUL1

Setting:
not used by MicroStation not used by MicroStation not used by MicroStation not used by MicroStation not used by MicroStation not used by MicroStation not used by MicroStation view number in full mode screen 1 view number in full mode screen 2

Type:
int dpfp 3 uint word 4 word 3 int 9 dpfp byte

Offset:
N/A N/A N/A N/A N/A N/A N/A 16

VWFUL2

byte

17

15-78

MicroStation 95 Reference Guide

Type 9 Variables
TCB Name:
VWTABL

Setting:
view parameter tables (59 words per view) Parameter(s): VWACZ (equivalent to VTnACZ) VWCNV (equivalent to VTnCNV) VWFLG (equivalent to VTnFLG) VWLEV (equivalent to VTnLEV) VWTRN (equivalent to VTnTRN) VWXDL, VWYDL, VWZDL (equivalent to VTnEXT) VWXOR, VWYOR, VWZOR (equivalent to VTnORG)

Type:

Offset:
18, 136, 254

8 int 8 dpfp 8 word 8 word 9 dpfp 8, 8, 8 uint 8, 8, 8 int

XAXSCL YAXSCL ZAXSCL

x-axis scale factor y-axis scale factor z-axis scale factor

dpfp dpfp dpfp

1112 1120 1128

MicroStation 95 Reference Guide

15-79

15

User Commands

Type 66 variables

Type 66 variables
Type 66 variables are saved in the MicroStation extended TCB element (type 66, level 9) (see page 18-61) when FILEDESIGN is executed.
TCB Name:
ACTAB ACTPNT ALTAB ALTSCL ANRDOT APANG APANG2 APCOLS APROWS APTAB APTOL APTSCL AXLANG AXLORG CELNAM

Setting:
active cell name active point active line terminator cell name line terminator scale factor angle readout accuracy active pattern angle (rows) active pattern angle (columns) active pattern column spacing active pattern row spacing active pattern cell name active pattern tolerance active pattern scale factor Axis Lock angle increment Axis Lock start angle cell file name

Type:
2 rad50 2 rad50 2 rad50 dpfp byte dpfp dpfp int int 2 rad50 int dpfp dpfp dpfp 128 char

15-80

MicroStation 95 Reference Guide

Type 66 variables
TCB Name:
EXTLCK

Setting:
Extended locks bit settings as follows: 0: Axis Lock 1: Auxiliary input (stereoplotter, PC only) 2: Coordinate display 3: Automatic panning with tablet 4: Temporarily override Axis Lock 5: Stretch cells in fence 6: Isometric grid 7: Isometric pointer 8: Full view pointer 9 & 10 clear: Top isometric plane 9 set, 10 clear: Left isometric plane 9 clear, 10 set: Right isometric plane 9 & 10 set: All isometric planes 1112: Reserved 13: Single shot viewing command active 14: Single shot only command active 15: Single shot drawing command active 16: ACS Plane Snap Lock 17: Data points projected perpendicular to ACS plane 18: Active fill 19: Isometric Lock 20: Reserved 21: Intersection snap 22: Association Lock 23: Use Shared Cells 24: Void fence selection 25: Fast dynamics 26: Snappable patterns 2731: Reserved

Type:
int

MicroStation 95 Reference Guide

15-81

15

User Commands

Type 66 variables
TCB Name:
EXVWFL

Setting:
Extended view flags bit settings as follows: 0: Filled shapes, text, lines with width 1: Raster text display (Macintosh only) 2: ACS triad display 35: Reserved 6: Camera 79 clear: Wireframe display mode 7 set, 89 clear: Cross-section display mode 7 & 9 clear, 8 set: Wiremesh display mode 7 & 8 set, 9 clear: Hidden line display mode 7 & 8 clear, 9 set: Filled hidden line display mode 7 & 9 set, 8 clear: Constant shaded display mode 7 clear, 89 set: Smooth shaded display mode 79 set: Phong shaded display mode 10: Background display 11: Reference file clipping boundary display 12: Fast reference file clipping boundary display 13: Depth cueing 14: Dynamic update display 1531: Reserved grid aspect ratio (Y/X) snap divisor

Type:
word

GRDRAT: KEYPNT

dpfp word

15-82

MicroStation 95 Reference Guide

Miscellaneous variables

Miscellaneous variables
Miscellaneous TCB variables are initialized each time a design file is opened. They cannot be saved in the design file or otherwise stored between sessions.

A-C
TCB Name:
ACCSEC ACORGF ACSDEF ACSNAM ADPSHS ADPTTR ALCSEC AMBINT AMBLGT ANGBYT

Setting:
active cell starting sector, byte active cell origin flag (bit 0) ACS type for definition active ACS name dimension stack offset dimension tolerance scale factor line terminator sector, byte ambient light intensity ambient light status (on/off) number of bytes defining element rotation Value: 4: Number of bytes in 2D 16: Number of bytes in 3D starting sector, byte of active pattern cell minimum arc array column distance arc radius arc stroking tolerance array fill angle rectangular array number of columns

Type:
2 word word byte 2 rad50 int dpfp 2 word dpfp int word

APCSEC ARCMIN ARCOLD ARCRAD ARCTOL ARFILA ARNCOL

2 word int dpfp dpfp dpfp dpfp word

MicroStation 95 Reference Guide

15-83

15

User Commands

Miscellaneous variables
TCB Name:
ARNITM ARNROW ARROT ARROWD AUXXOR AUYXOR AUZXOR BACKFL BOWFNT

Setting:
polar array number of columns rectangular array number of rows polar array rotate rectangular array row distance auxiliary input x auxiliary input y auxiliary input z view background filename adjacent dimension terminator replacement font adjacent dimension terminator replacement symbol B-spline order cell library index file name cell file handle user specified x origin of new cell user specified y origin of new cell user specified z origin of new cell chamfer distance 1 chamfer distance 2 tolerance for automatic complex chain/shape creation construction line distance Clipboard rotation (Macintosh only) Clipboard paste scale x (Macintosh only) Clipboard paste scale y (Macintosh only)

Type:
word word byte dpfp int int int char byte

BOWSYM

byte

BSPORD CDXNAM CELHND CELORX CELORY CELORZ CHAMD1 CHAMD2 CHNTOL

byte 128 char int int int int dpfp dpfp dpfp

CLINED CLPROT CLPXSC

dpfp dpfp dpfp

CLPYSC

dpfp

15-84

MicroStation 95 Reference Guide

Miscellaneous variables
TCB Name:
CMDCLS

Setting:
class of active command 1: Placement 2: Viewing 3: Fence 4: Parameters 5: Locks 6: UserCommand 7: Manipulation 8: Show 9: Plot 10: Newfile 11: Measure 12: Input 13: Celllib 14: Filedesign 15: Compress 16: Reference 17: Database 18: Dimension 19: Locate 20: Tutclass 21: Workingset 22: Elementlist 23: Undo 24: Subprocess 25: Viewparam 26: Viewimmed 27: Windowman 28: Dialogman

Type:
word

MicroStation 95 Reference Guide

15-85

15

User Commands

Miscellaneous variables
TCB Name:
CMDSRC

Setting:
source of active command 400: FROM_KEYBOARD 401: FROM_CMDFILE 402: FROM_TUTORIAL 403: FROM_APPLICATION 404: FROM_UCM 405: TABLET_MENU 406: SCREEN_MENU 407: FUNCKEY_MENU 408: CURSOR_BUTTON_ MENU 409: PULLDOWN_MENU 410: CONTROL_STRIP_ME NU 411: HIERARCHICAL_MEN U 413: WINDOW_ICON 414: TOOL BOX_MENU 415: FROM_STARTUP 416: FROM_DIALOG 417: FROM_PROCESS 418: FROM_MDL 419: FROM_PRDFPI offset to located complex component cone radius 1 (top) cone radius 2 (bottom) database multi-row confirmation mode copy/move parallel distance current graphic groupplacement Precision Input settings box Angle field active command ID

Type:
word

CMPOFF CONER1 CONER2 CONFRM CPRDIS CUGRAF CURANG

uint dpfp dpfp word dpfp word dpfp

CURCMD

int

15-86

MicroStation 95 Reference Guide

Miscellaneous variables
TCB Name:
CURDIS

Setting:
Precision input settings box Distance field Precision Input settings box DX field Precision Input settings box DY field Precision Input settings box DZ field sector number of current element in design file Precision Input settings box X field Precision Input settings box Y field Precision Input settings box Z field offset into sector of current element in design file file number of current element current screen if single monitor

Type:
dpfp

CURDLX CURDLY CURDLZ CUREBL

dpfp dpfp dpfp word

CURPSX CURPSY CURPSZ CUREBY

dpfp dpfp dpfp word

CUREFL CURSCR

word byte

DG
TCB Name:
DASTYP: DBCTRL DBFORM DCTCHS DFBYTE DFSECT DGNFEX DGNFIL

Setting:
displayable attribute type database descriptors database forms mode terminal type design file ending byte design file ending sector design file extension design file name

Type:
byte uint word word word word rad50 3 rad50

MicroStation 95 Reference Guide

15-87

15

User Commands

Miscellaneous variables
TCB Name:
DGNHND DGNNAM DIGTRN DIMCEN

Setting:
design file handle design file name digitizer transformation dimension center mark size

Type:
int 128 char 12 dpfp int

15-88

MicroStation 95 Reference Guide

Miscellaneous variables
TCB Name:
DIMCMD

Setting:
current dimensioning command Value: Command 0: None 1: DIMENSION SIZE ARROW 2: DIMENSION SIZE STROKE 3: DIMENSION LOCATION SINGLE 4: DIMENSION LOCATION STACKED 5: DIMENSION ANGLE SIZE 6: DIMENSION ARC SIZE 7: DIMENSION ANGLE LOCATION 8: DIMENSION ARC LOCATION 9: DIMENSION ANGLE LINES 10: DIMENSION ANGLE X/Y 11: DIMENSION RADIUS 12: DIMENSION DIAMETER POINT 13: DIMENSION DIAMETER PARALLEL 14: DIMENSION DIAMETER PERPENDICULAR 15: DIMENSION LINEAR 16: DIMENSION ORDINATE 17: DIMENSION RADIUS EXTENDED 18: DIMENSION DIAMETER EXTENDED 19: DIMENSION CENTER dimension color + 1 (0 = Active)

Type:
word

DIMCOL

byte

MicroStation 95 Reference Guide

15-89

15

User Commands

Miscellaneous variables
TCB Name:
DIMFNT DIMMAR DIMSCL DIMTMP

Setting:
dimension font + 1 (0 = Active) dimension margin dimension scale dimension template Int: Bit Settings: 02: First terminator index 35: Left terminator index 68: Right terminator index 911: Adjacent terminator indexa 1214: Pre dimension symbol index 1618: Post dimension symbol indexb 15: Stack dimensions 19: Arc accent above dimension 20: Left witness line 21: Right witness line 22: Vertical dimension text 23: Vertical text when horizontal will not fit 24: Center mark (radial dimensioning only) 2531: Reserved

Type:
byte dpfp dpfp 24 int: 1 per command

15-90

MicroStation 95 Reference Guide

Miscellaneous variables
TCB Name:
DIMTXT

Setting:
dimension delimiter characters DIMTXT(1): Dimension prefix DIMTXT(2): Dimension suffix DIMTXT(3): Tolerance prefix DIMTXT(4): Tolerance suffix DIMTXT(5): Upper dimension prefix DIMTXT(6): Upper dimension suffix DIMTXT(7): Lower dimension prefix DIMTXT(8): Lower dimension suffix dimension weight + 1 (0 = Active) locate tolerance byte number of element in display sector number of element in display dimension text color + 1 (0 = Active) dimension text weight + 1 (0 = Active) not used by MicroStation enter data field character block of next element in design file offset of next element extended memory to reserve for applications (KB) active entity database entity number

Type:
8 char

DIMWGT DITTOL DSPBYT DSPSEC DTXCOL DTXWGT

byte byte word word byte byte

DYNAMC EDFCHR ELEBLK ELECNT EMMSIZ

word byte word word word

ENTITY

word

MicroStation 95 Reference Guide

15-91

15

User Commands

Miscellaneous variables
TCB Name:
EXDMFL

Setting:
extended dimension flags Bit Settings: 0: Join external dimensions 1: Add box around dimension text 2: Semi-automatic text placement mode 3: Include leading zeros 4: Include trailing zeros 5: Substitute comma for decimal point 6: Include capsule around dimension text 7: Superscript least significant digit 8: Round least significant digit 9: Omit leading delimiter 10: Color override 11: Line weight override 12: Text color override 13: Text weight override 14: Font override 15: Level override 16: Text size override 17: IGDS-compatible dimensions 18 & 19 clear: Open arrowhead 18 set, 19 clear: Filled arrowhead 18 clear, 19 set: Closed arrowhead 20: Reference file units 21: Relative dimension line 22: Underline text 2331: Reserved extend distance

Type:
int

EXTDIS

dpfp

15-92

MicroStation 95 Reference Guide

Miscellaneous variables
TCB Name:
FENCE FENPTS

Setting:
number of fence vertices array of fence vertices (max 101 points/100 sides) fence range (x,y,z) lowhigh view number containing fence file search mask (obsoletesee FLMASK) Bit Settings: 0: Active design file 131: First 31 attached reference files fillet radius file search mask Bit Settings: 0: Active design file 1255: Attached reference files flashbulb intensity flashbulb status (on/ off) font library bit map terminal font bit map font library name

Type:
word 202 int

FENRNG FENVW FILMSK

6 int byte int

FILRAD FLMASK

dpfp 8 int

FLSINT FLSLGT FNTLBM FNTTRM FNTNAM

dpfp int 8 word 8 word 128 char

MicroStation 95 Reference Guide

15-93

15

User Commands

Miscellaneous variables
TCB Name:
GETCLS

Setting:
command class returned to UCM GET 1: Placement 2: Viewing 3: Fence 4: Parameters 5: Locks 6: UserCommand 7: Manipulation 8: Show 9: Plot 10: Newfile 11: Measure 12: Input 13: Celllib 14: Filedesign 15: Compress 16: Reference 17: Database 18: Dimension 19: Locate 20: Tutclass 21: Working set 22: Elementlist 23: Undo 24: Subprocess 25: Viewparam 26: Viewimmed 27: Windowman 28: Dialogman

Type:
word

15-94

MicroStation 95 Reference Guide

Miscellaneous variables
TCB Name:
GETCMD GETSRC

Setting:
command ID returned to UCM GET command source returned to UCM GET 400: FROM_KEYBOARD 401: FROM_CMDFILE 402: FROM_TUTORIAL 403: FROM_APPLICATION 404: FROM_UCM 405:TABLET_MENU 406:SCREEN_MENU 407:FUNCKEY_MEN U 408:CURSOR_BUTTO N_MENU 409: PULLDOWN_MENU 410:CONTROL_STRIP _MENU 411:HIERARCHICAL_ MENU 413:WINDOW_ICON 414:TOOL BOX_MENU 415: FROM_STARTUP 416: FROM_DIALOG 417: FROM_PROCESS 418: FROM_MDL 419: FROM_PRDFPI

Type:
int word

a. In the DIMTMP variable, for bits 9-11, the terminator type is set as follows: Index: Terminator type 0: None 1: Arrowhead 2: Stroke 3: Origin 4: Dot b. In the DIMTMP variable, for bits 1618, the symbol type is set as follows Index: Symbol type 0: None 1: Radius 2: Diameter

MicroStation 95 Reference Guide

15-95

15

User Commands

Miscellaneous variables

HP
TCB Name:
HELPMD INDYNM IXUOR1 IXUOR2 IXUOR3 IXUOR4 IYUOR1 IYUOR2 IYUOR3 IYUOR4 IZUOR1 IZUOR2 IZUOR3 IZUOR4 LOCBSU LOCBSV LOCEND LOCMLN LOCORG LOCPOS LOCPNT

Setting:
help mode in dynamics flag scratch design point 1 (x) scratch design point 2 (x) scratch design point 3 (x) scratch design point 4 (x) scratch design point 1 (y) scratch design point 2 (y) scratch design point 3 (y) scratch design point 4 (y) scratch design point 1 (z) scratch design point 2 (z) scratch design point 3 (z) scratch design point 4 (z) located B-spline u parameter located B-spline v parameter located segment endpoint located multi-line number located segment origin file position of located element point on located element

Type:
word byte int int int int int int int int int int int int dpfp dpfp 3 dpfp int 3 dpfp uint 3 dpfp

15-96

MicroStation 95 Reference Guide

Miscellaneous variables
TCB Name:
LOCSEG LOCTBY LOCTSC LOCTYP LOCVRT LSCANB LSCANS LSTCLS LSTCMD LSTSRC LSTVW LSTXOR LSTYOR LSTZOR MAXPOL MAXREF MLENAN MLENCP

Setting:
located segment number located component byte located component sector type of located element closest located vertex locate/snap byte pointer locate/snap sector pointer last parsed class last parsed command last parsed source last point entered, view last point entered, X last point entered, Y last point entered, Z maximum polygon size (rendering) maximum number of reference files multi-line endpoint angle multi-line endpoint cap symbology (see MLPRSM) multi-line flag multi-line fill color multi-line midpoint cap symbology (see MLPRSM) multi-line number of lines multi-line origin angle multi-line origin cap symbology (see MLPRSM)

Type:
int word uword byte int word word word long word byte int int int int word dpfp int

MLFLAG MLFLCL MLMDCP

word byte int

MLNLIN MLORAN MLORCP

byte dpfp int

MicroStation 95 Reference Guide

15-97

15

User Commands

Miscellaneous variables
TCB Name:
MLPRDS MLPRSM

Setting:
multi-line component offsets multi-line component symbologies Each Int Bit Settings: 02: Line style 37: Line weight 815: Color 16: Line style override 17: Line weight override 18: Color override 19: Inner arc cap 20: Outer arc cap 21: Line cap 2223: Reserved 2430: Level 31: Construction class active entity MSLINK key field MicroStation version number maximum grid points per view maximum grid references per view number of axes in file (2 or 3) number of physical screens offset for cell origins offset for cell rotations offset for element origin offset for text elements

Type:
16 int 16 int

MSLINK MSVER MXGRDP MXGRDR NDICES NUMSCR OF.CLO OF.CLR OF.ELO OF.TXN

int word word word word byte word word word word

15-98

MicroStation 95 Reference Guide

Miscellaneous variables
TCB Name:
OUTFLG

Setting:
output flags Bit Settings: 01: Reserved 2: Snapped element highlighted 3: Allow UCM to get command selection 4: Inhibit element display requests 5: Reserved 6: Inhibit output to design file 715: Reserved not used by MicroStation not used by MicroStation points between number of bytes in point definition point distance polygon edges polygon radius segment number of projected point view number of projected point x UOR projected point y UOR projected point z UOR projected point properties mask for searches properties value for searches

Type:
word

PCOLOR PERSP PNTBET PNTBYT PNTDIS POLEDG POLRAD PRJSEG PRJVW PRJXOR PRJYOR PRJZOR PRPMSK PRPVAL

3 word 8 dpfp word word dpfp word dpfp byte byte int int int word word

MicroStation 95 Reference Guide

15-99

15

User Commands

Miscellaneous variables

RW
TCB Name:
RECORD

Setting:
MSLINK key of the row last located by FIND command Angle for reference file rotation pointer to reference file data Scale factors for reference file scaling last error message number restart locate at file beginning 2nd intersection component sector 2nd intersection component byte 2nd intersection file number 2nd intersection header byte 2nd intersection header sector file spec of database control file level symbology mask smallest text floating point scratch buffer Longword: Contents 1: Measured area of element 2: Measured perimeter byte number to start snap scan reference file for snap scan sector number to start snap scan

Type:
int

REFANG REFPTR REFSCL RELERR RSTLOC S2CMSC S2CMBY S2FILE S2HDBY S2HDSC SCHEMA SENA00 SMLTXT SMOBUF

dpfp int 3 dpfp word byte uword word word word uword 50 char word word 9 dpfp

SNAPBY SNAPFL SNAPSC

word word word

15-100 MicroStation 95 Reference Guide

Miscellaneous variables
TCB Name:
SNCMBY SNCMSC SNPTOL SOLDIR SOLINT SOLLGT SPCABV SRVANG STBL00 STRDEL STRKTL STRSEP STRTOL TAGADR TAGBIN TAGDEL TAGLEN TMATRX TPNPTS TPTABL TPTVW TRABYT TSKSIZ

Setting:
snapped component byte snapped component sector snapping tolerance solar light direction solar light intensity solar light status (on/ off) character spacing along element rotation angle for surface of revolution level symbology stream delta rendering stroke tolerance stereo separation (pixels) stream tolerance address of first character of tag binary value of tag auto-tag delta to increment tag length of tag transformation matrix number of entries in tentative point table tentative point history tables view numbers of tentative points 1 & 2 number of bytes in cell transform matrix conventional memory to reserve for applications (Kb) tutorial font tutorial name tutorial sector

Type:
word uword dpfp dpfp dpfp int int dpfp 63 words int dpfp int int word word word word 9 dpfp word 6 int 2 byte word word

TUTFNT TUTNAM TUTSEC

word 2 rad50 word

MicroStation 95 Reference Guide 15-101

15

User Commands

DGNBUF variables
TCB Name:
TXSCRN TYPMSK UCINAM VT1ANG VT8ANG VT1CAM VT8CAM VT1FOC VT8FOC WINMOD WITEXT WITOFF WRKFIL

Setting:
BIOS screen (PC only) type mask for searches UCM index filename view camera angle (radians) view camera position view camera focal length save function name in window command Extension line extension distance Extension line offset work filename (Macintosh manual save mode only) working set starting sector working window starting byte working window file working window starting sector

Type:
word 4 word 128 char dpfp 3 dpfp dpfp uint dpfp dpfp 128 char

WSSECT WWBYTE WWFILE WWSECT

word word word word

DGNBUF variables
When MicroStation creates or manipulates an element, a copy of the element is stored in an area of the TCB called DGNBUF. A UCM can read an element into DGNBUF with a RED or RDF statement or let the user identify an element with LOCELE or FENCE LOCATE. To let UCMs access any component of the element in DGNBUF, a set of variables is provided for each piece of element data. The variable that must be used depends on the type of element and in some cases on the file dimension (2D or 3D).

15-102 MicroStation 95 Reference Guide

DGNBUF variables
The FORTRAN programmer may find it convenient to think of the DGNBUF variables as equivalences into DGNBUF. For a C programmer, the concept of a union of element structures may be more descriptive.

General DGNBUF variables


TCB Name:
_DATE _FTIME _IGDSZ _TIME BYTLEN ID.CNT ID.GRF RANGEE

Setting:
date seconds size of element in DGNBUF (file units) system time element number of words to follow element index to attribute entity element graphic group number element range RANGEE (1): XLOW RANGEE (2): YLOW RANGEE (3): ZLOW RANGEE (4): XHIGH RANGEE (5): YHIGH RANGEE (6): ZHIGH words-in-description (complex header) display symbology Bit Settings: 02: Line style 37: Line weight 815: Color

Type:
2 char 4 dpfp

3 char word word word 6 int

SY.CNT SY.DSP

word word

MicroStation 95 Reference Guide 15-103

15

User Commands

word

DGNBUF variables
TCB Name:
SY.PRO

Setting:
properties indicator Bit Settings: 03 clear: Primary class 0, 23 clear, 1 set: Construction class 47: Reserved 8: Not locked 9: New 10: Modified 11: Database attributes present 12: Oriented relative to screen 13: Non-planar 14: Non-snappable 15: Hole (not solid) element type (deleted if bit 7 is set) element level (complex component if bit 7 is set)

Type:
word

UELETY XYZLEV

byte byte

Element-specific DGNBUF variables


TCB Name:
AR.OG3 AR.ORG AR.ROT AR.RT3 AR.SMJ AR.SMN AR.STA AR.SWA BB.NPT

Setting:
arc origin (3D) arc origin (2D) arc rotation angle (2D) arc quaternion (3D) arc semi-major axis arc semi-minor axis arc start angle arc sweep angle B-spline surface boundary number of points B-spline surface boundary number

Type:
3 int 2 dpfp int 4 dpfp dpfp dpfp int int word

BB.NUM

word

15-104 MicroStation 95 Reference Guide

DGNBUF variables
TCB Name:
BB.PNT BC.CNT BC.NKN BC.NPO BC.PAR

Setting:
B-spline surface boundary points B-spline curve words-in-description B-spline curve number of knots B-spline curve number of poles B-spline curve flags Bit Settings: 03: Order 4: Curve display 5: Control polygon display 6: Rational 7: Closed B-spline curve type B-spline knots B-spline number of poles B-spline poles B-spline surface words-in-description B-spline surface number of boundaries B-spline surface number of knots in u direction B-spline surface number of knots in v direction B-spline surface number of poles in u direction B-spline surface number of poles in v direction

Type:
n int int word word byte

BC.TYP BK.KNO BP.NPO BP.POL BS.CNT BS.NBO

byte n int word 101 int int word

BS.NKU

word

BS.NKV

word

BS.NPU

word

BS.NPV

word

MicroStation 95 Reference Guide 15-105

15

User Commands

DGNBUF variables
TCB Name:
BS.PRU

Setting:
B-spline surface u flags Bit Settings: 03: Order 4: Surface display 5: Control net display 6: Rational 7: Closed B-spline surface v flags Bit Settings: 03: Order 45: Reserved 6: Equal arc spacing 7: Closed 815: Reserved B-spline surface number of rule lines in u direction B-spline surface number of rule lines in v direction B-spline weight factors cell class bit map cell level bit map cell name cell origin (3D) cell origin (2D) cell transformation matrix (2D) cell transformation matrix (3D) cell range diagonal CL.VER(1): XLOW CL.VER(2): YLOW CL.VER(3): XHIGH CL.VER(4): YHIGH cell range cube diagonal CL.VR3(1): XLOW CL.VR3(2): YLOW CL.VR3(3): ZLOW CL.VR3(4): XHIGH CL.VR3(5): YHIGH CL.VR3(6): ZHIGH

Type:
byte

BS.PRV

word

BS.RLU

word

BS.RLV

word

BW.WGT CL.CLS CL.LVL CL.NAM CL.OG3 CL.ORG CL.ROT CL.RT3 CL.VER

n int word 4 word 2 rad50 3 int 2 int 4 int 9 int 4 int

CL.VR3

6 int

15-106 MicroStation 95 Reference Guide

DGNBUF variables
TCB Name:
CO.NVR CO.VER CS.NEL CU.NVR CU.VER CX.NEL DGNBF1 DGNBF2 DGNBFF DGNBUF EL.OG3 EL.ORG EL.ROT EL.RT3 EL.SMJ EL.SMN GR.DES GR.RAD LH.DES LH.DSP LH.PRO LN.BEG LS.NVR LS.VER PS.NVR PS.VER TC.BOR

Setting:
number of vertices vertices complex chain number of elements curve number of points curve coordinates complex shape number of elements plot buffer 1 plot buffer 2 dpfp scratch buffer element work buffer ellipse origin (3D) ellipse origin (2D) ellipse rotation angle (2D) ellipse quaternion (3D) ellipse semi-major axis ellipse semi-minor axis group description group description cell description display symbology cell header properties indicator line coordinates line string number of vertices line string coordinates point string number of vertices point string coordinates truncated cone base origin

Type:
word n int word word n int word 128 word 128 word 64 dpfp 256 word 3 dpfp 2 dpfp int 4 int dpfp dpfp word 13 rad50 10 rad50 word word n int word n int word n int 3 dpfp

MicroStation 95 Reference Guide 15-107

15

User Commands

DGNBUF variables
TCB Name:
TC.BRA TC.ROT TC.TOR TC.TRA TC.TYP

Setting:
truncated cone base radius truncated cone orientation truncated cone top origin truncated cone top radius truncated cone type Value: 0: General cone 1: Right cylinder 2: Skewed cylinder 3: Right cone 4: Skewed cone 5: Right truncated cone 6: Skewed truncated cone text node maximum allowed line length text node font number text node justification Value: 0: Left/top 1: Left/center 2: Left/bottom 3: Left margin/top 4: Left margin/center 5: Left margin/bottom 6: Center/top 7: Center/center 8: Center/bottom 9: Right margin/top 10: Right margin/ center 11: Right margin/ bottom 12: Right/top 13: Right/center 14: Right/bottom text node number of strings in node text node number text node origin (3D) text node origin (2D)

Type:
dpfp 4 int 3 dpfp dpfp word

TN.ALN TN.FON TN.JUS

byte byte byte

TN.NEL TN.NOD TN.OG3 TN.ORG

word word 3 int 2 int

15-108 MicroStation 95 Reference Guide

DGNBUF variables
TCB Name:
TN.ROT TN.RT3 TN.SCF TN.SPA TN.ULN TX.ED3 TX.EDF TX.FON TX.JUS

Setting:
text node rotation angle (2D) text node quaternion (3D) text node scale factors text node line spacing text node used line length text number of enter data fields (3D) text number of enter data fields (2D) text font number text justification Value: 0: Left/top 1: Left/center 2: Left/bottom 35: Text node only 6: Center/top 7: Center/center 8: Center/bottom 911:N/A text 12: Right/top 13: Right/center 14: Right/bottom text characters (2D) text characters (3D) text number of characters (3D) text number of characters (2D) text origin (3D) text origin (2D) text rotation angle (2D) text quaternion (3D) text scale factor

Type:
int 4 int 2 int int byte

byte byte byte

TX.LET TX.LT3 TX.NC3 TX.NCH TX.OG3 TX.ORG TX.ROT TX.RT3 TX.SCF

n byte n byte byte byte 3 int 2 int int 4 int 2 int

MicroStation 95 Reference Guide 15-109

15

User Commands

byte

RELERR Messages

RELERR Messages
When MicroStation detects an error, it changes the value of the TCB variable RELERR to a number that identifies an error message. The following table shows RELERR values and the corresponding messages.
Value:
7 12 15 16 18 18 19 20 21 22 23 27 29 31 35 39 43 44 47 50 54 55 56 57 57 58 59 60 62 67 68 71

Message text:
File not found Library not found No fence defined Invalid character Named view not found Illegal value - reenter No active cell Maximum element size Element not found Element off design plane Illegal definition Enter characters first Invalid tag Tag overflow Maximum text length 3D-only tool Cell nesting error Cell not found Invalid cell name 3D cell library, 2D file No cell library attached Cell already exists No cell origin defined No elements found No elements in cell definition Cell added to library Cell deleted Cell renamed Element too large No line terminator defined Accept/Reject (select next input) Named view not found

15-110 MicroStation 95 Reference Guide

RELERR Messages
Value:
81 82 87 196 265 268 269 270 271 272 287 287 384 481

Message text:
Add to existing group (Accept/Reject) Add to new group (Accept/Reject) Text node not found Select view Menu cell must be 2D Valid menu text node not found Bad menu cell Invalid menu type Bad menu block Menu text node error File is read only File is locked by another user - Read Only Tutorial not found Illegal operation on 1-1 ref file

Database RELERR messages (Oracle)


Value:
4000 4001 4002 4003 4004 4005 4006 4007 4008 44009 4010 44011 4012 4014 4015 4016 4017 4018 4019 4020

Message text:
Allocate database memory Command line syntax error No active entity defined Record not written to database No database linkage present Unable to generate report file No entity specified No MSLINK column in table Unable to open report file Entity number out of bounds Screen form file not found NULL linkage generation mode File not found Unable to locate database Unable to read MSCATALOG table More than one row returned by FIND Not a Select statement Database is not valid No rows returned from FIND No MSLINK column in the table

MicroStation 95 Reference Guide 15-111

15

User Commands

RELERR Messages
Value:
4021 4022 4023 4024 4025 4026 4027 4028 4029 4030 4031 4032 4033 4034 4035 4036 4037 4038 4039 4040 4041 4042 4043 4044 4045 4046 4047 4048 4049 4050 4051 4052 4053 4054 4055 4056 4057

Message text:
Illegal format of MSCATALOG Unable to review attributes Bad review table Table not present in MSCATALOG Unable to update MSCATALOG table Bad report specification Bad MSLINK key in DBREAD/DBWRITE Bad fence filter Bad fence filter No more slots for tasks Unable to create message queue Column number out of bounds Illegal scan comparison code Illegal types in MS_LINKTYPE Bad data type during DB_GETFMT Bad CONNECT statement format Error assigning MSLINK Error building ae table Error loading ae table No rows returned by SELECT RUNFORM program not found Screen form not found Illegal forms command No DAS table for this entity RUNFORM echo file not found Error starting SQL*FORMS No SQLFORMS output file found No entry in DAS table Invalid form command entered Allocation error for descriptor Error opening resource file Not logged in SQL error during table describe Descriptor larger than message Row larger than message packet Fetch failed, no active query No form defined for DAS type

15-112 MicroStation 95 Reference Guide

RELERR Messages Database RELERR messages (Xbase)


Value:
4000 4001 4002 4003 4004 4005 4006 4007 4008 4010 4011 4012 4013 4014 4015 4016 4017 4018 4019 4020 4021 4022 4023 4024 4025 4026 4027 4028 4029 4030 4031 4032 4034 4035 4036 4037

Message text:
Open control database Illegal control file format Allocate database memory Command line syntax error FIND unable to use entity or field name Unable to locate record in database Unable to read record from database No active entity defined Record not written to database Unable to generate key for index file No database linkage present in element Database for entity not currently open Unable to generate report file No fields identified on edit page No entity specified Database file not found Unable to open database file Not a valid database file Unable to locate master index file: %s Unable to open master index file Master index is not a valid index file Master index file not keyed to MSLINK Structure does not contain MSLINK Unable to open report file Entity number out of bounds Invalid number Conversion error Format file not found Database is not valid Index expression is compound Index field is not in the database Index must be character,numeric,date Bad entity number or alias during FIND Bad field number or name during FIND Database control file not defined NULL linkage generation mode

MicroStation 95 Reference Guide 15-113

15

User Commands

RELERR Messages
Value:
4038 4039 4040 4041 4042 4043 4044 4045 4046 4047 4048 4049 4050 4051 4052 4053 4054 4055 4056 4057 4058 4059

Message text:
Filter index file not found Filter index file not valid Unable to open filter index file Filter index file key not MSLINK File not found Database or entity number not found Read control database Unable to assign MSLINK key May not read/write memo fields No records in the control file Unable to lock database file Unable to lock index file No user MSLINK index files No table found in SELECT No column value found in SELECT =,<,>,>=,<=,<> not found in SELECT Trailing single quote not found No where clause in SELECT No field in where clause of SELECT Statement not recognized No rows returned by SELECT Illegal types in MS_LINKTYPE

Database RELERR Messages (INFORMIX)


Value:
4000 4001 4002 4003 4004 4005 4006 4007 4008 4009 4010 4011

Message text:
Allocate database memory Command line syntax error No active entity defined Record not written to database No database linkage present Unable to generate report file No entity specified No MSLINK linkage field Unable to open report file Entity number not between 0 and 65535 Screen form file not found NULL linkage generation mode

15-114 MicroStation 95 Reference Guide

RELERR Messages
Value:
4012 4013 4014 4015 4016 4017 4018 4019 4020 4277 4278 4279 4280 44281 4282 4283 4284 4285 4286 4287 4288 4289 4290 4291 4292 44293 4217

Message text:
File not found SQL error code Unable to locate database Unable to read MSCATALOG table More than one row from FIND Not a Select statement Database is not valid No rows returned from FIND No MSLINK column Unknown ESQL error message Illegal format of MSCATALOG Unable to review attributes Bad review table Table not present in MSCATALOG Unable to update MSCATALOG table Bad report specification Bad MSLINK key in DBREAD/DBWRITE Database not found Bad fence filter No more slots for applications Unable to create message queue Column number out of bounds Illegal scan comparison code Illegal types in MS_LINKTYPE Illegal data type in DB_GETFMT Unable to set MSLINK Column not found in any table

MicroStation 95 Reference Guide 15-115

15

User Commands

Commands for Applications

Commands for Applications


This chapter covers MicroStation commands that are designed to be activated by applications through simulated key-ins.

Simulating Key-ins
These commands are most useful in macros and UCMs. MicroCSL applications should call library routines where available. MDL applications should call built-in functions, where available, to perform the functions of these commands. In most cases, built-in functions and routines are more efficient and flexible than key-in simulations. For example, the built-in function mdlUtil_beep is more efficient than simulating the BEEP key-in and lets the application set the number of times to beep the speaker.

To simulate a key-in in a macro:


x Use the MbeSendKeyin statement.

Example Close and reopen active design file with simulated FLUSH command key-in.
MbeSendKeyin FLUSH

To simulate a key-in in a user command (UCM):


x Use a KEY (page 15-49) statement.

To simulate a key-in in a MicroCSL application:


x Call the prdfpi routine with subrequest 1008.

To simulate a key-in in an MDL application:


x Call the built-in function mdlInput_sendKeyin.:

Example /* Beep speaker with simulated BEEP command key-in. */


mdlInput_sendKeyin ("BEEP", 0, INPUTQ_EOQ, ustnTaskId);

15-116 MicroStation 95 Reference Guide

Application Commands

Application Commands
ACTIVE NODE (NN=) [node_number]
Sets the counter (the DGNBUF variable TN.NOD) used by MicroStation to number text nodes. Text node numbers are typically used by applications that bulk-load text. Applications should avoid resetting the counter to avoid assigning the same text node number to more than one text node.

ATTACH COLORTABLE (CT=)


The ATTACH COLORTABLE (CT=) <space|$|filename> command is used for color table attachment and detachment. CT=filename attaches the specified color table to the design file as the active color table. If the path is not specified, MicroStation looks for the color table in the directory assigned to the MS_DATA configuration variable. CT=filename is executed when the user clicks OK in the Open Color Table dialog box after selecting a file. CT=space detaches the active color table. CT=$ displays the name of the attached color table in the status bar.

ATTACH COLORTABLE CREATE (CT=,CREATE)


The ATTACH COLORTABLE CREATE <filename> command (CT=,CREATE <filename>) saves the attached color table in the specified file executed when the user clicks OK in the Save Color Table dialog box after specifying a filename. The WRITE keyword can be substituted for CREATE.

COLORTABLE DEFAULT
Attaches the default color table supplied with MicroStation to the active design file executed when the user chooses Default from the File menu and then clicks the Attach button in the Color Table settings box.

MicroStation 95 Reference Guide 15-117

15

User Commands

Application Commands

FLUSH
Closes the active design file and immediately reopens it to ensure that the most current version of the design file is available for reading by other applications. The display is unchanged.

INDEX
Creates a cell library index file, which contains the name of each cell in the attached cell library. The cell library index file is assigned the same filename as the cell library with the .cdx extension. The attached cell library is automatically indexed each time the Cell Library settings box opens.

NEWFILE (RD=)
Opens a design file as the active design file. The filename is stored in the TCB variable DGNNAM. If the filename is omitted, the active design file is closed and immediately reopened.

PAUSE <n>
Suspends or pauses MicroStation for n seconds or until the user presses a keyboard key, mouse button, or tablet cursor button. While MicroStation pauses, the pointer is not displayed. The effect is similar to that of a PAUSE statement in a UCM.

PLACE POINT STRING [CONTINUOUS | DISJOINT]


Places a point string element that is contiguous or disjoint for display purposes. A point string element consists of a number of vertices with orientations defined at each vertex. The orientation of each vertex is initialized to the identity transform. Point strings are primarily useful for specialized applications that need to specify orientations as well as point locations, such as a walk through. The maximum number of vertices in a point string is 48.

15-118 MicroStation 95 Reference Guide

Application Commands

To place a point string:


1. Activate PLACE POINT STRING [CONTINUOUS | DISJOINT].
Last keyword:
CONTINUOUS DISJOINT

Point string is displayed:


With lines connecting the vertices (same as a line string) As a set of discrete points

2. Send a data point to define a vertex. 3. Continue sending data points to define other vertices.

SET PLOTTER
Opens the Plot Driver dialog box to permit selection of a plotter driver file, which is identified by the MS_PLTR configuration variable and used when the user clicks the Plot Driver button in the Plot dialog box. If a plotter driver file is specified, the dialog box is bypassed.

SET XORSLOT <color_number>


Sets the color in which the tentative point crosshair and pointer are displayed to a value (0255). This is useful in applications that use raster backgrounds.

SHOW EOF
Displays the location of the active design files end of file mark in the status bar intended for use in application development rather than finished applications. The following display formats are used: Block and byte offset from the beginning of the file. Byte offset from the beginning of the file (in parentheses).

SHOW UORS
Activates a mode in which the design plane position, in UORs, of each data point is displayed in the status bar intended for use in application development rather than finished applications.

MicroStation 95 Reference Guide 15-119

15

User Commands

4. Send a Reset to end the point string.

Application Commands

UNDO ALL NOCONFIRM


Negates all drawing operations recorded in the undo buffer. MicroStation does not request confirmation as it does when the user chooses All from the Edit menus Undo Other sub-menu or keys in UNDO ALL.

VIEW CLEAR
To clear a view:
Clears a view(s).
1. Activate VIEW CLEAR. 2. Send a data point to select each view.

15-120 MicroStation 95 Reference Guide