Product Review: IFT Server

by Tom Hebenstreit

Published 1999-09-21    Printer-friendly version

Review Editor's note:This is the first of two reviews of the Internet Framework Templates. This one covers the Server templates, while the second one will cover the Client Edition and how the two pieces fit together. Note that the Client edition is not required to use the Server Edition.

Logic Central's Internet Framework Templates are a relative newcomer on the Clarion Third Party scene, but they have already generated a fair number of questions on the TopSpeed newsgroups. The easiest way for me to introduce you to them is probably to begin by answering the most common of those questions. I'll also define a few terms that I'll use throughout the review.

(Acronym alert! It is impossible to talk about Internet communications without quickly becoming surrounded by the various terms and abbreviations that constitute 'Internet speak'. I will try to provide enough simple explanations and background so that the review is understandable, but it is far beyond the scope of this review to explain the bare metal details of the Internet.)

What are the Internet Framework Templates (IFT)?

These templates handle low-level communications across the Internet using the Windows Sockets (WinSock) libraries that are either built into or available for all versions of Windows. The protocol IFT uses for communicating over those sockets is HTTP (Hyper Text Transport Protocol), the same protocol that is the basis of the World Wide Web.

What is a socket (port)?

Sockets are tough to explain! Think of an old-fashioned telephone switchboard, where an operator answers all calls and then plugs each incoming call into a private connection with a local telephone. The socket is a bit like the operator. There is a single port (connection point) within an IP address that, by Internet standards, is a public port. For web servers, it is port number 80. When you send a request to a web server, that request goes to the public port, which then assigns a private socket/port (connection) with which you and the server to hold your conversation (in other words, request and receive data).

Once the server has assigned the private connection, it can move on to the next public request. In the meantime, you and the server use the private port until you are done, and then the port is freed so that it can be used again for someone else (just like hanging up the phone frees up a phone circuit). Note that you can have web servers (such as an IFT program) that listen to ports other than 80 (80 is simply the default). If you already have a web server on a particular machine, you can, for example, have an IFT server listening on port 81 or 89 or just about any other valid port number (the most common alternate address is 8080, which is easy to remember). To address a request to the non-standard port, you simply add the port number to the URL or IP address using a colon, as follows (this is a real link to Logic Central's IFT demo server):

http://24.5.80.133:89

In this example the HTTP request will go to port 89 rather than 80. If there is a server on that port, it will do exactly what a regular server does, create a private connection for the request and then wait for the next request on its public port.

What web servers does IFT work with?

Programs created with IFT do not work with a web server, they are a web server. This is a key point! You do not need a standard web server at all, as do other approaches such as CGI, Clarion Internet Connect, the Tornado OCX or many others. If you do happen to want to run an IFT program (or many of them) on a machine that has a standard server, you simply need to assign each one to different port.

What can I do with IFT?

The most common use of IFT would be to build what is called an "'application server." This is a specialized web server (program) that is built to provide one particular set of services, just like most of the Windows applications that you normally build with Clarion. The app could serve up standard web pages, custom pages built on the fly, send/receive data, send email (if you write code to do that), handle file uploads or just about any other service that is common across the Internet. In a way, you can think of an application server as a specialized form of client-server application built to operate over the Internet. The client requests something from your program, and your IFT program sends it back as either a web page or as binary data. If I sound rather vague about what exactly an IFT program can do, it is because you can use IFT to do just about anything you can imagine.

Ok, enough background.

Major Features

• The Internet Framework Templates handle all of the lowest level communications details, leaving you to attend to the task of handling requests and providing any and all content.
• The product is completely template code - no libraries or DLLs are needed (other than the standard Winsock DLLs).
• All standard methods for requesting data from a web server (GET, POST and HEADER) are supported.
• Additional utility functions are provided to take care of many common tasks, such as decoding information from forms and so forth.
• Bonus templates (called PowerMerge templates) are included to provide a variation of mail merge. This allows you to place tokens within other text and use these functions to replace the tokens with actual data. Thus you can write generic code or web pages, which are then filled in by the merge template code on demand.

Installation

The IFT package is provided as a standard single file install.

Installation proceeded without problems, but also without frills. The installer didn't locate my Clarion5 folder (it is on an E drive), didn't show any show any documentation and didn't register the templates for me. No icons were created and my Windows menus were not modified. The biggest shortcoming, though, was that it didn't tell me where IFT was being installed. I had to poke around in my Clarion5 directory to discover a new folder named \IFTEXAMPLES.

Once I located that directory, I found both the documentation and two example applications.

Documentation

I normally leave discussions of documentation until the latter half of a review, but in this case it needs to be mentioned right up front. The documentation is, in a word, sparse, totaling about six or seven printed pages. The biggest pointer in the docs is to study the sample applications that are provided, as they demonstrate most of the common techniques that you would use to build fully functional IFT servers. Two demo apps come with IFT, one to illustrate how to use IFT, the other to show how to use the PowerMerge templates (they are used in the IFT demo app as well). On the minus side, the demo apps are not very well commented, so you will need to study them fairly closely.

Additionally, since the templates provide a framework for other technologies such as HTTP and HTML, there is a definite learning curve beyond that of the templates themselves.

So, be forewarned - while the templates themselves are very simple to use, you will need to be prepared to spend some quality time tracking through the code they generate in order to learn just where your custom code should go. You will also really need to learn some basics regarding HTTP, HTML and the theory of how these things all work together. That information is not covered in the documentation either, but there must be a gazillion books on HTML out there, many of which you can pick up cheap in the remainder bins for $5-10. On top of that, there is no better place for learning about web technologies than on the web itself.

Time to move on to the templates themselves.

Implementation

Starting at the beginning, I registered the five templates that comprise IFT (two for IFT itself, the other three for PowerMerge and some demo functions).

I then created a server using Clarion 5 according to the steps laid out in the documentation. Basically, this involved:

1. Creating a new 32-bit application (ABC templates)
2. Adding the IFT Global Extension template
3. Creating a simple window procedure, and adding the IFT Start/Stop buttons control template to it.
4. Adding the IFT Procedures and Routines extension template to the window.
5. Compiling and running the application.

Pressing the 'Start' button on my server window (as shown below in Figure 2) started the actual process of having my server listen for requests on the selected Port (Figure 1 shows how I specified the port in the templates).

Figure 1. Specifying the server port.

Figure 2. My test server in action (not much to look it, is it?)

Once it was up and running, the next step was to test it out by sending it a request from a web browser. I fired up Netscape 4.61 and typed in the following URL (this is not a real world wide web address, though it is valid on my test machine): http://localhost:8080/test

Lo and behold, up popped a page with a "Test Successful!" message. Where did it come from? The templates offer an option to generate a procedure that responds to the /test page with a user definable message. This is a nice touch, as it lets you verify that things are working without doing anything other than the above five or six steps. Remember, if I hadn't specified the port (8080), my request would have gone to my normal web server (which is running on the same machine) rather than the IFT server.

Well, that was certainly easy. The problem, though, was that my spiffy new IFT server didn't do anything useful yet. Well, that's not really true. By making its default folder a directory on my machine that contained an actual web site, it quite happily served up pages and images from that site. Neat! Right out of the box I had a basic web server built in Clarion.

Moving along, I compiled and ran the demo application. Whoops. Trying to request pages from that IFT server didn't work at all. I received either strange messages or Netscape (and IE) would try to download zero byte length pages to my hard disk.

After a bit of research I discovered that IFT had defaulted to C:\Clarion5 for the demo home directory. Once I changed that to the real location on my E drive, and stopped and restarted IFT, the demo started working. Well, sort of. I tried the /test parameter like the first time and it didn't work. Back to the app for another look and I discovered that the demo was set to respond to /mytest rather than /test. This is another case where the documentation should be clearer about what is needed to run the demo, and it seems to me that it should be consistent with the documented /test syntax as well.

A key point to understand when working with IFT is that the URL (page) you request may or may not be a physical file on disk. For example, when the IFT server received the request for /test, it already knew that this was a special case. Instead of looking for a file to send back, it simply created the response right then and there, in memory, and then sent that response back to the browser case (see Listings 1 and 2 below).

It may look like you are requesting a physical file, but in reality you are simply passing a parameter to the IFT server (just like calling a parameterized procedure in Clarion). In cases where there is no special code for handling a request, IFT automatically looks on disk to see if there actually is a file and then sends it back if the file is found. That's why the /test request worked even though the demo directory was set wrong (it never looked for a directory), and also why IFT works as a normal web page server right out of the box.

What came next? Well, to be frank, it was a number of days wading through both the generated code and the demo code, studying how it handled the various kinds of requests that can be submitted via HTTP, asking questions, copying code to my applications and in general just getting a feel for the amount of flexibility the templates offer (a LOT, by the way). Fortunately, I'm already quite comfortable with HTTP and HTML, so at least I didn't have that mountain to climb.

To give you a bit of a feel what is involved, here is the code that is generated by the templates to send back that automatic test page. First, the bit that checks for \test as a special case. This is part of a larger section of code that parses out what the user requested, and then tests to see what that request was.

Listing 1. Checking for the test parameter.

Case UPPER(mPathName)       !mPathName contains the request
 of UPPER('test')
   OnSendTestData(ReqSocket)
 ! lots more 'OF' this or that tests 

That's pretty straight forward. Here is the actual procedure to create the response page:

Listing 2. Creating and returning the Test response page

OnSendTestData PROCEDURE(SOCKET ReqSocket) 
             Code
         clear(sendbuf,-1)
         clear(SendHDRbuf,-1)
         sendbuf='<<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">'
         sendbuf=sendbuf&'<<html><<head><<title>Test
        Message<</title>'
        
        sendbuf=sendbuf&'<</head><<body><<center><<font
        face="Verdana">'
         sendbuf=sendbuf&'<<H2><<font
        color="#FF0000"><<P><<P><<P><<P>
         Test Successful!<</font><</H2>'
        
        sendbuf=sendbuf&'<</font><</center><</body><</html>'
         SendHDRBuf='HTTP/1.0 200 OK<13><10>'
        
        SendHDRBuf=SendHDRbuf&'Date:'&DateTimeStamp(Today())&'<13><10>'
         SendHDRBuf=SendHDRbuf&'Server: IFTTester/1.0<13><10>'
         SendHDRBuf=SendHDRbuf&'MIME-version: 1.0<13><10>'
         SendHDRbuf=SendHDRbuf&'Pragma: no-cache<13><10>'
         SendHDRbuf=SendHDRbuf&'Content-type: text/html<13><10>'
        
        SendHDRBuf=SendHDRbuf&'Last-modified:'&DateTimeStamp(Today())&'<13><10>'
         SendHDRBuf=SendHDRbuf&'Content-length:
        '&len(sendbuf)&'<13><10><13><10>'
         sendbuf=clip(SendHDRBuf)&clip(sendbuf)
         Err=ssend(ReqSocket, sendbuf, len(sendbuf),0)
         OnCloseClientSocket(ReqSocket)

Now, before you run screaming from the review, that there are really only four things happening here.

1. The two text buffers that will hold the response page are cleared. Why two? If you look, it is building two things. The first is the actual page to be displayed in your browser, and that page contains standard HTML. The second is the HTTP header that describes the page so that your browser knows where it came from and how to display it. Most of the code is simply concatenating text into two big strings. Oh, yeah - and why is the header created after the page? If you'll look at the line 4 up from the bottom, you'll see that it is using the standard LEN() function to get the length of the HTML page. This becomes part of the header so that your browser knows just how many bytes should be read from its port (and that number isn't available until after the page string is complete).
2. The two buffers are concatenated. Here is where the HTTP header is placed in the proper position to be sent first.
3. The IFT ssend() function is used to actually send the information (the buffer) back to the requestor (you and your browser) using the private socket.
4. The socket is closed since we are finished with it.

That's not so bad now, is it? You can see though how having some knowledge of HTTP and HTML can be important (how else will you know what to send back?).

Be aware that you can use visual design tools such as Microsoft FrontPage, Netscape Composer, Macromedia Dreamweaver and so on to create your pages. You can then use the included PowerMerge templates to merge data into those pages where appropriate. You are not forced into hand coding all headers and HTML.

Performance

Once I actually got an IFT-based server running, the performance of my IFT created server programs was very good. Remember, when compared to something like IIS (Microsoft's web server - Internet Information Server), an IFT program is a lean, mean server machine unencumbered by the need to do anything beyond what you tell it to.

Note: I will be doing more performance testing over the next few weeks as I begin working with the Client version of IFT, and will include more performance information in that review.

Technical Support

Technical support was excellent. I bombarded Mike Pasley (the author of the templates) with an endless stream of email questions, problems (mostly my own) and comments. All responses were fast and informative. One template problem I discovered in the PowerMerge templates was fixed by the next day, with a new version waiting in my mailbox. Another problem was solved within an hour so.

Logic Central also monitors the TopSpeed Third Party news group. Questions posted there are generally answered in short order.

I must point out, though, that Logic Central's Technical Support is just that - support for technical problems related to the templates. They can't be expected to teach you the ins and outs of HTTP, HTML, URL encoding/decoding and all those other nuts and bolts that can be used to build a web-based application server (remember that learning curve I talked about earlier?).

Room for improvement

As I'm sure you have discerned by now, IFT as a product is definitely in need of better documentation. Eminently useful templates and utilities such as the PowerMerge functions were not documented at all in the version that I was testing. Logic Central is aware of these shortcomings, though, and hopefully the situation will improve as they have time to work on it.

The documentation also suggests looking at the embeds to help learn templates. By my count, there were more than 65 IFT-specific embed points in my test server - yikes! Not that I am complaining at all about there being so many embed points; that's a very good thing and adds to the flexibility. I just don't want to have to manually inspect them all to learn the product!

The install could also be improved by making more basic information (such as the installation directory) available to the user.

Summary

The Internet Framework Templates are a very powerful tool which open up an entirely new avenue for using Clarion to build Internet-based applications. Ironically, the fact that IFT makes it incredibly easy to get close to the metal is both its greatest strength (indeed, its reason for existence) and its greatest drawback. After all, once you are there you are left close to the metal, and it's up to you to do the rest.

The bottom line is that if you have a need to build any kind of Internet application server, and are willing to put in the time to learn basic Internet standards and skills such as working with HTTP and HTML, you really can do virtually anything with these templates.

That is why they are called a Framework, after all.

The Internet Framework Templates Server Edition list for US$299, and can be purchased via the Internet from BMT Micro.

The IFT Server purchase page is: http://www.bmtmicro.com/catalog/ifthttpserver.html
The IFT Client purchase page is: http://www.bmtmicro.com/catalog/ifthttpclient.html

If you are buying both at the same time or have bought one and you are returning later to buy another you can receive a$20 discount (after Logic Central has verified your prior purchase).

More information, demos and answers to frequently asked questions can be found at the Logic Central web site: http://www.logicentral.com

Vendor Comments from Mike Pasley of Logic Central

The IFT 2.01 version will be coming out with additional functionality including a Base64 codec and use of the WWW-Authenticate header. Documentation, as has been noted, will be increased and improved to respond to the growing user base, which is including many developers new to Internet programming. The Internet Framework toolset will continue to expand to make even new internet protocol developments more accessible to the Clarion developers. Technical support will come to include a live chat session (probably) at the Logic Central website. Please continue to view Logic Central and Clarion Magazine web sites for the latest products and news from Logic Central. The IFT will continue to expand its editions and their functionality. Suggestions will continue to be welcomed. I would also like to take this opportunity to thank all who have given me support on this project.

---

A longtime Clarion user, Tom Hebenstreit is an admitted tool junkie who refuses to go straight and code without his arsenal of third party products. During those rare moments when he isn't either using or writing about Clarion, he indulges his twin passions for blues and beer by performing around Southern California in a variety of totally-obscure-but-famous-any-day-now rock and blues bands.

Printer-friendly version

Copyright © 1999-2009 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