Possibilities - An SDL Primer - Part 3 - Using Macros

Contact:   eSoft, Inc. (Makers of TBBS)
           15200 E. Girard Ave., Suite 3000
           Aurora, CO  80014
           (303) 699-6565      Voice
           (303) 699-6872      Fax
           (303) 699-8222      BBS
           support@esoft.com   E-Mail

AN SDL PRIMER - PART 3 - USING MACROS
-------------------------------------

*** From January 1991 Possibilities Newsletter ***
*** Copyright 1991 by eSoft, Inc.  All Rights Reserved ***

An SDL Primer -- Part 3: Using Macros
by Alan Bechtold

The TBBS System Definition Language Compiler (SDL), is easier than it looks.  
Simply put, it's just a different approach to designing and maintaining all 
of your TBBS system's menus.  Although you don't have to give up the 
comfortable menu-driven MEDIT program completely, you probably will -- after 
you start getting the drift of SDL -- because SDL is a complete replacement
for MEDIT in every way.

In our first two installments we've covered all the basics you need to write 
working SDL source code and create menus.  Now it's time to learn how to 
drastically cut down the time and effort you spend -- with SDL Macros.  
Macros can actually reduce cumbersome often-repeated source code to a few 
simple keystrokes.  And they're surprisingly easy to create and use.

What are MACROs?

SDL Macros are like abbreviations, but much more compressed.  They're a TBBS 
menu designer's shorthand.  If you run Lotus 1-2-3 or any one of the popular 
DOS macro programs, you're probably already familiar with the general 
concept of macros.

SDL Macros are created by typing a Macro Directive into your SDL source 
code.  The Macro Directive names and defines each of your Macros.  You 
decide how many Macros you wish to use, what their names are and what they 
mean.

Just think of SDL Macros as a way to customize SDL to your own liking by 
adding your own commands which can stand for any text you'd like.

Once you've defined a series of macros, the text they represent is then 
included in your expanded source code listings (and in the menus that result 
from compiling your source code), placed wherever you've used the matching 
Macro Callouts in your SDL source code (we'll take a look at Macro Callouts 
in a minute).

You can, for example, define a Macro to represent the authorization flag 
settings for one class of user on your system.  Then, whenever you type the 
name of that Macro in your SDL code (the Macro Callout), that particular 
configuration of authorization flag settings will appear in your expanded 
source code listing and in the TBBS menu that results when you compile the 
complete SDL source code listing.

The first step is to define the Macros you'll be using.  This is done, 
anywhere within your SDL source code file, with the Macro: Directive.

The Macro: Directive works like the Menu: Directive we learned about last 
time.  In your source code, type "Macro:" followed by the name you wish to 
assign to that particular Macro.

For example, to create a Macro named "Users" you would type "Macro: Users" 
on one line.  Then, on the lines following the Macro name, you would type 
the text that Macro will represent.  Macro names can include any 
alphanumeric characters, including the special characters _ # $ and &, in 
any combination, up to 128 characters in length.

The standard Macro Definition structure looks something like this:

Macro: Users
     .
     .  Body of Macro "Users"
     .
Macro: MoreUsers
     .
     .  Body of Macro "MoreUsers"
     .
EndMacro:

The body of your Macro is everything that appears between the "Macro: name" 
and the "EndMacro:" Directives.  This is the actual text or menu definition 
information that will appear, wherever you place the appropriately named 
Macro Callout in your source code, in your compiled system menus and 
expanded SDL source code listings.

Macro Callouts are simply an @ sign followed by the Macro's name.  To call 
out our sample Macro, with the name Users, you would simply type:

@@Users

anywhere in your SDL source code where you want the text you've defined with 
the Macro: Users Directive to appear.

Macro Callouts can be included in any SDL source code text, including Text 
Definition blocks.  This makes the @ character special.  SDL will think you 
are calling out a Macro whenever the character appears in your text unless 
you type two @@'s in a row instead.  This is the way you tell SDL that you 
want a single @ sign to be treated as text.

Ordinarily, a single space between the end of your Macro Callout and the 
continuation of your text is enough to tell SDL where your macro name ends, 
but not always.  For example, if a Macro, named UserDrive, was defined to 
replace the drive designator D:, it could be written like this:

Macro: UserDrive
D:
EndMacro

and would be called out like this:

@@UserDrive

but, inside a string of text, you might run into a situation where you want 
to use the macro like this:

Opt Data=@UserDrive \PATH\USERS

Note the space following the @UserDrive callout above.  This is necessary, 
to tell SDL that the Macro Callout has ended and the pathname, which is the 
continuation of your source code text, has begun.  But, when SDL expands 
this Macro, as you compile your source code, you'll get an unwanted space 
between the resulting D: drive designator and the pathname, like this:

OptData=D: \PATH\USERS

In cases like this, just type a + sign at the end of your Macro Callout to 
tell SDL you've reached the end of the callout, without the extra space.  
For example:

OptData=@UserDrive+\PATH\USERS

would properly expand to:

OptData=D:\PATH\USERS

Ordinarily, the + sign isn't necessary at the end of Macro Callouts outside 
of text strings, but you can use this convention any time you wish.

PARAMETER PASSING...

If you want to reduce your keystrokes (and source code) even more, SDL's 
Macro Parameter Passing can be the answer.  With Parameter Passing, you can 
specify up to nine arguments within your Macro Definition (with %1, %2, %3 
and so on, through %9), then actually define each of those arguments in each 
Macro Callout, changing them with each Callout as you see fit.

This sounds more complex than it really is.  Actually, Parameter Passing is 
just a way to make selected Macros more flexible.  For example, you COULD 
create the following different Macro definitions:

Macro: Define1
Type=34 Key=D Opt Data=C:\FILES\DNLD
Macro: Define2
Type=28 Key=F Opt Data=C:\FILES\UPLD
EndMacro:

These two Macros would be called out with the @DEFINE1 and @DEFINE2 
callouts, respectively.  This is a perfectly acceptable way to do it.  But 
you could, instead, define this SINGLE Macro:

Macro: Define
Type=%1 Key=%2 Opt Data=%3
EndMacro:

and call it out several different ways in your SDL source code.  In the 
above example Macro, we've used three Parameters for the actual menu 
configuration data.  The number of each Parameter tells SDL how to order the 
list of variable Parameters that you'll specify when you call out the above 
Macro in your SDL source code.  For example, you could call out the SAME 
example Macro two different ways:

@@DEFINE(34,D,C:\FILES\DNLD)

and

@@DEFINE(28,F,C:\FILES\UPLD)

This would give you the same result as the two DIFFERENT Macro definitions 
and Macro Callouts in the preceding example.

Notice that your arguments are stated within parenthesis, in the order in 
which you wish them to be placed.  The parentheses always follow the Macro 
Callout, with no spaces between them and the Callout.

You can include embedded and trailing spaces in your Macro Callout 
arguments.  However, you must enclose your arguments within single or double 
quotes if you want to include leading spaces, commas or parenthesis as part 
of a Macro parameter.

Arguments within Macro Parameters can be mixed any way you wish, as long as 
there are no more than the nine total that are allowed.  You can also leave 
out arguments when calling out a Macro with parameters.  When a Macro 
Callout with blank parameters is expanded, the missing arguments will be 
blank in your compiled menu and expanded source code listing.  This 
capability can be useful for those TBBS menu options that automatically 
revert to default settings when left blank.  Why type more than you have to?

EQUATE DIRECTIVES

Another quick and easy way to use Macros within your SDL code is the Equate 
Directive.  The Equate Directive works like a Macro and follows all of the 
rules of Macro definition, but it's defined on a single line.  Equate 
Directives are especially handy if you want to define a single parametric 
value.  For example:

Equate: DataFiles = D:\TBBS\DATAFILE

defines exactly the same macro as:

Macro: DataFiles
D:\TBBS\DATAFILE
EndMacro:

Equates are called out exactly the same way as you would call out any Macro.  
The Equate we defined in the above example could be called out like this:

Opt Data=@DataFiles+\FILE1

This type of equate can be very useful if you move areas around on your disk 
drive.  You need only change the equate and recompile your menus.  All of 
the menu commands which reference files will automatically begin to look in 
the new area.  You avoid the need to track down and change each entry 
individually!

You can use Parameter Passing or any other Macro feature within your Equate 
Directives, as long as you can fit it all on a single line. 

MACRO NESTING...

If you want to get the most power out of your SDL macros you can also 
include Macros within your Macros.  This is called Macro Call Nesting.  You 
can even use Macro Callouts in other Macro definitions or as parameters 
within Macro Callouts.

This ability to incorporate Macros within Macros allows you to effectively 
double up on your customized "SDL shorthand" as you create new Macros.  
Macros can be nested in this way up to 25 levels deep.

There are some excellent examples of Macro Nesting in your TBBS manual 
(pages 7-8 and 7-9) and we'll cover this capability in depth in the final 
installment of this series.  We'll take a look at some favorite SDL tricks 
and tips and generally wrap up all the loose ends then, too.

Until then, take time to experiment with Macros.  Try using them in your SDL 
code.  Create at least one Macro Definition that includes a Macro Callout 
within it and we'll check your progress next issue.

- END -
PS0191-4
Rev. 1/91

Copyright (C) 1994 eSoft, Inc., All Rights Reserved.  Permission granted
to distribute this file in its entirety, without modification, to any
interested party.  Any other use requires the written permission of
eSoft, Inc.

IMPORTANT:  The information herein is subject to change without notice.
Please call or write to confirm factual information of importance to you
or your organization.

