README File

CGI Templates for Clarion
by Dave Berton
This code is freeware.  I take no responsibility
if it happens to destroy everything.
Send all suggestions to 102644.3557@compuserve.com


What this is all about:
----------------------
This is about wanting to get your databases on the web quickly and easily
using Clarion.

If you are looking to build a super-high traffic site with a
slick and seamless web interface, you should use Clarion Internet Connect,
that's what its there for. If you are looking for a solution for an immediate
problem, or you just want to get some tables of data out on the web, then this
code should get you started.

CGI (common gateway interface) can be utilized directly from Clarion.  We
basically fool the WWW server into thinking we are a console program,
outputting all the HTML we want in the meantime, as easily as writing to a
data file.

I am not going to go into the details of CGI here (there are plenty of
resources available on the web: Tom Hebenstreit's series of articles in
ClarionOnline is the best place to start out).  Suffice to say that if you
know that you want to use CGI, then these templates will let you do it with
Clarion.  The code included here is by no means completely exhaustive, but it will
be enough to get you well on your way.

For those of you who have seen the other releases of this template
before, there isn't too much new stuff. The good news is, it has been
re-written so that writing a CGI app in Clarion is much easier and more
flexible, and additional support for other WWW servers can be added (hopefully
sooner than later).

How to write a CGI app in Clarion (how the template/object works):
-----------------------------------------------------------------
Follow the directions below for getting all the files in the right
places, the template registered, etc.

Start a new application and make it 32-bit.

Add the global CGI extension to your application.  You can enter many settings
from here, including the (required) name of your global CGI object which will
basically run the whole show for you.  The rest of your application will use
this global object to, for example, output some HTML or figure out what button
the user pushed on his/her web browser, etc.  The 'HTML Setup' tab will allow
you to enter some optional prompts that effect the appearance of the HTML
pages your program outputs (see the ADVANCED.APP sample app for an example of
using these).  The 'Tables' tab allows you to specify some default settings
when outputting HTML tables.

After adding this global extension, your application will generate code that
instantiates the cCGI object as a global class.  There will be additional
Global embed points that you can use to alter the behavior of the global
object (for example, you can add code that runs every time your program
outputs the Header or Footer of an HTML page).

The last thing that a CGI application requires is a first procedure.  A
PROCEDURE template called 'CGISource' is also included and can be used here
(see both sample apps for use of this procedure template).  The CGISource
procedure template is exactly the same as the 'Source' Clarion procedure
template, except CGISource allows you access to the CGI method reference.

Once you have defined a first procedure, you are done.  The rest is up to you.

The best way to see the way the CGI templates 'wrap' themselves around the
normal application code is to generate the HELLO.APP and look at the
default program source file (HELLO.clw).  In there, you will see that the
object you named in the CGI global extension template has been derived from
cCGI.  You will also see that there are some virtual methods in your
derived class (you have access to these methods in the global embeds).  After
the CODE statement, your global object calls its Init() method.  This prepares
the object and allows it to figure out where to write HTML to. Then the
applications first procedure is called (this is where you can place the meat
of your CGI code). When that procedure is finished, the Kill() method is
called to clean things up.

Files included in this zip:
--------------------------
README.TXT       !- This file
cCGI.CLW         !- cCGI Class method definition file (goes in LIBSRC dir)
cCGI.INC         !- cCGI Class include file (goes in LIBSRC dir)
CGI.TPL          !- CGI Template file (goes in TEMPLATE dir)
CGI.TPW          !- CGI Template file (goes in TEMPLATE dir)
ADVANCED.APP     !- Sample app for you to play with
HELLO.APP  	 !- Sample app for you to play with
ADVANCED.DCT     !- Sample dictionary used by ADVANCED.APP
ADVANCED.EXE     !- Compiled sample program (goes in SCRIPTS dir)
HELLO.EXE  	 !- Compiled sample program (goes in SCRIPTS dir)
SALES.TPS        !- Sample data file used by ADVANCED.EXE
CGISAMP.HTM      !- HTML file used to run samples (goes in WWWROOT dir)

What you need in order to use this stuff:
-------------------------------
You will need Microsoft Internet Information Server (IIS) version 2.0, which
means you also have Windows NT, installed and running (confirm this by typing
"localhost" as the HTTP address from your web browser). (NOTE: It is true that
these templates used to work with O'Reilly's WebSite server, however, I have
not had access to WebSite for some time now.  If someone can confirm that they
still work with WebSite, I would like to hear about it.)

You will need Clarion 4 BETA3a.  I have not tested on anything higher than
this for lack of time.  If someone can do a recompile with BETA 4, and
everything looks good, let me know.

You need a web browser (I have tested this on IE and Netscape).

Where everything goes and what to do with it when it gets there:
---------------------------------------------------------------
After unzipping, place the template files (CGI.TPL and CGI.TPW) in your
CLARION4\TEMPLATE directory.

Place the object files (cCGI.INC and cCGI.CLW) in your CLARION4\LIBSRC
directory.

Open Clarion and register the CGI.TPL template.  You are now ready to load and
poke around the two sample apps (see below for more on these).

Place CGISAMP.HTM in your INETPUB\WWWROOT directory (or wherever you have told
IIS to locate your HTML files).

Place the compiled sample programs (ADVANCED.EXE and HELLO.EXE) in your
INETPUB\SCRIPTS directory (or wherever you told IIS to locate your
executables).

The sample programs:
--------------------
HELLO.EXE - Here are the steps I went through to get this program
running on the web.
1. Start a new 32-bit app.
2. Add the CGI global template extension.
3. Filled in the name of my object in the prompt provided.
4. Selected 'CGISource' as the procedure type for the Main(ToDo) procedure.
5. Went into 'CGI Processed Code' embed for the Main procedure and typed one
line of code.
6. Checked the 'Declare Globally' check box in the Main procedure.
7. Compiled the program.

I moved the executable into my INETPUB\SCRIPTS and called it from my browser
by typing "localhost/scripts/HELLO.exe".  Alternatively, you can use
CGISAMP.HTM to activate the program.

ADVANCED.EXE - This app takes advantage of most of the features that the
template and cCGI object offer.  Your best bet is to poke around and see what
I did.  (NOTE: ADVANCED.EXE expects to find SALES.TPS in the same directory
that it runs from.  Therefore, you will need to tell IIS that the
INETPUB\SCRIPTS directory has 'execute' -and- 'read' priveledges for this
program to run successfully.)  Use CGISAMP.HTM to activate this program.

General Dos and Don'ts
----------------------
Remember to always compile 32-bit and to always have your applications first
procedure defined.

Avoid using windows and the MESSAGE() function, since this will hang IIS (CGI
programs are not supposed to be windows programs). Although, as you will see,
the ADVANCED.APP uses the PROCESS procedure to output some HTML.  In that
ase, the window opens and then closes, so everything is cool.  Just be
careful.

Dig around the cCGI class files to see what is going on under the hood - its
all fairly simple stuff.

Making the templates better:
---------------------------
I have enjoyed writing and rewriting this code periodically over the past
year or so.  I have plans in the back of my head to do a good deal more
ith them, but have not had the time yet.  If anyone is at all interested, I
would love to hear suggestions for improvement.  Contact me at
102644.3557@compuserve.com.

Hope someone gets some use out of this.

db


NOTE: Sample code, applications, and HTML pages included in this zip are provided as examples only, and are not intended for use as production-quality Web applications. 