DMM Varkon^® Tutorial
A Beginner's Guide to the Varkon Parametric Modeling and CAD Application Development System
By David M. MacMillan

6. Overall Model and MBS Program Structure

6.1. Purpose

Most of the information in this section is also covered in section 4.5., "Editing and Compiling MBS Code", and in chapter 5., "Coordinate Systems." The intent of the present chapter is to give a unified account of the overall structure of a Varkon model in terms of:

• The structure of its MBS modules
• The relationships of its coordinate systems

6.2. MBS Program Structure

6.2.1. Model == MBS Program

There is a one-to-one correspondence between a Varkon model and an MBS program; each Varkon model is implemented by exactly one MBS program, and each MBS program implements exactly one Varkon model. A Varkon "job" consists of one model/MBS program plus additional information concerned with things such as the displaying of this model.

6.2.2. MBS Program is a Tree

An MBS program consists of a tree-structured hierarchy of MBS modules. Exactly one module, designated the "active" module, serves as the root of this tree.

6.2.3. MBS Modules

An MBS module consists of a number of conventional programming structures (variables, expressions, control statements, etc.) It also contains two types of program calls to externally defined entities:

• built-in MBS functions and procedures
• user-written MBS modules

These two types of external entities are called in two different fashions.

Built-in MBS functions are simply called through what seems to be a pretty standard procedure-call mechanism. The use of these functions is described in the MBS and Varkon documentation. For example, the following illustrates a call to a built-in MBS function which draws a line:

local drawing module t1();
beginmodule
   lin_free (#1, vec(0,0), vec(100,100));
endmodule

Built-in MBS functions are leaf nodes on the MBS program tree. They are black boxes whose internal workings are opaque to the user, and which thus have no further module-hierarchy associated with them.

A built-in MBS function returns a value. (For example, the sin() function.) A built-in MBS procedure does not return a value. (For example, the procedure lin_free() does not return a value.)

User-written MBS modules are called in a very different manner. Actually, user-written MBS modules are not called at all. Rather, they are invoked via the MBS procedure part(). Exactly one MBS module is called in every part() procedure. Thus, perhaps counterintuitively, the part() procedure does not serve to group elements into parts. This function is served by the MBS module itself, and to some extent by the "group" construct of MBS (which operates within a module). The part() procedure serves only as a calling mechanism which links other modules into the current module.

Thus, it is not legal to call a user-written MBS module called widget directly:

local drawing module t1();
beginmodule
   ! THIS IS NOT CORRECT
   widget ("widget 1", 2, 3);
   ! THIS IS NOT CORRECT, EITHER
   widget (#1, "widget 1", 2, 3);
endmodule

Instead, widget() is invoked through the part() procedure:

local drawing module t1();
beginmodule
   ! CORRECT
   part (#1, widget ("widget 1", 2, 3));
endmodule

(More precisely, the example above is correct if widget is a "global" module which does not need a specific local coordinate system specified. Issues of coordinate systems will be discussed later.)

Though Varkon is not a classical object-oriented system, it does have certain object-oriented characteristics. In object-oriented terminology, it is possible to think of an MBS module as defining a "class" and of the part() construct as creating an instance of that class.

It is through the part() mechanism that the set of MBS modules which comprise an MBS program are organized into a hierarchy.

User-written MBS modules may or may not be leaf nodes on the MBS program tree. They may of course call built-in MBS functions and procedures. They may also call (using the part() procedure) other user-written MBS modules.

6.2.4. Macro Modules - A Separate Hierarchy

The discussion above applies only to MBS modules with the "local", "global", or "basic" geometry attribute. Such geometrical MBS modules participate in the creation of a model and its corresponding MBS program tree.

MBS modules with the "macro" attribute differ in two major respects from the three types of geometric modules:

• They may not partipate in creating geometry.
• They may not be called from a geometric module.
  NOTE: I am no longer certain that this is true.

These constraints mean that while "macro" MBS modules can be grouped into program trees, these trees are independent of a job's model and geometric MBS program tree.

Macro modules may be invoked interactively by using interactive function f152. This function is available in the standard menu hierarchy as: "MAIN MENU 2D" [or "MAIN MENU 3D"] -> FILE -> macro

Macro modules may also be called from other macro modules. However, they may neither be called from geometry modules nor may they call geometry modules.

6.2.5 Macro Module Functionality in Geometric Modules

However, geometry modules can do many (all?) of the things that macro modules can do. Consider as an example the "count" program from the Varkon documentation:

MACRO MODULE count(STRING filename*80 >"Enter name of file !");

          STRING line*132;
          FILE   f;
          INT    count;

          BEGINMODULE

          !*
          !***Open the file for read access.
          !*
             open(f,"R",filename);
          !*
          !***Loop and read lines until end of file.
          !*
             count:=0;
             loop:
             line:=inlin(f);
          !*
          !***If a line was read increase counter and loop again.
          !*
             IF iostat(f) = 0 THEN
             count:=count + 1;
             GOTO loop;
          !*
          !***If no line was read there are no more lines to read. Close the file and
          !***display the result in a VARKON listwindow.
          !*
             ELSE
             close(f);
             lst_ini("Result of linecount for file ="+filename);
             lst_lin("Count="+str(count));
             lst_exi();
             ENDIF;

          ENDMODULE

Convert this macro module to the geometric type of the current model (I happen to be using a 3D geometry example as I write this) and give it the "global" attribute. (If given the "local" attribute one would have to specify a local coordinate system for it, which wouldn't make sense as it's not geometrical. "global" geometry for a nongeometric module doesn't necessarily make sense either, but at least you don't have to make an issue of it.) To do this, change the first line to:

global geometry MODULE count(STRING filename*80 >"Enter name of file !");

To invoke this module, just call it up as a part. It is necessary to give this "part" a sequence ID. It is also necessary to specify the parameters explicitly; Varkon will not prompt for them:

GLOBAL GEOMETRY MODULE t1();
BEGINMODULE
  part(#1,count1("trashfile.txt"));
ENDMODULE

6.3. The Coordinate System Structure of a Model

[NOT FINISHED]

Legal Matters

Version 1.3, 1998/06/17. Feedback to dmm@lemur.com
http://www.database.com/~lemur/vk-structure.html

Go to the:

• DMM Varkon Tutorial - 7. Simple 2D Drawing
• DMM Varkon Tutorial - 5.5. Summary: Local, Global, Basic
• DMM Varkon Tutorial - 1. Main Page and Contents
• Official Varkon Homepage

• Delightful Machines Page
• Singing Lemur ^TM Home Page