The DataCAD Developer Network (DDN) is an online resource for information and support for DCAL® (DataCAD Applications Language) developers as well as anyone interested in creating fonts, toolbars, hatch patterns, or linetypes for use in DataCAD.
#71990 by Jsosnowski
Thu Aug 03, 2017 10:25 am
PART ONE - A DCAL FOR DELPHI PRIMER - INTRODUCTION

This series of posts are intended to provide an expanded and annotated working template for writing Datacad D4D macros. Many Datacad users may have dabbled in coding DCAl macros, but the new Delphi version is significantly more complex. Although there are several sample D4D macros provided by Datacad, I found understanding them challenging. Sample code for IniBrowser posted in the Datacad forum by Mark Madura shed more light on the subject, but I thought a more detailed examination might offer Datacad users more confidence in attempting to write their own macros. My goal is to streamline the learning curve for anyone making the transition between the original DCAL programming language and the more complex process used in D4D. I must warn you that I am a self taught coder and although I have tested the code provided in these posts and make explanations with confidence, there is always the possibility (probability?) that I don't have all the facts exactly correct, especially in the assumptions I have made regarding what is going on inside Datacad when interacting with the macros. I encourage readers to ask questions, make comments, and amplify the posts with replies.

I should also point out that as I tested examples and began writing more D4D test macros I found it useful to alter the format presented in the samples and change the names of some of the types, variables and methods to make things more readable. The general operation is similar but THERE ARE DIFFERENCES. While the macro model developed in these posts is similar to the samples provided by Datacad, be careful in pasting code together between sources. Among the changes made are:

1. Replacing the elseif options in a menu function to a 'case' structure.
2. Providing a naming convention for menu functions as <Name>_doMenu.
3. Changed name of D4D function argument 'pl' to 'p_LR' (pointer to a Loop Record) and 'parg' to 'P_DR' (pointer to a Data Record).
4. (Others will be added as the postings progress).

As conceived there are at least 8 parts to be posted, although I can see others emerging as I dive deeper into macro application issues. Posts will include:

1. Introduction
2. The Main Function
3. Required Macro Record Structures
4. The doMenu Function
5. Macro Templates
6. Other Macro Considerations
7. Delphi Language & Delphi Forms
8. Dcal to D4D Code Conversion Issues
9. Prerequisites, References, Resources & Setup.

HISTORY (very brief)
From my examination and research, DCAL is based on a programming language related to Modula 2 developed as an extension to the Pascal programming language. Delphi is another extension of Pascal, created by Borland Software, later purchased and extended by Embaracdero Technologies inc., that expanded the language as an object oriented programming language with implementations to create a graphical user interface for developing windows-based programs without some of the more complex windows operating syhtem coding. D4D provides a greatly expanded vocabulary of capabilities beyond Pascal or Modula 2 allowing Datacad macros to perform activities that were previously beyond its capabilities such as operating windows based forms. Although both DCAL and D4D code read similarly there are differences in language and grammar. However, DCAL code can be translated to D4D fairly simply once the differences are understood. The Part Six posting discusses some of the differences.

DCAL vs D4D
This series of postings assumes that the reader has some basic experience writing macros in DCAL format. In fact the discussions in these posts use DCAl macros as a base, demonstrating how D4D is used to accomplish the same tasks while addressing additional challenges.

D4D Macros are compiled as .dll (dynamic link library) files using the file extension .dmx. Dynamic Linked Library files are collections of additional methods (functions and procedures) which can be used by a Windows based program ('.exe') extending its capabilities. Datacad opens the library file, searches for a specific function called Main and follows the instructions included there. That's basically it. Main serves as a router that directs the focus of the macro operation to various Menu functions (',Name>_doMenu') included in your macro.

The basic framework of at Datacad macro is the menu loop. Datacad's entire user interface is based upon it. Once Datacad is started, users are presented with a menu and asked to select an option by pointing, pressing a keyboard shortcut, or selecting a function key. Datacad then executes some code associated with the menu selection and then the cycle starts again. This psuedo code function shows the basic framework for this cycle:

Code: Select allfunction Dcal_MenuLoop : returnvalue
var
  //declare any variables
begin
  //initialize variables
  repeat    //menu loop
    //display section  - display the menu
    //input section  - get the user's selection
    //execute section  - act upon selection made
  until done;
  //finalize loose ends before exit
end;


In this example, a macro calls the function Dcal_menuLoop, declares any needed variables and begins its operation. The actual menu loop is operated by the repeat...until done statement which contains three steps: display - input - execute.

D4D creates a similar loop structure although the implementation is more complicated (see the PART FOUR post). In general, for a DCAL macro, Datacad calls the macro and lets it maintain focus until the user selects 'exit' or the presses a Datacad keyboard shortcut/hotkey to jump out of the macro and into another Datacad menu structure such as the 'Move' or 'Copy' menu. A DCAL macro can, at any time, ask Datacad for user input, using interface function such as getPoint() or getesc(). The result of these requests are immediately accessible to the macro and the macro continues immediately after to the next line of code using the 'return' value of that function. The macro maintains focus until the user selects exit or jumps to a built-in Datacad Menu using a keyboard interrupt. When that occurs the macro file is closed and must be restarted to use it again. When Datacad was upgraded to include multiple drawing files open at the same time, a new programming problem arose. Datacad now had to be able to manage multiple running drawing file threads using the same macro with different data and at different stages of operation. Previously, each time a DCAL macro calls a user interface method, the macro paused to await the user response. This will not work if the user can switch drawings and start the same macro in that drawing file. To work correctly in the new multi-drawing environment, the macro must exit its menu loop after the user makes an input selection, return control to Datacad and have Datacad reenter the macro when that request is completed. The menu loop is now split between Datacad and the macro and the drawing and all relevant data in the macro can change while Datacad has the macro focus. Datacad must therefore tell the macro where to return to when it returns control focus to the macro. Datacad gets that information from the previous iteration of the macro using two pointer arguments in the function call (see PART TWO). The macro samples provided in the D4D package provide examples of how this achieved and additional postings in this series will go into detail explaining how it works and special conditions that must be addressed.
Last edited by Jsosnowski on Mon Sep 18, 2017 2:53 pm, edited 4 times in total.
#72046 by Jsosnowski
Wed Aug 09, 2017 8:49 am
Please note that as I put together this Primer I am often making revisions to PARTS that have been published without annotation of the changes. Once all the major sections have been published I will make revision notes to further changes.

Joe Sosnowski

Who is online

Users browsing this forum: No registered users and 8 guests

About DataCAD Forum

The DataCAD Forum is a FREE online community we provide to enhance your experience with DataCAD.

We hope you'll visit often to get answers, share ideas, and interact with other DataCAD users around the world.

DataCAD

Software for Architects Since 1984