written by Sumbera, S., Nov. 2002

4. MDL API

MDL API functions and built-in variables overview

An MDL Application Programming Interface (MDL API) is a set of functions and variables declaration in which MicroStation provides its functionality to third part software developers. Main purpose of the API is to spare from programmer the need to write software for MicroStation at very low level. MDL API achieving first level of abstraction from the fundamental MicroStation functionality.

MDL API library is one of the core parts in MDL framework. MDL API functions are often denoted as built-in functions because the API function itself is just exposed internal MicroStation rutine. These same built-in functions are part of the MicroStation executable and are used by Bentley programmers to develop MicroStation essential components as well. Hence as the MDL developer, you has more or less the same possibilities to control MicroStation as Bentley do, exluding undocumented functions, of course.

MDL runtime and API functions reside in a bunch of Dynamic Link Libraries (DLL), so they are executed directly as a native code. This is important for performance. A few API libraries (actually about 14) are designed as MicroStation Shared Libraries (MSL) which are interpreted.

We may divide all API functions into 4 major groups:

• CAD engine functions
• System and utility functions
• Database functions
• Graphical user interface GUI

Typicaly these functions have commonly syntax:

mdl + area of interest + underscore + operation

however there are two exeptions in prefix : dynamic link modules functions have prefix dlm and embeded arrays functions have prefix jmdl

Context of MDL execution. MDL in a form of p-code is interpreted by MDL runtime. MDL API reside either in native code as DLL or in interpreted MicroStation Shared Libraries (MSL). MDL can interact with dynamic link modules – the term for user DLL. All components run in process of MicroStation.

MDL API function overview (not complete)

Displayable element functions

Area of API	#	fdf file	API function prefix	Comment
B-spline functions	152	msbsplin.fdf	mdlBspline_	used to create and manage B-splines
Accudraw	1	mdllib.fdf	mdlAccudraw_	for Accudraw optimalization
Cell functions Shared Cell functions	42 21	mscell.fdf msscell.fdf	mdlCell_ mdlCellIterator_ mdlSharedCell_	used to read, iterate, create, manipulate or delete cells in a cell library. and to place celss in a design file
Element change tracking	2	changetrack.fdf	mdlChangeTrack_	enables monitoring of all changes in DGN file
Element creation	20	mselemen.fdf	mdl..._create	used for element creation ( Arc, Circle, Cone, Curve, Ellipse, Line, LineString, PointString, Shape, Surface, Text, TextNode, ComplexChain)
Element information extraction	13	mselemen.fdf	mdl..._extract	used to extract information from specific element types.
Element common functions	43	mselemen.fdf	mdlElement_	used to common single element operations
Element intersection	4	msmisc.fdf	mdlIntersect_	Serves as API for intersection between elements
Element modification	4	msmisc.fdf	mdlModify_	allows to modify single element or element descriptors
Element descriptor functions	105	mselmdsc.fdf	mdlElmdscr_ mdlCopyContext_	used to operate with component elements of complex elements.
Element clipping	5	msmisc.fdf	mdlClip_	enables to clip elements.
Element association	23	msassoc.fdf	mdlAsoc_	provide access to the element association capabilities used to create association points in dimensions, multi-lines, and shared cells.
Element linkage	34	mslinkge.fdf	mdlLinkage_	allows assign, modify , delete or extract database linkage of element
Multi-line elements	21	msmline.fdf	mdlMline_	used to create and modify multi-lines elements
Measurments functions	8	msmisc.fdf	mdlMeasure_	retrieves basic measure properties of element descriptor.
Transient elements	14	mstrnsnt.fdf	mdlTransient...	provides API for transitional elements
Dimensioning element Function	23 28	msdim.fdf msdimstyle.fdf	mdlDim_ mdlDimStyle_	used for element dimensioning operations
Nested Element instances presentation	30	msdisplaypath.h	mdlDisplayPath_	enables manage multiple instances of element in reference files or cells.
Element reference	30	elementref.h	elementRef_	enables uniquely identify element within session
Surface creation	7	mselemen.fdf	mdlSurface_	used for surface operations
Patterining	8	msmisc.fdf	mdlPattern_
Mesh elements	71	msmdlmesh.fdf	mdlMesh_	used for facet geometry

Element search

Loacate elements	40	mslocate.fdf	mdlLocate_ mdlAutoLocate_	enables locate elements.
Scanning	62	msscan.fdf msscancrit.fdf	mdlScan_ mdlScanCriteria_	API for scanning file for elements
Snapping	19	mslocate.fdf	mdlSnap mdlAccuSnap_	enables snaps to elements either by tentative point or automatically as the cursor pass over elements.
Hit list	10	mshitpath.h	mdlHitPath_	logic to finds all elements in a view that are near a test point.

Container functions

Matrix storage	26	msmdlmatrix.fdf	mdlMatrix_	serves as container for matrices of numbers.
Embedded Arrays	165	embedded....fdf	jdmlEmbedded....	provides various value linear containers
Dynamic arrays	13	msdarray.fdf	mdlDArray_...	provides simple dynamic arrays
String List	37	msstrlst.h rmgrstrl.h	mdlStringList_ strlist_	enables to use string lists as dynamic array

User interface

Input handling functions	23	msinput.fdf	mdlInput_	API for input management
Output handling	47	msoutput.fdf	mdlOutput_	API for message output

State control	21	msstate.fdf	mdlState_	enables state control functions
Windows functions	87	mswindow.fdf	mdlWindow_	general windows management, drawing and docking
Function key	9	msmisc.fdf	mdlFuncKey_	manage Func key menu.
Dialog box and Dialog item functions	705	msdialog.fdf ditemlib.fdf msritem.fdf htmllib.fdf miscilib.fdf ..and otheres	mdlDialog_	API for Dialog boxes and dialog items
View handling	193	msview....fdf	mdlView....	enables view and view group management
Digitizer function	3	msinput.fdf	mdlDigitize_	handling digitizer events

Resources

Resource management	25	msrmgr.h	mdlResource_	API for resiurce management
Parse command table	10	msparse.fdf	mdlParse_	Command table fucntions

Interoperability

C Expression	18	mscexpr.fdf	mdlCExpression_	enables evaluate C expressions at runtime
BASIC interface	3	msbasic.fdf	mdlBasic_	used for BASIC macro information
inter program communication	19	extprg.fdf	mdlExternal_ extprg_	Enables external programs to communicate with Microstation
Dynamic link modules	14	dlmsys.fdf	dlmSystem_	allows smooth interoperability with DLM(DLL) and MDL

System

MDL system	85	mssystem.fdf	mdlSystem_	API for miscellaneous MDL system functions, handling events and configuration of variables
Undo API	9	msundo.fdf	mdlUndo_	management of redo/undo functions
Version	2	msver.fdf	mdlVersion_	extract information about current running version of platform and MicroStation
License API	14	mslicens.fdf	mdlLicense_	enables queries on license information
Active setting functions	4	msmisc.fdf	mdlParams_	switches Microstation active parameters

..and many other functions...

MDL built-in variables

MDL API doesn’t contain only functions, it has also bunch of global variables that may be accessed in your MDL applications. You may think of this variables as a shared memory between MicroStation and MDL applications. Although these global variable’s names and types are known to the MDL compiler so you need not to explicitly declare them in MDL program, is is good coding practice to declare them as extern, especially if you plan to compile MDL code into native library.

Many of these built-in variables are structures or unions. For example, the variable tcb (terminal control block) is a pointer to a structure containing much of the information concerning the current design file.

In the following table, if the variable has a derived type, the name of the include file
that contains the definition is specified.

MDL Variable Types

Variable	Type	Description
dgnBuf	MSElement*	Holds all the information on the current element in dgn-buf. All elements are loaded into this buffer by a locate or element manipulation commands.
statedata	MSStateData	Contains all the information on the current state function. Defined in global.h
tcb	Tcb*	“Terminal Control Block” holds all the information on the current DGN file. Defined in tcb.h
mgds_modes	Mgds_modes	Contains the mode information about the current execu-tion of MicroStation. Defined in <global.h>
graphConfig	MSGraphConfig	Contains the graphics configuration. Defined in global.h
mdlCommandNumber	long	Contains the command number of the most recently started MDL application command.
userPrefsP	UserPrefs*	Contains miscelaneous user preferences. Defined in userpref.h
mgdsPrompt[35]	char	Holds the text for the prompt. The default is "uStn>".
render_designLightP	void*	Allows to define custom light source for rendering. ligh source is defined in light.h
msTransientElmP	TransDescrP	A general purpose transient descriptor
mdlErrno	int	Error number for various MDL functions

Built-in floating point constants

In addition to these built-in variables, MDL has a number of built-in floating point
constants that are frequently used. They have prefix fc_ and complete list you may find in msvars.fdf For example:

mail comments to stanislav@sumbera.com