heitml Language Guide
by Keith Oustalet

Note: The Language Guide can also be viewed as a single large Web Page if you'd like to print the entire document.

Who Should Read This

This Language Guide is intended to show you how to use heitml.

Our Introduction and heitml Features sections have already provided you with a few ideas regarding the unique possibilities afforded by a product that combines HTML Web Publishing with SQL databases.

But heitml if also a full-featured programming language. It offers structured, modular programming techniques in an easy-to-learn format. In fact, heitml offers so many straight-forward, common sense solutions to traditional Web Applications development problems that you can't really appreciate it until you've had a chance to work with it for awhile.

This manual is intended to provide a framework of understanding that will enable you to get your heitml applications up and running in the shortest possible time. This is not an HTML tutorial, however, so if you don't already have a working knowledge of it, you should buy an HTML reference book and keep it handy.

One of heitml's many strengths is its ability to interact with SQL Databases in an almost invisible manner. Even if you have no previous experience with SQL you'll find it a relatively simple matter to create a wide range of Database Applications with the tools provided in our dba Library. Every computer language has it's own rules and commands to learn, and heitml is no different. But we think you'll find heitml so similar to HTML that it will seem like a natural extension of the working habits you've already developed. SQL poses a few new challenges, but if you don't already know the difference between adding a <TABLE> to your HTML Web Pages and "CREATE"-ing a TABLE in SQL, don't panic, because those differences should become clear in the sections where SQL database operations are explained.

Best of all, you don't have to be an experienced programmer to learn how to use heitml as a stand-alone language. Like HTML, heitml was designed to appeal to non-professionals, and you'll be surprised to discover how quickly you can get professional-looking applications up and running. Many books have succeeded in teaching the basics of HTML in a week or less, and we think heitml can be learned in a similar time-frame.

Of course, heitml really shines if you're already familiar with concepts like Modular Programming, Functions, Procedures, and Parameter Passing; topics that have become so important to modern programming languages that professionals would feel lost without them. Again, however, you don't need to panic if these areas are new to you. The Language Guide tells you what you need to know when you need to know it, and it provides many easy to understand examples that demonstrate how these techniques are to be employed. With the recent announcement from Microsoft that future versions of their Web Browser will be fully integrated with the operating system, it should be clear that "Browser-based" applications are the wave of the future and that programmers (professional or not) will need new tools to help them keep up with this fast changing world. heitml is proud to be among the first of those tools, and we are equally proud that our product has features that will appeal to the most hard-core and dedicated C or Java programmers, yet remains accessible to the legion of non-professional HTML programmers who played such a large part in making the World Wide Web what it is today.

Suffice it to say that, whether you're an HTML programmer who is looking to expand his/her horizons, or a full-time professional who wants to retain the features of his favorite language, yet work within a single integrated environment, we think you'll find that heitml is a software system that truly "takes the World Wide Web to a higher level".

Designing Web Page Templates

heitml provides a high-level framework within which you can develop, enhance, and maintain Web Sites, along with the ever growing amount of data you want to publish on the World Wide Web.

We're going to demonstrate how this framework operates by providing you with concrete, real-life examples. First we'll define a Web Page "template" that can serve as a model upon which to build your Web Applications. This template will not only make it quicker and easier to get your Web Pages up and running, it will ensure that your Pages maintain a consistent "look and feel". Users will feel comfortable navigating your Site, without becoming disoriented or confused about where they are, or where they want to go.

Our first example will assume you have a corporate or product Logo you'd like to display at the top of each page, followed by a marketing slogan. Also, at the bottom of each page you want to let everyone know how they can send you Email.

We only need a few heitml specific Tags for this; namely, the <def>, <defenv>, and <include> Tags.

Defining your own Tags

First, let's define a Tag that will display your Logo whenever it's called:

<def ShowLogo>
   <IMG SRC="/DirectoryName/LogoName.gif">
</def>

As you can see, we've simply taken an HTML command that points to an image source and given it a name. From now on, any time you want to display "LogoName.gif" in a Web Page, all you have to do is place the pre-defined <ShowLogo> Tag in your code, and heitml will insert the necessary information into the HTML page before passing it on to your Web Browser.

Next, let's define another Tag to hold a slogan that you want associated with your company or product:

<def ShowSlogan>
  <P>
  <FONT COLOR="#8b0000>
  <B>h<I>ei</I>tml takes the World Wide Web 
  to a higher level!</B>
  </font>
  <P>
</def>

Now we'll define a Tag that shows your Emaill address, at the same time providing a hot-link directly to your mail box:

<def EmailAddress>
 <P>
 Send your comments to
 <A HREF=MAILTO:oustalet@h-e-i..de> 
    oustalet@h-e-i.de </A>
</def>

The <defenv> Tag ties everything together for us like this:

<defenv MyWebPageLayout> 
  <HTML>
    <BODY BGCOLOR="BEIGE"> 
      <ShowLogo>
      <ShowSlogan>
        <defbody> <P>
      <EmailAddress>
    </BODY>
  </HTML>
</defenv>

Finally, let's assume that we've placed all of the above code examples into a file called "mylayout.hei". From now on, anytime we start to design a new Web Page, all we need do is include "mylayout.hei" at the top. You then make a call to <MyWebPageLayout>, add any additonal statements necessary to complete that Web Page, and then let heitml know you've finished by issuing the End Tag </MyWebPageLayout>.

Here's what it should look like:

<include mylayout.hei>
 
<MyWebPageLayout>
 
Anything else you want to do with this Web Page 
should be placed here.
 
</MyWebPageLayout>

And here's what MyWebPageLayout looks like when interpreted by your Web Browser:

heitml takes the World Wide Web to a higher level!

Anything else you want to do with this Web Page
should be placed here.

Send your comments to oustalet@h-e-i.de

There are many things you can do to spruce up <YourOwnWebPageLayout>, but of course, we're just getting started.

Creating SQL Tables

If you're an SQL user, chances are that you already have a number of database files available, and that some or all of them will be used in developing your heitml Web Pages. Nevertheless, there may be times when you wish to create new SQL tables from within your heitml application, and the following code samples provide a simple demonstration of how that can be accomplished using the <dbupdate> command.

For Standard SQL: Some SQL's allow this:

<dbupdate> CREATE TABLE tablename (Guest_Name char(50), Email char(50), Address char(60), Country char(60), Comment char(250), Password char(8)) </dbupdate>

<dbupdate> CREATE TABLE tablename (Guest_Name varchar(50), Email varchar(50), Address varchar(60), Country varchar(60), Comment varchar(250), Password varchar(8)) </dbupdate>

For Standard SQL:	Some SQL's allow this:
*<dbupdate> CREATE TABLE tablename* (Guest_Name char(50), Email char(50), Address char(60), Country char(60), Comment char(250), Password char(8)) </dbupdate>**	<dbupdate> CREATE TABLE tablename (Guest_Name varchar(50), Email varchar(50), Address varchar(60), Country varchar(60), Comment varchar(250), Password varchar(8)) </dbupdate>

Note: It is beyond the scope of this text to discuss the differences between various implementations of SQL. If you are only using one SQL database program, you probably don't care about the differences. And if you're using more than one, chances are you've already discovered these differences for yourself. Many vendors add their own extensions to a given software standard, either as a means of filling what they perceive to be gaps in their functionality, or simply as a means of differentiating their product from that of another vendor. This Language Guide will strive as much as possible to adhere to the SQL standard and provide single code examples that work under all SQL implementations. When necessary or desireable, however, we will provide multiple examples, leaving it to the Reader to ponder the reasons why.

Creating heitml FORMs

The HTML FORM Tag gives us much to be thankful for. We use it to create fill-in forms containing checkboxes, radio boxes, text input windows and buttons, and without it, our Web Pages would not be nearly so interactive. But designing HTML FORMs can sometimes be a bit of a chore, which is why heitml users will discover that they now have additional reasons to be thankful.

As illustrated earlier, heitml allows us to define our own Tags, and, as we are about to see, this feature greatly simplifies the FORMs creation process.

Suppose we wanted to create the following simple input form that allowed visitors to our Web Site to sign a guestbook and give us their comments:

Guest book form:

Here's an example of how HTML users might create this form:

<H3> Guest book form </H3> 
<FORM ACTION=gins1.hei>
 <TABLE BORDER>
  <TR>
   <TD> Guest_Name </TD> 
   <TD> <input name="Guest_Name" size=25> </TD> 
  </TR>

  <TR>
   <TD> Email  </TD>
   <TD> <input name="Email" size=25> </TD>
  </TR>

  <TR>
   <TD> Address </TD>
   <TD> <input name="Address" size=25> </TD> 
  </TR>

  <TR>
   <TD> Country </TD>
   <TD> <input name="Country" size=25> </TD>
  </TR>

  <TR> <TD> Comment </TD>
       <TD> <textarea name="Comment"
                      cols=30
                      rows=2 
                      wrap="physical"> 
            </textarea> </TD>
  </TR>
 </TABLE>
 <INPUT TYPE="submit" VALUE="Submit">
</FORM>

HTML users see this as a simple, straightforward approach to laying out a FORM. heitml users, however, would likely take a different approach. Notice that the HTML code has a rather cluttered look about it, even though we've used indentations wherever possible to enhance readability and to better show those elements that are dependant upon (or contained within) higher-level control elements. (For instance, the <form> contains a <table> composed of <TableRows> that, in turn, display <TableData>.) This is a long-established, heirarchial approach to programming that has been widely employed.

And yet, as we'll see in just a moment, heitml allows us to go a step further in this regard. By defining our own Tags, heitml lets us take a modular approach to Web Page Publishing, in the process creating a set of re-useable tools that become more valuable with each Page we create.

To illustrate this concept, let's look again at the guestbook FORM, but this time, instead of looking at the HTML code, let's look at it the way your Web Browser displays it and see what we notice.

Guest book form:

We might describe this form by saying that it has seven elements: a Title, four simple input fields, a textarea, and a button. But notice how the act of describing the form actually reveals that we are not dealing with seven elements, but instead only four:

A Title
Input Fields
A Textarea
A Button

Now let's take what we've observed and see if we can define heitml Tags to handle these four elements. The first element, the <FormTitle> can be handled with a simple variable declaration:

<let FormTitle="Guest book form:">

Input Fields are composed of a label name followed by a number representing the maximum length (or size) of the data field, and we can define such a Tag in heitml as follows:

<def InputField>
 <TR>
  <TD> <? name> </TD> 
  <TD> <input name="<? name>" size=<? size>> </TD>
 </TR>
</def>

The Textarea is composed of a label name, an integer representing the column width, another integer specifying the number of rows that will be displayed on-screen, and an instruction that tells HTML how to wrap text. The heitml Tag to define it looks like this:

<def InputTextarea>
  <TR> <TD> <? name> </TD>
       <TD> <textarea name = "<? name>" 
                      cols = <? cols> 
                      rows = <? rows> 
                      wrap = "<? wrap>" >,
            </textarea> </TD>
  </TR>
</def>

Our fourth and final FORM element is a button that tells HTML we've finished entering data into the FORM and we're ready to submit it for processing. Let's define it as follows:

<def Submit>
  <input type="submit" value="Submit"> 
</def>

Now that we've taken a higher-level look at our FORM elements and organised them into re-useable modules, let's see how heitml brings them all together with a practical coding example:

<form action=gins1.hei>
 <h3> <? FormTitle> </h3>
 <table border>
  <InputField name = "Guest_Name" size = 25> 
  <InputField name = "Email"      size = 25> 
  <InputField name = "Address"    size = 25> 
  <InputField name = "Country"    size = 25> 
  <InputTextarea name = "Comment"
                 cols = 30 
                 rows = 2 
                 wrap = "physical">
 </table>
 <Submit>
</form>

By modularizing our FORM elements we've reduced the task of creating this and any future FORMs to a few simple procedure calls. We can modify the FORM by adding or deleting input and textarea fields at will, just by passing the necessary parameters to our pre-defined Tags.

Notice how much simpler it is to read the above heitml code in comparison to the previous HTML coded FORM. We are no longer distracted by the clutter of HTML Tags that open and close <TableRows> and <TableData>, because all of that is handled automatically by the code we created when we defined the <InputField> and <InputTextarea> procedures.

In fact, we should point out that a special feature of heitml syntax allows us to go one step further in eliminating the cluttered look of HTML. If we think of HTML Tags as "text handling Tags" and heitml Tags as a series of "programming processes or procedures" then it makes sense to enhance the programming "look and feel" of heitml by employing a semi-colon to separate these processes from one another (as illustrated by the following):

<form action=gins1.hei>
 <h3> <? FormTitle> </h3>
 <table border>
  <InputField name = "Guest_Name" size = 25; 
   InputField name = "Email"      size = 25; 
   InputField name = "Address"    size = 25; 
   InputField name = "Country"    size = 25; 
   InputTextarea name = "Comment"
                 cols = 30 
                 rows = 2 
                 wrap = "physical";
  > 
 </table>
 <Submit>
</form>

Once we've entered heitml processing mode (which happens any time heitml recognizes a User-defined Tag) we've already more or less made the switch from a Document Description Language view of things to a Procedural Programming Language view anyway, so it makes sense to employ this new syntax.

We'll see more useful examples of this syntax later. For now it's enough to simply think of it as a way to get rid of a few unattractive looking less-than/greater-than symbols.

Astute readers should note that they can use heitml to create an entire suite of buttons for use within their FORMs, similar to the <Submit> button we've created as an example. All of these buttons can be kept together in an <include> file along with any other pre-defined Tags needed to create your heitml application.

Summary

In this section we took a new look at the process of creating HTML FORMs by introducing the concept of modularity. We showed how you could use heitml Tags to define procedures that not only help automate the task of creating FORMs, but have the added benefit of making your code easier to read and understand. These methods can be applied to virtually all aspects of HTML Web Pages and we hope that by studying these examples you will begin to see possibilities for your own applications, both old and new.

Accessing Databases

You access SQL databases with heitml's <dbquery> command. We'll start here with a simple example and then build on it, with subsequent examples becoming progressively more complex. Along the way, you'll not only develop an appreciation for the usefulness of the <dbquery> command, but you should also come away with ideas to use when addressing specific problems in the applications you develop.

All of these examples will draw information from our "guestbook" database, which you can see if you visit our SQL Form example page.

Extracting FIELD NAMES from an SQL TABLE

Normally, you would expect to know the field names already, assuming that the SQL TABLE or DATABASE resides on your own server. But let's pretend for a moment that you can't remember the fields for a particular TABLE, and you're too lazy (or too engrossed with your current programming assignment) to consult whatever documentation you keep on hand to answer such questions.

So let's use the following <dbquery> to get the information we need:

<dbquery>  SELECT * FROM guestbook 
   <db head> <fname> 
</dbquery>

And here's the result of that query:

Guest_Name Email ADDRESS Country Comment Password

Now let's see if we can separate the field names from each other by surrounding the query with a TABLE BORDER. While we're at it, let's make it a bit easier to read by defining the field names (represented by the <fname> tag) as though they were TABLE HEADINGS. Modifications to the code are shown in red:

<table border bgcolor=ffffff>
   <dbquery>  SELECT * FROM guestbook 
      <db head> <th> <fname> </th> 
   </dbquery>
</table>

And here's our new result:

Guest_Name Email ADDRESS Country Comment Password

Of course, now that we know what field names are in the TABLE, we might like to take a look at some of the records.

Displaying records from an SQL database

We could display the records contained within the Guestbook by making another simple modification to our code (also shown in Red).

Note: Because this is only an example, and it's not necessary for us to see every record in the guestbook database at this time, we've limited the srvmax variable to 4. You might want to keep this in mind when developing your own applications, especially if the default value for srvmax on your system is set to a very high number. You wouldn't want heitml to generate an HTML page that listed a million records. That would tie up your Web Server quite a while (not to mention the transmission time to the client's Web Browser).

<let srvmax = 4>
<table border bgcolor=ffffff>
   <dbquery>  SELECT * FROM guestbook 
      <db head> <th> <fname> </th> 
        <db body>  
        <db rowbegin> <tr> 
           <db column> <td> <field> </td> 
        <db rowend> </tr> 
   </dbquery>
</table>

And here's the result (note that the Comment field has been omitted to fit within the confines of the Browser display window):

Guest_Name Email ADDRESS Country
Hermann P. Rapp rapp@regio-info.de D-68259 Mannheim Germany/ Europe

The Giant from Armonk BigBlue@ibm.com Armonk, New York USA

Marc Boschma marcb@telstra.com.au Locked Bag 4840. Melbourne, VIC 8100 Australia

Keith Oustalet oustalet@h-e-i.de E 7, 14 : 68159 Mannheim Germany

Guest_Name	Email	ADDRESS	Country
Hermann P. Rapp	rapp@regio-info.de	D-68259 Mannheim	Germany/ Europe
The Giant from Armonk	BigBlue@ibm.com	Armonk, New York	USA
Marc Boschma	marcb@telstra.com.au	Locked Bag 4840. Melbourne, VIC 8100	Australia
Keith Oustalet	oustalet@h-e-i.de	E 7, 14 : 68159 Mannheim	Germany

Even though the srvmax variable has been limited to 4, we can discover the true number of records satisfying a given search condition by using the SQL COUNT() command. Here's how we'd change our code:

<let srvmax = 4>
<table border>
   <dbquery>  SELECT COUNT(*) FROM guestbook 
      <db head> <th> <fname> lt;/th> 
        <db body>  
        <db rowbegin> <tr> 
           <db column> <td> <field> </td> 
        <db rowend> </tr> 
   </dbquery>
</table>

And here's the result:

EXPR
28

EXPR
28

One of the niecest things about heitml's <dbquery> command is the control it gives you over how you display the results of your queries. The previous examples in this section showed all records in TABLE format, but you can just as easily create an ordered LIST. Here's a code sample:

<let srvmax = 2>
<ol>
  <dbquery>   SELECT * FROM guestbook 
    <db body>   
      <db rowbegin> 
        <li>
          <table border bgcolor=ffffff>
            <db column>
              <tr> <td> <b> <fname> </b> </td> 
                   <td> <field> </td>
              </tr>
      <db rowend> 
          </table> <p>  
  </dbquery>
</ol>

And here's the resulting output:

Guest_Name	Hermann P. Rapp
Email	rapp@regio-info.de
ADDRESS	D-68259 Mannheim
Country	Germany/ Europe
Comment	Pretty impressive !! heitml will take our website http://www.regio-info.de to a higher level .....
Password

Guest_Name	The Giant from Armonk
Email	BigBlue@ibm.com
ADDRESS	Armonk, New York
Country	USA
Comment	Nice implementation of SQL here.
Password

Before we leave this section on Accessing Databases we should note that each of the preceding code examples assumed that you wanted to show all the fields belonging to a given query (as defined in the SELECT * command). You can, of course, limit the fields returned by a query simply by specifying the fields you want to see (e.g. SELECT Guest_Name, Email FROM guestbook).

Alternatively, however, we could also control the output from a query by using a more specific syntax within the framework of a <dbquery> Tag, illustrated as follows:

<let srvmax = 4>
<table border bgcolor=ffffff>
  <tr> <th> Name <th>
       <th> Email </th>
    <dbquery q> SELECT * FROM guestbook 
      <dbrow>
         <tr> <td> <? q.Guest_Name> </td>
              <td> <? q.Email> </td>
         </tr>
    </dbquery>
  </tr>
</table>

And the output looks like this:

Name Email
Hermann P. Rapp rapp@regio-info.de

The Giant from Armonk BigBlue@ibm.com

Marc Boschma marcb@telstra.com.au

Keith Oustalet oustalet@h-e-i.de

Name	Email
Hermann P. Rapp	rapp@regio-info.de
The Giant from Armonk	BigBlue@ibm.com
Marc Boschma	marcb@telstra.com.au
Keith Oustalet	oustalet@h-e-i.de

Even though the SELECT * command requested every field from the guestbook, we used the <dbrow> feature of the <dbquery> command to display only a sub-set of those fields.

Creating Hot Links with data obtained from SQL TABLES

Our last example above generated a list of names and Email addresses, but these Email addresses would be far more useful if you could simply click on them and send a message. Because heitml makes it so easy to mix HTML code with your SQL queries, we only have to make one small change to our code to bring the information in our SQL guestbook to life:

<let srvmax = 4>
<table border bgcolor=ffffff>
 <tr> <th> Name <th>
      <th> Email </th>
  <dbquery q> SELECT * FROM guestbook 
   <dbrow>
      <tr> <td> <? q.Guest_Name> </td>
           <td> <a href=mailto:<? q.Email>>
                 <? q.Email> </a> </td> 
         </tr>
    </dbquery>
  </tr>
</table>

And here's the new output:

Name Email
Hermann P. Rapp rapp@regio-info.de

The Giant from Armonk BigBlue@ibm.com

Marc Boschma marcb@telstra.com.au

Keith Oustalet oustalet@h-e-i.de

Name	Email
Hermann P. Rapp	rapp@regio-info.de
The Giant from Armonk	BigBlue@ibm.com
Marc Boschma	marcb@telstra.com.au
Keith Oustalet	oustalet@h-e-i.de

Summary

In this section we started off by showing you how to interrogate an SQL TABLE or DATABASE in order to find out the names of the individual fields. Then we showed how to take those field names and use them in the heading of an HTML <table> that displayed individual records from the DATABASE. We showed you how to control the number of records outputted from your Server, using the <srvmax> variable, as well as how to find out how many records satisfied a given search condition by using the SQL COUNT() command.

We demonstrated the flexibility of heitml's <dbquery> command by showing you alternative ways of displaying results from a search (e.g. creating an ordered list with HTML's <ol> Tag). We also showed how you can restrict the information a user see's, either by specifying field names through the SQL SELECT command, or by using a more specific syntax within the <dbquery> Tag.

And finally, we showed how easily HTML tags can be interleaved with SQL queries by creating hot links to information found within the SQL database.

We have certainly not exhausted the possibilities of heitml's <dbquery> Tag. There are literally thousands of ways to retrieve data using the SQL SELECT command, and the way you present that data is limited only by your imagination. But we've given you some ideas to get you started, and the best way to become proficient with <dbquery> is to make your own modifications to the above examples and see how they work.

Altering SQL Tables

SQL users know they can ADD or DROP fields from an SQL TABLE by using the ALTER TABLE command. Similarly, entire files can be added to (or dropped from) an SQL DATABASE with the ALTER DATABASE command.

heitml wouldn't be complete if it didn't give you the same degree of control over your environment, so we'll show you how to do that with the <dbupdate> Tag. Although we won't spend a lot of time here, the syntax of <dbupdate> is quite simple, and you shouldn't have any trouble applying it in a wide variety of situations.

To ADD a field: To Drop a field:

<dbupdate> ALTER TABLE guestbook ADD Password CHAR(8) </dbupdate>

<dbupdate> ALTER TABLE guestbook DROP Password <dbupdate>

To ADD a field:	To Drop a field:
<dbupdate> ALTER TABLE guestbook ADD Password CHAR(8) </dbupdate>	<dbupdate> ALTER TABLE guestbook DROP Password <dbupdate>

Naturally, it is beyond the scope of this Language Guide to enter into a discussion of the relative merits or potential pitfalls of allowing Client Users to make modifications to your SQL TABLES and DATABASES. There may be times, however, when you, the application designer, find it convenient to make such modifications on your own Server while working within the heitml framework. In any case, heitml's goal is to provide a seemless, integrated HTML/SQL environment. We can only assume, therefore, that you have taken the precaution of defining a list of valid User Names and Passwords in the Security Database on your Server, thus protecting your SQL DATABASES from unauthorized changes.

Updating SQL Tables

This section will demonstrate how to use the SQL INSERT, DELETE and UPDATE commands from within your heitml applications. All of these operations can be performed within heitml's <dbupdate> Tag. As usual, we'll be working with our SQL guestbook to demonstrate our examples, and we'll start by showing how to add records to it. If you haven't already read about Creating heitml it would be a good idea to do so now, because our first example assumes that the information being added to the guestbook was obtained from the heitml FORM created in that section.

Here is what the code looks like:

<dbupdate> 
  INSERT INTO guestbook  
   (Guest_Name, Email, Address, Country, Comment)
  VALUES
   (<? ff.Guest_Name quoted>,
    <? ff.Email quoted>, 
    <? ff.Address quoted>, 
    <? ff.Country quoted>,  
    <? ff.Comment quoted>)
</dbupdate>

As you can see, we've used the heitml ?-Tag above to evaluate the contents of the "ff.fieldname" expressions and pass the result along to SQL for insertion into the database. Additionally, we specificed the quoted argument to ensure that the result was treated as a string. The effect is the same as if we had done the following:

<dbupdate> 
 INSERT INTO guestbook  
  (Guest_Name, Email, Address, Country, Comment) 
 VALUES
  ("Keith Oustalet",
   "oustalet@h-e-i.de", 
   "1812 Madison St., Metairie, LA 70001", 
   "USA",  
   "I'll be famous now that my name appears in a 
    heitml Web Page.") 
</dbupdate>

Experienced programmers know, however, that this literal method of INSERT-ing records into a file is too specific to be generally useful. Since our the first method accepts input from variables whose values are reassigned each time a user fills out the guestbook FORM and clicks on the pre-defined <Submit> button, it is more flexible and, thus, more practical for real-world applications.

To DELETE a record from an SQL TABLE we could, again, do it by referencing the contents of a variable, or by matching a literal as follows:

By referencing a variable:

<dbupdate> 
  DELETE FROM guestbook
   WHERE 
     Guest_Name = <? ff.Guest_Name quoted> 
</dbupdate>

By matching a literal:

<dbupdate> 
  DELETE FROM guestbook
   WHERE 
     Guest_Name = "John Smith" 
</dbupdate>

Finally, the syntax of the SQL UPDATE command could be illustrated as follows:

<dbupdate> 
  UPDATE guestbook
    SET  Guest_Name = <? ff.Guest_Name quoted>, 
              Email = <? ff.Email quoted>, 
            Address = <? ff.Address quoted>
   WHERE Guest_Name = <? Old_Guest_Name quoted> 
</dbupdate>

A Sample heitml Database Program

Previous sections of this Language Guide introduced a variety of heitml topics. Some, like Defining your own Tags, were simple and straightforward. Others, like Creating FORMs, showed the advantage of using a modular, "tool building" approach to designing your heitml applications. In each of these sections we tried to stimulate your thinking and show how heitml adds new dimensions to HTML Web Publishing. Now it's time to take what we've learned and "put it all together", so to speak.

In this section we'll re-visit some of the topics already covered and, in the process, create modules and procedures that show how simple it is to launch new Web applications with a minimum amount of effort, while simultaneously giving them a professional, well-ordered appearance.

We'll start by assuming that you have an SQL TABLE called LINKS which you created to store information about interesting things you've found while surfing the Web. Lots of Web Sites have a "Links" page these days, but they seldom give you much information about the Site itself, or what you can expect to find once you get there. Therefore, in creating this LINKS database, we'll further assume that you want to use it more or less as a showcase of information that can be shared with other users.

So, here's one example of the type of Fields this SQL database could contain, as well as a code fragment to CREATE it:

<dbupdate> 
    CREATE TABLE LINKS 
           (TITLE        varchar(30), 
            IMAGEPOINTER varchar(64), 
            WEBSITEURL   varchar(100), 
            DESCRIPTION  text)
</dbupdate>

The TITLE field will be used like chapter headings to create a table of contents that points to the information in the database. IMAGEPOINTER contains the location of a GIF or JPG that represents the type of artwork a User might expect to find at the Site if he clicks on the the hot-link contained in the field WEBSITEURL. And finally, DESCRIPTION, of course, is anything you want to say that helps the User decide whether or not the Site's worth visiting.

Now let's take a Top Down approach to designing a heitml-coded Web Page that allows the User to access the records in this database.

First, we'll design a Layout similar to what we saw in the Designing Web Page Templates section of this manual. We'll include all the usual elements, a Logo, a Slogan, an Email address to appear at the bottom of the page, and, just for the hell of it, a picture of the not-so-handsome guy who created the application (as well as this Language Guide). We won't show the actual code for this Layout because it's simply a variation on what you learned in the Designing Web Page Templates sub-section of Getting Started.

The main body of our Web Page will contain a narrow "Table of Contents" column on the left, with a much larger column on the right to display information about the various Web Sites contained in our LINKS database. The table of contents will therefore be a list of clickable references (or pointers) to the individual database records. Each time a User clicks on an item in the Table of Contents column, we'll simply re-initialize our Web Page, and pass a variable to an SQL SELECT statement to retrieve the information.

When our application first starts, we could just list the Table of Contents on the left and wait for the User to click on something. But it would be even better if we started our application with a default value that points to an introductory record that explains what our LINKS database is all about.

And that's just about it, really. We need just three items: a Web Page Template (or Layout), a Search Variable (containing either a default value, or a pointer to the item the User wants to see), and a MainBody (subdivided into a Table of Contents column, and a RecordInfo column).

Here's what our Top-level code would look like:

<include mylayout.hei> 
 <KeithWebPageLayout> 
      <SetSearchValue> 
      <MainBody>
 </KeithWebPageLayout>

One of the benefits of Top Down design is that all the coding details are hidden from us until such time as we need to see them, instead of cluttering up the page and making it difficult for the programmer to zoom in on the section of code we're interested in.

Right now, of course, we want to examine the pre-defined <SetSearchValue> Tag to see how values are assigned to the SQL SELECT search-variable used later point in the program:

<def SetSearchValue>
 <if isempty(ff.gn)>
   <let gl.GetRecord=" INTRODUCTION">
 <else>
   <let gl.GetRecord=ff.gn>
 </if>
</def>

Obviously, the first time our Web Page is called, ff.gn will be empty, so we assign the default value " INTRODUCTION" to the global variable gl.GetRecord . (Notice that we have a leading "space" character before the word INTRODUCTION. This is just a little trick we've used to force INTRODUCTION to always appear at the top of our alphabetically sorted Table of Contents.) For all subsequent calls to our Web Page, ff.gn will contain the TITLE selected for viewing by the User.

Now let's look at the <MainBody> Tag:

<def MainBody>
 <TABLE>
   <TR> <TD WIDTH="17%" VALIGN="top"> 
            <ShowTableOfContents>
        </TD>

        <TD VALIGN="top">
            <ShowRecordInfo>
        </TD>
   </TR>
 <TABLE>
</def>

Here's where we discover how to divide our display area into columns. We've simply used the HTML <TABLE> Tag to define a <TableRow> with two <TableData> columns. The first column is limited to only 17% of the useable page area which, by default, gives the remaining page area to the second column. In both cases we've used the VALIGN="top" argument to make sure that the data in both columns always starts from the top. We don't know which column will be longer than the other and we don't care. We just want to make sure that the User sees data from the very top of the display area (after the WebPageLayout information) and doesn't have to go hunting for it.

Now let's take a look at the <ShowTableOfContents> Tag:

<def ShowTableOfContents>
 <TABLE>
  <FONT size="-3">
    <dbquery q> 
      SELECT TITLE FROM LINKS ORDER BY TITLE
       <dbrow>
        <TD>
         <a href=kdisrec1.hei?gn=<? q.TITLE furl>>
             <? q.TITLE></a><br>
        </TD>
    </dbquery>
  </FONT>
  <p> <img src="Bilder/V_border.gif">
 </TABLE>
 <p>
</def>

A couple of things are worth mentioning here. First, we see that <ShowTableOfContents> reveals that we are dealing with nested tables, since all of the data displayed by this Tag is itself contained within the parent TABLE defined in the <MainBody> Tag.

Next, because we know that the <MainBody> Tag has allocated only 17% of the displayable page area to the <ShowTableOfContents> Tag, we've used the HTML <FONT> Tag to select a small type size. This will help to ensure that our TITLE data stays within its pre-defined limits.

Finally, the real work of this Tag is performed by the heitml <dbquery> Tag, which we've highlighted for your attention. The SQL SELECT statement contained within <dbquery> gets all the TITLE data, sorts it alphabetically, then displays it in hot-link format.

The <img src> Tag appearing just before we close the TABLE is simply to provide a vertical border at the bottom of the Table of Contents column. If the Table of Contents were to grow very long, we'd eventually eliminate this line of code.

The last thing we need to look at is the <ShowRecordInfo> Tag:

<def ShowRecordInfo>
 <TABLE>
  <dbquery q>  SELECT * FROM LINKS
   WHERE TITLE=<? gl.GetRecord quoted>
   <dbrow>
    <IMG SRC=<? q.IMAGEPOINTER> ALIGN="left">
    <H3> <?gl.GetRecord> </H3>
    <A HREF=<? q.WEBSITEURL >> 
               <? q.WEBSITEURL> </A>
    <P> 
    <B> <? q.DESCRIPTION html> </B>
  </dbquery>
 </TABLE>
</def>

Again we see a nested table. We also see how the gl.GetRecord variable defined in the <SetSearchVariable> procedure is finally used to retrieve the particular record our User wants to see. More importantly, however, is the way the <ShowRecordInfo> Tag shows how seemlessly HTML statements can be interleaved with heitml.

So there it is. A Top Down approach to Web Page Publishing. You never have to look at more than a few lines of code at once (and if you do, you'll probably find you haven't modularized your data enough yet). We hope you've been impressed by how little code we needed to generate to get this Web Page up and running, but this simple programming example is just the beginning. The more you work with heitml, the more you'll find it has to offer.

User-defined Functions

We know there'll be times when you need to define a function for you own purposes. As much as we'd like to provide you with a comprehensive set of Library and Built-In Function, we can't think of everything, so the next best thing is to allow you to create your own.

Functions are defined as follows:

<def FunctionName [Parameter1, Parameter2,...]; [heitml] return expression; /def>

The FunctionName is required, of course, but you only have to include as many or as few parameters as needed to complete whatever task you want to perform. Some functions don't require any parameters, but most require one or two. The [heitml] in the above definition means that you can include whatever intermediate statements are necessary to manipulate the passed parameters before arriving at a result. Mostly, however, you'll find that your functions can simply evaluate the parameters in an expression, the result of which is returned or "passed back" to the program.

To illustrate this concept let's first define a couple of simple mathematical functions that require only one parameter. We'll call them sqr and cube because they take a numerical value (real or integer) and raise them to the second and third powers respectively. Here's what they look like:

heitml input: <def sqr x; return x * x; /def> <let x=4; ? sqr(x)> <br> <? sqr(5)>	heitml input: <def cube x; return x * x * x; /def> <let x = 3; ? cube(x)> <br> <? cube(4)> <br> <? cube(sqr(2))>
resulting output: 16 25	resulting output: 27 64 64

As you can see, you can pass parameters to heitml functions any way you like: as pre-defined variables, as constants (sometimes referred to as "immediate" values), or you can even pass another function as an argument (nested functions).

Now we'll go one step further and design a function with two parameters called power, which takes a number x and raises it to the power y:

heitml input:

<def power x y;
  i = 1; a = x;
  while i <y; a = a * x; i = i + 1; /while; 
  return a;  
 /def>

<let x = 3; y = 4; ? power(x,y)>
<br> <? power(2,16)>

resulting output:
81
65536

There are several interesting things we should point out about the above function. First, you'll notice that we couldn't simply evaluate x and y in a mathematical expression and return the result. We had to perform a series of intermediate steps which included

initializing a counter variable called i
preserving the initial value of x by assigning it to variable a
multiplying a by x
incrementing the counter variable i
and repeating the calculation while i < y

We could also have initialized i to a value of 2 and repeated the calculation while i <= y. Either method would have suited our purposes.

Now let's take a look at some functions that manipulate character strings. Here's an example that returns the leftmost "x" number of characters from a string:

heitml input:

<def left string x;
   return substring(string,0,x);  
 /def>

<let string="1234567890"; x=4; ? left(string,x)>

resulting output:
1234

Notice that we used the heitml Built-in Function substring to do most of the work for us.

And now here's a function that returns "x" number of characters starting from the right side of a string:

heitml input:

<def right string x;
   return
   substring(string,len(string)-x,len(string));  
 /def>

<let string="1234567890"; x=4; ? right(string,x)>

resulting output:
7890

OK, by now you should have an idea of what's required to create your own functions, so go ahead and have fun!

Control Statements

heitml provides two basic control Tags called <if> and <while> which, as we will see shortly, can be used in a wide variety of situations. Although heitml is not normally a Case Sensitive language, internal Tag names such as "if" and "while" must always appear in lower case, otherwise heitml will not recognize them. Needless to say, this will cause your programs to react in a manner different from what you intended.

Earlier in the Language Guide we mentioned the fact that, in additon to standard HTML syntax, heitml Tags can use an alternate syntax to eliminate some of the clutter caused by all the "< >" symbols that appear in HTML pages. Although we will introduce the <if> and <while> Tags using the traditional HTML syntax, from now on, when appropriate, we will use the alternate syntax to give our Source Code examples a cleaner look. (For a more complete discussion of heitml's alternate syntax, see "heitml as an integrated Template and Programming Language" in the General Design page of the Language Reference.)

Here is the <if> Tag in its basic form:

<if condition> Do This <else> Do That </if>

And here is a similar example for the <while> Tag:

<while condition>
Other heitml & HTML Tags and Text
</while>

These two examples, while deceptively simple, lay the foundation for the development of incredibly flexible and sophisticated Web Applications. Let's see if we can describe a few situations that demonstrate what we are talking about.

At the time this is being written, anyone with Internet access can visit the Web Sites of Microsoft or Netscape to download a free copy of the most current version of their Web Browser software. One would think that such a policy would almost guarantee that everyone in the Web Community would always use the latest Browsers these companies have to offer. In truth, however, there are many reasons why we find a lot of people using old Browers that do not support the latest features.

In any event, Web Designers often find themselves in a position where they either have to choose between creating simple, "plain Vanilla" Web Sites catering to the least capable Web Browsers, or they are forced to maintain multiple versions of their Web Sites. This stiuation could be as simple as the old "Frames/no-Frames" issue, but today it more often involves issues related to competing technologies like JavaScript, VBScript, JavaApplets, and ActiveX, not to mention the ever growing number of Plugins available from other Vendors.

Fortunately, heitml offers a way to find out what kind of Web Browser and Operating Systsm is being used by the people who Surf your Site and, in combination with the <if> statement, set up multiple pathways to service these Users from within a single Web Page.

One of the Built-in Server Variables heitml recognizes is called SrvUserAgent. (See Server Information in the heitml Running Examples section for a complete list.)

Here is the information SrvUserAgent shows us about you:

MSIE

And here are some of the things we've seen returned by the SrvUserAgent variable about other people surfing our Web Site:

Mozilla/3.01 (Win16;I)
Mozilla/3.01 (Win95;I) via proxy gateway CERN-HTTP/3.0 libwww/2.17
Mozilla/2.0 (compatible;MSIE 3.0b; Windows 3.1)
Mozilla/2.0 (compatible;MSIE 3.0B; Win32)
Mozilla/2.0 (X11; I; SunOS 4.1.3_U1 sun4m)

If this seems like a confusing variety of information to get from a single variable, don't worry. The important thing here is that in all cases the SrvUserAgent tells us which Browser and Operating System a person is using.

In order to make this clear, heitml has a tool we can use that checks to see if a specific string of characters is contained within a Variable. For instance, we could use the SrvUserAgent as the string to be searched, and call the contains( ) Function as an expression to be evaluated by the <if> Tag.

Here's an example of how that might work:

<if contains(SrvUserAgent,"MSIE 3") && contains(SrvUserAgent,"Win32") > Your Browser supports ActiveX and VBScript < else if contains(SrvUserAgent, "MSIE 3") && contains(SrvUserAgent, "Windows 3.1") > ActiveX is not supported on Windows 3.1 < else if contains(SrvUserAgent, "Win16") || contains(SrvUserAgent, "Windows 3") > Java Applets not supported on this OpSys < /if /if /if>

In the above example the two &&-symbols represent a logical AND condition. In other words, only "if This AND That" are true, will the condition be satisied. The two ||-symbols represent an OR condition, which means a condition is satisfied "if This OR That" is found to be true.

Also, we have surrounded the text statements outputted by each condition in wing-like brackets "> <" to help clarify the fact that one of the features of the heitml alternate syntax is that all text and old-style HTML Tags are executed from "within the wings" so to speak. We'll see more about this alternate syntax in our next example.

For instance, our first example above is provided merely to show how you would build <if> statements that test multiple conditions. In a real-world application you wouldn't just print a message telling a User what features his Browser does or does not support. Chances are he already knows some of the strengths and weaknesses of his given Browser and, for reasons of his own, has decided to stick with it.

Instead, the <if> Tag, contains( ) Function, and SrvUserAgent variable should be used with the thought in mind of discovering things about your Users that later help you dynamically assemble and ship versions of your Web Pages that best take advantage of the capabilities of each User's Browser.

Imagine, for example, that you want to design a re-useable code module to be placed at the top of every Web Page you develop. This code module would be designed to interrogate the SrvUserAgent variable and set values to Global Variables. These values would then tell your application what features should or should not be included in a Web Page. In effect, they would serve as "Guides", creating different views of your Web Pages to different Users.

Here's one way you might do this:

/ / User-defined Tags go first. <def SetUserBrowserValues; / / Initialize Global Variables to "false" gl.ActiveX = "false"; gl.VBScript = "false"; gl.JavaApps = "false"; gl.JavaScript = "false"; / / Test for Browser & OpSys. if contains(SrvUserAgent,"MSIE 3") && contains(SrvUserAgent,"Win32"); gl.ActiveX = "true"; gl.VBScript = "true"; gl.JavaApps = "true"; gl.JavaScript = "true"; else if contains(SrvUserAgent, "MSIE 3") && contains(SrvUserAgent, "Windows 3.1"); gl.VBScript = "true"; gl.JavaScript = "true"; else if contains(SrvUserAgent, "Mozilla/3") && contains(SrvUserAgent, "Win95"); gl.JavaApps = "true"; gl.JavaScript = "true"; else if contains(SrvUserAgent, "Mozilla/2") && contains(SrvUserAgent, "Win32"); gl.JavaApps = "true"; gl.JavaScript = "true"; gl.VBScript = "true"; else if contains(SrvUserAgent, "Nozilla/2") gl.JavaScript = "true"; /if /if /if /if /if; /def> / / Program execution begins here. <SetUserBrowserValues; ShowLogo; ShowSlogan; ShowIntroText; if gl.ActiveX = "true"; LaunchActiveXmenu; else if gl.JavaApps = "true"; LaunchJavaAppMenu; else ShowHTMLmenu; /if /if; MoreStuffGoesHere; ShowNavigationToolBar; ShowEmailInfo; ShowCopyrightMessage >

Notice in the above example that we first set all Global Variables to false as a Safety Valve. This assures that no Browser Specific features will be launched unless it has been determined that it is safe to do so.

Notice also, that instead of constantly opening and closing our heitml Tags with "< >" symbols, we simply separated them with a semi-colon. As you can see, the heitml alternate syntax is closer to what you would expect to find in a programming language because, in fact, heitml is a full-featured programming language. We think you'll find that, as your Web Pages become more heavily populated by heitml Tags and control statements, you will come to depend on this syntax, simply because it makes your code easier to read and understand.

You don't have to use this "programming" syntax if you don't want to, but it provides an easy method of separating heitml Tags from standard HTML Tags, thus helping you to keep track of when you are in "programming mode" and when you're in old-fashioned "text mode" (i.e. HTML mode).

One final thing to notice about the above example is that you no longer see any HTML Tags. HTML is a Document Discription Language. heitml is a modular Programming Language. The more highly structured and modular your code is, the more insulated you are from the underlying HTML formatting details. HTML Tags are still very much a part of heitml programming, but they don't need to clutter up your code, making it difficult to read. If you want to make changes to the <ShowIntroText> or <ShowNavigationToolBar> modules, your merely have to go to the section of code where those modules were defined. Otherwise, they stay out of your way, allowing you to examine the flow of your application from the perspective of a high-level overview.

Before leaving this page we'll give a short example of how to use the <while> Tag. The <while> Tag is designed for situations where a procedure will be executed one or many times, depending on a certain condition. For instance, in database applications it is common for a search query to return more results than can reasonably be listed on a single Web Page.

Here's a technique using the <while> Tag that limits the number of records displayed resulting from an SQL Search Query:

<dbquery > SELECT * FROM guestbook < dbhead; fname; dbbody; i = 0; while i < 10; dbrowbegin; dbcolumn; field; dbrowend; i = i + 1; /while; /dbquery >

Even though the above SQL SELECT statement uses the asterisk to indicate that it wants the query to return every record from the Guestbook table, the while i < 10; limits the amount of data that is outputted to the Web Page.

dba Tutorial: Introduction

The dba Library contains a complete set of Hei-Level tools that make it easy for you to work with SQL Databases. These tools save you the trouble of developing your own solutions to many common database operations.

Using the pre-defined Tags in the dba Library, you can INSERT new records, DELETE or UPDATE old records, and BROWSE both forward and backward through a list of records. You can view data in any sort sequence you desire: alphabetically, by date, with one or more key fields, in ascending or descending order.

You can even SELECT records to view based on almost any set of conditions you might imagine. In short, the dba Library is so powerful you can use it as a Template-based approach to a wide variety of SQL Database Applications.

Although we have already provided quite a bit of documention about these Tags in the heitml Libraries section of this Web Site, we recognize that it can be rather intimidating to absorb so much information at once. Therefore, we have created this Tutorial introduction to help get you started. It is a step by step reference, based on a real life example that you should already be familiar with - namely, our Interactive Guestbook.

The Source Code Template we used to create the Interactive Guestbook can be downloaded from our Registered Apps Database. If you haven't done so already, you should consider downloading and printing it out. The Source Code makes it easier to see how the individual parts fit into the application as a whole and it should prove beneficial to have it handy while you are reading the Tutorial.

A dba application is divided into four parts:

Part 1: the dba Declaration part
Part 2: the Database Action part
Part 3: the TABLE view

Part 4: the FORM view

Each part is discussed in the pages attached to this section. Starting off with a high-level overview, the discussion gradually delves deeper into the various sub-parts, explaining how they relate to and interact with one another. At the lowest level, simplified examples are drawn from the Guestbook Template, enabling you to relate what you are learning to the way it appears in final form.

Once you have read through Part 4, you should have no trouble plugging the Guestbook Template into your own Web Site and modifying it to suit your needs.

A Tips & Tricks section is included at the end of this Tutorial that will help you move beyond the basics, and prepare you to solve problems and create more advanced applications on your own.

dba Part 1: Declaration

To declare a dba application, you need to provide the following basic information:

the Application Name.
the SQL Table Name used by the Application.
the Data Field Structure of the SQL Table.
the Names of any Index Files you want to maintain.
the Key Fields for each Index File declared.
the names of any BLOB or Textarea Data Fields.
the .hei filename that processes User requests.

whether or not Maintenance operations are permitted.

If this sounds like a lot to keep track of, don't worry. As you will see in a moment, all of the above information gets passed to various dba Tags in a logical and orderly manner. In fact, four of the above requirements can be satisfied by passing four simple parameters to the <dbapp> Tag.

The <dbapp> Tag is always the very first dba Tag you declare, and normally it should come near the top of your program after the <include dba.hei> Tag.

Here is a theoretical example:

Generally, the Application Name should be kept as short as possible, because it becomes the Master Control Structure for all variables in the dba application. In the Interactive Guestbook, for instance, it is more convenient to reference a Data Field called Email as gb.Email than GuestBook.Email.

The rel parameter contains the name of the SQL Table that stores your data. It can be as long as you like (within the limits of your individual SQL software package). If you want to call the table MyInteractiveGuestbook and your SQL system allows it, then go ahead. In this case, the length of the Table name will not become a burden to you because, once it has been declared, you never have to deal with it again. The dba application will handle all Table references and operations automatically.

The src parameter contains the name of the .hei File Name that processes User requests for this application. It can be any legal name accepted by your Operating System. A dba application can be split up among various heitml Web Pages, but in many cases you will find it more convenient to simply keep all the dba Parts together in a single Page.

The last parameter needed by the <dbapp> Tag specifies the Maintenance Mode. Normally, maint = true when you are developing and testing the application. Once the application is placed in production on your Web Site, however, you should set maint = false.

When Maintenance Mode is true, you can call a dba program by passing a special action parameter to it on the command or URL line. For example, to initialize an application and create the necessary SQL Table, you would type something similar to the following in the URL line of your Web Browser:

http://www.MyWebSite.com/guestbook.hei?action=create

If everything is successful (i.e. if there are no syntax errors or other problems with your code) the program will simply respond by saying "Tables Created".

While working in maint = true mode you should never enter any real life data into your Table, only test data. This is because the testing process often leads you to discover that you need to make changes to or add Data Fields in your Table Definition that you had not originally considered. When this happens, you can go back to the Source Code, redefine your Table structure, and start over again by calling your program with action = drop, followed by action = create or, to combine these drop/create actions, use the action = drcreate parameter.

OK, now that we've used the <dbapp> Tag to declare the Application Name, the SQL Table Name, the .hei File Name, and the Maintenance Mode, we move on to a special Environment Tag called <dbacreate>. This Tag is called an Environment Tag because, as you learned in the Defining your own Tags section of this Language Guide, it requires an End Tag in the form of </dbacreate> to show where the operations performed by this Tag come to an end.

Of the four remaining dba Declaration part requirements listed above, two will be handled by the <dbacreate> Environment Tag - namely, the SQL Table Definition, and the Index Files you want this application to maintain.

Here is how we do that:

<dbacreate gb>
  <dbupdate> 
     create table TableName (
        Email       varchar(60), 
	Title       char (10),
        FirstName   varchar(30),
	LastName    varchar(60),
   	Address1    varchar(60), 
   	Address2    varchar(60), 
	City	    varchar(40),
        State	    char (2),
	Zip         char (10),
        Country     varchar(60), 
	Telefon     varchar(30),
	Telefax     varchar(30),
        Comment     text,
        Favorite    varchar(60),
        FavComment  text,
	Heitmluser  char,
	SysAdmin    char,
	Programmer  char,
	Designer    char,
	Manager	    char,
	Platform    char(15),
	OpSys	    char(15),
	DbSys	    char(15),
	WebServ     char(15),
	Password    char(61),
	EntryDate   int,
	EntryTime   int,
	EntryIP	    char(16),
	EntryHost   varchar(60),
        EntryUser   char(16),
	pub	    char
     ) 
  </dbupdate>

  <dbupdate>
   create unique index TableNameEmail 
   on TableName (Email)
  </dbupdate>

  <dbupdate>
   create unique index TableNameDT
   on TableName (EntryDate, EntryTime)
  </dbupdate>

</dbacreate>

Notice, first of all, that the <dbacreate> Tag contains the Application Name that was defined in the <dbapp> Tag. In this case, we decided on a nice short name like gb to cut down on the amount of typing we'll have to do. Since every Tag in the dba Library requires that the Application Name be passed to it, you'll soon grow to appreciate the value of short names.

The second thing to notice is that the <dbacreate> Tag controls the operation of a lower-level Tag that you learned how to use in the Creating SQL Tables section of this Language Guide. As you can see, the low-level <dbupdate> Tag is called three times: first to create the Guestbook Table, and then twice more to create Index Files. The first Index File uses the Email Data Field as its key, and the second Index File uses the EntryDate and EntryTime Data Fields.

As already mentioned, you can use any Table Name your SQL system allows when naming these files. But consider that it might be a good idea to develop a practice where related Index Files bear similar names to the files they are associated with. For example, if you called the Guestbook Table Gbook, you might want to call the Index Fields GbookIndxEmail and GbookIndxDT.

One last thing we'll point out here is that there are a number of Data Fields in the Interactive Guestbook Table that you never see when you browse this application on our Web Site. For instance, EntryDate and EntryTime are assigned at the time a new record is entered using the SrvDate and SrvTime variables that are demonstrated in the Server Information page in our Running Examples section. The information for the EntryIP, EntryHost, and EntryUser Data Fields are supplied by the SrvIp, SrvHost, and SrvUser variables. These are just little things you can do to gather passive information about the people who Surf your Web Site.

If you are wondering how these fields can ever be viewed if they are not displayed in the Interactive Guestbook program, it's simple: We merely have a more complete program based on this same Template residing in an administrative area of our Web Server.

We point this out so you can see how applications can be designed with many purposes in mind. If you've given enough thought to the kind of data you want to collect, it becomes relatively easy to add or delete various code sections from an application depending on who will ultimately use it. Depending on a person's status (e.g. Registered Member, or Unknown Surfer), you could design applications that restrict some users from seeing things they are not authorized to see, while presenting a richer, more detailed set of Data to users who belong to your Club, Organization or User Group.

The last two items we need to Declare in this section are the Key Fields and the Textarea Fields. Not all dba applications will have such fields, but when they do, we use two special Tags to declare them.

The <dbakeyfield> Tag has the following syntax:

<dbakeyfield ApplicationName "KeyFieldName">

This Tag should be declared immediately after the <dbacreate> Environment Tag to let your application know which Key Fields should be used. If your application only has a single Index File with a single Key, then your program might contain this:

<dbakeyfield gb "Email">

A more sophisticated application might contain an Index File with several keys. In that case, you should declare each of them in the preferred order of importance. For instance, if your application allowed people to make repeated entries under the same Email or UserName (note that the Interactive Guestbook only allows a single entry for each Email address), you might have an Index File based on the Email, EntryDate, and EntryTime fields. In that case, your application should contain three references to the <dbakeyfield> Tag:

Assuming you had a group of Users who made many entries to your database, you could Browse your database in alphabetical order based on the Email Field, with each Email address clustered together in date order.

A variation on this might be the following:

In the above example, you could Browse the Email addresses in reverse alphabetical order, with the most recent entries appearing first, then stretching backwards in time.

Although it is beyond the scope of this Tutorial to give a complete discussion of the possiblities afforded by maintaining multiple Index Files with multiple Key Fields, you should definitely do a bit of experiementing on your own in this area. If you have already read the Control Statements page in this Language Guide, you should realize that you could set up a series of <if> <else> </if> control statements that dynamically select among a variety of Key Fields and Sort Orders, depending on the needs of your Users.

The last item tells your dba application about any Textarea Data Fields you might be using. Most SQL Database systems have a Data Type called text that is handled as a Binary Large Oblect. Because these BLOB Data Fields are handled differently, you must declare them in to your dba applications.

Here's how we do that:

Naturally, the <dbaTtext> Tag is only necessary when your application uses a Data Field of type text.

Summary

In this section we talked about eight things you must declare in any application using the dba Library. We showed you which Tags to use to accomplish this, how to use them, and which order to declare them. Additionaly, we pointed out some things to consider when designing your own applications:

that a single application could show all Data Fields to one class of users, while hiding some from others.
that multiple Key Fields and Sort Orders can be dynamically selected at Run Time using the <if> Tag to control the order in which data is presented.
that special Data Types like Binary Large Objects require special treatment.

dba Part 2: Database Action

The Database Action part of a dba application performs four functions. It Inserts new records, Updates existing records, Deletes unwanted records, and, for applications using Key Fields, it updates the pointers in the Index File(s).

The above described functions are controlled by three Tags, two of which are Environment Tags that require a number of important parameters to be passed to them:

<dbaupdate AppName r o submitaction="display">
Validation tests, passwords checking
and other stuff goes here.
</dbaupdate>
<dbadelete AppName r deleteaction="first">
Authorization procedures
(password checking, etc.) goes here.
</dbadelete>

<dbakeyupdate>

The <dbaupdate> Environment Tag has four parameters:

The Application Name
Tuple variable r, to collect data from an input FORM.
Tuple variable o, which preserves the original Data (in cases where new, updated data is being collected).
A variable called submitaction, which tells the application what to do after the record has been updated.
Most commonly, you would want to simply display the entry as it would appear to others, and give the User a chance to go back into Edit Mode (which will be explained in Part 4 of this document), and make any changes or enhancements he feels are necessary.

Normally, the only parameter you will be concerned with is the Application Name, which, as seen in previous examples from the Interactive Guestbook, we have named gb. With each new application you develop, you should assign a unique Application Name. All other parameters, however (r, o, and submitaction), should simply be included as you see them above.

Most important, however, is the stuff that goes on inside the <dbaupdate> Tag. Most of the time, you'll want to perform a number of procedures before you allow someone to enter a new record, or update an old one. If your Data Entry Form contains fields that cannot be left blank, then of course, you'll want to verify that information has been entered into each field for which an entry is required. If you don't want unauthorized people to make changes to someone else's record, then you have to do a Password Check, just like we do in the Interactive Guestbook. And finally, if you have Data Fields whose values are automatically assigned prior to posting, this is where you would do it.

The following code sample comes from the Interactive Guestbook Template. We have included more comments here than in the original source code to help you understnad what is going on:


<dbaupdate gb r o submitaction="display";
 / / Is the LastName field empty?
 if isempty(r.LastName); 
    / / Show error message.
    dbaerrmsg> A Name must be given  </dbaerrmsg; 
 /if;

 / / If "o" is not empty, this is an UPDATE.
 if !isempty(o);  
    / / Transfer original data to updated fields.
    r.EntryDate  = o.EntryDate; 
    r.EntryTime  = o.EntryTime; 
    r.EntryIP    = o.EntryIP; 
    r.EntryHost  = o.EntryHost; 
    r.EntryUser  = o.EntryUser;
 else 
    / / "o" is empty, so this is an INSERT.
    / / Server Variables supply the needed data.
    r.EntryDate  = SrvDate;
    r.EntryTime  = SrvTime;
    r.EntryIP    = SrvIp;
    r.EntryHost  = SrvHost;
    r.EntryUser  = SrvUser;
 /if;

 / / Is this User authorized to make changes?>
 dbapasswordcheck gb master=crypt("BackDoor");
/dbaupdate>

If you remember that we specified the Email Data Field as one of our Key Fields, you may be wondering why we didn't perform a Validation Check to make sure that the Email Field contained data. The answer is that dba applications are smart enough to know that Key Fields are required; therefore, it performs such checks automatically. If the Email field had been left empty, an Error Message would have been displayed saying "No update performed - Email must be given.. One of the beauties of creating applications with the dba Library is that you only have to perform Validation Checks on fields the application could not otherwise have known were needed. In an application with multiple Key Fields, this "automatic validation check" can save you a lot of heartache that would otherwise occur if you forgot to perform those checks on your own.

The second <if> statement in the above code determines whether the action to be performed on the Database is an INSERT> or an UPDATE>. If the "o" tuple contains Data, it means that a record with the specified Key Field already exists in the Database and we need to UPDATE it with whatever new data has been entered. The <else> part is only executed when the "o" tuple is empty, which means that a new record needs to be INSERTed into the Database.

The last thing we do is call the <dbapasswordcheck> Tag to check the User's authorization. The User must always enter a Password, even when he is creating a new entry. This password will later be Used to determine if the User has the right to make changes to this record.

Of special note is the fact that the <dbapasswordcheck> Tag accepts a parameter called master. This Master Password is optional, but strongly recommended, because it provides an administrative "Back Door" into the application that permits you to edit or eliminate any offensive or unauthorized entries. You can include the master parameter as part of the application you place in the public part of your Web Site, but a better idea would be to include it in a separate application in a restricted access area. In any case, passwords are encrypted before being written into the Database as an additional security measure. It would be a good practice to assign a unique master password to each dba application, but if you are the only person responsible for administrative control over the Tables in your Database, it may be more convenient to simply use the same master password over and over again (so long as you aren't silly enough to call it "BackDoor", of course. ;-)

Now we turn our attention to the <dbadelete> Environment Tag. There are three parameters you need to supply to this Tag:

The Application Name
The relational tuple "r"
A special parameter called deleteaction, which tells the application what to do after the record has been deleted.

A good idea would be to assign deleteaction = "first", which puts the User back into Browse mode starting at the first record. From there he can browse through the Database, select records to view, edit, or delete, or simply return to whatever program he came from when he first entered the application.

Here is an example of how this Tag should be used:

<dbadelete gb r deleteaction="first";
   dbapasswordcheck gb master=crypt("BackDoor");
/dbadelete>

Just as in the <dbaupdate> Tag, you should include a call to the <dbapasswordcheck> Tag to prevent unauthorized people from deleting records.

The last Tag in this section is called <dbakeyupdate>, the purpose of which is to check whether any of the Key Fields have been modified and, if so, to adjust the Index Files accordingly. There are no parameters to this Tag and it can be omitted from applications that do not use Index Files and Key Fields.

Summary

This section explained how to use the dba Library Tags that perform actions on the Database.

For the <dbaupdate> Tag we pointed out various Validation and Authorization checks that could be performed, as well as the automatic assignment of secret or "hidden" fields that the User never sees.

The <dbadelete> Tag can be used to perform Authorization checks on the Passwaord Data Field. Additionally, it contains an action parameter that tells the dba application what to do after the delete is performed.

Finally, the <dbakeyupdate> Tag ensures that all Key Fields and Index Files are updated accordingly.

dba Part 3: The TABLE View

You should think of the TABLE View part of a dba application as the place where you decide which Data Fields to show a User while he Browses through your Database. In Browse Mode, it is not always necessary or convenient to show everything a record contains. You only need to show what's necessary for the User to select the records he wants to view in more detail.

For instance, in Browse Mode, our Interactive Guestbook shows only the Name of the person who made the entry, the URL of his Favorite Web Site, and the Date and Time he made the entry. If you want to go directly to the Web Site, you can simply click on the link provided. Most people, however, would first click on the User Name to see what additional information has been provided. It's at this point that the dba application switches into Form View Mode, which we explain in part 4 of this Tutorial.

There are quite a lot of Tags you can use in the Table View, but basically they can be divided into three categories:

Table Format Tags
Data Field Display Tags

Database Action Tags

As we'll see in a moment, this simple classification scheme covers a rich assortment of Tags, many of which can be used in combination with other Tags to create astonishingly flexible and reactive presentations.

There are two Table Format Tags, which are actually Environment Tags used to create a framework within which you define the appearance of the Table to be displayed.

Here is a simple overview of how they would appear in a dba application:

<dbaTable gb cnt=25 cond="pub='T'">
  <let cnt=25>  
  <TABLE> 
    Define your Table Header <TH> line here. 
    <dbaTableEntry gb r>
       Data Field Display Tags go here. 
    </dbaTableEntry>
  </TABLE>
  Database Action Tags go here.
</dbaTable>

The <dbaTable> Tag accepts three parameters, the first two of which are required. The first parameter, as always, is the Application Name, which we have called gb here. The second parameter cnt establishes a counter to control the number of records displayed on each screen. If this parameter is to be used anywhere else within the <dbaTable> Environment, it should be declared and initialized as we demonstrated above using the <let> Tag.

The third parameter is optional. We have used it in the Interactive Guestbook to give people an opportunity to keep their entry private. Some Users may prefer to keep their information private, while others may perhaps welcome the chance to hear from other heitml programmers. In any case, the cond or condition parameter is used here as method of keeping some records private.

The cond parameter could also be used in an application where various search functions are allowed. Although we have not done so here, the Interactive Guestbook Template could easily be modified to select entries where, for example, pub='t', DbSys='mSQL', and Opsys='Linux'. Such a parameter could be passed using either of the two methods as follows:

As literal data inserted directly 
into the Source Code:

<dbaTable gb 
      cnt=25 
cond="pub='t' AND DbSys='mSQL' AND OpSys='Linux'"> 

Or, as a variable assigned at 
runtime under program control:

<dbaTable gb cnt=25 cond=gl.SearchCondition>

Obviously, the second method provides more flexibility, because it allows the application to respond in different ways, depending on the values assigned to the SearchCondition variable.

Between the <dbaTable> and <dbaTableEntry> Tags you should open an HTML Table and define the appearance of the Heading Line. This will identify the Data Fields that appear in the records listed by <dbaTableEntry>.

Here's a simplified example from the Guestbook Template:

<dbaTable gb cnt=25 cond="pub='T'"> 
 <let cnt=25> 
 <table border=4 cellpadding=0 cellspacing=0>
  <tr>
   <th> Name              </th>
   <th> Favorite Web Site </th>
  </tr>

  <dbaTableEntry gb r>
    Data Field Display Tags go here.
  </dbaTableEntry>
</table>
  Database Action Tags go here.
</dbaTable>

Next you define the appearance of the data fields to be displayed. The <dbaTableEntry> Tag accepts two parameters, the Application Name and the variable "r", which points to the contents of the current record. Everything that appears between the <dbaTableEntry> Environment is repeated for each record to be displayed. We use the Data Field Display Tags to add formatting options to the data in each field.

Again, here is a simplified code sample from the Guestbook Template:

<dbaTable gb cnt=25 cond="pub='T'"> 
  <let cnt=25>  
  <TABLE> 
    Table Header <TH> line is defined here. 

    <dbaTableEntry gb r>
     <tr bgcolor="<? gl.Beige>">
      <td> <dbaAdisplay gb> 
             <dbafi gb "FirstName"> 
             <dbafi gb "LastName"> 
           </dbaAdisplay> 
      </td>

      <td> <dbaLink gb "Favorite"> </td>
     </tr>
    </dbaTableEntry>

  </table>
  Database Action Tags go here.
</dbaTable>

We will delay our discussion of the Data Field Display Tags until part 4 of this Tutorial. For now we will mention only a few basic points. The FirstName and LastName Data Fields are displayed together in the same <TableData> column. The <dbaAdisplay> Tag is actually a Database Action Tag. It creates an anchor Tag, or pointer, to the location of that record in the SQL Database. If the user clicks on this link, the Form View part of the program receives that record pointer and retrieves the record from the database for display. And finally, the <dbaLink> Tag creates another anchor Tag, this one an absolute reference to the address of the Web Site contained in the Favorite data field. If the user clicks on this link, (s)he is transported to that Web Site.

All of this should be made clear simply by Browsing through our Interactive Guestbook and clicking on the links to see what happens.

The last thing we need to talk about before leaving this section relates to the Database Action Tags. Currently, there are a wide variety of Database Action Tags, but in this section we will concern ourselves only with the ones that can be used in the TABLE View part of a dba Application. Database Action Tags are easy to recognize for several reasons:

They all share the format: <dbaAaction>, where the action part of the Tag name describes what the Tag does.
All Database Action Tags are Environment Tags, which means that they require and End Tag in the form: </dbaAaction>.
They all create hot-links to specific records in the Database. In other words, any text or data enclosed by a dba Action Tag is underlined just as though you had used the standard HTML <a href> or <a name> anchor Tags. A User can click on the link, and the dba Action Tag retrieves the record it points to in the Database and performs a specific action.

Database Action Tags can be sub-divided as:

Those that act on a group of records.
Those that act on a single record.

The dba Action Tags that act on a group of records help you nagivate or "Browse" through the Database n-number of records per screen or Web Page view. They are:

<dbaAfirst gb> First <? cnt> Records </dbaAfirst>
<dbaAlast gb> Last <? cnt> Records </dbaAlast>
<dbaAnext gb> Next <? cnt> Records </dbaAnext>
<dbaAprev gb> Prev <? cnt> Records </dbaAprev>

All of the above Tags take a single parameter: namely, the Application Name, as seen in all other dba Tags. You can place any descriptive message you like in the body of the Tags. In this case, we've simply told the user how many records he can expect to see with each page view, and where those records will be coming from. The cnt variable is always defined immediately following the <dbaTable> Tag, as described previously. You can make this variable as large or as small as you like, but keep in mind the volume of data you will be delivering to each Web Page, and the potential delay Users with slow connections may experience.

The dba Action Tags that act on a single record are:

<dbaAedit> <? gb.LastName> <dbaAedit>
<dbaAshow> Show All fields <dbaAshow>
<dbaAempty> Add your own entry </dbaAempty>
<dbaAdelete> Delete this Record </dbaAdelete>

As we've tried to illustrate above, you can place almost any information imaginable between the Beginning and End Tags, but normally you will want at least one of the Tags to make it clear which record is being acted upon. For instance, if you look again at the simplified code sample from the Guestbook Template, you will see that we only used one of these Tags in our TABLE View. Therefore, it seemed wise to display the name of the person who's record was being displayed.

You will want to be careful about using the <dbaAdelete> Tag. It would be unwise to put this Tag in an application where anyone on from the Web could maliciously purge records from you Database. But in an Administrative Application placed in a secure area, this Tag makes it very convenient for quickly deleting old, out of date, or offensive records. The Administrator could rapidly scan through a Database, deleting records with a single click.

The <dbaAempty> Tag is something best positioned near the top or bottom of a Web Page. It gives Users the opportunity to contribute their own entries to the Database. Clicking on the link from this Tag sends the User to the input form you created in the FORM View that we will describe in the next section.

There is a subtle but important distinction to be made between the <dbaAshow> and <dbaAedit> Tags. The Show Tag takes you to the Form View in such a manner as to display the contents of the individual data fields in a record. The Edit Tag takes you to the Form View as well, but in this case the User is presented with the raw data as it was originally entered into the Form. In other words, if certain data fields contain HTML formatting Tags, the Show Tag displays the data as interpreted by your Browser, while the Edit Tag shows the data in its true form.

The Edit Tag can be useful in two situations: First, when you want to encourage people to learn something about how other Users formatted their entries. You can pick up a lot of tips and tricks simply by looking at other people's code. And second, when the original User wants to come back and make changes or enhancements to his entry, the Edit Tag gives him quick access. In this case, alterations to the individual records should be Password protected, as we'll demonstrate in the next section of this Tutorial.

Summary

This section explained how a dba Application presents a Browsable list of records from a Database. We presented a theoretical model as an overview, and then a simplified code example from the Guestbook Template to give you an idea of how to set up the first (or Table Heading) row, followed by a quick look at how individual Data Field Display Tags could be contained within (surrounded by) Database Action Tags that allow the User to select individual records for a closer look.

We delayed an in-depth discussion of the Data Field Display Tags until the FORM View section immediately following this one, because in this, the TABLE Vew part, the Database Action Tags are more important.

We explained the naming convention that makes it easy for the programmer to recognize these Database Action Tags when he sees them in the Source Code. We sub-divided the Tags into two easy to remember groups, and we gave an example of each Tag, and how it should be used.

We've only touched the surface of how these Tags operate in this section, because the purpose of this Tutorial is to give you a quick introduction to the structure of a dba Application. Later pages in the Advanced Topics part of the Language Guide will treat these Tags in more depth.

dba Part 4: The FORM View

The FORM View is the heart of a dba application, for this is where new records are entered into the database, and existing records can be displayed or modified.

Users will Browse through the database in Table View, displaying a pre-determined number of records per page, as previously explained in Part 3 of this Tutorial. When the User wishes to see more detailed information about individual records, however, that record is displayed on a page by itself in FORM View.

The main Tag in this section is the <dbaForm> Tag. This is an Environment Tag, inside of which a layout is specified both for data entry and display purposes.

A simplified dba FORM is defined as follows:

<dbaForm gb r keyact="upd">
<TABLE>
Define FORM Data Fields here.
</TABLE>
</dbaForm>

What happens inside the <dbaForm> Environment depends on the nature and type of Data Fields to be entered or displayed. In Part 3 we briefly mentioned that there are a large number of Data Field Display Tags you can use to define a FORM. Each Tag is designed to handle a specific situation. Here are the Tags to be explained in this section:

For Generic Data Fields:
<dbafi gb fieldname size maxsize def>
<dbaTfi gb fieldname size maxsize>
<dbaTab gb fieldname size maxsize>

For Special Purpose Data Fields:
<dbaMailto gb fieldname size maxsize def>
<dbaLink gb fieldname size maxsize def>
<dbafiPassword gb size pref="Password:">

<dbaCheckBox gb fieldname>
Message
</dbaCheckBox>

<dbaSelect gb fieldname>
<dbaOption gb value>
<dbaOptionV gb value>
</dbaSelect>

<dbaTextArea gb fieldname cols rows disp>

Here is how a dba FORM might look using the generic Tags: