microstation v8 xm

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 95’s 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 StatementsA 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.

Elementary user interface operators

For a complete list, see “User Interface Operators” on page 15-41.

Elementary MicroStation interface operators

For a complete list, see “MicroStation Interface Statements” on page 15-44.

Operator: Description:

TST Conditionally branch to another statement.

GO Unconditionally branch to a label.

END Exit from the UCM.

PAUSE Temporarily stop the UCM.


MSG Display message in status bar.

GET Get input from user.


CMD Activate MicroStation command.

PNT Send data point to MicroStation.

RST Send Reset to MicroStation.

KEY Send key-in to MicroStation.

SLI Send last input to MicroStation.

15-2 MicroStation 95 Reference Guide

UCM Statements

Use

r C

omm

and

s 15

Elementary design file input/output operators

For a complete list, see “Design File Input/Output Statements” on page 15-49.

Elementary assignment operator

The SET (page 15-52) statement assigns the value of an expression to a variable. Other statements listed in “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.

General statement syntaxThe 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.


RED Read element from design file at a specific location.

WRT Write element to design file.

STO Save setting.


DBREAD Read column(s) from linked database row.

DBWRITE Write column(s) to linked database row.

DBADD Add row to connected non-graphic database.

DBDELETE Delete row from connected non-graphic database.


Introduction to UCM Programming

Lesson: Introduction to UCM ProgrammingThis lesson is an introduction to programming UCMs.

Exercise: Creating and activating a simple UCMSuppose 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 MicroStation’s “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 4KEY 'ACTIVE COLOR 3'; Set active color to color 3KEY 'ACTIVE STYLE 1'; Set active line style to 1KEY 'ACTIVE WEIGHT 0'; Set active line weight to 0END ; 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

◆ 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



Use

r C

omm

and

s 15

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

Exercise: Prompting from UCMsThe 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:

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 'stThis is the Status Field'MSG 'cfThis is the Command Field'MSG 'msThis is the Message Field'MSG 'prThis is the Prompt Field'MSG 'erThis is the Error Field'END

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'

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

Field: Used to display:

Status (st) Status (usually lock status).

Command (cf) The name of the selected tool or view control.

Message (ms) Messages (usually active element attribute settings).

Prompt (pr) Prompts.

Error (er) Error messages.a

Arrangement of fields on the screen.

Status

Key-in

MessagePromptError



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 key-in:

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 'NOECHO'MSG 'cfCustom messages.'KEY 'ACTIVE LEVEL 4'KEY 'ACTIVE COLOR 3'KEY 'ACTIVE STYLE 1'KEY 'ACTIVE WEIGHT 0'MSG 'stWiring Attributes set.'MSG 'msLEVEL=4, COLOR=RED, STYLE=1, WEIGHT=0'MSG 'prYou are now ready to place the wiring.'MSG 'er '

EXITUC:KEY 'ECHO'END



Use

r C

omm

and

s 15

✍ 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 .

SET CONTRL=CONTRL ! 768

The IGDS-compatible statement to reactivate messages and prompts is:

SET CONTRL=CONTRL & -769

Exercise: Receiving input, registers, and branching in UCMsThe 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 MicroStation’s “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.



; BRANCH.UCMKEY 'NOECHO' ; Disable messagesMSG 'st ' ; Clear Status fieldMSG 'cfBranch.ucm' ; Display UCM name in Command fieldMSG 'er ' ; Clear Error field

START:MSG 'msEnter some characters'; PromptMSG 'prReset to exit' ; ReminderGET K,KEYIN, R,EXITUC ; If key-in, jump to KEYIN

; Else if Reset, jump to EXITUCGO START ; Else return to START

KEYIN:MSG 'er ' ; Clear fieldsMSG 'pr 'MSG 'ms 'TST K0 GT 20, LONG ; If input > 20 chars, jump to LONGSET C0='cfYou keyed in: '+KEY; Build messageMSG C0 ; that echoes your inputGO START ; Jump to START

LONG:MSG 'erInput > 20 characters, please re-enter'GO START ; Return to START

EXITUC:MSG 'er ' ; Clear Error fieldMSG 'ms ' ; Clear Message fieldMSG 'cf ' ; Clear Command fieldMSG 'st ' ; Clear Status fieldMSG 'prBranch.ucm exited' ; Display exit statusKEY 'ECHO' ; Enable messagesEND

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 user’s 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.



Use

r C

omm

and

s 15

Exercise: Locating elements and DGNBUFMuch 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 element’s 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 MicroStation’s “ucm” directory, is just such a tool. Here is the listing:



; 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 ; Make sure to start searchingSET WWBYTE=0 ; from beginning of design fileKEY 'NOECHO' ; Disable messagesMSG 'stChgAttr.ucm' ; Display UCM nameMSG 'ms ' ; Clear Message fieldMSG 'er ' ; Clear Error field

;;; Main Routine; ------------START:

KEY 'LOCELE' ; Locate elementMSG 'cfChange Element Symbology and Level'; Display "tool" name

GETELE:GET P,FNDELE, R,EXITUC ; If data point, jump to FNDELE

; Else if Reset, jump to EXITUCGO GETELE ; Else return to GETELE

FNDELE:PNT ; Send data point

TSTELE:TST RELERR NE 0, START ; If element not found, return to STARTMSG 'prAccept/Reject' ; PromptGET P,CHANGE, R,REJECT ; If data point, jump to CHANGE

; Else if Reset, jump to REJECTGO GETELE ; Else return to GETELE

REJECT:RST ; Send ResetGO TSTELE ; Return to TSTELE

CHANGE:SET XYZLEV = ACTLEV ; Change levelSET SY.DSP = IDSYMB ; Change symbologyWRT CUREBL, CUREBY ; Write element back to design fileGO START ; Return to START

;



Use

r C

omm

and

s 15

; Exit; ----EXITUC:

KEY 'NULL' ; Clear MicroStation stateMSG 'prChgAttr.ucm exited' ; Display statusSET WWSECT=0 ; Restore search positionSET WWBYTE=0KEY 'ECHO' ; Enable messagesEND

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.

✍ 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 operatorThe 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 MicroStation’s “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.



; DISPCHNG.UCM -- Sequentially highlight all that have been modified in; a design file.; Initialize; ----------

KEY 'NOECHO'CMD NULCMD ; Clear MicroStation stateMSG 'cfDisplay Changes'

SET WWSECT = 0 ; Set search to the beginning of the file

SET WWBYTE = 0SET CUREBL = WWSECTSET CUREBY = WWBYTE

;; Main Routine; ------------TOP:

RED CUREBL, CUREBY ; Find first elementTST UELETY EQ 34, SKIP ; Skip shared cell definition elementTST RELERR NE 0, EXITUC ; Exit when at the EOF

SET R0 = LH.PRO & 1536 ; Test modify bitTST R0 EQ 0, SKIP ; in properties word

KEY 'DISPLAY HILITE'PNT ; highlight element

SKIP:SET CUREBL = ELEBLK ; point to next elementSET CUREBY = ELECNTGO TOP

; Exit; ----EXITUC:

SET WWSECT = 0 ; reset file pointersSET WWBYTE = 0KEY 'ECHO'CMD NULCMDMSG 'stDisplay Changes Completed'END

Exercise: Locating new elementsIt is often convenient to manipulate elements as they are placed in the design file. This simple example, which is delivered as “blockpat.ucm” in MicroStation’s “ucm” directory, prompts the



Use

r C

omm

and

s 15

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 “end-of-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-of-design 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.



; BLOCKPAT.UCM Place a block and then hatch it.;; Initialize; ----------

KEY 'NOECHO' ; Disable messagesMSG 'st ' ; Clear Status fieldMSG 'cfBlockpat.ucm' ; Display UCM name in Command fieldMSG 'er ' ; Clear Error field

;; Main Routine; ------------START:

SET R0 = DFSECT ; Save current end-of-design pointersSET R1 = DFBYTECMD PBLOCK ; Activate the PLACE BLOCK command

GETDP1:MSG 'msPlace a block' ; PromptMSG 'prEnter first data point-Reset to exit'GET P,DP1,R,EXITUC ; If data point, jump to DP1KEY 'BEEP' ; Else if Reset, jump to EXITUCGO GETDP1 ; Else sound warning and return to

GETDP1DP1:

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 DP2KEY 'BEEP' ; Else if Reset, jump to EXITUCGO GETDP2 ; Else sound warning and return to

GETDP2DP2:

PNT ; Send along second data pt to close the block

SET WWSECT = R0 ; Set the search pointers to startSET WWBYTE = R1 ; at the old end-of-design location

KEY 'PA=45' ; Set pattern angle 45KEY 'PD=:1' ; Set pattern spacing to 1 sub-unitKEY 'HATCH' ; Simulate the HATCH key-inPNT ; Send a data point to locate the new

elementPNT ; Send a data point to accept the new

elementGO START

;; Exit


Using a UCM Template

Use

r C

omm

and

s 15

; ----EXITUC:

CMD NULCMD ; Clear MicroStation stateSET WWSECT = 0 ; Restore search positionSET WWBYTE = 0

MSG 'er ' ; Clear Error fieldMSG 'ms ' ; Clear Message fieldMSG 'cf ' ; Clear Command fieldMSG 'st ' ; Clear Status fieldMSG 'prBlockpat.ucm exited' ; Display exit status

KEY 'ECHO' ; Enable messagesEND

Using a UCM TemplateA 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 MicroStation’s “ucm” directory.


Using a UCM Template

; TEMPLATE.UCM;; DESCRIPTION:;; VARIABLES:; CALLS:

; CALLED BY:;; Initialize; ----------

KEY 'NOECHO' ; Disable messagesSET WWSECT=0 ; Make sure to start searchingSET WWBYTE=0 ; from beginning of design fileSET A0=ACTANG ; Save active angleSET A10=XAXSCL ; Save active scale factorsSET A11=YAXSCLSET A12=ZAXSCLSET UCASC=ACTAB ; Save active cell nameSET R1=UCWRD(1) ; in R1,R2,R3SET R2=UCWRD(2)SET R3=UCWRD(3)

;; Main Routine; ------------START:; *; *; *;; Error Messages; --------------ERR1:

SET MSG='erError in last operation. RELERR='+RELERRMSG MSG ; Display error message in Error

fieldGO EXITUC

; Exit; ----FINISH:

KEY 'NULL' ; Clear MicroStation stateMSG 'er ' ; Clear Error fieldMSG 'cf ' ; Clear Command field

EXITUC:MSG 'st ' ; Clear Status fieldMSG 'prUCM exited'; ; Display status


UCM Format

Use

r C

omm

and

s 15

KEY 'ECHO' ; Enable messagesSET WWSECT=0 ; Restore search positionSET WWBYTE=0SET ACTANG=A0 ; Restore active angleSET XAXSCL=A10 ; Restore active scale factorsSET YAXSCL=A11SET ZAXSCL=A12SET UCWRD(1)=R1 ; Restore active cellSET UCWRD(2)=R2SET UCWRD(3)=R3SET ACTAB=UCASCEND

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.

✓ 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.

UCM FormatA 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]

LabelsLabels 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:


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.

OperatorsOperators, 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.

RulesEach 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


UCM Execution

Use

r C

omm

and

s 15

preceding the number with the “at” symbol—@). For example, all of the following are valid:

12.345 -235@100 (decimal 64)+3423423412e-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 ExecutionFor information about activating UCMs, see “Activating a UCM” in Chapter 8 in the User’s 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>.


UCM Variables

Error handlingIf 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 exitset err = 0 ; Clear error statusgo 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 VariablesThere 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.


UCM Variables

Use

r C

omm

and

s 15

UCM registersUCM 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): Size: Description:

R0-R31 16 bits integer scratch registers.

ERR 16 bits MicroStation sets ERR to indicate errors before branching to EXITUC.

NUM 16 bits set to the number of characters input from the keyboard.

I0-I15 32 bits double precision integer scratch registers.

XDT, YDT 16 bits tablet coordinates for last data point.

XUR, YUR, ZUR 32 bits UOR coordinates for last data point.

VNO 16 bits low byte — view for last data point high byte — multi-view spot flag1 = multi-view0 = single view

A0-A15 64 bits double precision floating point scratch registers.

KEY 42 characters register where MicroStation puts user key-ins. Can also be used as a scratch register.

K0 16 bits number of characters in KEY.

MSG 42 characters character scratch register (generally used for prompts and messages to user).

M0 16 bits number of characters in MSG.


UCM Variables

TCB variablesThe 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 isn’t 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

C0-C15 42 characters character scratch registers (can be combined for strings of up to 252 characters). Arguments are stored in these registers, beginning with C0.

N0-N15 16 bits number of characters in C0-C15. If value is –1, the C# register is combined with the next one.

FNO 16 bits register for identifying menu and tutorial command selection.

Register(s): Size: Description:


UCM Variables

Use

r C

omm

and

s 15

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:

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

✍ 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:

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

DFSECT, DFBYTE

Sector and byte pointers to the end of the design file.

WWSECT, WWBYTE

Sector and byte pointers to the starting element search position.


UCM Variables

The common element pointers are listed below:

✍ 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.

DGNBUF variablesDGNBUF 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

CUREBL, CUREBY

“Block” and offset of “current” element.

ELEBLK, ELECNT

“Block” and offset of next element.

Pointers upon opening of design file.

Header Elements

End of File

WWSECT, WWBYTE CUREBL, CUREBY

ELEBLK, ELECNT

DFSECT, DFBYTE

Type 8. 9. 10

Element 1

Element n

-1


UCM Variables

Use

r C

omm

and

s 15

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 file’s dimensionality and therefore whether to use the 2D or 3D DGNBUF variables.

For example:

TST NDICES NE 2, THREED ; Test dimensionalitySET I1=EL.ORG(1) ; Set 2D DGNBUF variableGO NEXT ; Branch past 3D code THREED:SET I1=EL.OG3(1) ; Set 3D DGNBUF variable next:

Array variablesVarious 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 ; Initialize counterSTART:

TST UCASC(R0) EQ ',' ,FOUND ; If character is ",", branch; to FOUND

SET R0 = R0+1 ; Else increment counterTST R0 EQ 33, NONE ; If counter = 33, branch to NONEGO START ; Else test next character

FOUND::

NONE:

This statement copies the entire contents of UCASC—all 32 characters—to 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.


File Naming

File NamingThe 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 MicroStation’s “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 variablesYou can define Configuration Variables (see Chapter 4 in the User’s 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.


Error Messages

Use

r C

omm

and

s 15

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 MessagesThe following error messages can be generated while a UCM is active:

Error message: Meaning:

Bad array Array sizes do not match.

Bad destination variable

Destination is not a variable.

Bad message field

Must be either pr, er, cf, st, or ms.

Bad string operation

Only “+” is valid for strings.

Bad subscript Variable is not an array.

Bad value Value conversion error.

Bad variable name

Variable is undefined.

Divide by zero Illegal operation (result is undefined).

File too large File does not fit in UCM buffer.

Label [ ] undefined

Label not found in UCM.

Math error Usually indicates overflow.

String overflow File contains too many strings.

String too long Maximum string length is 80 characters.

Subscript out of range

Subscript is too large.

Symbol table overflow

There can be a maximum of 100 labels.

Syntax error Line contains invalid syntax.

TCB file missing MicroStation cannot find “tcbvars.dat.”

UCM nesting error

Cannot open temporary file. (MicroStation cannot write to directory assigned to MS_DATA.)


Servicing Tutorials with UCMs

Servicing Tutorials with UCMsA 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 operationThe 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 ; Save OUTFLGSET OUTFLG=OUTFLG ! @10 ; Allow menu command selections

NEXT:GET I,KEYENT,T,GRASEL ; Get tutorial inputSLI ; Send other inputs to File

BuilderGO NEXT

KEYENT:. ; Service key entry field input..

GRASEL:. ; Service graphic selection field

input..

EXITUC:SET OUTFLG=RO ; 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.



Use

r C

omm

and

s 15

Servicing key entry field inputBecause 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 1TST FNO EQ 2, FIELD2; Input from field 2GO 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 inputSET RO=1 ; Parse function code = 1TSK '_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 inputA 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,



information is provided to the UCM in the FNO, NUM, and KEY registers. This information is described below.

✍ 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.

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.

Field Type: FNO: NUM: KEY:

P 1,2 char. count primitive command name

C 3 char. count cell name

R 4 char. count cell name

S 5 char. count symbol character

U 6 UC slot # N/A

D 7 char. count tutorial cell name

A 8 field # N/A

Field Type: FNO: NUM: KEY:

K N/A char. count ASCII characters

T N/A char. count ASCII characters



Use

r C

omm

and

s 15

The following example shows how graphic selection field inputs can be detected.

SET RO=OUTFLG ; Save OUTFLGSET OUTFLG=OUTFLG ! @10 ; Allow menu command activation

NEXT:GET M,MENU,T,GRASEL,K,KEYIN; Get graphic selection inputGO 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

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.



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 ; Service graphic selection field inputTST NUM EQ 1, APCMD1 ; Application command 1?TST NUM EQ 2, APCMD2 ; Application command 2?GO NEXT ; Unrecognized field

APCMD1:. ; Command 1 processing..GO NEXT

APCMD2:. ; Command 2 processing..GO NEXT

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 1SET MSG=TUTNAM ; Get tutorial nameTOT 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.


Adapting IGDS UCMs for MicroStation

Use

r C

omm

and

s 15

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 ; Display default units in key entry ; field 11

TOT 12, ' ',1 ; Erase key entry field 12

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.

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 fieldsThe 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 MicroStationBecause 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.


Adapting IGDS UCMs for MicroStation

The following IGDS TCB variables are not supported in MicroStation.

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

SET CMDTYP=0SET 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'

orCMD 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.

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

a. MicroStation’s terminal type is 15.

CMDTYP SCANER FSPCnn RFFEXn

IGOTO DCTCHSa DLVLnn RFUICn

LOPTNO DGNSIZ DFLGnn RFLDSn

REJIGT FSPNnn RFFILn RFVERn

AUXXOR AUXYOR AUXZOR

IGDS TCB variables:MicroStation replacement:

DGNFIL, DGNFEX, DGNVER, DGNUIC, DGNLDS

DGNNAM

CELFIL, CELFEX, CELVER, CELUIC, CELLDS

CELNAM

DMRSFL, DMRSEX, DMRVER, DMRUIC, DMRLDS

SCHEMA

UCXLIB, UCXEXT, UCXVER, UCXUIC, UCXLDS

UCINAM


Compiling UCMs

Use

r C

omm

and

s 15

The following UCM operators are not supported in MicroStation:

DC (substitute KEY 'BEEP')RUN (use TSK)CAN (use TSK)

Compiling UCMsYou 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>.


UCM Statement Syntax

UCM Statement SyntaxA 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.


Program Flow (Branching) Statements

Use

r C

omm

and

s 15

Program Flow (Branching) StatementsThe following statements control UCM flow:

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:

✍ 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.

To: Use this statement:

Conditionally branch to another statement.

TST (page 15-37)

Unconditionally branch to another statement.

GO (page 15-38)

Exit from the UCM. END (page 15-38)

Activate another UCM. UCM (page 15-38)

Activate another UCM as a subroutine; save and restore registers.

CLS (page 15-39)

Activate another UCM as a subroutine, without saving registers.

CAL (page 15-39)

Temporarily stop the UCM. PAUSE (page 15-40)

LT less than (<)

GT greater than (>)

EQ equal to (=)

NE not equal to (≠)

LE less than or equal to (≤)

GE greater than or equal to (≥)

MT matches



Examples: TST KEY EQ 'NEXT', AGAIN ; Branch to AGAIN if user keyed in "NEXT"

TST KEY MT 'NEXT', AGAIN ; Branch if any string starting with ; "NEXT" is keyed in

TST r0,GT,0,LOOP ; Branch to LOOP if R0 > 0

TST RELERR NE 0 EXIT ; Exit if there was an error

TST KEY(1) EQ 'A', CONT ; Branch if first character of KEY ; is "A"

GO[label:] GO destination

Descr. Unconditionally branches to destination.

Example GO HELLO; Branch to HELLOGO 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.



Use

r C

omm

and

s 15

Examples: UCM 'new' ; Activate NEW.UCMUCM 'C:\USR\HANK\NEW.UCM' ; Directory specified with filename

; (DOS systems)

UCM 'HD:Usr:Hank:New.Ucm' ; Folder specified with filename ; (Mac OS)

UCM '/usr/hank/new.ucm' ; Directory specified with filename; (UNIX systems)

UCM 'PROD:new.ucm' ; Directory specified by configuration; variable "PROD"

UCM C0; ; 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: CLS 'new' ; Activate NEW.UCMCLS 'C:\usr\hank\new.ucm' ; Directory specified with filename

(DOS)

CLS 'HD:Usr:Hank:New.Ucm' ; Folder specified with filename (Mac)

CLS '/usr/hank/new.ucm' ; Directory specified with filename (UNIX)

CLS 'PROD:new.ucm' ; Directory specified by environment; variable "PROD"

CLS C0 ; Filename specified in C0

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



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' ; Activate NEW.UCMCAL 'C:\usr\hank\new.ucm' ; Directory specified with filename

; (DOS systems)

CAL 'HD:Usr:Hank:New.Ucm' ; Folder specified with filename; (Mac OS)

CAL '/usr/hank/new.ucm' ; Directory specified with filename; (UNIX systems)

CAL 'PROD:new.ucm' ; Directory specified by environment ; ; variable "PROD"

CAL C0 ; Filename specified in 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 until user presses a keyPAUSE 'prHello World', 10 ; Display "Hello World" in the Command

; Window Prompt field and pause for; no more than 10 seconds


User Interface Operators

Use

r C

omm

and

s 15

User Interface OperatorsThese statements interface with the user (through MicroStation):

MSG[label:] MSG message

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.

Example MSG 'erThis is an error message' MSG 'prThis is a prompt'MSG 'cf ' ; Clear the Command fieldMSG MSG ; Message is in MSG register

To: Use:

Display message in status bar. MSG (page 15-41)

Get input from user. GET (page 15-42)

Display information in tutorial. TOT (page 15-43)

pr Prompt field

er Error field

cf Command field

st Status field

ms Message field



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

Descr. Suspends the UCM until the user provides input.

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:

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

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.

If the input: Then:

Is of a type that corresponds to a specified keyword

Branches to the corresponding label.

Is not of a specified type The next statement is processed.

Keyword: Input type: Data stored in:

P Data point XDT, YDT, XUR, YUR, ZUR, VNO

K Key-in KEY (text string), NUM (number of characters)

R Reset (No data is stored.)

C Unattached cursor button

XDT, YDT, XUR, YUR, ZUR, VNO, NUM (button number)

M Menu or function keya

FNO (type of command), NUM (number of characters), KEY (key-in string for command)

T Tutorial graphic selection field

FNO (type of command), NUM (number of characters), KEY (key-in string for command)

I Tutorial key entry field

FNO (field number), NUM (number of characters), KEY (key-in string)

GETCMD number that uniquely identifies the command.



Use

r C

omm

and

s 15

Examples: GET K, KEYIN ; Branch to KEYIN if user ; input is a key-in

GET K,KY12, P,POINT, R,EXITUC ; Branch on key-in, data point,; or Reset

TOT[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 ; Display "Hello" in field 2TOT 3 ; Position pointer in field 3

TOT 11, ' ', 1 ; Clear field 11

TOT R0, KEY, NUM ; Display last key-in in field identified by R0

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

GETCLSa number that identifies the command class.

GETSRCa number that identifies the source of the command.


MicroStation Interface Statements

MicroStation Interface StatementsThese statements let UCMs send inputs to MicroStation as if they had been input from the keyboard, mouse, or digitizing tablet:

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.

To: Use:

Activate a command. CMD (page 15-44)

Send a data point to MicroStation.

PNT (page 15-44)

Send a Reset to MicroStation. RST (page 15-49)

Send a key-in to MicroStation. KEY (page 15-49)

Send last input to MicroStation. SLI (page 15-49)



Use

r C

omm

and

s 15

If any of these operands is omitted, its default is used.

Examples: PNT ; Send data point with defaultsPNT ,,,,,,68,1 ; Send data point with search for

; lines, text nodes, and text.

PNT ,,,,,,,,20 ; Search on level 20

PNT ,,,,,,,,,,12 ; Search for construction and ; dimension class elements

PNT,,,,,,32,,10,,,512,8704 ; 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

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

operand number:

Definition: Default:

1 X UOR value XUR register

2 Y UOR value YUR register

3 Z UOR value ZUR register

4 view number VNO register

5 X Tablet coordinate XDT register

6 Y Tablet coordinate YDT register

7, 8 Type all types

9 Level active level or displayed levels (depending on Level Lock)

10 complex element modea

1

11 class SYSCL TCB variable

12, 13 properties (not checked)



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:

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

operand7 type: operand8 type: Bit number:

1 17 0

2 18 1

3 19 2

4 20 3

5 21 4

6 22 5

7 23 6

8 24 7

9 25 8

10 26 9

11 27 10

12 28 11

13 29 12

14 30 13

15 31 14

16 32 15



Use

r C

omm

and

s 15

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.

W To prevent corruption of the design file, UCMs should not modify a component element of a complex element without also 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:

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

Class: Bit No./Class Value:

Primary 0

Pattern Component 1

Construction 2

Dimension 3

Primary Rule 4

Linear Pattern 5

Construction Rule 6



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):

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).

Bit name: Number:

L 8

N 9

M 10

A 11

R 12

P 13

S 14

H 15


Design File Input/Output Statements

Use

r C

omm

and

s 15

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.

✍ 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).

Examples: KEY ; Send string in KEYKEY C0, 4 ; Send first 4 characters in C0

KEY 'locele' ; Activate LOCELE command

KEY 'LV=4' ; Set active level to 4

KEY 'MDL LOAD calculat'; Load Calculator/Preprocessor

KEY 'AA={asin(1)} ; Set active angle to arcsine(1)

SLI[label:] SLI

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

Design File Input/Output StatementsThese statements directly read and write design files:

To: Use:

Read element from design file at a specific location.

RED (page 15-50)

Read element from design file without transforming reference file coordinates.

RDF (page 15-50)

Write element to design file. WRT (page 15-50)

Save setting in design file. STO (page 15-51)



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 ; Read current elementRED 2, 4, 0 ; 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.

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



Use

r C

omm

and

s 15

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 file’s 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 ; Save Active FontSTO ACTLEV 1176 ; Save Active Level


Mathematical, Conversion, and Assignment Statements

Mathematical, Conversion, and Assignment StatementsThese statements perform mathematical calculations or logical operations, convert between character and numeric variables, and assign values to variables:

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

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

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.

a. Not supported in IGDS.

To: Use:

Assign value of expression to variable. SET (page 15-52)

Convert character string (in working units) to/from integer (in UORs).

CVT (page 15-53)

Compute square root. SQR (page 15-54)

Compute sine and cosine. SCS (page 15-54)

Compute arc tangent. ATN (page 15-54)

Keyword: Meaning: Keyword: Meaning:

+ addition, if var1 is numeric; concatenation, if var1 is a character string

$ logical XOR

– subtraction | logical ORa

* multiplication ^ logical XORa

/ division % modulus operatora

! logical OR << left bit shifta

& logical AND >> right bit shifta



Use

r C

omm

and

s 15

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 ; Store input pointSET I1=YURSET I1= R0 ; Convert from 16 bit to 32

bit

SET A1 = i0sm*2 ; Multiply by 2 and save ; as floating point

SET FBFDCN=FBFDCN & -17 ; Turn off Snap Lock

SET I1 = I3 % I4 ; Remainder of I3/I4

SET I1 = I3 << 3 ; Left shift I3 by 3 bits

SET I1 = I3 >> 3 ; Right shift I3 by 3 bits

SET C1 = 'This ASCII string was 40 characters long'; N1=40

SET C1 = C1 + ' but is now 54' ; N1=54. C2 is undefined. ; N2=-1.

SET N1 = 16 ; 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



recommended to handle the case of a UOR value that is not a 32-bit integer—that 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 coordinatesCVT A0 = '200:5,5000:22,800:8' ; Convert to UORsSET I0 = A0 + GOXUOR ; Add global originSET I1 = A1 + GOYUORSET I2 = A2 + GOZUOR

; Convert design cube coordinates to working units for displaySET A0 = I0 – GOXUOR ; Subtract global originSET A1 = I1 – GOYUORSET A2 = I2 – GOZUORCVT 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 ; A1 = delta XSET A2=I3 - I1 ; A2 = delta YATN A0, A2, A1 ; A0 = angle


Matrix Statements

Use

r C

omm

and

s 15

Matrix StatementsThese statements perform mathematical operations or conversions on matrices:

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 UCM’s 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 ; Multiply matricesMML LS.VER(1),TMATRX,LS.VER(1),LS.NVR ; Transform line string

; vertices through TMATRX

To: Use:

Perform matrix multiplication or transform series of points.

MML (page 15-55)

Transpose matrix. MTN (page 15-56)

Convert rotation matrix to double precision, floating point format.

CQM (page 15-56)

Convert cell transformation matrix to double precision, floating point format.

CCM (page 15-56)


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.

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 matrixCCM TMATRX,CL.RT3; Convert 3D cell transformation matrix

If design file is: var2 is: var1 contains:

2D Element rotation angle

2 × 2 matrix

3D Quaternion rotation 3 × 3 matrix


MicroCSL Application Interface Statements

Use

r C

omm

and

s 15

MicroCSL Application Interface StatementsThese 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.

TSK[label:] TSK application [, var1…varN]

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 [,var1…varN]

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" applicationWT 'APPS:CALC.EXE', A1, C0 ; Wait for "Calc" output

To: Use:

Start an application with specified parameters.

TSK (page 15-57)

Wait for data from an application. WT (page 15-57)


Database Interface Statements

Database Interface StatementsThese statements let UCMs interface to a non-graphic database to which MicroStation is connected:

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)”

✍ For more information about database interfaces, see “MicroStation and Non-graphical Data” in Chapter 11 in the Administrator’s Guide.

✍ Database operators and statements are not supported in VAX-based 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.

To: Use:

Read column(s) from linked database row.

DBREAD (page 15-58)

Write column(s) to linked database row. DBWRITE (page 15-59)

Add row to database. DBADD (page 15-59)

Delete row from database. DBDELETE (page 15-60)

Column name: Type:

vendor Char (30)

type Char (10)

flowrate Number (10,2)

cost Number (6,2)

mslink Number (10)


Database Interface Statements

Use

r C

omm

and

s 15

Numeric columns are read into the A# floating point registers beginning with A0 and incrementing for successive columns.

Examples: DBREAD 'Pumps' 4 'vendor' ; entity: 1, row: mslink = 4,; C0=vendor

DBREAD 1 2 'vendor' 'type' ; 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

DBWRITE[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


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.


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.


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 VariablesProgrammers 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


Categories of TCB Variables

Use

r C

omm

and

s 15

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 VariablesThere 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 typesThese are the data types:

Type: Description:

byte 8 bits of data

word 2 bytes of data

int 4 bytes, double precision integer

dpfp 8 bytes, double precision, floating point

char character

rad50 3 character, Radix-50 data (see below)

unit 4 bytes, unsigned double precision integer

uword unsigned 2 bytes


User Command Registers

Radix-50 Character SetThe 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:

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 RegistersA set of registers is included in the TCB for general purpose use by applications, particularly UCMs:

Character: Radix-50 Value (Octal):

space 000

A–Z 001–032

$ 033

. 034

(Unassigned) 035

0–9 036–047

TCB Name: Definition: Type:

A0…A15 double precision floating point registers

dpfp

C0…C15 character scratch registers

40 char

ERR error indicator word

FNO menu and tutorial field ID number

word


User Command Registers

Use

r C

omm

and

s 15

I0…I15 double precision integer registers

int

K0 number of characters in KEY0

word

KEY key-in 42 char

M0 number of characters in MSG

word

MSG message 42 char

N0…N15 registers with number of characters in C0–C15

word

NUM number of characters in KEY

word

R0…R31 integer scratch registers

word

VNO current view number word

XDT x cursor coordinate word

XUR x UOR coordinate int

YDT y cursor coordinate word

YUR y UOR coordinate int

ZUR z UOR coordinate int

TCB Name: Definition: Type:


Type 9 Variables

Type 9 VariablesA 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 TCB’s 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: Sets: Type: Offset:

ACTANG active angle dpfp 1096

ACTLEV active level byte 1178

ADPATC active line terminator byte 1413

ADPCFO font number for origin terminator byte 1416

ADPCTC origin terminator byte 1417

ADPDFO font number for diameter terminator byte 1418

ADPDTC diameter terminator byte 1419

ADPEFA English fractional accuracy Bit Settings:None: Display decimal to nearest integer0 & 7: Display decimal to nearest .11 & 7: Display decimal to nearest .012 & 7: Display decimal to nearest .0013 & 7: Display decimal to nearest .00014 & 7: Display decimal to nearest .000015 & 7: Display decimal to nearest .0000016 & 7: Display decimal to nearest .00000017: Display decimal to nearest .000000010: Display fraction to nearest 1/21: Display fraction to nearest 1/42: Display fraction to nearest 1/163: Display fraction to nearest 1/324: Display fraction to nearest 1/64

byte 1174


Type 9 Variables

Use

r C

omm

and

s 15

ADPFMT angle readout specificationValue:0: Decimal degrees1: Degrees, minutes, seconds

byte 1506

ADPLEV dimension levelNo bits set: Active levelBits 1–63 set: Specific level selected

byte 1176

ADPMFA metric fractional accuracyBit Settings:None: Display decimal to nearest integer0 & 7: Display decimal to nearest .11 & 7: Display decimal to nearest .012 & 7: Display decimal to nearest .0013 & 7: Display decimal to nearest .00014 & 7: Display decimal to nearest .000015 & 7: Display decimal to nearest .0000016 & 7: Display decimal to nearest .00000017: Display decimal to nearest .000000010: Display fraction to nearest 1/21: Display fraction to nearest 1/42: Display fraction to nearest 1/163: Display fraction to nearest 1/324: Display fraction to nearest 1/64

byte 1175

ADPMOD linear dimensioning modesBit Settings:0 & 1 clear: Parallel to view axis0 set, 1 clear: Parallel to design plane axis0 clear, 1 set: Parallel to element0 & 1 set: Parallel to arbitrary axis2 set, 3 clear: Auto placement mode2 set, 3 set: Semi-manual placement mode2 clear, 3 set: Manual placement mode4 clear: Extension lines off4 set: Extension lines on5 set, 6 clear: Left justification5 clear, 6 set: Center justification7 clear: Label angular as length7 set: Label angular as degrees

byte 1177

ADPOFO font number for stroke terminator byte 1414

ADPOTC stroke terminator byte 1415



Type 9 Variables

ADPPAR dimensioning settingsBit Settings:0 clear: Primary system: English 0 set: Primary system: metric 1 clear: Display in single mode1 set: Display in dual mode2 clear: Tolerance generation off2 set: Tolerance generation on3 clear: Plus/minus tolerancing3 set: Limit tolerancing4 & 5 clear: Text parallel & above dim. line4 set, 5 clear: Text parallel & embedded in dim. line4 & 5 set: Text horizontal & embedded in dim. line6 clear: Mechanical6 set: AEC

byte 1179

ADPREF dimension display format byte 1181

measurement (bits 0–2)Bit Settings:0–2 clear: Master & sub-units0 set: Master units0 & 1 set: Working units2 clear: Decimal display2 set: Fraction display

labeling (bits 3–5) Bit Settings:3 clear: Master units only3 set: Master & sub-units4 clear: Label generation off4 set: Label generation on5 clear: Delimiter generation off5 set: Delimiter generation on

ADPRS2 coordinate readout byte 1507

decimal accuracy (bits 0–2) Bit Settings:0–2 clear: 1/10,0000 set: Integer1 set: 1/100 & 1 set: 1/1002 set: 1/1000



Type 9 Variables

Use

r C

omm

and

s 15

fractional accuracy (bits 3–7) Bit Settings:3–7 clear: 1/23 set: 1/43 & 4 set: 1/83–5 set: 1/163–6 set: 1/323–7 set: 1/64

ADPSFO font number for active line terminator byte 1412

ADPTLO lower tolerance int 1424

ADPTSR text height (if ADPTSR=0, use active text height and width)

int 1420

ADPTUP upper tolerance int 1428

ADRES2 dimension display accuracy byte 1180

decimal accuracy (bits 0–2) Bit Settings:0–2 clear: 1/10,0000 set: Integer1 set: 1/100 & 1 set: 1/1002 set: 1/1000

fractional accuracy (bits 3–7) Bit Settings:3–7 clear: 1/23 set: 1/43 & 4 set: 1/83–5 set: 1/163–6 set: 1/323–7 set: 1/64

ANGFMT angle readout formatValue:0: Decimal degrees1: Degrees, minutes, seconds

byte 1159

AUXTYP active ACS type word 1508

AZIANG azimuth true north angle dpfp 1166



Type 9 Variables

C–L

TCB Name: Setting: Type: Offset:

CAFONT active font number

byte 1158

CANODE highest node number + 1

uword 1258

CELFEX rad50 cell library extension

rad50 1242

CELFIL rad50 cell library name

3rad50 1236

CELLDS rad50 cell library device

rad50 1246

CELUIC cell library directory

word 1244

CELVER cell library version number

word 1248

CFBYTE cell library ending byte

word 1252

CFSECT cell library ending sector

word 1250

CHHGT character height in UORs

uint 1144

CHWID character width in UORs

uint 1148

CNTRL1 miscellaneous flag wordBit Settings:0: Enable user help mode1: Boresite Locka

2 clear: Project snap modea

2 set: Keypoint snap mode3: ACS Plane Lock

word 1504


Type 9 Variables

Use

r C

omm

and

s 15

CONTRL locks and mode control wordBit Settings:0: Grid Lock1: Unit Lock2: Reserved3: Point/stream mode4: Delayed patterning5: Display aspect ratio6–7: Reserved8: Inhibit “cf”, “st”, and “pr” messages9: Inhibit “er” messages except for fatal10–13: Reserved14: Display window altered15: Reserved

word 0

CONZHI contour Z high, 2D

int 992

CONZLO contour Z low, 2D

int 980

DFRANG design file low/high range in UORs

6 int 1188

DMRFLG database record delete flag

byte 1409

DMRLDS not used by MicroStation

rad50 N/A

DMRSEX not used by MicroStation

rad50 N/A

DMRSFL not used by MicroStation

3 rad50 N/A

DMRUIC not used by MicroStation

word N/A

DMRVER not used by MicroStation

word N/A



Type 9 Variables

EU.MU number of sub-units/master unit

int 1084

EU.UOR number of positional units/sub-unit

int 1088

FBFDC2 not used by MicroStation

word N/A

FBFDCN miscellaneous locks and controlsBit Settings:0: Solid/hole, set = hole1: Scale Lock2: Text Node Lock3: Angle Lock4: Snap Lock5: Text mirroring6: 2D/3D design file, set = 3D7: 2D/3D cell library, set = 3D8: Lines with width9: Clip fence selection10: Graphic Group Lock11: Level Lock12: Assign active attribute14: Attribute search enabled (fence contents)15: Overlap fence selection

word 1186

G.RG grids/reference grid

word 14

GGBASE graphic group base number

uword 1254



Type 9 Variables

Use

r C

omm

and

s 15

GOXUOR global origin x of design plane in UORs

dpfp 1212

GOYUOR global origin y of design plane in UORs

dpfp 1220

GOZUOR global origin z of design plane in UORs

dpfp 1228

GRAFIC highest graphic group number + 1

word 1160

IACTFL initial active file no.

byte 1411

IDPROP active element propertiesBit Settings:0–3 clear: Primary class0, 2–3 clear, 1 set: Construction class4–7: Reserved8: Not locked9: New10: Modified11: Database attributes present12: Oriented relative to screen13: Non-planar14: Non-snappable15: Hole (not solid)

word 1182



Type 9 Variables

M–T

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

IDSYMB active element symbologyBit Settings:0–2: Line style3–7: Line weight8–15: Color

word 1184

LKGNMD: database linkage modeValue:0: New Linkage Mode1: Information Linkage Mode2: Duplicate Linkage ModeNegative: Absolute value indicates the number of empty (null) DMRS linkages appended to newly created cell headers

byte 1408


MAMADF not used by MicroStation

3 rad50 N/A

MAMADV not used by MicroStation

rad50 N/A

MAMAEX not used by MicroStation

rad50 N/A

MAMAUC not used by MicroStation

word N/A

MAMAVR not used by MicroStation

word N/A

MU.CHR master unit name ASCII

2 char 1092



Type 9 Variables

Use

r C

omm

and

s 15

MU.DF number of master units /design plane

uint 1080

NNBASE node number base

uword 1256

NODLLN active line length

byte 1156

NODSPA active line spacing

int 1152

RFCNTL reference file control flag

byte 1163

RFFEX1… RFFEX3

not used by MicroStation

rad50 N/A

RFFIL1… RFFIL3


3 rad50 N/A

RFLDS1… RFLDS3


rad50 N/A

RFLEV1… RFLEV3


3 word N/A

RFSCT1… RFSCT3


word N/A

RFUIC1… RFUIC3


word N/A

RFVER1… RFVER3


word N/A

RNDANG Angle Lock roundoff value

dpfp 1104

RNDSCL Scale Lock roundoff value

dpfp 1136

RNDUNT Unit Lock roundoff UORs

dpfp 2

SU.CHR sub-unit name ASCII

2 char 1094

SYSCL system class bit map

word 1274



Type 9 Variables

TNJUST text node justificationValue:0: Left/top1: Left/center2: Left/bottom3: Left margin/top4: Left margin/center5: Left margin/bottom6: Center/top7: Center/center8: Center/bottom9: Right margin/top10: Right margin/center11: Right margin/bottom12: Right/top13: Right/center14: Right/bottom

byte 1157

TPMODE tentative point modeValue: 0: Locate mode1: Measure delta2: Measure angle (3 points)3: Measure angle (2 points)4: Measure view delta5: Locate mode with aux coordinate6: Measure delta with aux coordinate

byte 1164



Type 9 Variables

Use

r C

omm

and

s 15

U–Z

TPSMDE tentative point sub-mode — angle mode value (bits 0-3)Value:0: Conventional1: Azimuth2: Bearingbits 4–7: Not used by MicroStation

byte 1165

TUTVW: not used by MicroStation

byte N/A

TXJUST text justificationValue:0: Left/top1: Left/center2: Left/bottom3–5: Unused6: Center/top7: Center/center8: Center/bottom9–11: Unused12: Right/top13: Right/center14: Right/bottom

byte 1162


U.G UORs/grid int 10

UCASC UCM ASCII array

32 char 1290

UCBYT UCM byte array 32 byte 1290

UCDPF UCM dpfp array

4 dpfp 1290



Type 9 Variables

UCDPV UCM VAX format double precision array

4 dpfp 1290

UCINT UCM integer array

8 int 1290

UCRAD UCM Rad50 array

rad50 1290

UCWRD UCM word array

16 word 1290

UCXEXT Rad50 UCM index file extension

rad50 1282

UCXLDS UCM index file disk

rad50 1286

UCXLIB Rad50 UCM index file name

3 rad50 1276

UCXUIC UCM index file directory

word 1284

UCXVER UCM index file version

word 1288

VT1ACZ…VT8ACZ

view 1–view 8 active Z

int 132, 250, 368…

VT1CNV…VT8CNV

view 1–view 8 conversion factor DITS/UORs

dpfp 124, 242, 360…

VT1EXT…VT8EXT

view 1–view 8 extents

3 uint 40, 158, 276…



Type 9 Variables

Use

r C

omm

and

s 15

VT1FLG…VT8FLG

view 1–8 display flagsBit Settings:0: Fast curve, arc ellipse1: Fast text2: Fast font3: Line weight4: Patterns5: Text nodes6: Enter data underlines7: On/off (open/closed)8: Delay/update9: Grid10: Level symbology11: Points12: Line constructs13: Dimensioning14: Fast cell15: Def/undef

word 18, 136, 254…

VT1LEV…VT8LEV

view 1–view 8 level bit maps

4 word 20, 138, 256…

VT1ORG…VT8ORG

view 1–view 8 origins

3 int 28, 146, 264…

VT1TRN…VT8TRN

view 1–view 8 transformation matrices

9 dpfp 52, 170, 288…

VTAACZ not used by MicroStation

int N/A

VTACNV not used by MicroStation

dpfp N/A

VTAEXT not used by MicroStation

3 uint N/A

VTAFLG not used by MicroStation

word N/A

VTALEV not used by MicroStation

4 word N/A

VTAORG ACS origin 3 int 1090

VTATRN ACS transformation matrices

9 dpfp 1114



Type 9 Variables

VTDACZ not used by MicroStation

int N/A

VTDCNV not used by MicroStation

dpfp N/A

VTDEXT not used by MicroStation

3 uint N/A

VTDFLG not used by MicroStation

word N/A

VTDLEV not used by MicroStation

4 word N/A

VTDORG not used by MicroStation

3 int N/A

VTDTRN not used by MicroStation

9 dpfp N/A

VWFUL1 view number in full mode screen 1

byte 16

VWFUL2 view number in full mode screen 2

byte 17



Type 9 Variables

Use

r C

omm

and

s 15

VWTABL 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)

8 int8 dpfp8 word8 word9 dpfp8, 8, 8 uint8, 8, 8 int

18, 136, 254…

XAXSCL x-axis scale factor

dpfp 1112

YAXSCL y-axis scale factor

dpfp 1120

ZAXSCL z-axis scale factor

dpfp 1128



Type 66 variables

Type 66 variablesType 66 variables are saved in the MicroStation extended TCB element (type 66, level 9) (see page 18-61) when FILEDESIGN is executed.

TCB Name: Setting: Type:

ACTAB active cell name 2 rad50

ACTPNT active point 2 rad50

ALTAB active line terminator cell name 2 rad50

ALTSCL line terminator scale factor dpfp

ANRDOT angle readout accuracy byte

APANG active pattern angle (rows) dpfp

APANG2 active pattern angle (columns) dpfp

APCOLS active pattern column spacing int

APROWS active pattern row spacing int

APTAB active pattern cell name 2 rad50

APTOL active pattern tolerance int

APTSCL active pattern scale factor dpfp

AXLANG Axis Lock angle increment dpfp

AXLORG Axis Lock start angle dpfp

CELNAM cell file name 128 char


Type 66 variables

Use

r C

omm

and

s 15

EXTLCK Extended locks — bit settings as follows: 0: Axis Lock1: Auxiliary input (stereoplotter, PC only)2: Coordinate display3: Automatic panning with tablet4: Temporarily override Axis Lock5: Stretch cells in fence6: Isometric grid7: Isometric pointer8: Full view pointer9 & 10 clear: Top isometric plane9 set, 10 clear: Left isometric plane9 clear, 10 set: Right isometric plane9 & 10 set: All isometric planes11–12: Reserved13: Single shot viewing command active14: Single shot only command active15: Single shot drawing command active16: ACS Plane Snap Lock17: Data points projected perpendicular to ACS plane18: Active fill19: Isometric Lock20: Reserved21: Intersection snap22: Association Lock23: Use Shared Cells24: Void fence selection25: Fast dynamics26: Snappable patterns27–31: Reserved

int



Type 66 variables

EXVWFL Extended view flags — bit settings as follows:0: Filled shapes, text, lines with width1: Raster text display (Macintosh only)2: ACS triad display3–5: Reserved6: Camera7–9 clear: Wireframe display mode7 set, 8–9 clear: Cross-section display mode7 & 9 clear, 8 set: Wiremesh display mode7 & 8 set, 9 clear: Hidden line display mode7 & 8 clear, 9 set: Filled hidden line display mode7 & 9 set, 8 clear: Constant shaded display mode7 clear, 8–9 set: Smooth shaded display mode7–9 set: Phong shaded display mode10: Background display11: Reference file clipping boundary display12: Fast reference file clipping boundary display13: Depth cueing14: Dynamic update display15–31: Reserved

word

GRDRAT: grid aspect ratio (Y/X) dpfp

KEYPNT snap divisor word



Miscellaneous variables

Use

r C

omm

and

s 15

Miscellaneous variablesMiscellaneous 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


ACCSEC active cell starting sector, byte

2 word

ACORGF active cell origin flag (bit 0)

word

ACSDEF ACS type for definition

byte

ACSNAM active ACS name 2 rad50

ADPSHS dimension stack offset

int

ADPTTR dimension tolerance scale factor

dpfp

ALCSEC line terminator sector, byte

2 word

AMBINT ambient light intensity

dpfp

AMBLGT ambient light status (on/off)

int

ANGBYT number of bytes defining element rotationValue:4: Number of bytes in 2D16: Number of bytes in 3D

word

APCSEC starting sector, byte of active pattern cell

2 word

ARCMIN minimum arc int

ARCOLD array column distance

dpfp

ARCRAD arc radius dpfp

ARCTOL arc stroking tolerance dpfp

ARFILA array fill angle dpfp

ARNCOL rectangular array number of columns

word



ARNITM polar array number of columns

word

ARNROW rectangular array number of rows

word

ARROT polar array rotate byte

ARROWD rectangular array row distance

dpfp

AUXXOR auxiliary input x int

AUYXOR auxiliary input y int

AUZXOR auxiliary input z int

BACKFL view background filename

char

BOWFNT adjacent dimension terminator replacement font

byte

BOWSYM adjacent dimension terminator replacement symbol

byte

BSPORD B-spline order byte

CDXNAM cell library index file name

128 char

CELHND cell file handle int

CELORX user specified x origin of new cell

int

CELORY user specified y origin of new cell

int

CELORZ user specified z origin of new cell

int

CHAMD1 chamfer distance 1 dpfp

CHAMD2 chamfer distance 2 dpfp

CHNTOL tolerance for automatic complex chain/shape creation

dpfp

CLINED construction line distance

dpfp

CLPROT Clipboard rotation (Macintosh only)

dpfp

CLPXSC Clipboard paste scale x (Macintosh only)

dpfp

CLPYSC Clipboard paste scale y (Macintosh only)

dpfp




Use

r C

omm

and

s 15

CMDCLS class of active command1: Placement2: Viewing3: Fence4: Parameters5: Locks6: UserCommand7: Manipulation8: Show9: Plot10: Newfile11: Measure12: Input13: Celllib14: Filedesign15: Compress16: Reference17: Database18: Dimension19: Locate20: Tutclass21: Workingset22: Elementlist23: Undo24: Subprocess25: Viewparam26: Viewimmed27: Windowman28: Dialogman

word




CMDSRC source of active command400: FROM_KEYBOARD401: FROM_CMDFILE402: FROM_TUTORIAL403: FROM_APPLICATION404: FROM_UCM405: TABLET_MENU406: SCREEN_MENU407: FUNCKEY_MENU408: CURSOR_BUTTON_MENU409: PULLDOWN_MENU410: CONTROL_STRIP_MENU411: HIERARCHICAL_MENU413: WINDOW_ICON414: TOOL BOX_MENU415: FROM_STARTUP416: FROM_DIALOG417: FROM_PROCESS418: FROM_MDL419: FROM_PRDFPI

word

CMPOFF offset to located complex component

uint

CONER1 cone radius 1 (top) dpfp

CONER2 cone radius 2 (bottom)

dpfp

CONFRM database multi-row confirmation mode

word

CPRDIS copy/move parallel distance

dpfp

CUGRAF current graphic group–placement

word

CURANG Precision Input settings box Angle field

dpfp

CURCMD active command ID int




Use

r C

omm

and

s 15

D–G

CURDIS Precision input settings box Distance field

dpfp

CURDLX Precision Input settings box DX field

dpfp

CURDLY Precision Input settings box DY field

dpfp

CURDLZ Precision Input settings box DZ field

dpfp

CUREBL sector number of current element in design file

word

CURPSX Precision Input settings box X field

dpfp

CURPSY Precision Input settings box Y field

dpfp

CURPSZ Precision Input settings box Z field

dpfp

CUREBY offset into sector of current element in design file

word

CUREFL file number of current element

word

CURSCR current screen if single monitor

byte


DASTYP: displayable attribute type

byte

DBCTRL database descriptors uint

DBFORM database forms mode word

DCTCHS terminal type word

DFBYTE design file ending byte

word

DFSECT design file ending sector

word

DGNFEX design file extension rad50

DGNFIL design file name 3 rad50




DGNHND design file handle int

DGNNAM design file name 128 char

DIGTRN digitizer transformation

12 dpfp

DIMCEN dimension center mark size

int




Use

r C

omm

and

s 15

DIMCMD current dimensioning commandValue: Command0: None1: DIMENSION SIZE ARROW2: DIMENSION SIZE STROKE3: DIMENSION LOCATION SINGLE4: DIMENSION LOCATION STACKED5: DIMENSION ANGLE SIZE6: DIMENSION ARC SIZE7: DIMENSION ANGLE LOCATION8: DIMENSION ARC LOCATION9: DIMENSION ANGLE LINES10: DIMENSION ANGLE X/Y11: DIMENSION RADIUS12: DIMENSION DIAMETER POINT13: DIMENSION DIAMETER PARALLEL14: DIMENSION DIAMETER PERPENDICULAR15: DIMENSION LINEAR16: DIMENSION ORDINATE17: DIMENSION RADIUS EXTENDED18: DIMENSION DIAMETER EXTENDED19: DIMENSION CENTER

word

DIMCOL dimension color + 1 (0 = Active)

byte




DIMFNT dimension font + 1 (0 = Active)

byte

DIMMAR dimension margin dpfp

DIMSCL dimension scale dpfp

DIMTMP dimension template Int: Bit Settings:0–2: First terminator index3–5: Left terminator index6–8: Right terminator index9–11: Adjacent terminator indexa

12–14: Pre dimension symbol index16–18: Post dimension symbol indexb

15: Stack dimensions19: Arc accent above dimension20: Left witness line21: Right witness line22: Vertical dimension text23: Vertical text when horizontal will not fit24: Center mark (radial dimensioning only)25–31: Reserved

24 int: 1 per command




Use

r C

omm

and

s 15

DIMTXT dimension delimiter charactersDIMTXT(1): Dimension prefixDIMTXT(2): Dimension suffixDIMTXT(3): Tolerance prefixDIMTXT(4): Tolerance suffixDIMTXT(5): Upper dimension prefixDIMTXT(6): Upper dimension suffixDIMTXT(7): Lower dimension prefixDIMTXT(8): Lower dimension suffix

8 char

DIMWGT dimension weight + 1 (0 = Active)

byte

DITTOL locate tolerance byte

DSPBYT byte number of element in display

word

DSPSEC sector number of element in display

word

DTXCOL dimension text color + 1 (0 = Active)

byte

DTXWGT dimension text weight + 1 (0 = Active)

byte

DYNAMC not used by MicroStation

word

EDFCHR enter data field character

byte

ELEBLK block of next element in design file

word

ELECNT offset of next element word

EMMSIZ extended memory to reserve for applications (KB)

word

ENTITY active entity database entity number

word




EXDMFL extended dimension flagsBit Settings:0: Join external dimensions1: Add box around dimension text2: Semi-automatic text placement mode3: Include leading zeros4: Include trailing zeros5: Substitute comma for decimal point6: Include capsule around dimension text7: Superscript least significant digit8: Round least significant digit9: Omit leading delimiter10: Color override11: Line weight override12: Text color override13: Text weight override14: Font override15: Level override16: Text size override17: IGDS-compatible dimensions18 & 19 clear: Open arrowhead18 set, 19 clear: Filled arrowhead18 clear, 19 set: Closed arrowhead20: Reference file units21: Relative dimension line22: Underline text23–31: Reserved

int

EXTDIS extend distance dpfp




Use

r C

omm

and

s 15

FENCE number of fence vertices

word

FENPTS array of fence vertices (max 101 points/100 sides)

202 int

FENRNG fence range (x,y,z) low–high

6 int

FENVW view number containing fence

byte

FILMSK file search mask (obsolete—see FLMASK)Bit Settings:0: Active design file1–31: First 31 attached reference files

int

FILRAD fillet radius dpfp

FLMASK file search maskBit Settings:0: Active design file1–255: Attached reference files

8 int

FLSINT flashbulb intensity dpfp

FLSLGT flashbulb status (on/off)

int

FNTLBM font library bit map 8 word

FNTTRM terminal font bit map 8 word

FNTNAM font library name 128 char




GETCLS command class returned to UCM GET1: Placement2: Viewing3: Fence4: Parameters5: Locks6: UserCommand7: Manipulation8: Show9: Plot10: Newfile11: Measure12: Input13: Celllib14: Filedesign15: Compress16: Reference17: Database18: Dimension19: Locate20: Tutclass21: Working set22: Elementlist23: Undo24: Subprocess25: Viewparam26: Viewimmed27: Windowman28: Dialogman

word




Use

r C

omm

and

s 15

a. In the DIMTMP variable, for bits 9-11, the terminator type is set as follows:Index: Terminator type0: None1: Arrowhead2: Stroke3: Origin4: Dotb. In the DIMTMP variable, for bits 16–18, the symbol type is set as

followsIndex: Symbol type0: None1: Radius2: Diameter

GETCMD command ID returned to UCM GET

int

GETSRC command source returned to UCM GET400: FROM_KEYBOARD401: FROM_CMDFILE402: FROM_TUTORIAL403: FROM_APPLICATION404: FROM_UCM405:TABLET_MENU406:SCREEN_MENU407:FUNCKEY_MENU408:CURSOR_BUTTON_MENU409: PULLDOWN_MENU410:CONTROL_STRIP_MENU411:HIERARCHICAL_MENU413:WINDOW_ICON414:TOOL BOX_MENU415: FROM_STARTUP416: FROM_DIALOG417: FROM_PROCESS418: FROM_MDL419: FROM_PRDFPI

word




H–P


HELPMD help mode word

INDYNM in dynamics flag byte

IXUOR1 scratch design point 1 (x)

int


int


int


int

IYUOR1 scratch design point 1 (y)

int


int


int


int

IZUOR1 scratch design point 1 (z)

int


int


int


int

LOCBSU located B-spline u parameter

dpfp

LOCBSV located B-spline v parameter

dpfp

LOCEND located segment endpoint

3 dpfp

LOCMLN located multi-line number

int

LOCORG located segment origin

3 dpfp

LOCPOS file position of located element

uint

LOCPNT point on located element

3 dpfp



Use

r C

omm

and

s 15

LOCSEG located segment number

int

LOCTBY located component byte

word

LOCTSC located component sector

uword

LOCTYP type of located element

byte

LOCVRT closest located vertex int

LSCANB locate/snap byte pointer

word

LSCANS locate/snap sector pointer

word

LSTCLS last parsed class word

LSTCMD last parsed command long

LSTSRC last parsed source word

LSTVW last point entered, view

byte

LSTXOR last point entered, X int

LSTYOR last point entered, Y int

LSTZOR last point entered, Z int

MAXPOL maximum polygon size (rendering)

int

MAXREF maximum number of reference files

word

MLENAN multi-line endpoint angle

dpfp

MLENCP multi-line endpoint cap symbology (see MLPRSM)

int

MLFLAG multi-line flag word

MLFLCL multi-line fill color byte

MLMDCP multi-line midpoint cap symbology (see MLPRSM)

int

MLNLIN multi-line number of lines

byte

MLORAN multi-line origin angle

dpfp

MLORCP multi-line origin cap symbology (see MLPRSM)

int




MLPRDS multi-line component offsets

16 int

MLPRSM multi-line component symbologiesEach Int Bit Settings:0–2: Line style3–7: Line weight8–15: Color16: Line style override17: Line weight override18: Color override19: Inner arc cap20: Outer arc cap21: Line cap22–23: Reserved24–30: Level31: Construction class

16 int

MSLINK active entity MSLINK key field

int

MSVER MicroStation version number

word

MXGRDP maximum grid points per view

word

MXGRDR maximum grid references per view

word

NDICES number of axes in file (2 or 3)

word

NUMSCR number of physical screens

byte

OF.CLO offset for cell origins word

OF.CLR offset for cell rotations

word

OF.ELO offset for element origin

word

OF.TXN offset for text elements

word




Use

r C

omm

and

s 15

OUTFLG output flagsBit Settings:0–1: Reserved2: Snapped element highlighted3: Allow UCM to get command selection4: Inhibit element display requests5: Reserved6: Inhibit output to design file7–15: Reserved

word

PCOLOR not used by MicroStation

3 word

PERSP not used by MicroStation

8 dpfp

PNTBET points between word

PNTBYT number of bytes in point definition

word

PNTDIS point distance dpfp

POLEDG polygon edges word

POLRAD polygon radius dpfp

PRJSEG segment number of projected point

byte

PRJVW view number of projected point

byte

PRJXOR x UOR projected point

int

PRJYOR y UOR projected point

int

PRJZOR z UOR projected point

int

PRPMSK properties mask for searches

word

PRPVAL properties value for searches

word




R–W


RECORD MSLINK key of the row last located by FIND command

int

REFANG Angle for reference file rotation

dpfp

REFPTR pointer to reference file data

int

REFSCL Scale factors for reference file scaling

3 dpfp

RELERR last error message number

word

RSTLOC restart locate at file beginning

byte

S2CMSC 2nd intersection component sector

uword

S2CMBY 2nd intersection component byte

word

S2FILE 2nd intersection file number

word

S2HDBY 2nd intersection header byte

word

S2HDSC 2nd intersection header sector

uword

SCHEMA file spec of database control file

50 char

SENA00 level symbology mask

word

SMLTXT smallest text word

SMOBUF floating point scratch bufferLongword: Contents1: Measured area of element2: Measured perimeter

9 dpfp

SNAPBY byte number to start snap scan

word

SNAPFL reference file for snap scan

word

SNAPSC sector number to start snap scan

word



Use

r C

omm

and

s 15

SNCMBY snapped component byte

word

SNCMSC snapped component sector

uword

SNPTOL snapping tolerance dpfp

SOLDIR solar light direction dpfp

SOLINT solar light intensity dpfp

SOLLGT solar light status (on/off)

int

SPCABV character spacing along element

int

SRVANG rotation angle for surface of revolution

dpfp

STBL00 level symbology 63 words

STRDEL stream delta int

STRKTL rendering stroke tolerance

dpfp

STRSEP stereo separation (pixels)

int

STRTOL stream tolerance int

TAGADR address of first character of tag

word

TAGBIN binary value of tag word

TAGDEL auto-tag delta to increment tag

word

TAGLEN length of tag word

TMATRX transformation matrix 9 dpfp

TPNPTS number of entries in tentative point table

word

TPTABL tentative point history tables

6 int

TPTVW view numbers of tentative points 1 & 2

2 byte

TRABYT number of bytes in cell transform matrix

word

TSKSIZ conventional memory to reserve for applications (Kb)

word

TUTFNT tutorial font word

TUTNAM tutorial name 2 rad50

TUTSEC tutorial sector word



DGNBUF variables

DGNBUF variablesWhen 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).

TXSCRN BIOS screen (PC only)

word

TYPMSK type mask for searches

4 word

UCINAM UCM index filename 128 char

VT1ANG…VT8ANG

view camera angle (radians)

dpfp

VT1CAM…VT8CAM

view camera position 3 dpfp

VT1FOC…VT8FOC

view camera focal length

dpfp

WINMOD save function name in window command

uint

WITEXT Extension line extension distance

dpfp

WITOFF Extension line offset dpfp

WRKFIL work filename (Macintosh manual save mode only)

128 char

WSSECT working set starting sector

word

WWBYTE working window starting byte

word

WWFILE working window file word

WWSECT working window starting sector

word



DGNBUF variables

Use

r C

omm

and

s 15

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


_DATE date 2 char

_FTIME seconds 4 dpfp

_IGDSZ size of element in DGNBUF (file units)

word

_TIME system time 3 char

BYTLEN element number of words to follow

word

ID.CNT element index to attribute entity

word

ID.GRF element graphic group number

word

RANGEE element rangeRANGEE (1): XLOWRANGEE (2): YLOWRANGEE (3): ZLOWRANGEE (4): XHIGHRANGEE (5): YHIGHRANGEE (6): ZHIGH

6 int

SY.CNT words-in-description (complex header)

word

SY.DSP display symbologyBit Settings:0–2: Line style3–7: Line weight8–15: Color

word


DGNBUF variables

Element-specific DGNBUF variables

SY.PRO properties indicatorBit Settings:0–3 clear: Primary class0, 2–3 clear, 1 set: Construction class 4–7: Reserved8: Not locked9: New10: Modified11: Database attributes present12: Oriented relative to screen13: Non-planar14: Non-snappable15: Hole (not solid)

word

UELETY element type (deleted if bit 7 is set)

byte

XYZLEV element level (complex component if bit 7 is set)

byte


AR.OG3 arc origin (3D) 3 int

AR.ORG arc origin (2D) 2 dpfp

AR.ROT arc rotation angle (2D)

int

AR.RT3 arc quaternion (3D) 4 dpfp

AR.SMJ arc semi-major axis dpfp

AR.SMN arc semi-minor axis dpfp

AR.STA arc start angle int

AR.SWA arc sweep angle int

BB.NPT B-spline surface boundary number of points

word

BB.NUM B-spline surface boundary number

word



DGNBUF variables

Use

r C

omm

and

s 15

BB.PNT B-spline surface boundary points

n int

BC.CNT B-spline curve words-in-description

int

BC.NKN B-spline curve number of knots

word

BC.NPO B-spline curve number of poles

word

BC.PAR B-spline curve flagsBit Settings:0–3: Order4: Curve display5: Control polygon display6: Rational7: Closed

byte

BC.TYP B-spline curve type byte

BK.KNO B-spline knots n int

BP.NPO B-spline number of poles

word

BP.POL B-spline poles 101 int

BS.CNT B-spline surface words-in-description

int

BS.NBO B-spline surface number of boundaries

word

BS.NKU B-spline surface number of knots in u direction

word

BS.NKV B-spline surface number of knots in v direction

word

BS.NPU B-spline surface number of poles in u direction

word

BS.NPV B-spline surface number of poles in v direction

word



DGNBUF variables

BS.PRU B-spline surface u flagsBit Settings:0–3: Order4: Surface display5: Control net display6: Rational7: Closed

byte

BS.PRV B-spline surface v flagsBit Settings:0–3: Order4–5: Reserved6: Equal arc spacing7: Closed8–15: Reserved

word

BS.RLU B-spline surface number of rule lines in u direction

word

BS.RLV B-spline surface number of rule lines in v direction

word

BW.WGT B-spline weight factors

n int

CL.CLS cell class bit map word

CL.LVL cell level bit map 4 word

CL.NAM cell name 2 rad50

CL.OG3 cell origin (3D) 3 int

CL.ORG cell origin (2D) 2 int

CL.ROT cell transformation matrix (2D)

4 int

CL.RT3 cell transformation matrix (3D)

9 int

CL.VER cell range diagonalCL.VER(1): XLOWCL.VER(2): YLOWCL.VER(3): XHIGHCL.VER(4): YHIGH

4 int

CL.VR3 cell range cube diagonalCL.VR3(1): XLOWCL.VR3(2): YLOWCL.VR3(3): ZLOWCL.VR3(4): XHIGHCL.VR3(5): YHIGHCL.VR3(6): ZHIGH

6 int



DGNBUF variables

Use

r C

omm

and

s 15

CO.NVR number of vertices word

CO.VER vertices n int

CS.NEL complex chain—number of elements

word

CU.NVR curve number of points

word

CU.VER curve coordinates n int

CX.NEL complex shape—number of elements

word

DGNBF1 plot buffer 1 128 word

DGNBF2 plot buffer 2 128 word

DGNBFF dpfp scratch buffer 64 dpfp

DGNBUF element work buffer 256 word

EL.OG3 ellipse origin (3D) 3 dpfp

EL.ORG ellipse origin (2D) 2 dpfp

EL.ROT ellipse rotation angle (2D)

int

EL.RT3 ellipse quaternion (3D)

4 int

EL.SMJ ellipse semi-major axis

dpfp

EL.SMN ellipse semi-minor axis

dpfp

GR.DES group description word

GR.RAD group description 13 rad50

LH.DES cell description 10 rad50

LH.DSP display symbology word

LH.PRO cell header properties indicator

word

LN.BEG line coordinates n int

LS.NVR line string number of vertices

word

LS.VER line string coordinates

n int

PS.NVR point string number of vertices

word

PS.VER point string coordinates

n int

TC.BOR truncated cone base origin

3 dpfp



DGNBUF variables

TC.BRA truncated cone base radius

dpfp

TC.ROT truncated cone orientation

4 int

TC.TOR truncated cone top origin

3 dpfp

TC.TRA truncated cone top radius

dpfp

TC.TYP truncated cone typeValue:0: General cone1: Right cylinder2: Skewed cylinder3: Right cone4: Skewed cone5: Right truncated cone6: Skewed truncated cone

word

TN.ALN text node maximum allowed line length

byte

TN.FON text node font number

byte

TN.JUS text node justificationValue:0: Left/top1: Left/center2: Left/bottom3: Left margin/top4: Left margin/center5: Left margin/bottom6: Center/top7: Center/center8: Center/bottom9: Right margin/top10: Right margin/center11: Right margin/bottom12: Right/top13: Right/center14: Right/bottom

byte

TN.NEL text node number of strings in node

word

TN.NOD text node number word

TN.OG3 text node origin (3D) 3 int

TN.ORG text node origin (2D) 2 int



DGNBUF variables

Use

r C

omm

and

s 15

TN.ROT text node rotation angle (2D)

int

TN.RT3 text node quaternion (3D)

4 int

TN.SCF text node scale factors

2 int

TN.SPA text node line spacing

int

TN.ULN text node used line length

byte

TX.ED3 text number of enter data fields (3D)

byte

TX.EDF text number of enter data fields (2D)

byte

TX.FON text font number byte

TX.JUS text justificationValue:0: Left/top1: Left/center2: Left/bottom3–5: Text node only6: Center/top7: Center/center8: Center/bottom9–11:N/A text12: Right/top13: Right/center14: Right/bottom

byte

TX.LET text characters (2D) n byte

TX.LT3 text characters (3D) n byte

TX.NC3 text number of characters (3D)

byte

TX.NCH text number of characters (2D)

byte

TX.OG3 text origin (3D) 3 int

TX.ORG text origin (2D) 2 int

TX.ROT text rotation angle (2D)

int

TX.RT3 text quaternion (3D) 4 int

TX.SCF text scale factor 2 int



RELERR Messages

RELERR MessagesWhen 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: Message text:

7 File not found

12 Library not found

15 No fence defined

16 Invalid character

18 Named view not found

18 Illegal value - reenter

19 No active cell

20 Maximum element size

21 Element not found

22 Element off design plane

23 Illegal definition

27 Enter characters first

29 Invalid tag

31 Tag overflow

35 Maximum text length

39 3D-only tool

43 Cell nesting error

44 Cell not found

47 Invalid cell name

50 3D cell library, 2D file

54 No cell library attached

55 Cell already exists

56 No cell origin defined

57 No elements found

57 No elements in cell definition

58 Cell added to library

59 Cell deleted

60 Cell renamed

62 Element too large

67 No line terminator defined

68 Accept/Reject (select next input)

71 Named view not found


RELERR Messages

Use

r C

omm

and

s 15

Database RELERR messages (Oracle)

81 Add to existing group (Accept/Reject)

82 Add to new group (Accept/Reject)

87 Text node not found

196 Select view

265 Menu cell must be 2D

268 Valid menu text node not found

269 Bad menu cell

270 Invalid menu type

271 Bad menu block

272 Menu text node error

287 File is read only

287 File is locked by another user - Read Only

384 Tutorial not found

481 Illegal operation on 1-1 ref file


4000 Allocate database memory

4001 Command line syntax error

4002 No active entity defined

4003 Record not written to database

4004 No database linkage present

4005 Unable to generate report file

4006 No entity specified

4007 No MSLINK column in table

4008 Unable to open report file

44009 Entity number out of bounds

4010 Screen form file not found

44011 NULL linkage generation mode

4012 File not found

4014 Unable to locate database

4015 Unable to read MSCATALOG table

4016 More than one row returned by FIND

4017 Not a Select statement

4018 Database is not valid

4019 No rows returned from FIND

4020 No MSLINK column in the table



RELERR Messages

4021 Illegal format of MSCATALOG

4022 Unable to review attributes

4023 Bad review table

4024 Table not present in MSCATALOG

4025 Unable to update MSCATALOG table

4026 Bad report specification

4027 Bad MSLINK key in DBREAD/DBWRITE

4028 Bad fence filter


4030 No more slots for tasks

4031 Unable to create message queue

4032 Column number out of bounds

4033 Illegal scan comparison code

4034 Illegal types in MS_LINKTYPE

4035 Bad data type during DB_GETFMT

4036 Bad CONNECT statement format

4037 Error assigning MSLINK

4038 Error building “ae” table

4039 Error loading “ae” table

4040 No rows returned by SELECT

4041 RUNFORM program not found

4042 Screen form not found

4043 Illegal forms command

4044 No DAS table for this entity

4045 RUNFORM echo file not found

4046 Error starting SQL*FORMS

4047 No SQLFORMS output file found

4048 No entry in DAS table

4049 Invalid form command entered

4050 Allocation error for descriptor

4051 Error opening resource file

4052 Not logged in

4053 SQL error during table describe

4054 Descriptor larger than message

4055 Row larger than message packet

4056 Fetch failed, no active query

4057 No form defined for DAS type



RELERR Messages

Use

r C

omm

and

s 15

Database RELERR messages (Xbase)


4000 Open control database

4001 Illegal control file format



4004 FIND unable to use entity or field name

4005 Unable to locate record in database

4006 Unable to read record from database



4010 Unable to generate key for index file

4011 No database linkage present in element

4012 Database for entity not currently open


4014 No fields identified on edit page


4016 Database file not found

4017 Unable to open database file

4018 Not a valid database file

4019 Unable to locate master index file: %s

4020 Unable to open master index file

4021 Master index is not a valid index file

4022 Master index file not keyed to MSLINK

4023 Structure does not contain MSLINK


4025 Entity number out of bounds

4026 Invalid number

4027 Conversion error

4028 Format file not found


4030 Index expression is compound

4031 Index field is not in the database

4032 Index must be character,numeric,date

4034 Bad entity number or alias during FIND

4035 Bad field number or name during FIND

4036 Database control file not defined



RELERR Messages

Database RELERR Messages (INFORMIX)

4038 Filter index file not found

4039 Filter index file not valid

4040 Unable to open filter index file

4041 Filter index file key not MSLINK

4042 File not found

4043 Database or entity number not found

4044 Read control database

4045 Unable to assign MSLINK key

4046 May not read/write memo fields

4047 No records in the control file

4048 Unable to lock database file

4049 Unable to lock index file

4050 No user MSLINK index files

4051 No table found in SELECT

4052 No column value found in SELECT

4053 =,<,>,>=,<=,<> not found in SELECT

4054 Trailing single quote not found

4055 No where clause in SELECT

4056 No field in where clause of SELECT

4057 Statement not recognized

4058 No rows returned by SELECT







4004 No database linkage present



4007 No MSLINK linkage field


4009 Entity number not between 0 and 65535

4010 Screen form file not found




RELERR Messages

Use

r C

omm

and

s 15

4012 File not found

4013 SQL error code

4014 Unable to locate database

4015 Unable to read MSCATALOG table

4016 More than one row from FIND

4017 Not a Select statement


4019 No rows returned from FIND

4020 No MSLINK column

4277 Unknown ESQL error message

4278 Illegal format of MSCATALOG

4279 Unable to review attributes

4280 Bad review table

44281 Table not present in MSCATALOG

4282 Unable to update MSCATALOG table

4283 Bad report specification

4284 Bad MSLINK key in DBREAD/DBWRITE

4285 Database not found


4287 No more slots for applications

4288 Unable to create message queue

4289 Column number out of bounds

4290 Illegal scan comparison code


4292 Illegal data type in DB_GETFMT

44293 Unable to set MSLINK

4217 Column not found in any table



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-insThese 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:

◆ 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):

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

➤ To simulate a key-in in a MicroCSL application:

◆ Call the prdfpi routine with subrequest 1008.

➤ To simulate a key-in in an MDL application:

◆ Call the built-in function mdlInput_sendKeyin.:

Example /* Beep speaker with simulated BEEP command key-in. */mdlInput_sendKeyin ("BEEP", 0, INPUTQ_EOQ, ustnTaskId);


Application Commands

Use

r C

omm

and

s 15


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 DEFAULTAttaches 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.



FLUSHCloses 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.

INDEXCreates 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.



Use

r C

omm

and

s 15

➤ To place a point string:

1. Activate PLACE POINT STRING [CONTINUOUS | DISJOINT].

2. Send a data point to define a vertex.

3. Continue sending data points to define other vertices.

4. Send a Reset to end the point string.

SET PLOTTEROpens 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 (0–255). This is useful in applications that use raster backgrounds.

SHOW EOFDisplays the location of the active design file’s 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 UORSActivates 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.

Last keyword: Point string is displayed:

CONTINUOUS With lines connecting the vertices (same as a line string)

DISJOINT As a set of discrete points



UNDO ALL NOCONFIRMNegates all drawing operations recorded in the undo buffer. MicroStation does not request confirmation as it does when the user chooses All from the Edit menu’s 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.


microstation v8 xm

Documents