Getting Started With MDL (Microstation Development Language) Programming

First chapter, the basic methods MDL Programming

The MDL language is for the C programming language, therefore, we have a look at the C programming language; the basic methods and how to use them inside MDL Law. The iintent of this chapter is not to teach you how to use the C language programming, there are many books about that. We assume that the reader is already familiar with the C programming language, it only involves a number of necessary MDL C functions. Here we discuss the basic methods of MDL programming.

The basic concept

The MDL language is a structured programming language for building an application of the standard commands, functions and objectives. We would like to briefly describe the MDL as in the following.

MDL is a language that uses C structures, with its own run-time libraries, compiler, linker, library management process Sequence, and Micro Station environments.

This book will go beyond the programming language MDL. It is a foundation for developing Micro Station Application tools. Before we begin the preparation of MDL code, we should have some terminology, standards and conventions clear.

MDL program structure

The MDL procedure is a MDL language in accordance with the rules of combining a collection of statements. Program statements include the following:

• ? Control structure or description (declaration) statements
• ? Assignment Statements
• ? function / procedure call statements
• ? pre-processing directives
• ? Notes

These statements are combined into the MDL program as a text file, using the extension ". Mc". We write an MDL program with a string to draw a box around the same time, extending from the box on a lead. We will see it as a typical MDL program
example. We will then use the new elements to make a unit. The program name is "plbox.mc" (see Figure 1.1). There are vmany ways to write this program. While you read this book you will note there are many changes in this program, complete the procedures listed in this chapter.

Finally, we will learn it step-by-step.

Notes

Note that the purpose is for the reader to understand the procedure, but also to enable programmers to modify the program to understand the procedure functions. The forward slash and asterisk (/ *) starts, and the opposite sign (* /) ends a comment. The The compiler will ignore the comments. MDL does not support nested comments.
In Micro Station V8, of course, it is also possible to use double slashes (/ /) on a single line for comments.

Contains the file

Contains the file is such a file that is included in the compile-time pre-processing program read into the program for use of the MDL source code. Sometimes also called the header include file documents, because they are at the beginning of the source.

We can put the common constants in a separate document, then various programs can include this file to ensure that these constants are consistent. There are two definitions of the include file method:

# include <mdl. h>


Figure 1.1 PLBOX the results of running

The convention is to use ". H" for the file extension. If you use angle brackets then the pre-processing program attempts MDL contains mesh Recorded.

Bentley \ Program \ Micro Station \ mdl \ include will find the <mdl. h> file.

Or, we can put the file name in quotation marks, that informs the preprocessing program to contain the file that contains the file description statements directory to find the package with the file.

# include "plbox.h" / * Generated by "rcomp-h plbox.r" * /

How do we know which one to use with documents? All the file names are listed in the <<MDL ??>. For example, when we use mdlText_extractShape, it must contain the <mselems. h> file. These documents can be included within Micro Station.

In the ... Bentley \ Program \ Micro Station \ mdl \ include directory to find.

In the Plbox. mc program, will use the following include files:

/*----------------------------------------------------------------------+

? Include Files ?

+----------------------------------------------------------------------*/

#include <mdl.h> /*system include files*/

#include <global.h>

#include <mselems.h>

#include <userfnc.h>

#include <rscdefs.h>

#include <tcb.h>

#include <plbox.h> /*Generated by rcomp:h plbox.r" */

Finally, an include file plbox.h should arouse attention because it consists of a resource file compiled betrayals. The second chapter has further explanation of the Resource file.

Micro Station V8 introduced the new file type ". Fdf", they are function definition files (Function Definition File). These documents contain certain category MDL function prototypes definitions, while another might include files references. Therefore, for V8 programming you will see we often simply procedures beginning contains these. Fdf documents do.

Variable Description

We use a variable before you must first define it. In most cases, at the beginning of program design we will not know which variables will be used. In this section we assume you already know what variables aree needed. Using MDL there are many approaches for definitions of variables, we wll see the basic concepts for explanation.

Definition of variables

The term "variable" means that names and memory addresses are linked. The amount of memory needed to store the variable depends on the variable type. The term "address" iindicates a variable storage address. For example, the value of an integer variable count is 20, its address is given by the & count. That is, the "&" symbol is the number back to count the address, rather than count the value of, this is a very important concept. Many programmers do not understand variables and that leads to errors. It addresses the meaning of the program generated many problems.
MDL is a language-sensitive pairs of uppercase and lowercase letters. When you define a variable or function name it should be firmly borne in mind. For example, the variables linePts and LinePts are different.

Variable Types

How variable the variable type definitions for storage and which operate it. The basic variable types are short, int, float,doublet, and char.

The following table defines the various MDL variable types.

Types of storage values:

Variable scope

Variable description of the scope of the definition of variables for which part of the program. In order to determine the scope of variables, an MDL program source code according to the level Divided into many pieces.

A block can be a program or a function. The entire file can be considered as a block. Blocks can be nested in other blocks, so a block in the external variables are defined by all nested blocks recognition. An internal block defined in the variable name with an external block.

Variable the same name

In this case, the internal block variable will replace the external block variables, but this is only limited in-house within the scope of the block.

In this case, the internal block variable is considered local variables. Their values and their presence only by those who explain the function of the commitments that they Recognition. Global variable was MDL program for your recognition of all the functions.

Static variables and automatic variables

A variable has a storage type. Categories decide how to store a variable storage, how long it lives, as well as in the program where the variable names can be be referred to. If we describe the function of a variable to not do special treatment then it is an automatic variable. This means that when we call a function, the variable is automatically generated, when we leave this function it is abandoned. Sometimes, the need to retain the function is assigned to local variables. The final value of the static modifier static compiler directives are stored from a call to the next call to a local variable's value. A default variable is automatically a variable. Global variables may be static (in the MDL source module called by any recognized, but not by other source modules used).

If a global variable is not described as static then it can also be used by other source modules. In our example PLBOX, we need to define two functions for all of our global variables, we need to accommodate 128 to define a string variable textin, it is noteworthy because the "type" buffer is of 128 characters.

They define variables pntP to hold the data points.

/*------------------------------------------------------------+

¦ Private Global variables ¦

+------------------------------------------------------------*/

static char textin[128];

Dpoint3d pntP[2];

MDL internal variables

MDL provides global variable for our programs. Since they loaded in the compilation process, we need not go through the definition of a direct with these variables. Many internal variables are the structure or joint. For example, the variable * tcb is a design document that contains all the current information in a knot structure. If an internal variable with a simple type, such as int, contains the header files then it does not need to. However, if the internal type is a structure or union or a structure or union pointer points to, then it must include the appropriate header files. Details on the header files please refer to the appendix.

MDL function

There are two kinds of function types, pre-defined functions and generated functions. In order to use a function, you can access it must be set before the Meaning it. In order to use the predefined function, must be the beginning of our consultation document have the correct include files. MDL offers two different sets of pre-defined functions, namely, the standard C function and MDL-specific functions (with prefix mdl).

This book does not include the interpretation of the standard C function. You can find them in many C language tutorials. MDL supports the following standard C functions.

File operations, input and output: fclose, leof, ferror, fflush, fSetc, fgets, fopen, fprintf, fputc,fputs, fread, freopen, fscanf, fwrite, fseek, ftell, getc, printf, putc, remove, rename, rewind,sscanf, setbuf, setvbuf, sprintf, tmpfile, tmpnam, ungetc, unlink, vfprintf, vprintf, vsprintf.

This book does not include the interpretation of the standard C function. You can, in many C language tutorial to find them. MDL supports the following character classification and conversion:

isalmum, isalpha, iscntrl, isdigit, isgraph, islowcr, isprint, ispuct, isspace, isupper, isxdigit, toascii, tolower. toupper.

String Manipulation: strcat, strchr, strcmp, strcmpi, strcpy, strcspn, strlen, strlwr, strncat, strncmp, strncpy, strpbrk, strrchr, strspn, strstr, strok, strupr.

Cuncun allocation, buffer management and data conversion: atof, atoi, atol, calloc, exit, free, getenv,malloc, memchr, memcmp, memcpy, memmove, memset, rand, realloc, srand, strlod, strol, strloul.

Math: acos, asin, atan, atan2, ceil, cos, cosh, exp, labs, flooy, fmod, frexp, log, log1O, ldexp, ntodf, pow, sin, sinh, sqrt, tan, tanh.

Date and time: sctime, ctime, difftime, gmtime, localtime, strftime, time.

Variables: va_arg, va_end, va_start. MDL supports ANSI and K & R control variable approach.

main Function

Although not an MDL program must contain a main function, it is rare for there to be no main function. In MDL the main function serves three kinds of purposes.

Main is the initial entry. It is essentially an initial function. The main function returns to Micro Station when the MDL program is still resident (except for a program to uninstall MDL).

Main ()

{

RscFileltandle rfHandle;

/*load our command table */

if(mdlparse_loadCommandTable (NULL)= NULL)

mdloutput_error ("Unable to load command table.");

mdlResource_openFile (&rfHandle,NULL, FALSE);

mdloutput_prompt ("Key-in in place BOX to execute");

}

The main function will load the command table Micro Station. In the next chapter we will discuss the order form and resource file.

Display Information

The Micro Station command window can display the information divided into six areas. These six areas are, the wrong information domain (er-ror), prompted the domain (prompt), the command field (command); type the domain (keyin), information field (message), and the status field (status).

• If the tcb-> control.inh_msg Set to a non-zero value, we can ban all the information sent to these domains.

• If the tcb-> cont, such as rol.inh__err set to a non-zero value, letter Number of mdlOutput__error will not display information.
  
  Information function are summarized as follows:
  

• mdlOutput_ error In the command window to display information within the designated areas

• mdlOutput_ prompt

• mdlOutput_ command

• mdlOutput_ keyin

• mdlOutput_ status

• mdlOutput_ errorU In the command window to display information within the designated areas, these functions ignore the ban-bit

• mdlOutput_ promptU

• mdlOutput_ commandU

• mdlOutput_ keyinU

• mdlOutput_ messageU

• mdlOutput_ statusU

• mdlOutput_ printf According to parameters MSG_MESSAGE,MSG_ERROR,MSG_PROMPt,MSG_STATUS, MSG_COMMAND And MSG_KEYIN
  
  In any one field as specified in the command window to display information.
  

• mdlOutput_ vprintf As above, but according to format string to display information

• mdlOutput_ rscPrintf In the command window displays Messagelist within the Resource Information

• mdlOutput_ rscvPrintf As above, but according to format string to display information
  

Structure and joint

Structure allows us to value various types of relevant combinations. As we will see MDL include file, due to ease of use, the structure has been widely used. In the The following examples, we have defined a structure called the elm_ hdr, and generated a type ELm_ hdr. Here the preprocessor directives # if, # else and # endif are in the following chapter.

/*----------------------------------------------------------------+

¦ ELement Header structure-common to all Micro Station elements ¦

+ ---------------------------------------------------------------*/

typedef struct elm_hdr

{

UInt16 type; /* element type */

#if !defined (BITFIELDS_REVERSED)

UInt16 reserved:6; /* reserved for future flags - always 0 */

UInt16 archive:3; /* modified or added and not yet committed to history; or conflict*/

UInt16 deletedCmplxHdr:1; /* deleted complex by header */

UInt16 nonModel:1; /* true if this element is file-specific and does not belong in any model */

UInt16 locked:1; /* element is locked */

UInt16 isGraphics:1; /* element is a graphics element, has Dsp_hdr */

UInt16 isComplexHeader:1; /* is a complex header, must have number of elements following its header */

UInt16 complex:1; /* this element is part of a complex element */

UInt16 deleted:1; /* this element is deleted */

#else

UInt16 deleted:1; /* this element is deleted */

UInt16 complex:1; /* this element is part of a complex element */

UInt16 isComplexHeader:1; /* is a complex header, must have number of elements following its header */

UInt16 isGraphics:1; /* element is a graphics element, has Dsp_hdr */

UInt16 locked:1; /* element is locked */

UInt16 nonModel:1; /* true if this element is file-specific and does not belong in any model */

UInt16 deletedCmplxHdr:1; /* deleted complex by header */

UInt16 archive:3; /* modified or added and not yet committed to history; or conflict */

UInt16 reserved:6; /* reserved for future flags - always 0 */

#endif

UInt32 elementSize; /* number of words in element */

UInt32 attrOffset; /* offset (in words) from start of element to attributes */

UInt32 level; /* element level */

ElementID uniqueId; /* unique ID of element */

double lastModified; /* last time this element was changed */

} Elm_hdr;

In order to use this structure, we must define the variable type ELm_ hdr, and use the dot operator to access it.

For example, we define the type ELm_ hdr variable hdr:

ELm_ hdr hdr;

In order to change elements of the layer, we will use the statement:

hdr.level=3

Elements of the Joint

The joint is a special structure, that allows a variable to store multiple types of values. However, there is only one value at any time that can use this variable, that in the Fortran language, the equivalent of "equivalence." TCB variables UCBYT, UCWRD and UCASC are examples of the concept of a joint.

A Joint is a kind that allows us a relatively easy way to deal with a powerful means of data. Consider the following elements of the joint msELementUnion. In this joint, we might add DGNBUF written into every one within the Micro Station element. A fixed element of the first ELm_ hdr is also in the joint.

/*------------------------------------------------------------------------------+

| name element_unio - union of all element types |

+-------------------------------------------------------------------------------*/

typedef union msELementUnion

{

Elm_hdr ehdr;

Header hdr; /* NOTE: hdr.dhdr is not valid unless ehdr.isGraphics is set */

Cell_2d cell_2d;

Cell_3d cell_3d;

Line_2d line_2d;

Line_3d line_3d;

Line_String_2d line_string_2d;

Line_String_3d line_string_3d;

Text_node_2d text_node_2d;

Text_node_3d text_node_3d;

Complex_string complex_string;

Ellipse_2d ellipse_2d;

Ellipse_3d ellipse_3d;

Arc_2d arc_2d;

Arc_3d arc_3d;

Text_2d text_2d;

Text_3d text_3d;

Point_string_2d point_string_2d;

Point_string_3d point_string_3d;

Cone_3d cone_3d;

Surface surf;

Bspline_pole_2d bspline_pole_2d;

Bspline_pole_3d bspline_pole_3d;

Bspline_curve bspline_curve;

Bspline_surface bspline_surface;

Bspline_weight bspline_weight;

Bspline_knot bspline_knot;

Bsurf_boundary bsurf_boundary;

Raster_hdr raster_hdr;

Raster _comp raster_comp;

ApplicationElm applicationElm;

ColorTable colorTable;

ReferenceFileElm referenceFileElm;

Int16 t mp[MAX_ELEMENT_WORDS];

Int16 buf[MAX_INTERNAL_ELEM_WORDS];

} MSELementUnion, MSELement;

In this way, we can define MSELementUnion types of variables el:

MSELementUnion el;

When we read one element, we cannot determine what elements. The use of elements of the joint, we can test the elements of a fixed head el.ehdr. In the example below, we can examine a line element, the use of joint that we can access el.line_2d in the same data.

if(el.ehdr.type=LINE_ELM

{

el.Line_2d.start.x +=100;

el.Line_2d.start.y +=100;

}

Please note that we are a joint member how to use to extract data from the joint, and use another member to operate information. In this example, we have made a 2D line from the right move to move 100 units 100 units.

Pointers

In the MDL pointer in the right understanding of many errors that may arise. And for the use of variables, we can use int, float, double and char to illustrate the pointer. Consider the MDL in the ordinary usage of the pointer.

Note: The parameter table * PString the definition of variables, in this book, we need to use the ANSI method parameter list defines the type of argument, this method has the advantages of checking the type argument.

private void parselnputstring(char * pString)

{

char*pResult;

if(pResult=strtok(pString.""))!=NULL)

{

strncpy(oldstring.pResult.sizeof(newString));

if((pResult = strtok(NULL""))! = NULL)

STRRCPY(newString.pResult.sizeof(oldstring));

}

}

In the preceding example, we see two characters pointers * pString and * pResult. An asterisk (*) tell the program to store the pointer pString within the memory address to find the string value.

Passed by reference

There are two ways to pass parameters, namely, passed by value and passed by reference. When we come to passing parameters by reference, we give the address of variables to receive parameters. Therefore, the argument is called the program to change the call to any change in the value of program variables, because both share the same memory address. We need to pass a string by reference. We can address by using a pointer pointing to a string to do a string of passes, when a string is aAn array of characters when we do not need to use &, and MDL are used in all references to pass an array.

For example, the following note tells us that the string must be treated as a pointer to it passed to the parselnputstring.

Char string [20]; /*definition of string on main program*/

parseInputstring(string);/*pass the string into our function*/

Private void parselnputString(pstring) /*pass itby reference*/

char *pstring; /*define as a pointer*/

Back to looking at our main function, structure, rfHandle as a pointer to pass. Character (&) is the address operator. It is returned to the memory address of a variable, rather than the variable value.

mdlResource_OpenFile(&rfHandle,NULL,FALSE);

Program mdlResouce_openFile is a predefined function. When we find it in the MDL manuals, we will see the first one variable must be
Shall be a pointer. By using the & symbol in front of rfHandle, we have provided the correct format to the function variables.

Passing by value

We can also pass variables by value. In other words, this variable has been assigned at the same time, this value is copied to the receiver parameters. Is called the program variables change is local. When the program is the end of its value will be lost. See the following examples, the process should be placed in view, a 2-arc. Which, viewNumber passed by value. Whether we have done right to receive parameters, when we complete the call, the variable is not changed.

vieWNumber=2;

placeArcbyCenter(viewNumber)

Private void placeArcbyCenter (int view)

{

MSELementUnion arc;

Dpoint3d arcp[3];

double origin;

arcp[0].x=25.; /*start point*/

arcp[0].y=35.;

arcp[0].Z=fc_zero; /*floating point constant*/

arcp[1].X=55.; /*center point*/

arcp[1].y=35.;

arcp[1].Z=fc_zero; /*floating point constant*/

arcp[2].X=85.; /*end point*/

arcp[2].y=35.;

arcp[2].Z=fc_zero; /*floating point constant*/

origin=55.0;

if(mdlArc_createByCenter(&arc,Null,arcpt,True,origin,view)==success)

{

mdlELement_display(&arc,NORMALDRAW);

mdlELement_add(&arc);

}

}

Note: MDL arrays are consistent with C language conventions, from 0. For example, in the preceding definition of Dpoint3darcP [3], the array subscript is arcp [0], arcp [1], and arcp [2].

Function pointer

In the MDL, we can put the address of the function as an argument to pass. Therefore, the program can reference the value of a pointer to call this function.

Function pointers are widely used in MDL. For example, the function mdlState_startPrimitive asks the former two variables that are pointing to a function pointer.

mdlstate_ startPrimitive(placeBOX_ FirStPOint, placeBOX_ start,1,2):

Function PlaceBox_ firstPoint and placeBox_ Start appear to be references to their previous. We can start in the program where the definition of the function name to meet this requirement; or call the function it had previously appeared with complete (this is the usage throughout the book).

Micro Station: state machine

Micro Station is an event-driven machine. That is, at any point, an incident Micro Station into a given state, and a state of the handler to process its input. We can call to place online orders and PLACELINE the first demonstration of a point. When we move the cursor, the second point, like pulling a rubber band, like moving across the screen, we will choose WINDOWAREA the command and select the new window, rather than the second given data points. In the Windows update, this line has been eliminated. As a state machine, the Micro Station command state can be distinguished. View the command-line commands and put a different state. Therefore, we can assume that this line is still active, press the reset button so that we exit the view command and return to place the command line.

Figure 1.2 Micro Station input process

We can write an MDL program to deal with the establishment of a state function or type of information, such as data points such as input information. In this way we can enter the Micro Station basic (primitive) level. We write any of MDL applications, there will be more convenient, and does not require additional programming.

The other Micro Station programming tools, such as the UCM and MicroCSL, is to line up Micro Station commands. By Figure 1.3 we can see, UCM, and MicroCSL in the input queue, task distribution, and circulation among the external applications. Therefore, the state ordered the distribution layer applications will be out of control.

Resources

Resource is a group called the resource file being stored in the data. A typical data set is a string, an error message, raster icons and order form. The use of resources purpose of the paper is to separate the data and application source code. Using this method has many advantages.

• To reduce the overall memory requirements, because only the data is required for the installation.

• Multiple applications can share the same resource.

• Easy maintenance. Tips and information on the changes without changes to the application. For example, you can integrate applications into other languages, such as French.

In later chapters, we will discuss the resources and the generation method.

Command Table

Bottom of the main program from the resource file to install the application command table. Command table defines a command language. For exercise, we assume that the main will command PLACEBOX into Micro Station. In later chapters, we would also like to discuss the order form.

main ()

{

RscFileHandle rfHandle;

if(mdlParse_loadcommandTable(NULL)=NULL)

mdloutput_error("Unable to load command table.");

mdlResource_openFile(&rfHandle,NULL,FALSE);

mdloutput_prompt("key-in PLACE BOX to execute");

}

Here we tell Micro Station, our application order merely exists, we do not have enforcement procedures. This is the strength of the MDL. It allows application developers to enter the Micro Station "basic" level. We now define a group called PLACEBOX with the basic commands.

In order to activate our MDL process, we should get the uStn> prompt, type PLACE BOX. Microsration does a word-by-word analysis of our typing. Therefore, only type PLACE will have a vague command. Micro Station can not distinguish it from PLACELINE. Generate a named PLACEBOX basic commands will not be able to use the command table, because the command is not level, so that the command can not be classified. Command category is very important, it allows Micro Station decisions or the allocation of the current state of the application. In our application to generate the command PLACEBOX table, we need to discuss this issue in detail.

When the Micro Station has successfully analyzed the user's typed message, it generates an order number. An application with the command the task of linking the ID and the command ID is used to determine the application of the implementation of this command and calls this function. In the following program, cmdNumber to function placeBox_start and a command number combination. When we type PLACEBOX time, MDL began PlaceBox_ start implementation.

cmdName placeBOX_start()
cmdNUmber CMD_PLACE_BOX
{
mdlstate_startPrimitive(placeBox_firstpoint,placeBox_start,1,2);
}

The program mdlState_startPrimitive state function will be established in order to use a data point to activate PLaceBOx_firstpoint, a rest will loop implementation placeBOx_start. At the same time, it will generate information form number from 0 to 1, information, and it appears in the command field, while the No. 2 information displayed in the prompt field. In the second chapter we will discuss the interest rate table and its generation method.

State Control Function

A Micro Station command sequence is composed of an application, another application in the implementation of its final prior to the end of a command. PLACELINE in the implementation of the command, the implementation of a user command to open the window, it should be clear tips: WINDOW AREA. Write an event-driven applications as the MDL procedure does not make this application to be suspended. Determine the number of functions to control the incident. In this section we will discuss the state of various control functions, these functions are the core of MDL programming. There are four Micro Station command states.

1. Basic commands are used to generate, modify and delete elements. Start a basic command will terminate on the one basic commands, and the basic commands in another one to replace it until the order has been in active. Start a basic command must be called about the command:
   
   mdlstate_ startPrimitive: Start only the basic commands used to generate the elements.
   
   mdlstate_ startModifyCommand: Start one for the place and modify the elements of the basic commands.
   
   mdlstate_ startFenceCommand: The establishment of a basic command to operate a function of the fence.
   

2. View Order Status
   
   The View command modifies or updates the view. We need to start calling the mdlState_startViewCommand view command. Start a view command will hang a basic command, when the view control at the end, hanging up the basic commands continues to work. If the user enters reset then the end of the view that we must mdlState_exitViewCommand life mdlState_startViewCommand command to start a view out of the view mdlState_exitViewCommand command.
   

3. Direct order status
   
   A direct command modifies the settings (such as changing the capture state, or type WT =). Do not call the direct orders of the state function, it does not affect the basic order or view order status.
   

4. Utility Command Status
   
   Practical non-interactive command execution functions such as COMPRESS. In the end we need to use a command called practical
   
   mdlState_ startDefaultCommand?