Possibilities - An SDL Primer - Part 1 - Getting Started With SDL

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 1 - GETTING STARTED WITH SDL
-------------------------------------------------

*** From November 1990 Possibilities Newsletter ***
*** Copyright 1990 by eSoft, Inc.  All Rights Reserved ***

An SDL Primer -- Part 1: Getting Started With SDL
by Alan Bechtold

The idea of a "computer language" conjures up images of all-night sessions 
in front of a terminal -- struggling to master a complex new way to talk to 
your computer.  SDL -- the TBBS System Definition Language Compiler -- isn't 
that way at all.

SDL is just a different way to design and maintain all of your TBBS system's 
menus.  SDL's approach to TBBS menu construction and maintenance is easy to 
learn.  With SDL, you use your favorite word processor or text editor to 
write out all of your TBBS menus in an ASCII text file.  It's like writing a 
letter, but you have to learn to write it in terms that the SDL compiler 
will understand, so it can follow your instructions and build the TBBS menus 
you want.

The first step is to understand how the SDL compiler works. The SDL compiler 
reads your SDL source file (the ASCII text file I mentioned above) and, like 
a dutiful French chef, follows your commands, creating TBBS menus exactly 
as you've specified.

Because you may already have menus you built with MEDIT, the SDL decompiler 
is also provided.  The SDL decompiler takes TBBS menus that already exist on 
your system and creates an SDL source file for your system.  This allows you 
to start using SDL whenever you're ready.  You can start with the MEDIT 
menus you've got now, without worrying about re-doing anything you've 
already done on your system.

Since most TBBS system designers start with MEDIT and already have at least 
a few TBBS menus they're using on their systems, let's start by getting 
familiar with the SDL decompiler.

Pick one of your menu files -- a simple one would be best to start with -- 
and we'll decompile it together.  Since I don't have any way to know which 
existing menu you've selected to decompile I'll use your top level menu -- 
MENU0000.CTL -- in the following examples. 

Make sure the program SDLDC.COM is in the same subdirectory as the menu 
file, then type:

SDLDC SAMPLE /M:0000

The "/M:0000" on the the end of the above command is an option that tells 
SDLDC to decompile only the single menu file named after the "/M:".

Typing the above command will decompile the menu file MENU0000.CTL, and 
create an ASCII text file named SAMPLE.SDL.  This is the SDL source file 
that is your menu written in SDL format.  You can look at it with any word 
processor or text editor.

In fact, go ahead -- use your word processor to look at SAMPLE.SDL.  Then 
look at the your MENU0000.CTL file with MEDIT (the original menu file itself 
isn't changed or destroyed by SDLDC.COM).  You'll definitely gain some 
insight into the way SDL works.

For example, the ASCII text SDL source file for a simple menu to read 
messages on your system might look like this:

Menu:0000
Billing:7
Title:
READ TBBS MESSAGES
------------------
EndTitle:

Entry:
<R>ead Messages
A1=--X-----
Key=R Type=6 Opt Data=Bulletin Board
	. . .
EndMenu:

The first line in the above example -- Menu: 0000 -- tells the SDL compiler 
that all text that follows, until the line reading EndMenu: is reached 
contains the specifications for a single TBBS menu named 0000.

Billing:7, the next line, indicates that the above menu will accrue time 
against the user's account in  Billing Class 7, as specified in ULEDIT by 
the TBBS system designer.  If this line is absent, the menu is assigned to 
Billing Class 0 by default.

Next comes the line that reads Title:.  This command -- like the Menu: and 
EndMenu: commands -- tells the SDL compiler that the text which follows -- 
until the line that reads EndTitle: is reached -- will be displayed as the 
title of the specified menu.

The Entry: command specifies the various options offered to the user on this 
particular menu.  The specifications that follow the Entry: command ("A1=" 
"Key=" "Type=6" and "Opt Data=Bulletin Board"), indicate the A1 flags that 
must be set for the user to access this specific menu option, the key that 
will activate the option, the option's TBBS Type (in this case, the Receive 
Messages option), and the Opt Data that must be specified for that menu 
option.  These serve the same functions as their counterparts in MEDIT.

You should see by now that the text in an SDL source file is very much like 
the layout of a menu when you look at it with MEDIT.  That's because SDL was 
designed to extend and broaden MEDIT, to replace it totally.

If you wish, you can also decompile all the menus on your TBBS system into a 
single  ASCII SDL source file.  To do this, just type:

SDLDC SAMPLE

If you leave OFF the optional /M: argument that was included in our first 
step, SDLDC will decompile every menu in your system into the single source 
file you've named.  This file will contain all of your TBBS system's menus, 
in easy-to-modify ASCII text, and will afford you a complete overview of 
your system at all times.

It also allows you to use all the powerful features your favorite word 
processor or text editor has to offer modifying and updating your system's 
menus.  Control codes can also be entered in SDL source files, so you can 
build menus incorporating ANSI or IBM graphics.

Now it's time to compile the menu(s) we just decompiled.  Make sure the 
program SDL.COM is in the same subdirectory as SAMPLE.SDL.  Then, type:

SDL SAMPLE

and the SDL compiler will compile the ASCII text file, SAMPLE.SDL, that was 
created when you decompiled the menu(s) from your own system, back into .CTL 
file form.  This new .CTL file would include any changes we made to the 
source file with your text editor -- if we had made any.

Because you can define all of your system's menus in a single ASCII .SDL 
text file, you can also instruct SDL to compile only a single menu from an 
.SDL file.  You do this by following the above command with a slash, "M:" 
and the name of the single menu you want compiled.  In our example, you'd 
type:

SDL SAMPLE /M:0000

to instruct the SDL compiler to compile only the MENU0000.CTL menu file from 
SAMPLE.SDL, even if it contained source code for all of your system's menus.  
This option allows you to keep your entire system's menu definitions in a 
single source file, but still makes it easy to make changes to individual 
menus.

To see how SDL works with your entire system, type the following:

SDLDC SAMPLE

This will make SDLDC decompile ALL the menus on your TBBS system into a 
single SDL source file, named SAMPLE.SDL.  When the compiler's through, load 
up your favorite word processor again and take a look at SAMPLE.SDL.  This 
time you'll see every menu in your TBBS system, written out in SDL source 
code, ready to modify, change, or compile again.

Now, let's compile only the menu from your system that we decompiled as our 
first step in this tutorial.  To do this, type:

SDL SAMPLE /M:0000

You will see that SDL only compiles and replaces MENU0000.CTL even though 
the SAMPLE.SDL file contains all of the menus in your system.

There are two more options you can use when you run the SDL compiler: 
LISTING and / T.

SDL's LISTING option creates a fully expanded ASCII text file of a specified 
single menu or of your entire system, with all the macros you used in your 
original SDL source file fully expanded.  This is useful when you begin 
defining Macros in your SDL source.

SDL Macros are just like the macros used in many applications programs or 
with DOS.  They allow you to specify groups of commands, even entire menus, 
with a single keyword.  We'll discuss SDL Macros -- and the LISTING option
-- in part three of this tutorial series.

The / T option will perform a test compile of any single menu or of your 
entire system.  SDL will compile the menus you specify, but doesn't actually 
write any .CTL files as a result.  This is useful when you want to test to 
make sure you've written your SDL source code correctly.  If you've made any 
errors in your SDL source code, a quick test compile with SDL and the / T 
option will notify you of them with an error message.

Next issue, we'll examine the syntax of TBBS's System Definition Language -- 
the way to actually phrase your SDL commands so the compiler will understand 
them.  Until then, practice using the SDL compiler.  Try decompiling your 
menus.  Use MEDIT to examine each .CTL file and your word processor to 
examine the ASCII SDL source file closely.

As an added exercise, copy one of your menu .CTL files to a file with a new 
name (keeping the .CTL extension), so you have a menu file you can play 
with.  Use MEDIT to change something in the new menu file you've created, 
then decompile the changed menu to SDL.  See if you can spot the changes by 
looking at the resulting .SDL source file with your text editor.  Then, use 
your text editor to try and change the menu BACK the way it was.  Compile 
the changed menu with SDL and see how the new .CTL file looks with MEDIT.

Try these exercises a few times and you'll not only be ready for the next 
installment, you'll be ahead of the rest of the class.  See you then.

- END - 
PS1190-5
Rev. 11/90

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.

