Basic Web Pages from VO Applications

Copyright (C) 1997, Paul Piko

 

Introduction

Have you heard about this thing called the internet? Who hasn’t? And have you noticed how advertisements for all sorts of products are now displaying a web page address? To say the visibility of the internet is growing is almost an understatement.

As an application developer you have to consider the current computing trends and the demands of clients, so let’s take a look at how CA-VO can be used to tackle the internet.

CA-VO can be used to write a custom web browsers. Two examples showing variations of this are supplied with the product. They can be found in the SAMPLES\INTERNET\BROWSER and the SAMPLES\INTERNET\IE30 directories.

CA-VO can be used to write a web server – this was shown at CA-World 97, and the source code was subsequently made available for download from the CAVO20 Compuserve forum and from CA’s FTP site.

In fact, CA-VO can be used to create applications that email, connect to FTP sites, transfer data, and more.

The focus of this paper is on creating CA-VO applications that generate web pages. These pages may be static – files that are written by the CA-VO application and then posted to a web site.

Or the pages may be dynamic, produced by a CA-VO application that is executed in response to a user request.

So what is a web page?

Web pages are text files formatted in a special way. This formatting is called HTML (HyperText Markup Language), and each piece of coded information in the file is referred to as a tag. The HTML tags, which specify keywords between angle brackets (<>), are interpreted by web browsers and result in effects that include font changes, emphasis, italics, images, tables, links and more.

Static Web Pages

Let us imagine a situation that would suit production of static web pages. Let us say you are part of a company that has a sales tracking system. Each month the company wants to publish the performance analysis figures for each of the branches on its intranet. You could write a CA-VO application that queries the sales tracking system files and writes out the performance analysis figures to an HTML file. This file could then be put into a place accessible by the intranet’s web browsers for viewing, or linked to by other web pages.

 

Dynamic Web Pages

It is possible to set up your web pages so that a user can make an application run on the server just by clicking on a link or by filling in and sending an HTML form.

This is quite commonplace – a good example of this is a search engine. If you go to a search engine web site, you fill in the details you want to look for on a form then you click the search button. A program runs on the server, attempting to meet your request, and then an HTML form of results is displayed. This result form is dynamically created.

Commonly the language used for the server application is C or Perl. But it could also be CA-VO (as long as the server can run a Windows application).

CGI (Common Gateway Interface) is the way our CA-VO application can communicate to the web browser. When the user clicks on a link or submits an HTML form, the server reacts by starting the specified application. The server passes information from the user to the application through environment variables. The application runs, querying the environment variables as necessary. Information is passed back to the user’s browser via the server through the standard output stream (STDOUT).

So our server–based CA-VO application needs to:

  • Query environment variables
  • write strings (formatted as HTML) to the standard output steam

It doesn’t need any user interface code, since it is dealing directly with the web server.

Note that the strings written out can contain whatever data is required – the CA-VO application could look up databases or perform calculations, whatever you need.

 

How do I test this stuff?

Before we get into the details of how to write these applications, we need to look at the things you will need to be able to test them.

The most basic test environment you can have for this a single computer running either:

  • Windows 95 and Personal Web Server (PWS is downloadable from www.microsoft.com)
  • Windows NT 4 Workstation with Peer Web Services

However, using just one computer makes it difficult to be sure when it is running like a client and when it is running like a server.

So you should at least aim to have two computers, networked, with TCP/IP protocol installed – your own mini intranet. You can use Windows 95 and PWS installed on one or both computers, or Windows NT 4 on one or both. Any combination is workable.

Both PWS and Peer Web Services set up directories to organise the files that are available on the intranet. By default, PWS uses C:\WEBSHARE\WWWROOT as the directory to install web pages. Peer Web Services uses C:\INETPUB\WWWROOT as the default directory for web pages.

Under both PWS and Peer Web Services you can use the computer’s network name in a URL to call up web pages. So if I have two computers, one called PC1 and the other PC2, and I wanted to view the web files residing on PC2, I could start my web browser and specify a URL as follows:

http://PC2/mypage.htm

If I had PWS on PC2 this would show the file on PC2 called C:\WEBSHARE\WWWROOT\MYPAGE.HTM.

PWS and Peer Web Services also have a separate directory to store executables that are run via the intranet. PWS uses C:\WEBSHARE\SCRIPTS, and Peer Web Services uses C:\INETPUB\SCRIPTS.

HTML Basics

Before we start trying to write programs that produce HTML pages, let us go over the basics of what makes HTML page.

As stated previously, an HTML page is a specially formatted text file. Every HTML page includes the following text:

 

<HTML>

 

<HEAD>

<TITLE></TITLE>

</HEAD>

 

<BODY>

</BODY>

 

</HTML>

The text starting with "<" and ending with ">" is called a tag. Most tags, but not all, have a corresponding closing tag, made by including a "/" in the original tag. So <HTML> represents the start of our HTML document and </HTML> indicates the end.

The heading section of the page (between <HEAD> and </HEAD>) contains information relating to the structure of the page and can include a page title (between <TITLE> and </TITLE>) that appears on your web browser window.

The body section, containing most of the content of your page, occurs between the <BODY> and </BODY>.

We can update our skeleton HTML page to produce a title and some text in the browser:

 

<HTML>

 

<HEAD>

<TITLE>My Basic Web Page</TITLE>

</HEAD>

 

<BODY>

Our main text appears within the body of the page.

</BODY>

 

</HTML>

Tags can also contain modifiers that adjust the way they operate. For example, to force the background colour of the page to white we can use

 

<BODY BGCOLOR="#FFFFFF">

Or we can achieve an enhanced effect by placing an image on the background:

 

<BODY BACKGROUND="paper.gif">

Tags can also be nested – to emphasise part of a sentence we can use the <B> tag to make text appear bold.

 

<BODY BACKGROUND="paper.gif">

 

Our <B>main text</B> appears within the <B>body of the page</B>.

 

</BODY>

 

Normally, web browsers ignore extra spaces and carriage returns in your HTML file. To space text out, or for a new line you need to explicitly embed codes to force the formatting.

<BR> can be used to break a line. &nbsp; is a special code that can be used to force a space to appear.

 

<BODY BACKGROUND="paper.gif">

 

Our <B>main text</B> appears <BR> within the <B>body of the&nbsp;&nbsp;&nbsp;&nbsp;page</B>.

 

</BODY>

There are many other components available in HTML, too many to examine in detail here. In summary, some of the more common are:

 

Italics

<I>????</I>

Underline

<U>????</U>

Monospace font

<TT>????</TT>

Change font size-where x is from 1 to 7

<FONT SIZE=x>

????

</FONT>

Change font name

<FONT FACE="Arial">

????

</FONT>

Change font colour

<FONT COLOR="#111111">

????

</FONT>

New paragraph

<P>

Image

<IMG SRC="pic.gif" WIDTH=100 HEIGHT=100>

Link to page

<A HREF="link.htm">Go to link page</A>

Link to site

<A HREF="http://www.cai.com">CA’s page</A>

Email link

<A HREF="mailto:piko@melbpc.org.au">Email Paul Piko</A>

Centre

<CENTER>????

</CENTER>

Horizontal Line

<HR size=3>

Comment

<!-- A comment -->

There are numerous resources available for you to become proficient in HTML. The internet is a great place to find the information you need. Here are some starting points:

Beginner’s Guide to HTML

http://www.ncsa.uiuc.edu/General/Internet/WWW/HTMLPrimerAll.html

So you want to make a web page, Table Tutor, Form Tutor and Frames Tutor

http://junior.apk.net/~jbarta/

HTML Quick Reference Guide

http://www.mcp.com/que/developer_expert/htmlqr/at-htmlqrquery.html

 

Making a Static Web Page

Once you have and understanding of the HTML concepts it should be clear that it is not difficult to create a static web page. A CA-VO program like the following can write out appropriately formatted string to a file – in this case using the low-level file functions:

 

FUNCTION start

 

    LOCAL ptrFile AS PTR

 

    ptrFile := CreateHTML("C:\TEMP\MYPAGE.HTM","My Web Page")

 

    WriteHTMLBody(ptrFile)

 

    CloseHTML(ptrFile)

 

 

FUNCTION CreateHTML(cFile,cTitle)

 

    LOCAL PtrFile AS PTR

 

    ptrFile := FCreate(cFile)

 

    IF ! ptrFile == F_ERROR

        FWriteLine(ptrFile,"<HTML>")

        FWriteLine(ptrFile,"<HEAD>")

        FWriteLine(ptrFile,"<TITLE>"+;

            cTitle+"</TITLE>")

        FWriteLine(ptrFile,"</HEAD>")

    ENDIF

 

    RETURN ptrFile

 

FUNCTION WriteHTMLBody(ptrFile)

 

    IF ! ptrFile == F_ERROR

        FWriteLine(ptrFile,"<BODY>")

        // The code that goes here could query a database

        // or perform calculations, then write out to the

        // HTML file

        FWriteLine(ptrFile,"The answer is "+"<B>42</B>")

        FWriteLine(ptrFile,"</BODY>")

    ENDIF

 

FUNCTION CloseHTML(ptrFile)

 

    IF ! ptrFile == F_ERROR

        FWriteLine(ptrFile,"</HTML>")

        FClose(ptrFile)

    ENDIF

 

The file that is produced, in this case C:\TEMP\MYPAGE.HTM can then be moved to a location where it is accessible to the web server.

In testing, if you are using PWS in its default configuration you would put MYPAGE.HTM into C:\WEBSHARE\WWWROOT. Under Peer Web Services, you would put it in C:\INETPUB\WWWROOT. You can then call up the page in your web browser: e.g.

http://pc2/mypage.htm

If your testing is successful, you should then be able to post the page on the internet. The technique to do this varies from ISP (Internet Service Provider) to ISP and depends on who is hosting your site. Details on how to do this should be available from them.

If you do not need real time updates to your web page, and you don’t have huge amounts of data, creating static pages is a good option. You do not have to care what web server your site runs on (e.g. UNIX) because all you are providing is HTML files. You could automate the running of the generation program and schedule frequent uploads to your server to keep the pages up to date.

However, if you want to give the user the latest information, and allow them to narrow down the information they are interested in rather than having to wade through numerous pages, then a dynamic web page may be the answer.

Making a Dynamic Web Page

An example program that produces dynamic web pages is included with CA-VO – you’ll find the file CGI.AEF in the SAMPLES\INTERNET\CGI directory.

When you import the AEF you will find a copy of an HTML form that can be used to invoke the application. You need to take a copy of the text contained in the HTML Form module and write it out to a file, e.g. CGITEST.HTM. This HTML page is the one the users will see when they want to query your web site:

In your test environment under Windows 95 or NT 4, you can put a copy of this form into the WWWROOT directory.

However, there are a few changes to make to customise it to your environment . To make the sample easily adaptable some configuration details are included in the form. If you take a look at the source of the HTML file you will see the following:

 

<!-- The action statment defines the executable to be run -->

<!-- to process the query. Change the path to the location -->

<!-- where you put the EXE on your internet server. -->

<FORM ACTION="http://cavodev1/scripts/bin/vocgi.exe" METHOD=POST>

 

<!-- The CGI sample has been setup up, to take the input database -->

<!-- as form input. Change name and path of the database if -->

<!-- necessary. -->

<INPUT NAME="database" VALUE="\inetsrv\data\demo.dbf" TYPE=HIDDEN>

 

<!-- An index file to be used with the database can be specified. -->

<!-- However, it is not required. Change name and path of the -->

<!-- index file if necessary. -->

<INPUT NAME="index" VALUE="\inetsrv\data\demolast.ntx" TYPE=HIDDEN>

 

<!-- A field list to select the fields from the database to be -->

<!-- displayed in the output can be specified. If no field -->

<!-- list is given, all fields will appear in the output -->

<INPUT NAME="fields" VALUE="Last, First, Street, City, State, Zip" TYPE=HIDDEN>

 

The first item that needs changing is the FORM ACTION line, where reference is made to the program that will run when the form’s Submit button is pressed. In the test environment we have described earlier, we need to put the executable in a directory that has security permission allowing execution of programs. By default this is the SCRIPTS directory, so our URL on this line should read:

http://pc2/scripts/vocgi.exe

The next three INPUT NAME lines set up environment variables that our CGI program will be able to query and act on. In this example the variables contain the name of the database, the index to use and the fields to show.

When you write your own version of the CGI program you may decide to obtain this information from somewhere else rather than picking it up from the form. The choice is yours.

Having updated the HTML form and put it into the WWWROOT directory, you need to make sure the CGI program and data files are correctly installed. Use CA-VO to create VOCGI.EXE, then copy it to C:\WEBSHARE\SCRIPTS for PWS, or C:\INETPUB\SCRIPTS for Personal Web Server. Make sure you also copy across the DLLs that VOCGI needs:

CAVO2RDD.DLL

CAVO2SYS.DLL

CAVONT20.DLL

CAVORT20.DLL

CAVODBF.RDD

DBFNTX.RDD

If you write your own CGI program you may end up with additional DLLs to install as well, e.g. if you use CDX indexes you would need _DBFCDX.RDD and DBFCDX.RDD.

The data files need to be placed into the directory that VOCGI expects to find them, which depends on what path you put into the HTML form. For this example, let us assume that we specified the value for the database as "..\data\demo.dbf", and the value for the index as "..\data\demolast.ntx". This means we would copy the files into a directory called DATA under the parent of the SCRIPTS directory, since VOCGI will be running in the SCRIPTS directory.

The sample is now ready to run. Use your web browser to open CGITest.HTM, e.g. fill in a URL like this:

http://pc2/cgitest.htm

The query form appears in the browser. Now click on the Submit Query button. This will invoke our VOCGI program. If all is configured correctly, VOCGI.EXE will run on the server machine and process the form’s query. Successful completion of the program produces a dynamic web page:

The environment variables are listed first on the page for debugging purposes, then follows a table containing the data extracted from the database.

If we return to the query form we can change the requested information, specifying that we only want the first match when the last name starts with "B".

When we submit this query VOCGI adapts its behaviour and presents us with the result of our query in a different format:

This shows the power of being able to dynamically configure the output according to the user’s requests.

 

How does VOCGI.EXE work?

VOCGI.EXE first makes a call to the Windows API function AllocConsole(). This function sets up handles to access standard input and standard output.

The output from VOCGI will be directed to standard output, which the web server will then direct to the user.

The first information that VOCGI sends to standard output is a string that informs the web server the format of the data we will be sending:

Out("Content-type: text/html")

(The function Out() is included in the source – it just appends a line feed character then writes the string to standard output.)

VOCGI then picks up and verifies the environment variables. However, before we can use the values we need to parse them because under CGI certain characters are handled specially, e.g. spaces are converted to "+". This means we have to reverse the process prior to using the value.

Also, all the query parameters are concatenated into a single string containing name and value pairs. This query string needs to be broken apart into its separate pieces.

Once the query values are determined the code in VOCGI gets a little complicated, due to the fact that it is being generic. You can pass the name of any database, any index and a list of any fields to VOCGI and it will extract the appropriate details, in browse or form view. The important thing to note is that as it goes through accessing the database it is building up an HTML string, which it then writes out to standard output. It keeps doing this until it finishes reading the database.

Finally VOCGI makes a call to the Windows API function FlushFileBuffers() to ensure that all information has been written from the system’s buffers, and then calls FreeConsole() to release the console it had allocated earlier.

 

More details about CGI are available from:

CGI - Forms Tutorial - Creating the Form

http://www.efn.org/webbuild/tut_form.html

How to Use CGI and Make HTML Forms

http://www.gu.edu.au/gwis/cwis/doc/cwis_cgi_forms.html