Clarion, the Web, OOP and You

by Tom Hebenstreit, Review Editor

Published 1997-10-01    Printer-friendly version

I am often asked if Clarion for Windows (CW) can be used to create an interactive World Wide Web site, with CW programs being used to read form data, respond to requests, and generate dynamic HTML (web) pages to be sent back to the user.

The answer, in a word, is YES! And it's probably much easier than you might think, thanks to the various CW pioneers who have already blazed this trail for you to follow.

During the course of our journey, we will cover these broad topics:

• Gathering and displaying information interactively on the Web using normal CW programs
• Using Templates and App shells to simplify the creation of your Web programs
• Using OOP to simplify using web objects

When we are finished, you should have a good basic grasp of how you can use your current skills and tools to create powerful web sites.

Before we begin, however, a bit of background may be in order: This article is based loosely on a presentation which I gave at the recently completed TopSpeed DevCon in Ft. Lauderdale, Florida. It will be presented in two parts, with this issue laying the groundwork in Web basics, the ways your programs can interface with a Web Server and the tools you will need to help you build your web sites.

The next installment (scheduled for the November issue) will delve into the actual OOP classes, code, templates and application shells that I am currently using to build web sites and transfer files across the Internet. All of the templates, application shells and OOP API wrappers discussed in the second article will be available for download in that issue.

A word about Clarion Internet Connect

First off, this is NOT an article about CIC (Clarion Internet Connect, also known as CWIC). Since I was asked two questions time and time again at DevCon (given the emphasis placed on CIC by TopSpeed), let's get them out of the way right now for you as well:

Does CIC make obsolete the kind of CW web usage discussed in my presentation (and which we will cover in these articles)?

No, it most surely does not. CIC is a powerful (and expensive) solution for certain business needs, but it is also massive overkill for many simple Web jobs. In addition to the cost, it also requires that all visitors to your web site have a Java enabled browser (and that the browser's Java support is turned on). If a user fails those requirements, they will not be able to make use of your site, period.

In contrast, the methods we will cover in these articles do not require anything special from visitors to your site in the way of browsers or Java, etc. We will be discussing standard web technologies currently in use in thousands of web sites every day (including the one you are using right now - Clarion Online!).

Can one do everything CIC does using the methods laid out here; i.e., can I get CIC's functionality without having to buy it?

Again, the answer is no. CIC is a great product, and the very power that makes it overkill for basic needs also makes it uniquely suited to solving problems which are difficult if not impossible to solve using the standard web technologies we will cover here.

To summarize, Clarion is more than flexible enough on its own to accommodate most basic web programming needs, while CIC provides that special advantage for cutting edge web development. As with most situations like this, use the tool appropriate to the job, and be glad that CW gives you so many options!

And before you ask, yes, I own CIC and intend to use it for developing large, new business apps for corporate deployment across the web.

OK, put on your Webmaster hat now and let's begin our trip through web-land!

World Wide Web Basics

In this section, we will cover the basics of the World Wide Web as it relates to your future CW web programs. It is NOT intended to teach you everything about the Internet, just to introduce you to the types of knowledge you should be familiar with to work with the web.

But why do I need to know this stuff, anyway?

• You wouldn't expect to be able to write CW programs without knowing something about Clarion, so how can you expect to create web sites without knowing something about the web?
• The method you choose for interfacing your programs with a web server determines just how much you do need to know (or learn).
• The finer the control you require over your program and the pages it creates, the more you will need (or find useful) to know.

As we shall see, there are several levels at which you can use CW to interface with a Web Server, and they each require different levels of knowledge and/or skill with basic web technologies such as HTML (Hypertext Markup Language).

How the web works

Since you are here at a web site, we will assume you know about Uniform Resource Locators (URL) and domain names, etc. (such as www.ClarionOnline.com). Just to be clear though, the basic flow of the web is as follows:

1. You use your Browser to request a page or action via URL or link (HTTP)
2. The web server figures out what to do with the request
3. For Static Pages, the web server finds the page (actually a file) and sends it back
4. For Dynamic Pages/Links, The server runs your program, which creates a page and passes it back to the server, then the server returns the page created by your program to you
5. Your browser parses/displays the page (HTML)

Now, that's pretty simple, isn't it? Let's delve a bit deeper...

Hypertext Transport Protocol (HTTP)

HTTP is the transport protocol for the World Wide Web, and it specifies how web browsers and servers actually communicate with each other. In other words, it is the 'language' used to make the connections between your browser and a web server, and it provides the mechanism which carries (or transports) both your requests and the resultant web pages back and forth.

Other common protocols include FTP (File Transfer Protocol, which we will cover next month), News, Gopher and so forth. The key point to remember is that each protocol is used to accomplish a specific task, and it can only talk to other machines that have the same protocol installed.

So, how does this concern us and our CW web programs? Read on...

Every web request (and response) that is sent has a set of HTTP 'headers' that contain information about the request and who or what sent it. Headers are organized into 'Field=Value' pairs, with a field name on the left and the value for that field on the right.

For example, a typical HTTP header might look something like this (don't worry if it looks like Greek to you for now):

HTTP_ACCEPT=image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, */*
HTTP_ACCEPT_LANGUAGE=en
HTTP_CONTENT_LENGTH=67
HTTP_CONTENT_TYPE=application/x-www-form-urlencoded
HTTP_HOST=www.tequila.com
HTTP_REFERER=http://www.tequila.com/JListTop.htm
HTTP_UA_PIXELS=640x480
HTTP_UA_COLOR=color8
HTTP_UA_OS=Windows 95
HTTP_UA_CPU=x86
HTTP_USER_AGENT=Mozilla/2.0 (compatible; MSIE 3.01; Windows 95)
HTTP_PROXY_CONNECTION=Keep-Alive
HTTP_PRAGMA=No-Cache

This information is available to your CW programs, and it can tell you a lot about who sent the request, what kind of browser they were using, what kind of images the browser can display, what language they are using, how much data was sent and more.

To illustrate, the above header tells us that the user was using Microsoft Internet Explorer 3.01 (HTTP_USER_AGENT) running under Windows 95 (HTTP_UA_OS). We can also see that they were looking at a page called 'JlistTop.HTM' (HTTP_REFERER) on a server at 'www.tequila.com' when they sent this request, i.e., clicked on our link.

Based on any of the above, you might wish to tailor the web pages your program creates to, for example, take advantage of some special feature of their browser. Do you need to use any of this information? Nope. It's just there for the asking if you want it.

HTML - Hypertext Markup Language

HTML is the basic language of the web. It describes and formats ALL content on the web - the web would not exist without it. I am not going to attempt to teach you HTML here (there are literally hundreds of books available to do that), rather, I will just list a few basic points:

• The basic unit of HTML is the 'tag' - an instruction to your browser which is contained between a 'less than' symbol (<) and a 'greater than' symbol (>)
• Tags are never displayed on your browser screen, they just tell your browser what to do, e.g., turn on bold text, turn off bold text, center some text, etc.
• Most tags operate in pairs: for example, <p> begins a paragraph while </p> indicates the end of the paragraph.
• Required Tags: <HTML> <BODY>
  These define the beginning and end of web page and of the body (the displayable portion) of a page.
• Other tags format text and/or place objects and structures on the page (links, forms, images, tables, etc.)

Where does HTML impact your CW programs? Simple - every page you create to send back to a user on your site will consist of HTML tags surrounding and formatting the information you wish to display. We will discuss a few ways communicating with a web server where you can avoid learning HTML, but for the most part, you will need to at least learn some basics.

Communicating with a Web Server

OK, enough of the basics. Now we move on to choosing the method your programs will use to communicate with a web server. Say what? That's right, there are multiple ways to have a CW web program talk to a server, and the way you choose will be dictated by a number of factors:

• How complex are your requirements?
• How much HTML do you want to write (if any)?
• What kind of server will your programs be running on?
  (It goes without saying that your ISP must be using Windows NT or even 95 as the server operating system - no amount of magic will get your CW programs to run on a Unix web server! What we mean here is are they using IIS, Netscape, WebSite, etc.)
• Does your ISP (Internet Service Provider) allow you to use a particular method on their servers? Some ISPs don't even allow you to run custom scripts (i.e., your CW programs) on their systems. If that's the case for you, you will need to look for another ISP to host your site.

Here is a brief list of the methods available to you, along with their advantages and disadvantages (watch out - alphabet soup ahead!):

IDC (Internet Database Connector)

IDC was developed by Microsoft for use with their Internet products.

Advantages

• No programming or HTML knowledge required
• Uses HTX files. (HTX files are a special type of web file which can contain what are, in essence, mail merge type tokens. The server will merge your data with the page before sending it back to the user. The page itself can be created using a WYSIWYG HTML editor like FrontPage)
• Can access TopSpeed TPS files via the TPS ODBC driver

Disadvantages

• Limited control over what happens
• Requires some knowledge of SQL
• Requires that your ISP install the TopSpeed ODBC driver
• Specific to the Microsoft IIS web server

If you are using Microsoft FrontPage to create your web pages, and will be hosting your site on a Microsoft IIS web server, IDC can be useful for simple tasks. MS FrontPage 97, for example, can create IDC requests and their HTX response pages using wizards, etc. A sample IDC request that sends the data on a feedback form to a mailbox might look something like this:

Datasource: SendMail
Template: ../FBSent.htx
SQLStatement: INSERT INTO SendMail (Addressee, Subject, Sender, Message)
+VALUES ('%SendToAddress%','%MessageType%',
+ '%ReturnAddress%','%Comments%' & chr$(13))
DefaultParameters: UserEmail=anonymous@x.net

As you can see, basically the entire request is an SQL statement to be used with an ODBC connection, along with the values to be inserted into the file. The real data from the form is substituted for the '%value%' type statements by the web server when the form is actually submitted.

Note: Since you don't actually use CW to access your data, we won't be discussing IDC any further. There is nothing to stop you, however, from using a combination of IDC for simple tasks and, say, CGI for more complex tasks against the same set of TPS data files.

Standard CGI (Common Gateway Interface)

CGI was originally developed as a means for Unix web servers to run programs (or scripts, in web-speak) on web servers.

Advantages

• Works with virtually all web servers (IIS, Netscape, WebSite, etc.)
• Uses the Environment and StdIn/StdOut to pass data to your programs
• Your programs can do virtually anything you want

Disadvantages

• Programs load/unload each time they are run
• Windows API calls must be used to obtain the data from the server

CGI is the workhorse of the web, and is by far the most common way to interface scripting (web programming) languages such as Perl or C (and in many cases, CW) with a web server. It is in the middle of the pack when it comes to performance - faster than Win-CGI programs, slower than ISAPI solutions (both discussed below).

Win-CGI (CGI adapted for Windows)

Win-CGI was adapted from CGI by Robert Denny to allow Windows based languages such as Visual Basic to be used on a web server. (VB does not support the StdIn/StdOut method used by CGI for passing data between the program and the server.)

Advantages

• Works with most web servers (IIS, Netscape, WebSite, etc.)
• Simple interface, no API calls
• Your programs can do virtually anything you want

Disadvantages

• Programs load/unload each time they are run
• Extensive use of temporary files to pass information

Win-CGI uses an INI file format to get the information to your program (examples next month). It is the simplest, but also the slowest of the methods discussed here.

ISAPI (Internet Server Application Program Interface) via OCX

ISAPI was developed by Microsoft to provide greater speed and flexibility in web programs. The primary way it accomplishes this is by having ISAPI programs compiled as DLL's, which are then loaded into the same program space as the server. Once it has been loaded, it is instantly available to handle requests without all the overhead associated with initializing, starting up and shutting down CGI and Win-CGI programs.

Unfortunately, CW is not a 'thread-safe' language (at least in its present incarnation), and that is a requirement for ISAPI. (Note: there are some intrepid souls out there using CW directly with ISAPI, but it requires a tremendous amount of knowledge about CW and its internal workings to avoid doing things that can crash the web server).

There is, however, a third party product that very nicely bridges the gap between CW and ISAPI - the Tornado OCX. Basically, it uses an OCX to mediate between an ISAPI DLL and your CW program. An Administrator program takes care of dispatching requests to your CW program as they are received, and passing the output from your program back to the web server.

Advantages

• Fast - your CW programs are always loaded in memory and ready to go with the data files already open (if you wish).
• Supports HTX files (no HTML in your programs if you don't want it).
• You can run multiple instances of your programs and the Tornado Administrator will automatically spread the load among them.
• The Tornado Administrator on the server can be accessed via your browser, allowing you to view its current state, shut it down and/or terminate instances of your program.

Disadvantages

• You must purchase the Tornado OCX ($49US last time I checked).
• It requires the ISP to install the OCX on their server and to work with you a bit in getting it registered and set up.

The biggest drawback to Tornado is that it IS an OCX, and so requires a bit more leeway from your ISP (you will definitely need an ISP who is willing to work with you). It is the fastest of the three primary methods, though, and worth pursuing if your need is for speed.

One final note about HTX files: Because they completely separate the HTML pages from your CW programs, those programs become much easier to maintain. Remember, if the HTML for your web pages is hard-coded into the program itself, a change to the page means a change to the program. Since HTX files are created and maintained using a WYSIWYG HTML editor such as MS FrontPage 97, you can make changes to your pages anytime you want without necessarily affecting the program at all.

Tools of the trade

Our final topic for this month concerns the tools you need to do web development on your PC. Basically, you need the following:

• Clarion for Windows 32-bit (but you already knew that, right?)
• Some knowledge of HTML
  - Check out some books on HTML. Quite often now you can get great deals on last years HTML books (the HTML standard hasn't changed much since version 3.0 - the current is 3.2).
• A WYSIWYG Web Page authoring program
  -FrontPage 97, Claris HomePage, HoTMetaL Pro, etc. They all let you design web pages in a visual, select and drop environment similar to the CW Window formatter. No HTML knowledge is required (though it is helpful).
• A Web Browser or three (preferably Netscape, IE and an older browser)
  - Browsers are notorious for displaying the same HTML page in slightly different fashions, so you'll want to test your pages in more than one browser before uploading them to a web site.
• A Web Server for Testing - a couple of good options include:
  - Microsoft PWS (Personal Web Server). This is basically a cut down version of IIS, MS flagship web server. It supports CGI, ISAPI and a host of other cool stuff, though, and come free with MS Front Page 97. You can also download it for free from the Microsoft web site. It's the best to use if your site will be hosted under IIS.
  - WebSite. This is a nice server which can be downloaded free from O'Reilly & Associates (www.ora.com). It supports Win-CGI, CGI and ISAPI.
• Lots of memory
  - Once you get CW, a web server, a browser or two and your programs all running at the same time, you'll appreciate having as much RAM as you can afford. 16 megs works, 32 megs works much better, and anything more is icing on the cake.

Note: You can install and run PWS or WebSite and right on your development PC while you are working on your CW programs. That way, you can test your applications through your browsers in exactly the same way they will run on a real web site -- without having to bother with uploading changes, worrying about crashes or spending all your time online testing. You only upload your programs after they are thoroughly tested and debugged. Your ISP will appreciate that - especially since many of them have a 'three strikes and you're out' policy whereby if your program crashes their server three times, you (or at least your programs) are outta there!

Coming up next month

Whew! Got all that?

Next month, we move from the external (choosing how to talk to the web server, etc.) to the internal (your CW programs). We'll look at downloadable examples of CGI, Win-CGI and Tornado applications and the templates that handle all of those pesky details of interfacing with the web server. We'll also go over examples of the OOP classes they use to do the work.

To give you a sneak preview of just how much work the templates, etc. do for you, the only thing you'll need to do in your CW web program is:

1. Get fields from a pre-loaded queue of the information sent by the server.
2. Do whatever you want with the data passed to you in the queue.
3. Write out the HTML for the web page to send back to the user (and if you are using Tornado and HTX files, you don't even need to write the HTML).

Intrigued? See you next month!

Printer-friendly version

Copyright © 1999-2008 by CoveComm Inc. All Rights Reserved. Reproduction in any form without the express written consent of CoveComm Inc., except as described in the subscription agreement, is prohibited.

Clarion Magazine ISSN 1718-9942