======================================================================

Company:                  Primac Systems Limited

Project:        PRIM (Permission Record Information Machine)

Version:                           1.0

======================================================================

Documentation
-------------
Date:            29 June 2001
Author:          Francis Wong

Project
-------
Commencing Date: 4 April 2001
Completed Date:  6 July 2001

Content
-------
1.   Essentials
1.1  Introduction
1.2  System Requirement
1.3  Installation
1.4  Configuration

2.   Functions
2.1  Report Show
2.2  Report Make
2.3  Report Remove
2.4  Setting
2.5  Field Select
2.6  Field Update
2.7  Field Insert
2.8  Field Delete
2.9  Tool Graph
2.10 System Logout
2.11 Table Create
2.12 Table Drop
2.13 Table Grant

3.   Features
3.1  Multilingual
3.2  Built-in Database Features
3.3  Data Types
3.4  Table and Field Specifics
3.5  SPRIM (PRIM Simulator)

4.   Troubleshooting
4.1  Login

5.   Package
5.1  File List

This manual can be redistributed under the terms of the
GNU General Public License as published by the
Free Software Foundation; either version 2 of the License,
or (at your option) any later version.

======================================================================

1. Essentials

======================================================================

1.1 Introduction

PRIM is an easy to use yet powerful record management
system. It is one of the world's first open source
system to integrate database tools with essential built-in
database features that are ready to use and can be accessed
anywhere through the internet. These features include:
Standard Database Administration Built-In Features such as
SQL queries, Reporting, Graph, User Permission Data Handling,
Data Display Setting, Scripting for Data Creation,
Multilingual Option, and many more.

---------------------------------------------------------------------

1.2 System Requirement

PRIM was developed and tested on the following system specifications.

Hardware

- MOTHERBOARD: ATX
- CPU: Intel Celeron 466mhz?
- RAM: 64 mb
- HDD: 6 gig (1 gig each partition)

Software

- Operating System: Windows 98 Second Edition 4.10.2222 A
- Web Server: Apache 1.3.12
- Scripting Language: PHP 4.0.2
- Database Server: MySQL 3.22.34
- Browser: Netscape Communicator 4.7

---------------------------------------------------------------------

1.3 Installation


Apache Webserver 1.3.12
-----------------------
Make sure that PHP is included as part of the webserver's
module so that php files will be executed as scripts.


PHP 4.0.2
---------
Make sure that the graph module is included in the package
so that the graph feature is ready to use. One way to check it
is to write a php script, say test.php, with:

<?php

phpinfo();

?>

The graph module is included if it shows under
the "gd" section that GD Support is "enabled".


MYSQL Database Server 3.22.34
-----------------------------
Make sure that the package includes a script file called
"script.sql". If you execute this script file it will
initialise the PRIM essential data into the database
before you can start using PRIM to manage your data.

To execute the script under the mysql database server, type:

source script.sql

Note: script.sql is for mysql only.

---------------------------------------------------------------------

1.4 Configuration

After executing the initialisation script "script.sql", there
will be a super user under the login name of "root". It is
best to change this user's login detail for security reasons
after you have executed the initialisation script "script.sql".
This super user can create new users, give them permissions
and has many data management privileges.


- To login as a super user initially:
(Apache Webserver - Standalone)
http://localhost/

Username: root
Password: root
Language: English


- Then you will see the main menu screen:

Setting: Table Name: usr
Click Ok

User: Update
Click Ok


There you should see the fields usrnm (username) and
psswrd (password). So you can change them for
the new super user login detail and then click Ok
for the changes to take effect.

You will need to go back to the login page so that you
can use PRIM under the new super user login. Otherwise,
you may get an error if you try to use the PRIM features
with the old login.


- Go to the login page:
(Apache Webserver - Standalone)
http://localhost/


======================================================================

2. Features

======================================================================

2.1 Report Show

The purpose of this feature is to show sets of data from different
tables. This is useful when you want to see data of related tables.
There are already some built-in reports for you to see e.g.
table_field. You can use the Report Show filtering options such as
Group By and Order By.

Group By: Groups the report data by a specific field.
Order By: Orders the report data in numerical/alphabetical order by
a specific field.

The report fields can also be filtered in the form.

Hint:
Examine the data then try to exam it after you've set
the Group By, Order By and column filters to see their effect
on the data view.

---------------------------------------------------------------------

2.2 Report Make

To create a report, you will have to specify a report name
and select at least one field from the tables listed in the form.
The table fields of the report will be saved in the PRIM
database. The data will be processed and displayed each
time the Report Show is called.

e.g.
You may want to include in the report user_table_field
the username column data from the table user, and the
fieldname column data from the table tablefield.
Then you will have to name the report and select the
fields in the form.

Report Name: user_table_field

User       : Username[Yes]
...
TableField : Fieldname[Yes]

This report should show the username information and the
tablefield information. To make a report with the tablefield
information from the tables owned by a username, there will need
to be a reference between the two tables in order to make that
connection. Otherwise, the report will make not make any sense
because it will just show two separate bits of information.

---------------------------------------------------------------------

2.3 Report Remove

To remove a report, you will need to select one of the
specified reports listed in the form. The built-in
reports, such as table_field, cannot be removed because
they are system reports.

e.g.
Assuming you've produced a report called user_table_field.

Report Name: user_table_field

Select the table, then click on Ok.

---------------------------------------------------------------------

2.4 Setting

Under the Main Menu Setting, you can select the table you wish
to observe, and the data range you wish to display by the
starting id and the number of data displayed from that id.

Hint:
Try change the table to usrprmssntbl from the setting.
Choose "Select" to view the data from that table and examine
them. Now change the shown settings and choose "select" again
to examine the data. You should be able to see its effect.

---------------------------------------------------------------------

2.5 Field Select

Field Select is a very useful feature for table data observations.
To filter the table data using User Select, you can enter
the field data in the form in order to narrow down your
search of specific data.

e.g.
Choose "Select" and examine the data from the table.
Try the column filter by filling it with value(s) to
narrow down the search. Submit it then examine the
difference between the data before and after the filtering.

Table Name: usrprmssntbl

id
--
5

This will select the fifth data entry from the table
"usrprmssntbl".

---------------------------------------------------------------------

2.6 Field Update

Field Update allows the user to update existing data in the
current table in the Setting. Make sure that the new
data satisfies the current table field requirements.
e.g. If the field is NOT NULL then a value is required
for that field otherwise an error will be prompted to
the user.

To choose the specific data you wish to update, use
field filter form of User Select to select the
first data of the result.

Hint:
You can narrow your search by filtering the result
using "Select" then update an existing data entry.

---------------------------------------------------------------------

2.7 Field Insert

Field Insert allows the user to insert new data in the
current table in the Setting. Make sure that the new
data satisfies the current table field requirements.
e.g. If the field is NOT NULL then a value is required
for that field otherwise an error will be prompted to
the user.

e.g.
Table Name: usr

lst_nm frst_nm othr_nm usrnm psswrd
-----------------------------------
Smith  John    Peter   john  john

After entering the data, click Ok to submit it.

Alternatively, you can use SPRIM which is a PRIM simulator
which can create and execute a script to insert multiple
values rather than inserting values one by one.

---------------------------------------------------------------------

2.8 Field Delete

Field Delete allows the user to delete existing data in the
current table in the Setting.

To choose the specific data you wish to delete, use
field filter form of User Select to select the
first data of the result.

Hint:
You can narrow your search by filtering the result
using "Select" then delete an existing data entry.

---------------------------------------------------------------------

2.9 Tool Graph

Graph is a feature that allows the user to see the
numerical representation of data in visual form.

e.g.
Table: Height

id  name    height_mm
---------------------
1   Anna    1600
2   Barbara 1650
3   Chris   1750
4   David   1900
5   Elisa   1700
6   Frank   1800

It is possible to visually observe the data discrepancies
by the range of record id shown above. This can be done
by selecting the "height_mm" field against the id field
in the Graph form.

---------------------------------------------------------------------

2.10 System Logout

Once you click Ok to logout, the session will be terminated.
So you will need to re-login if you wish to use PRIM again.

---------------------------------------------------------------------

2.11 Table Create

There are two types of tables you can create with PRIM.
These are independent and dependent tables. Independent
tables are stand-alone tables which does not require
values of another table. A dependent table requires
values from another table. The need for dependent tables
is to link up related tables together to associate
connected data.

e.g.
****************************************************
Independent Table: fruitshop
id ... name
-----------
1  ... fruits_r_us
2  ... fruit_mart

Table Name:  fruitshop
Table Type:  Independent
Field Total: 1

         Field Name  Field Type  Field Unique  Field Null
Field 1: name        varchar     yes           no
****************************************************
Independent Table: fruitname
id ... name
-----------
1  ... apple
2  ... orange
3  ... banana

Table Name:  fruitname
Table Type:  Independent
Field Total: 1

         Field Name  Field Type  Field Unique  Field Null
Field 1: name        varchar     yes           no
****************************************************
Dependent Table: fruitshop_fruitname
id ... fruitshop_id  fruitname_id  supply_unit   price_cent
-----------------------------------------------------------
1  ... 1             1             100           10
2  ... 1             2             50            50
3  ... 1             3             25            20
4  ... 2             1             50            20
5  ... 2             2             100           30
6  ... 2             3             75            10

Table Name:  fruitshop_fruitname
Table Type:  Dependent
Field Total: 4

         Field Name   Field Type  Field Reference Field Unique  Field Null
Field 1: fruitshop_id int         fruitshop       no            no
Field 2: fruitname_id int         fruitname       no            no
Field 3: supply_unit  int                         no            no
Field 4: price_cent   int                         no            no
****************************************************

When inserting new values into a dependent table, see
how the dependent table, fruitshop_fruitname, requires
the id of two independent tables, fruitshop and fruitname?
Those referenced ids must exist in the referenced independent
tables in order to make the data link.

Alternatively, you can use SPRIM which is a PRIM simulator
which can create and execute a script to create multiple
tables rather than creating them one by one.

---------------------------------------------------------------------

2.12 Table Drop

In order to drop a table, you will need to select one of
the tables you wish to drop from the table list in the
Table Drop form.

e.g.
Assuming you have created a table called fruitshop_fruitname.
Select the table then click Ok to drop the table.

Table Name: fruitshop_fruitname

All the data in the table will be lost after the table has
been dropped.

---------------------------------------------------------------------

2.13 Table Grant

To grant user the permissions to access the table that you
have created, you will have to:

1. Select the table that you wish to grant permission(s) to a
user from the Table Grant form.
2. Choose the user that you wish to grant the table permission(s)
to.
3. Decide the user permissions you wish to grant to the specified
table and user, then click Ok to submit the completed form.

e.g.
Assuming you have created a new user with the username "john"
and you have created a new table called fruitshop_fruitname.
1. Table Name: fruitshop_fruitname
2. User:       john
3. Permission:
   Select:     yes
   Insert:     no
   Update:     no
   Delete:     no

After submitting the above form, you will be able to grant
"john" with the "Select" permission to view the data in
the "fruitshop_fruitname" table.

======================================================================

3. Features

======================================================================

3.1 Multilingual

At the moment, PRIM has two language options to choose from:
English
Chinese (Big 5)

The language options can be chosen at the login page.

(Apache Webserver - Standalone)
http://localhost/

---------------------------------------------------------------------

3.2 Built-in Database Features

All records created by PRIM will have a unique id number to
identify itself from other data entries.
i.e. Field Name: id

All records created by PRIM will have the timestamp of the
insertion and updating of the data, with the exceptions of
the data created by the PRIM initialisation script "script.sql".
i.e. Field Names: insrt_dttm, updt_dttm

All records created by PRIM will have the username of the user
that has made last change of the data, with the exceptions of
the data created by the PRIM initialisation script "script.sql".
i.e. Field Name: lst_chnge_usr

---------------------------------------------------------------------

3.3 Data Types

At the moment, PRIM offers two data types to store field values
in the table:
Integer              (e.g. 10, -1, 0)
String of Characters (e.g. hello, abc_001, John Smith)

These are popular data types used for record management.

---------------------------------------------------------------------

3.4  Table and Field Specifics

- Table Name must be in lower case alphabetical characters.
They can be separated by an underscore "_".

- Field Name must be in lower case alphabetical characters.
They can be separated by an underscore "_".
- Field Type must be either INT (Integer) or VARCHAR (String).
- Field Reference can be left blank or other tables that
you have SELECT user permission on.
- Field Unique will group the fields of the table you wish
the data set to be uniquely identified.
- Field Null indicates whether or not the field can have
an empty value or not.

---------------------------------------------------------------------

3.5  SPRIM (PRIM Simulator)

The purpose of SPRIM is to create tables and fill them
in with data in one go. That is, without having to go
through the PRIM form to create them one by one manually.

You can benefit from SPRIM by using it to create scripts
and store them in a file. This is so that you can recreate
the data you want whenever you need them, say for testing
purposes or for easy access of data regardless of the
differences of other systems.

You can also use SPRIM to port data from another database
into the PRIM system provided that the data types
and table structures are the same.


To go to the SPRIM login page:

(Apache Webserver - Standalone)
http://localhost/simlogin.php

e.g.
You can create a script from scratch by first selecting
"Create" and a new table name in the first SPRIM form.
Then add each fields you wish to include in the table
and submit it. Since you might like to execute the script
in the future. You can create the script then copy and
paste it into a file. This also applies to "Insert" as well.

<tableelement action="create" name="shop">
<fieldelement name="name" value="" type="varchar" null="no" unique="" reference="">
</fieldelement>
<fieldelement name="type" value="" type="varchar" null="no" unique="" reference="">
</fieldelement>
</tableelement>

Do the same for "Insert" but this time give the table name
that you have just created. In the next form, simply fill in the
field name and value you wish to insert for that field. For
"Insert" to work in the SPRIM form, all the fields of
the table must be specified. This includes "id", "insrt_dttm",
etc.

<tableelement action="insert" name="shop">
<fieldelement name="id" value="" type="int" null="no" unique="" reference="">
</fieldelement>
<fieldelement name="insrt_dttm" value="" type="int" null="no" unique="" reference="">
</fieldelement>
<fieldelement name="updt_dttm" value="" type="int" null="no" unique="" reference="">
</fieldelement>
<fieldelement name="lst_chnge_usr" value="" type="int" null="no" unique="" reference="">
</fieldelement>
<fieldelement name="name" value="fruits_r_us" type="int" null="no" unique="" reference="">
</fieldelement>
<fieldelement name="type" value="fruit_barn" type="int" null="no" unique="" reference="">
</fieldelement>
</tableelement>

Hint: There is an XML script called "sample.xml" already
generated by SPRIM to create the tables called "fruit", "shop"
and "shop_fruit_stock". The script also insert sample data values
to those tables.

To copy and paste the script from a file, say "sample.xml",
to the SPRIM form, you can access the Input field form by selecting
"Create" then a dummy table name which does not yet exist in
the PRIM system. Then you will be able to see the Input field
in the next form where you can paste the script and submit it.

======================================================================

4. Troubleshooting

======================================================================

4.1 Login

Problem 1:
Cannot log in.

Possible Cause 1a:
Wrong login username and or password.

Solution 1a:
Make sure that you have the right login by checking if the
Caps Lock is on or off.

Possible Cause 1b:
Database Server has not started and or PRIM
was not initialised with the script "script.sql".

Solution 1b:
Start the Database Server.
Execute the "script.sql" ONLY if it has not yet been initialised,
otherwise you will wipe out all records generated by PRIM.

Possible Cause 1c:
Wrong login username and or password to the Database Server.

Solution 1c:
Go to file(s) of the PRIM system that deals with the login
to the database server.

======================================================================

5. Package

======================================================================

5.1 File List

action.inc
action.php
bargraph.inc
common.inc
mysqltwo.inc
create.inc
createthree.inc
createtwo.inc
db.inc
delete.inc
deletetwo.inc
drop.inc
droptwo.inc
english.inc
env.inc
graph.inc
graphtwo.inc
index.html
insert.inc
inserttwo.inc
lang.inc
login.inc
login.php
main.inc
main.php
menu.inc
menu.php
mysql.inc
reportmake.inc
reportmaketwo.inc
reportremove.inc
reportremovetwo.inc
reportshow.inc
reportshowtwo.inc
script.sql
select.inc
selectparser.inc
session.inc
setting.inc
settingtwo.inc
update.inc
updatetwo.inc
xmlparser.inc
grant.inc
granttwo.inc
logout.inc
simlogin.php
simlogin.inc
simmain.php
simmain.inc
primac.jpg
simsession.inc
simmenu.inc
simcommon.inc
simenv.inc
simlang.inc
simenglish.inc
simxmlparser.inc
simaction.php
simaction.inc
simmenutwo.inc
simmenu.php
simmenuthree.inc
simtable.inc
sprim.dtd
simfield.inc
mysqlfinal.inc
simtablecreate.inc
simmysql.inc
simdb.inc
simtableinsert.inc
menufield.inc
chinesebigfive.inc
sample.xml
documentation.txt

---------------------------------------------------------------------
