Kanchenjunga Quick Start



Who is this document for ?
This document is intended for those new to Kanchenjunga who have downloaded the software and are now ready to install and use the software for the first time.
This document consists of sections covering :-
Installation Instructions
Component Files and Directories
Configuration
Generating your first application


Installation Instructions

Firstly you need to have obtained and installed the Java Development Kit (JDK-1.0.2), your PATH variable should include a reference to the JDK binaries and your CLASSPATH variable should be set appropriately. Access to a postgres95 server is not required during the development stage, however, in order to test the generated applications it will be required later.

Having obtained your archive file, it should be untarred from a directory of your choice. This will create the 'Kanchenjunga' sub-directory containing all the package files.

Kanchenjunga can be executed by changing into this directory and typing 'kanch' on Unix systems or 'java kanchen'. This can only be executed from this directory.
Please note that this early version has no quit facility and so can only be stopped by issueing a control-C from the shell or using a kill command.

Component Files and Directories

The package consists of several directories :-
/ The top directory contains the main kanchen.class executable, the kanchen.conf configuration file and a top level Makefile for recompiling the package.
/doc Contains package documentation including this file.
/kanchenjunga Contains subclasses and graphics for the Kanchenjunga executable.
/data This is where project specific data is stored
/data/projects Kanchenjunga format project files, i.e. the ones you save from the package.
/data/apps Where the generated applications are deposited
/data/apps/kr Contains the Kanchenjunga runtime classes needed by the generated applications.
/data/apps/postgres Contains John Kelly's Postgres access classes, also needed at runtime. Please note these have been modified slightly from the original source.
If you move your final applications to another directory, you must also copy the kr and postgres subdirectories. BR>

Configuration

When you start Kanchenjunga, a toolbar should appear with several buttons active i.e. available for use. The far right button is for configuration and should be selected before any other operations are selected when first run. A user dialog will appear and prompt the user for the system parameters.
The parameters are :-
Target Selects the type of applications that will be generated by the system. Currently only 'Java-GUI' applications are supported.
RDBMS Specifies the host Database system to be used, only Postgres95 is supported at this time.
Database Host Is the full hostname of the database server, this will be hardcoded in the target applications.
Database Port The port number which the database server is using. This is usually 5432 for postgres.
Database Name The name of the database containing the data files used by the application.
Author The author's name to be commented in the generated source code.
Projects Directory Directory containing the users project files.
Target Directory Where the generated applications will be deposited.

Having completed these details, selecting 'OK' will save them permenantly or 'cancel' will ignore your changes and revert to the original settings. BR>

Generating your first application

Having started Kanchenjunga and assuming that you are happy with your configuration settings, you are ready to proceed. At this stage there are two options available to you, new project depicted by a folder icon and load project. Selecting the new project icon creates a new window containing a blank 'canvas'. There are now three more icons available to use:-
Save Project Saves and names the current project, I recommend that you do this frequently if you are using the Linux JDK, as it is prone to crashing when adding fields to a table.
New Table creates a new data table and corresponding data entry form into your application.
Generate Application Generates the java source code for the current application.


Creating Tables
As Kanchenjunga is a table-based RAD system is uses the table structures as a basis for generating application. Selecting the 'new table' icon or clicking on an existing table on the project canvas displays a dialog with the table parameters:-
Table Name Specifies the name of the table known to postgres, the data entry form will also be known by the same name.
Table Description This is the verbose description of the table, this will appear as the title of the data entry form.

Fields can be added to the table by clicking the 'add field' button on the dialog. Fields consist of the following parameters :-
Field Name The postgres compatible field identifier.
Field Description The descriptive name of the field that will appear on data entry forms.
Type This is the data type of the field, it can be char, int, float, date or text. The Text type corresponds to the postgres varchar and will create a multiline freeform text area on the form.
Length The length of the field, only applicable for the char type, but also specifies the length of the text field on the form so should be set to 10 for dates, 8 for numbers etc.
Pk - Primary Key Indicates whether the field is to be considered as part of the primary key. The primary key is unique and the form will prevent duplicate entries into the table. A primary key may include several fields. Every table must have a primary key.
Fk - Foreign Key Indicates whether the field is a foreign key i.e. relates to a primary key of another table. This is important for maintaining referential integrity between tables. Enabling the foreign key field will create a dialog requesting information concerning the relationship (see below).


Foreign Keys
Creating a foreign key requires details about the relationship. This information is used to enforce referential integrity in the application, and to create a browse facility to ease the input of foreign keys. The parameters required are :-
Foriegn Table This is the name of the table to which the field relates.
Foriegn Field The field within the foreign table to which this field relates.
Foriegn Descriptor Field A descriptive field in the foreign table which will be displayed during browsing.

All three attributes must be specified.

Generating Applications
When the table definition process is complete, clicking the 'Generate Application' will generate the Java source code for the application and place the resultant files into the /data/apps directory.
When this process is completed, Kanchenjunga can be exited (don't forget to save first). The user can then compile the resultant source code by typing './compile' in the /data/apps directory. Also a series of .sql files will be generated which contain the SQL table definitions for each of the defined files. These can be used to create the table within postgres using the monitor e.g.

psql dbname
\i mytable.sql
\q

The data entry forms can then be executed by using the command:

java tablename