Appgen-0.2
----------

Appgen is a an application generator and high level 4GL for creating WWW
based applications for use on the internet or corporate intranets. 
It is designed to use the Postgres95 database system but could probably be 
modified to work with any SQL database server such as mSQL. 
The generated C files and executables are designed to be executed as CGI 
scripts by a web server such as NCSA's HTTPD.

What does it do ?
Appgen generates data entry forms capable of adding, amending, searching 
for and deleting records from an SQL server (currently Postgres95). The
forms are based on HTML and so can be accessed via any Web browser.
The data structures are specified in a definition file which simply 
describes the fields of the database. The DEFGEN utility then compiles these
definition files into appgen source code which can modified before compilation
by the appgen compiler. The appgen compiler outputs standard C code which 
forms the cgi scripts. Some code relies on Java applets, which are provided. 

Installation
------------
You must have Postgres95 fully installed and working and also HTTPD. 
This package should ideally be extracted into /usr/local/AppGEN, although 
you can change it to something else but you'll need to modify the generated
makefiles. 
You'll need to copy the ag/ directory to the document root directory of your
web server e.g. cp -R ag /usr/local/httpd
The ag directory contains gif and java files needed at runtime.
You then need to add /usr/local/AppGEN/bin to your search path. 
Linux a.out (i386) binaries are provided but if you need to recompile them, they
should compile on most platforms, then do a make from the src/ directory.
You will obviously need the java development kit to recompile the applets.

Compiling and Installing the Personal Information Manager
---------------------------------------------------------
The PIM is provided as one of the sample applications. It is pretty basic, 
consisting of a To-Do list manager and a contacts database, but illustrates 
quite well the appgen 4GL and the benefits gained by running this sort of 
application in a groupware environment. The other sample applications are 
probably not of general interest as they are Estates related but do serve as
an example of appgen 4GL programming, demonstrating what can be achieved with
the system. All the sample applications are found in the apps/ directory.
To install the PIM, firstly you will need to modify the global.app file to 
set your site specific settings, the src directory is important as this will 
be the directory where the generated C files will be deposited. 
Type appgen pim.app, this compiles the pim file and produces the C files. 
Goto your src directory and type make, that compiles the C files and puts 
the executables into your CGI-BIN directory. 
You then need to create the SQL tables on postgres and setup some users, this 
is achieved by executed the pim.sql file e.g. psql <pim.sql
The application is then ready to use with netscape http://localhost/cgi-bin/pim
or whatever hostname and directories you have compiled with. Login with
username demo and password demo.

N.B. The cis.app file has been heavily modified after being generated by defgen
so if you run defgen cis.def you will overwrite the cis.app file with a much 
more basic version.


Usage
-----
There are three executables :-

defgen - is the application generator which generates appgen source code from 
         a table definition file (.def) Example structures are provided.
         Usage: defgen filename.def
         Outputs a file filename.app
         
appgen - is the appgen compiler, it compiles app files into cgi-scripts in C.
	 Usage: appgen filename.app
	 Outputs a series of C and html files into the src-dir directory.
	 
dbf2sql - Not really an integral part of appgen but provided for convenience.
	  Converts dBase III compatible DBF files to SQL, the SQL files consist
	  of a CREATE TABLE clause and a series of INSERT clauses.
	  Usage: dbf2sql filename.dbf
	  Outputs to stdout, so can be redirected. 	          



BUGS
----
Probably loads, 
* Def file parser needs improving, please stick to the format rigourously.
* Appgen has a few bugs, one nasty one is that it occasionally puts too 
  many brackets in C code for the CALC statement. The cis.app does this
  in invoice.c around line 292 which has to be edited prior to compilation. 

TODO
----
There is much I would like to do with this, which is why I am releasing
it, in the hope that it might attract other developers to contribute. A 
report generator would be quite an easy addition and some sort of 
menu generator would be nice. Appgen needs a lot of tidying, to iron out the 
bugs and perhaps introduce 2 passes to the compiler. More Java applets are 
needed for different graph types.
What I'm finally hoping for is a visual frontend, probably implemented in java,
so an application can be built with a few mouse clicks.
Documentation, there is a dire shortage of documentation, there is help file 
ag/help.html but it is a long way off being completed. My best advice is to 
study the example applications provided. The language is similar to DataFlex, 
in some respects and syntax. Its pretty straightforward once you get the hang 
of it but if you find some occaision when its not behaving itself or you find
that there are inconsistencies within it, please report it as a bug.


Licence
-------
Whilst I want to retain the copyright, I hereby grant any user permission to 
use, modify and distribute the software providing that the source is included 
with distributions and any modifications which are likely to be of use to the
wider internet community are emailed to me.
Any commercial interest in developing this for sale should seek permission from
the authors.


History
-------
Appgen 0.2 has been completely rewritten from scratch and does not incorporate
much from appgen 0.1. However DBF2SQL is unchanged from the previous version.
Credit should be acknowledged to paco@arraquis.dif.um.es, C.J.Leune@KUB.NL and 
Alberto Odria Diaz for their contributions to version 0.1.


Andrew Whaley
andrew@arthur.smuht.nwest.nhs.uk - Work
andrew@manix.demon.co.uk - Home 
