Possibilities - An SDL Primer - Part 4 - Advance Techniques

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 4 - ADVANCE TECHNIQUES
-------------------------------------------

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

An SDL Primer -- Part 4: Advanced Techniques
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.

We've gained a solid handle on SDL in the first three installments of this 
series.  In fact, we've covered everything you need to know to create and 
maintain all of your TBBS menus with SDL.  Now we're going take a look at 
some of SDL's more advanced capabilities.

Macro Call Nesting

Last month, we looked briefly at Macro call nesting. Simply put, Macro call 
nesting is the ability to include SDL Macros within other SDL Macros.  This 
capability can also be used to use Macros as parameters to other Macros.  
This is a potentially cumulative capability.  Macros containing other Macros 
can be nested inside still other Macros, and so on, up to 25 levels deep.

For example, let's create a couple of macros:

Macro: Action
Type=%1 Key=%2 OptData=%3
Macro: Download
46
Macro: Path
C:\TBBS\DOWNLOAD
EndMacro:

Now let's call out the above Macros, using some as Nested Macro Callouts:

@@Action(@Download,N,@Path+\FILES /NTL)

... for example, would expand to:

Type=46 Key=N OptData=C:\TBBS\DOWNLOAD\FILES /NTL

In the above example, the "@Download" and "@Path" Macro callouts, inside the 
parenthesis, are examples of Nested Macro Callouts being used as parameters 
to another Macro.

Although Macros are traditionally used by most computer software packages to 
reduce keystrokes, you might have noticed that the Macros in the above 
example are actually longer, in most cases, than the character strings they 
invoked.  Although the Macros might be longer, in the above example they're 
still useful to help the TBBS system designer organize the various disk 
drives, subdirectories and menu option types that might be used in a given 
TBBS system.  It's much easier to remember "@Download," for example, than it 
is to remember that a Type 46 menu command invokes a Pseudo Download 
Function.

The Include: Directive

The Include: Directive is yet another aid to organizing your SDL code.  You 
may have noticed by now that all the SDL code for a complete TBBS system can 
be incorporated into a single text file.  With a large TBBS system, a single 
SDL source code file can get bulky.  The Include: Directive, lets you 
effectively break up potentially source code files into multiple files, but 
still call them up for compilation as if they were all part of a single 
source code file.

It's kind of like eating a large meal one bite at a time.  That's always 
easier than trying to dump a whole plate down your throat all at once.

To use the Include: Directive, simply type "Include:" followed by the full 
DOS drive designator, path and, finally the name of the file that you wish 
to include in your source code.  An Include: Directive to insert a source 
file named MAILMENU.SDL residing in your \MENUS subdirectory might look like 
this in your main SDL source code:

Include: C:\MENUS\MAILMENU.SDL

Include: Directive files cannot have Include: Directives in them.  Only the 
original SDL file can have them.  But, you can use Include: Directives 
inside Macros in your original file.  Just remember that Include: Directives 
in Macros won't be executed until those Macros are expanded.

The Include: directive is especially useful when you make libraries of macro 
commands.  You can then invoke these standard macros by using the Include: 
directive in any SDL source file you create.

Conditional Compilation

Early in this series, we examined SDL's array of compilation options.  One 
advanced SDL compile capability we haven't yet examined is the Conditional 
compilation.

SDL's conditional compilation capabilities allow you to create and maintain 
several different systems within a single source code file or series of 
source code files.  This capability is especially useful, for example, to 
computer consultants who might need to manage several different TBBS systems 
for a number of clients.  Consultants who sell turnkey TBBS systems to their 
clients can use conditional compilation to create a single "basic" source 
code listing which is capable of creating a multitude of entirely different 
TBBS systems, depending on the commands given when he or she compiles each 
system.

This capability also allows you to construct complex macros which condition 
their actions on how many or what types of input parameters they are called 
with.  You could use this capability to offer an option to <S>can Messages 
in some of your system's message bases, but not in others.

The syntax is straightforward.  A Conditional Block is entered in an SDL 
source code listing, opening with either an If: or an IfNot: statement and 
closed by an Endif: statement.  All lines of code appearing between the 
conditional opening and closing statement are either enacted upon or 
ignored, depending upon whether they match the opening statement.

A conditional block looks like this:

If:   string1=string2
      .    lines of code which will be
      .    compiled if they match the
      .    conditional string)
Endif:

Or...

IfNot:   string1=string2
      .    lines of code which will NOT
      .    be compiled if they match the
      .    conditional string)
Endif:

The If: and IfNot: blocks you've entered into your source code are acted 
upon when you compile your SDL source code into a TBBS system menu or series 
of menus.  Since If: and IfNot: blocks entered into Macros will not take 
effect until the Macro is expanded, you can perform two or more tasks with 
the same Macro.  An example is:

Macro: Action
Key=%1 Type=%2
IfNot: %3=
Opt Data=%3
Endif:
EndMacro:

Note that the second string is absent in the IfNot: statement.  This makes 
the IfNot: test for the presence or absence of the third parameter in the 
macro.  If %3 expands to any text at all, it will fail to match an empty 
string (nothing) and generte the Opt Data portion of the command.  For 
example:

@@ACTION(K,11)

Would expand to:

Key=K Type=11

However, if a third parameter is added to the callout the expansion changes.  
For example:

@@ACTION(E,5,EMAIL)

Would expand to:

Key=E Type=5
Opt Data=EMAIL

ANSI and Graphics in TBBS Menus:

By far, the one SDL capability most often asked about is the ability to 
include ANSI and graphics in TBBS menus.  This is easier than it at first 
appears.

It is possible to enter graphics display strings in your SDL source code 
because SDL allows direct entry of control characters and ANSI characters in 
a source file.  This makes the task of designing graphics screens for your 
TBBS menus a fairly simple one.

You simply insert the proper ANSI or graphics characters in your SDL source 
code in the menu's Title: or Entry: Directive text block.  These can be 
commands to draw something as simple as a box or as complex as a screen 
drawing of a landscape.  Your only real limit is the number of characters 
that can be included in an Entry: Directive (1000 characters).  You can get 
around this limit by using several Entry: directives with a portion of the 
text on each one.   There are some good examples of such SDL files on the 
support board for your reference.

In either case, just include all of your system's menu commands in whatever 
ANSI or graphics screen drawing you devise, so they display as part of your 
drawing.  If you were drawing a simple box, a list of that particular menu's 
available commands should be displayed inside the box.  On a landscape, you 
could run the list of commands across the bottom or top of the screen, or 
maybe have them appear on a tree trunk, if you're inclined.

Next, set up all of the menu's appropriate Entry: Directives, but don't 
include a text line for each of the commands that are available on that 
menu.  Skip the text line for each Entry: Directive, setting up each of the 
menu's available commands without them.  Then, your menu will display the 
graphics menu you've drawn with ANSI codes and NOT the usual ASCII text 
lines you insert in each Entry:Directive, but each of the menu's defined 
keys will still work.

But, how exactly do you draw with ANSI codes?  This is essentially an art 
and precise instruction is far beyond the scope of an article of this size.  
The ANSI codes themselves are listed on the last page of the Overview 
section of your TBBS manual. If you're patient, it's best to enter ANSI 
graphics codes directly into your SDL source code.  A working knowledge of 
ANSI graphics codes will allow you to create a series of SDL Macros that 
draw specific lines and boxes that you might want to use regularly and these 
can then do a lot of the repetitive work for you.  Examples of such macros 
are also available on the TBBS support BBS for downloading.

But, there is another way...

Many TBBS system designers use a popular ANSI graphics drawing program, such 
as THEDRAW (available on the eSoft Support BBS).  With THEDRAW, you can 
actually DRAW your graphics on-screen, without having to know the actual 
ANSI codes that are being used.  The program then allows you to SAVE your 
drawings to an ASCII text file that will contain all the ANSI graphics codes 
that were used to draw the screen you've created.

Once you've drawn your menu screen with a program like THEDRAW, then saved 
it to disk, you can pull the resulting ANSI code file into your SDL source 
code with almost any word processor, inserting it right where you want it to 
display.  This method sometimes requires minor additional editing, so an 
understanding of how ANSI works is still useful, but it's usually not 
necessary.  The only editing you will normally need is to break the ASCII 
file into sections which are smaller than 1000 characters each and adding 
the Entry: directive in front of each one.

Whichever way you do it, be sure you set MEDIT Compatibility off in your 
source code (MEDIT can't handle ANSI control codes) and test each menu 
thoroughly.  You might have to do a little "hit-and-miss" re-designing, but 
it will work.

And that's literally everything you need to know to consider yourself an 
experienced, capable SDL programmer.  Like any language, you'll find 
yourself learning continually as you go, adding to your bag of tricks by 
trial and error.  Meanwhile, we'll continue to help you on your way in these 
pages.

- END -
PS0291-5
Rev. 2/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.

