Complexity

On its face, designing and building dBASE Plus Web applications appears to be exceedingly complex. The dBASE Plus Web Classes simplify this by hiding most of that complexity beneath their easy-to-use and easy-to-learn methods. The Web Wizards are even simpler - they bury all the difficult stuff beneath a simple step-by-step interface.

Nonetheless, it's important for you to understand exactly how dBASE Plus applications work (and particularly how they interact with the other components involved in Web applications) or you might find yourself without the basic tools required to deal with sticky situations when things go awry.

       

The relationship between the Browser, the Web Server and your dBASE Plus applet is very delicate. If any part of the chain is not set up or working right, the entire application fails. Fortunately, once you've got  all the pieces up and running, you'll find dBASE Plus Web applications to be remarkably stable over time. This is because dBASE Plus relies entirely on standard Internet protocols and tools: Browsers, Web Servers, HTTP, TCP/IP, CGl and HTML, not to mention dBL code and a wide range of databases. Don't let this plethora of applications, protocols and code daunt you. dBASE Plus makes it simple.

The Non-dBASE Plus Parts of a dBASE Plus Web Application

 Let's start with the outside parts: the Browser and the Web Server. They communicate with each other using http (HyperText Transfer Protocol), the protocol that powers your Browser and powers the Web. Fortunately, you don't need to know much about http or TCP/IP (the networking protocol of the Internet). Most of your work is on the back side of the server, acting as the interface between the Web Server and the data being queried or updated.

The only notable exceptions are the HTML page, that starts your application, and the response pages, that chain your applets together. Most often, your application will start with a static HTML page. That page contains a form, and that form contains "form components", such as Text  controls (simiilar to dBASE Plus Entryfields), Selects (Comboboxes), Lists (Listboxes), Checkboxes, Radiobuttons, Text Areas (Editors) and Buttons (Pushbuttons). There are no Grid, Notebook or container controls.

These HTML controls have name and value properties, just as dBASE Plus components do.

<INPUT TYPE="TEXT" NAME="FirstName" Value="Alan">

Fields have names and values. Field objects have names and values. Associative Arrays have names (keys) and values. This almost-universal implementation of name/value pairs allows the dBASE Plus Web Classes to black-box the process of retrieving, processing and storing data - dramatically simplifying the development of Web applications.

Tip: When you design an HTML startup or data-entry form, apply the same standards you'd apply to a dBASE Plus Windows application: Name your controls appropriately, size them correctly for the data to be entered, default them to obvious values, and position them for ease-of-use and clarity of data-entry.

On The "Back Side" of The Web Server

This is where dBASE Plus shines. It is, after all, one of the most sophisticated database development tools, and most Web applications are database applications.  Once your dBASE Plus applet is launched and the user's data passed along by the Web Server, there are six things you need to do and four of them are things you'd do in any good database app:

1)  Retrieve The Incoming Data   When the Web Server launches your server-side dBASE Plus application (sometimes called an Applet or Servlet) , it runs it as a child process, passing along a copy of its environment plus the data picked up from the user's HTML form. It sends this data either through the environment, a command-line parameter, or as a data stream. A data stream is a relatively new concept to dBASE Plus users. dBASE Plus applications can now read, or write, a stream of bytes to and from another application.  A byte stream is similar to a text file except the text flows in real time and doesn't get saved to disk. You can send data through a pipe from parent to child and child to parent without the overhead of creating, finding, reading and writing disk files.

The dBASE Plus Web Classes automatically determine how data was sent, how it's supposed to be received and then goes out and gets it .

2) Format The Incoming Data   Data that gets read into your application is received in a garbled form of Name/Value pairs. Like an .ini file, the dBASE Plus "Set" commands, or DOS environment commands (PATH=), these pairs must be parsed by your application and converted to dBASE Plus-readable data.

The incoming data stream may look something like this:

FIRSTNAME=Alan&LASTNAME=Katz&ADDRESS=102+Main+St%21

In the line above;

     The ampersand is the delimiter between pairs

     The plus signs are keyboard "spaces"

     The % indicates punctuation or special characters in Hex format.

     The left side of the equal sign is the name of the control on the HTML page

     The right side is the data the user typed into the control.

This is one more operation you can ignore. A simple dBASE Plus Web Class method: oemFormat( ) automatically converts this ANSI string into dBASE Plus OEM data and stores it to an Associative Array:

oCGI["FIRSTNAME"]="Alan"

oCGI["LASTNAME"]="Katz"

oCGI["ADDRESS"]="101 Main St."

Note: The dBASE Plus Web Classes consist primarily of the array in which the incoming data is stored. Derived from the built-in dBASE Plus AssocArray class, the Web Classes conveniently allow the data, and the methods that act on that data, to be stored in the same object.

3) Validate, Manipulate the data   OK, now you've got this data retrieved from the Browser, stored in your AssocArray as text , sitting there waiting for you to do something with it. What do you do first? The same thing you do in any decent database application: validate the data.

In the simplest cases, this might mean looking for missing data:

If empty(oCGI["LastName"]

  aData.sorryPage("Last name is required!")

endif

or performing more elaborate validation, such as checking a user's ID and password, or a customer's CustNo:

if not q.rowset.findKey(aData["Custno"])

  oCGI.sorryPage("Customer number is not valid!")

endif

or performing calculations or other data manipulation:

oCGI["FullName"] = trim(oCGI["LastName"])+', '+oCGI["FirstName"]

Tip: One of the nice features of the dBASE Plus Web Classes is that they let you pass an array instead of a string to the sorryPage( ) method (the HTML equivalent of MsgBox( ) in dBASE Plus or Alert( ) in other languages). You can batch all the errors instead of requiring your user to submit a page for one error at a time until he or she finally gets the darned thing right.

 Another Tip:For years we've been trying to convince dBASE Plus developers to do form-level validation instead of field-level validation. On The Web, this is a given. Although you can do rudimentary validation using client-side JavaScript, all your serious validation happens on the server after the form has been submitted.

4) Store Or Retrieve The Data   The methods of the Web Classes let you store your incoming data to a table, or send table data back to the user, with almost no code. Aside from instantiating a dBASE Plus Query object, reading and writing data should take only a single line of code each.

This automated, black-box data access only works if you name the form controls on your HTML page with names identical to the table fields they're going to or coming from. And that includes matching case. The AssocArray class is case-sensitive.

Tip:You'll also be amazed to see the speed of opening queries and saving rows in dBASE Plus when there's no WIndows GUI to slow it down.

5) Build (And Send) a Response Page   This is the hard part. For virtually every dBASE Plus applet you write, you have to write an HTML page as well. This response page gets sent back to the user to either allow forward motion through your application or at least give the courtesy of acknowledging their kindness in sending you data. If you don't send a page, the Web Server chokes, and your user will know  you blew it by virtue of an unkind message sent to the Browser.

Streaming is the process of generating code instead of text. Just as the dBASE Plus Form and Report Designers stream out dBL code, you'll be streaming HTML as the last act of your dBASE Plus applet.

Tip: It's simple to design the response page using Symantec's Visual Page, then use the new dBASE Plus utility, HTMLtoPRG, to convert the HTML into dBL code and have it poked right into an applet's source file. Very fast, very helpful..

Here are some typical Response pages:

  Thank You page.

  Confirmation of Order

  Acknowledgement of Data Received

  Another data-entry page (multi-page applications)

  A second copy of the page that launched your applet.

  A menu page to continue surfing the site

  The "Checkout" page for an Online Store

Some of these pages are pretty simple (such as the "Thank You" page). Others require that you build a whole new "launch" page for the next phase of the application.

 

 

 

Regardless of what you return to the user, it behooves you to personalize it. And that's very easy to do in dBASE Plus. You simply insert the values from your array into the HTML you stream back to the Web Server:

this.fOut.Puts('<B>Thank you, '+oCGI["FullName"]+;

               ',  for your order!')

Getting your data back to the Web Server is as simple as using the puts( ) method of the built-in dBASE Plus File Class.

6) Clean Up and Quit    Like all good dBASE Plus programmers, I'm sure you're always careful to clean up behind yourself when you close an application. Even though the dBASE Plus Quit command should close down everything and restore your resources, this is Windows and there seem to always be resource problems of one type or another. It's just good form to clean up your classes and queries:

q.active = false

q = null

d.active = false

d = null

oCGI = null

Quit

Tip: Cleanup is particularly important in Web applications. Losing a small amount of resources on one workstation, run by one user is probably not catastrophic. On the other hand, a Web applet may be run literally thousands of times a day. Chewed-up resources can have a drastic impact on your Web server.

Learning To Code dBASE Plus Web Applications.

If you're new to Web development, we strongly recommend that you generate a few dBASE Plus applets, using the Web Wizards, and inspect the resulting HTML and dBL code. The code generated by the Wizards can serve as an invaluable guide to creating interactive Web sites using dBASE Plus.

We also recommend that you take some time to look over the dBASE Plus Web Classes, which will help you dramatically improve your productivity in developing hand-coded, superfast Web applets.