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:

1. The Application Name AppName
2. Tuple variable r, to collect data from an input FORM.
3. Tuple variable o, which preserves the original Data (in cases where new, updated data is being collected).
4. 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 AppName parameter, 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 understand 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:

1. The Application Name
2. The relational tuple r
3. 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 Password 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.