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.

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 name="dba.hei" />

Tag.

Here is a theoretical example:

<include dba.hei> <dbapp ApplicationName, rel = "TableName", src = "FileName.hei", maint = true>

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 page in our Programming Tutorial 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:

<dbakeyfield gb "Email"> <dbakeyfield gb "EntryDate"> <dbakeyfield gb "EntryTime">

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:

<dbakeyfield gb "Email"         order="desc"> <dbakeyfield gb "EntryDate" order="desc"> <dbakeyfield gb "EntryTime" order="desc">

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 possibilities afforded by maintaining multiple Index Files with multiple Key Fields, you should definitely do a bit of experimenting on your own in this area. If you have already read the Dynamic Pages 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 Object (BLOB). Because these BLOB Data Fields are handled differently, you must declare them in to your dba applications.

Here's how we do that:

<dbaTtext gb "FavComment"> <dbaTtext gb "Comment">

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. Additionally, we pointed out some things to consider when designing your own applications:

1. that a single application could show all Data Fields to one class of users, while hiding some from others.
2. 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.
3. that special Data Types like Binary Large Objects require special treatment.