Updated for AutoCAD 2000!
17. How to Write a DIESEL Macro, Part 1

by Ralph Grabowski

For a dozen years, the status line of AutoCAD remained unchanged. Though Release 11, the status line displayed the O (ortho is on), S (snap is on), T (tablet is on), the x,y-coordinates, the and the layer name. Newer additions included P (paper space is on) and the current color.

For all that AutoCAD does, those seven indicators were not enough. Users wanted more information, even fundamentally basic information, such as the missing z-coordinate. The official Autodesk response to users want more on the status line was along the lines of, "We wouldn't be able to add more without missing out on what some other user wants, so it's best we do nothing at all." Sometimes the display driver allowed the user to customize the status line to a limited extent.

The History of Diesel

Then with AutoCAD Release 12 for DOS, Autodesk introduced the fully customizable status line. Unfortunately, the user couldn't simply select options from a dialog box. Instead, the user needed to learn Yet Another Programming Language, this one called "Diesel" and the sixth different programming interface added to AutoCAD at the time.

Short for "direct interactively evaluated string expression language," the programming logic of Diesel is as clear as the acronym's meaning. Despite the word "string," Diesel mostly operates on numbers, not strings. While its purpose is to customize the status line, Diesel has found its way into menu macros and became the most powerful programming environment available in AutoCAD LT -- much to the chagrin of Autodesk, who deliberately disabled the AutoLISP that was supposed to ship with LT because its retailer were worried LT's low price would canabalize sales of full- blown AutoCAD. Despite the handicap, European programmers have done some amazing things for LT third-party software with Diesel's limited facilities.

Is Diesel a true programming language? For me, the line of differentiation between a macro language and a programming language is whether there is logical functions, such as If, While, or even GreaterThan, etc. (Logic functions make it possible for the program to make decisions.) Diesel has logic functions but the syntax is so obscure that it begs to be known as a simple macro language -- and that's how I'll refer to it from now on.

What Diesel Does

Diesel allows me to change AutoCAD's status line so that it displays other useful information, such as the z-coordinate, the DWG filename, and the time. There is a limitation, though: the text displayed by Diesel is truncated after 32 characters, no matter how big I make the window (39 chraracters in Release 13 for Windows and LT for Windows 95). Diesel has an unusual format for its macro language. Every function begins with the dollar sign and a bracket:

No doubt, the purpose of the $-sign is to alert the AutoCAD command processor that a Diesel expression is on the way, just as the (-symbol alerts AutoCAD that an AutoLISP expression is coming up.

The opening and closing parentheses signals the beginning and end of the function. This allows Diesel functions to be nested, where the variable to one function is another function. The parantheses also allow Diesel to work on more than one variable at a time; the closing parenthesis alerts Diesel that there aren't any more variables.

Diesel works with 28 functions names (there were just 15 in AutoCAD LT Release 1 and 2; 27 in AutoCAD LT for Windows 95), as the list below shows. All Diesel functions take at least one variable; some take as many as nine variables. A comma always separates the function name and thevariable (s). Diesel tolerates no spaces.

Brief Listing of Diesel Functions

Math Functions
+ Addition
- Subtraction
* Multiplication
/ Division

Logical Functions
= Equal
< Less than
> Greater than
!= Not equal
<= Less than or equal
>= Greater than or equal
and Logical bitwise AND
eq (*) Determines if all items are equal.
if If-then
or Logical bitwise OR
xor Logical bitwise XOR

Conversion Functions
angtos Convert number to angle format.
fix Convert real number to an integer.
rtos Convert number to units format.

String Functions
index Extract one element from a single comma-separated series.
nth Extract the nth element from a one or more items.
strlen Returns the number of characters of the string.
substr Returns a portion of a string.
upper Convert text string to uppercase characters.

System Functions
edtime Display the system time.
eval (*) Passes a string to Diesel.
getenv Get a variable from the INI file.
getvar Get a system variable.
linelen (**) Returns the length of the display.

(*) Diesel functions not found in AutoCAD LT R1 and R2.
(**) Function not found in any version of AutoCAD LT.

Jumping Into Diesel

Enough of the preliminary stuff. Lets jump right in an put the customizable status line feature to work.

1. I use the ModeMacro system variable and type something:

Depending on where the status line is in your copy of AutoCAD, the words "Tailoring AutoCAD" should appear near to (or in place of) the coordinate display:

2. To restore the status line, I type the ModeMacro system variable with a "" (null string), as follows:

3. To display the value of a system variable, use the $(getvar function. This function gets the value of a system variable and displays it on the status line. I'll use the function to display the current elevation, as follows:

AutoCAD displays 0.0000 or something similar on the status line.

Diesel Error Messages

To go along with its obscure syntax, Diesel has an equally-bizaar set of error messages -- all four of them. The cryptic error messages are printed by Diesel on the status line. Here's what they mean, along with an example of how the error can occur:

$? I left off the right parenthesis; for example: $(+,1,2 Or, I forgot the the left quotation mark; for example: $(eq,"To

$(func)?? I typed the wrong name of the function; for example, $(stringlenth, ... )

$(func,??) I provided the wrong number of arguments the function; for example, $(if)

$(++) The output string too long.

To help me track down bugs in Diesel macro, I turn on the MacroTrace system variable on, as follows:

When it is turned on, AutoCAD displays a step-by-step evaluation of the Diesel macro in the Textscreen window. Here's how it works for this Diesel macro, which converts the value of the fillet radius to metric: $(*,2.54, $(getvar,filletrad))

A bug in MacroTrace causes to to re-evaluate the most recent Diesel expression over and over again. Each time I type something at the Command prompt (such as the Line command), MacroTrace re-displays its evaluation; however, it does not interfere except visually. For this reason, I need to turn off MacroTrace when I no longer need it, as follows:

Diesel Programming Tips

To end off this month, here are some tips for working with Diesel:

Tip #1: Each argument must be separated by a comma; there must be no spaces within the expression.

Tip #2: The maximum length of a Diesel macro is approximately 460 characters; the maximum display on the status line is roughly 32 characters.

Tip #3: Use the ModeMacro system variable to output the Diesel macro to the status line; ModeMacro outputs directly to the status line, until it reaches a $(, then it begins evaluating the macro.

Tip #4: To prevent evaluation of a Diesel macro, use quoted strings : "$(+,1)"; to display quotation marks on the status line, use double quotations: ""Test""

Tip #5: Use the MacroTrace system variable to debug the macro.

Tip #6: Use AutoLISP’s (strcat) function to string together a Diesel macro within AutoLISP.

Tip #7: Use the $M= construct to use Diesel expressions in a menu macro.

Summary

In this tutorial, we learned about the Diesel macro language and started to learn how to customize the status line. In the next tutorial, we'll use Diesel in menu macros and AutoLISP routines, and see just how complex Diesel can get.

Tailoring AutoCAD Part 16 | Part 17 | Part 18 is the next tutorial.

Comments on this tutorial series? Tell me about it.

Return to Contents.

All contents copyright 1995-9 XYZ Publishing, Ltd. . All rights are reserved. No material may be reproduced electronically or in print without written permission from XYZ Publishing, PO Box 3053, Sumas WA, 98295-3053, unless otherwise noted.