********************************************************************************
Readme for Addressbook cgi script

Copyright Mingyi Liu, 1999
This c++ cgi script is primarily used as either an addressbook or guestbook, even
though it can be used for many other databases.  It is compatible with Win32 
platforms, Win95/98/NT (other platforms not tested.  There might be some functions
that are not compatible with other platforms, but I didn't check carefully.  You
may check it out for yourself).  It is a freeware, but if you like it, you're 
welcome to send the author an e-mail or postcard to show appreciation.

********************************************************************************
Bug fix in Addressbook 3.32 (Which now have Portuguese and Dutch (in progress) versions 
at http://dhph.biochem.uiowa.edu/pricelab/address.html):
1. A problem when running addressbook under IIS (internet information server) on NT
is fixed.
2. Small changes to facilitate language translation added.
3. A boundary checking with html display added.

New feature in Addressbook 3.3:
1.Choice of colors in table display added.
2.New sorting feature in table display added.
3.Minor changes to exception handling.

Detail for usage of color choice in table display:
1. In "entry item display..." line in initiation file, say, it's
entry item display sequence=contact name,time stamp,-category,*subject,0,0,0,0,0
that means the color of fonts in category will be blue, while the font for subject
line will be red, the font for contact name and time stamp will be black by default.
2. You don't have to do anything to get the new sorting feature--it's automatically
added.
********************************************************************************
Any updates to the Addressbook program will be posted at 
http://dhph.biochem.uiowa.edu/pricelab/address.html

Addressbook 3.1 has the following features:
1. A fully customizable html interface that includes form input format, html 
table display, specification of specific items on html file (such as length 
of each form field, name of the addressbook, which form fields are required, 
which fields will be display in the table format, etc).  You can also specify 
for the program to display multiple-line textarea and menus instead of just 
single-line text box.  Because of extensive choices are given in initiation file, 
the program can easily be transformed into a guestbook or most other databases.  
What's more, you would be able to rename the program and rename the ini file so 
that you have several programs running for different purposes (e.g., one addressbook, 
one guestbook, etc.)  The html layout of the file is very well-designed.  You almost 
do not need to go back at all even if you continue to make queries/changes to 
entries in the database.  

2. A customizable database.  Because of txt format is chosen for database, you would
 be able to manually change the database if you want.  But be careful when you do this!

3. Fully searchable and sortable modes supported.  You can specify which fields other 
people may search and which fields will be used for sorting the search results. It 
accepts and searches for up to 10 words and support the use of quote mark as a way 
to combine two words into one search word.  If a user tries to add an entry that has 
the same name as an existing entry, a number tag will be added to the new entry 
automatically and the user will be alerted of the existing entry.

4. Various password modes supported: you can use separate passwords for add or change 
entries, you can specify case-sensitivity, you can specify that the user will be able 
to define a password when they first enter their entries so that they can later modify 
it themselves using the password, and you can specify a masterpassword that can be 
used for changing any entry, whatever the password the user had specified.

5. Support for both POST and GET methods so that you can directly link to the program 
output without going through a form input (see below).

6. Conversion module included.  The conversion.exe file included in the zip file takes 
the path specified in source line in [conversion] section of addressbook.ini file and 
covert the source file to format recogized by addressbook.exe and output to the 
destination file. 

********************************************************************************
Before you proceed, please read the following copyright notice and disclaimer:

By using this script, you agree to the following copyright notice and disclaimer:

Copyright notice:  You may copy or distribute freely the original program 
                   written by Mingyi Liu, provided that you do not market 
		   the program.  You also agree to keep the \\&copy Mingyi Liu,
		   1998 line on the title of your addressbook html file.

Disclaimer:  This script is provided on an "as-is" basis.  In no case the author 
             should be held responsible for any kind of damage to any computer
             resulted from the usage of the following script by you.

If you follow the readme file closely, there should be no problem resulted from 
using the addressbook.  For any technical questions, you may contact the author 
at mliu@blue.weeg.uiowa.edu.  However, reply is not guranteed.

********************************************************************************
Component included in the zip file:

**Adrs3_1.ini : This is where the customizable data is stored.  It must be put 
the same directory as your Adrs3_1.exe file (you can rename the file, but the 
file name must be less or equal to 8 letters, and the ini and exe file names 
must be the same).  

**source.txt: an example csv file that serves as an existing database file for 
conversion by conversion.exe

**Adrs3_1.txt: a sample databse file

**Adrs3_1.exe: this is the main program and it should be put under your web 
server's cgi script working directory (usually cgi-bin).  You may want to 
rename it to whatever you want, but please follow the same restrictions as 
specified above for renaming Adrs3_1.ini.

**Adrs3_1.html: this is the interface b/w users and the program.  You may 
modify it to suit your style.  However, the form portion should not be changed 
(e.g. act="add", etc. should not be changed.  But the entry items, e.g., project, 
etc., can be changed, provided that they are the same as the names you specified 
in the ini file).

**readme.txt: the file you're reading.

**convert.exe: used for converting existing database files to format used by my program.

if you want to see the addressbook in action, you may go to 
http://dhph.biochem.uiowa.edu/pricelab/address.html and feel free the change the 
entries there.  The password is guest for the addressbook.

********************************************************************************
Instruction to use:

1. Put the exe and ini file under your web server's cgi script directory (usually 
cgi-bin) or let your web master do that.
2. Modify the addressbook.ini when necessary.  The explanation for each item is 
provided below:
NOTE: ONLY THE DATA PORTION (string after '=' in ini file, e.g., "myaddressbook.
html" is the data portion of "html path=myaddressbook.html") MAY BE CHANGED. 
DO NOT ADD OR DELETE ANY LINES OR SECTIONS IN INI FILE!!

[***] denotes a section, any line below is an empty line or a line that contains data.

[file] section stored the file info for your addressbook.  
html path is the URL of your addressbook html file (either full or relative URL can be used)
exe file is the URL of the addressbook.exe file (full URL should be used)
database is the database file for your addressbook (absolute path should be used)

[contact] section denoted the e-mail address of the web master.

[password] section sets all password choices.  You must choose "user password=1" even
if you only intend to specify password for change entry but not search, or else no 
password checking would be performed whatsoever.  If a password is not specified for 
a specific operation, that operation will not be protected, i.e., if you want to 
restrict people that can add, change and delete entry, but do not want to block 
anybody from retrieving info from the addressbook, you should use the 
following [password] section:
[password]
use password=1
search entry password=
change entry password=guest
add entry password=guest
case sensitivity=1
use own password=1
masterpassword=guest

NOTE: case sensitivity sets the sensitivity for all passwords!  Use own password 
means the user can specify his/her own password when he/she added the entry, and 
that person would later be able to modify the entry without your assistance.  In 
that case, you probably would like to designate a masterpassword which allows you 
to change the entry no matter what password the user had specified.  That's the 
function of "masterpassword=..."

[database entry info] section contains crucial information (marked by *) and 
could result in crash of the application, so please strictly follow instruction 
when changing parameters:

*entry item (field) number lines denotes how many items you would like to have 
in any of your database entries.  For example, name is an item, e-mail address 
is another item of the entry.  NOTE: Name, time stamp and password items are 
mandatory and should always be included.  In addtion, Name should always be the 
first item in an entry, time stamp the second to last and password the last 
item.  In short, this number should be within range 3-19 (3<=Entry Item Number<=19)

*entry item DB storage length line denotes each item's length in database file.  
Some items might be longer.  You may change it to whatever you like for each item.

entry item name line specifies the name of the items of your entry.  You do not 
need to input spaces b/w your items to justify them.  They will be automatically 
justified when displayed in html file.  Extra spaces (which means space at 
either end or consecutive spaces) in item names will be deleted.  You must use 
e-mail or email, web site or homepage (all case-insensitive) in order for a 
automatic link to be attached to them so that the user can click on the link and 
be brought to the specified web site.  The names for time stamp and password 
should not be changed.  You can use '*' to specify that this entry field is 
required for your database.  If the user did not enter the info for one of 
those fields, the form would ask the user to fill in before proceed.

maximum waste entries stored in DB line specifies how many wasted entries are 
tolerable in the database file (this is because every time an entry is deleted, 
it is not really cut off from the database file, but rather, it is marked by a 
specific character).  Only when more than the specified number of entries was 
deleted and the database file became unecessarily big does the program clean them up.

[time stamp] this section specifies the time stamp display mode.  //1 is 
m/d/y(4 digits), 2 is abbreviated day of week name, m/d/y(2 digits), 
3 is m/d/y(4 digits), h:m, 4 is m/d/y(2 digits), h:m am/pm (m is month, 
d is day and y is year).
obsolete line means how many days can this entry stay in the database.  If you 
specify 0, the entry will never be outdated.  If you specify, say, 14 days, 
then any entry older than 2 weeks will be deleted when the program starts 
(however, for efficiency reason, the program is implemented such that if you 
change entry sequence, it may not delete all outdated entries).

[converion] section is used only when a conversion of file format is performed.  
source line indicates the full absolute path of the source file (a comma separated 
file (csv file produced by excel or exported by some program like outlook).  
Destination file is the same as database section, so it's omitted.

*output format line indicates the sequence of the items to be converted into new 
file format, if they're to be converted at all.  For example, 1,6,4,*,3,*,*,2,*,* 
means it's a 10-entry output (this number should be the same as Entry item number 
specified above!), first item in the source file will be the first iten in the 
destination file, the 6th item in source file be the second in destination, * indicates 
an empty output there.  You may have noticed that you can omit an entry item by simply 
not specify it in this line (like #5 item is omitted in the above sample).  You can 
also designate an item to be the time stamp or password, if the source file contains 
such an item.  If souce file does not contain an item (for example, time stamp or 
password) but you wish to add it to the destination file, use '*' followed by a number 
that indicates where the item should be placed.  Also be sure to transform time stamp 
and password and make them second last or last item in the destination file.

separation char line denotes what character was used to separate items in the source 
file.  Usually it is the comma character ','.

[search options] section
maximum found entries returned in search line specifies when multiple entries are found 
during a search, up to how many entries will be displayed.

sort option line specifies which fields could be used for sorting search results, the 
first field will be default when search form is displayed.  The name in this section 
should be exactly the same as entry item name line in [database entry info] section!

[entry html display options] specifies the options for html display.
database type means addressbook, guestbook, etc.  It is used at the bottom of 
addressbook html when the back link [go to ...(addressbook or guestbook)] is displayed.

html title specifies the first line of your html file body.

entry item html display length line specifies the length of item to be displayed in 
the html file.  There are contraints on the maximum value of these numbers (see below 
html display line length).  You may check out the sample html file and decide for 
yourself.  You may test it at will because these numbers will never result in crash 
of the program.  They may make the html layout ugly though, if the numbers are not 
designed well.

entry item display sequence line is more complicated.  This line denotes that when an 
entry is displayed in table format (used only when multiple entries are displayed) in 
html file, in what sequence the items will be displayed.  For example, contact name,time 
stamp,category,subject,0,0,0,0,0 name should be displayed first (this is mandatory!!), 
time stamp be displayed the second while the time stamp be displayed the third, etc.  
The important thing about this is: Check to make sure you wrote down the same number 
of fields as specified above.  0 should be used to identify the item you do not want 
to display.  Password item should not be displayed, so be sure to leave it out (however, 
if so intended, password can be displayed.  So be very careful!). 

entry table display mode line specifies the layout of the table display.  You may check 
it out by generating a table display you like using a html editor.  Then define the 
numbers following these rules: The first number specifies the number of rows it spans 
(this is the name item), the second one specify the second item to be displayed (it 
may not be the second item in the entry!  The sequence all depends on how you specified 
in entry item display sequence line).  When you want to change rows in the table, put a 
0 there.  It's very simple if you read the sample html file source code and compare with 
the input here in this line.

the lines below table display mode should have the same number as specified in entry 
item number.  These lines indicates how long these fields are when they're displayed 
in html file. '(' and ')' are used to specify an item is to be displayed in menu mode.  
In such case, the length of the field should be followed by a ',' and then immediately 
followed by '('.  Menu items are separated by ','.  As a general rule, DO NOT CHANGE 
SPACING B/W THE ITEMS.  Use the default spacing specified in sample ini file (i.e., 
do not add extra space when there wasn't a white space character in the sample file).  
'"' can be used to specify the use of multiple line textarea form inputs.  In this 
case, the " " will include 2 numbers, the first indicating how many rows this area has, 
the second indicating the columns.

********************************************************************************
Conversion file usage instruction:

Convert.exe is a standalone application that can be run independently under windows 
system, unlike addressbook.exe which must be accessed thru web server.  Double click 
convert.exe file and it will take the path specified in source line in [conversion] 
section and covert it to format recogized by addressbook.exe and output to the 
destination file.  NOTE: THE OUTPUT FORMAT IS ALSO AFFECTED BY DB storage length 
line, so if you change the length later, you need to re-convert the old file again.
ALSO NOTE: If you do not have a database file yet, you do not have to try create an 
empty one yourself.  Just access addressbook through server and it will create an 
empty file for you when specified database file is not found (the first line of 
empty file contains a number and a whole line with the same length as other entries.  
This number denotes the waste entry number in your database.  Do not change it). 
ALSO NOTE: Running converion.exe will rewrite the destination file (the file specified 
on database line in [file] section), so be sure to backup the old one if you want to 
try convert.exe out!
No sorting of the entries in the source file will be performed.

********************************************************************************
Some useful info:

The search function take up to 10 words ("word1 word2" is counted as one word and will 
be searched as a whole) and search the database.  The sequence of words do not matter, 
and only entries that contain all the words (case-insensitive) will be returned.  
If more than 10 words are entered, the words after 10th word will be ignored in search.

When a user tries to add a name that is exactly the same as an existing entry, a number 
tag will be added to the end of new entry.  This tag must be entered when you need to 
extract this profile for change or delete.

The get profile, add, delete, and change profile require an exact name match to get 
profile (name tag should be included too).

When instructions are followed carefully, this script should never get crashed by a user.  
However, I encourage you to make a backup of your database file.  Again, I'm not liable 
for any loss of data or damage resulted from using this script.  However, if you 
encoutered a problem even when you're sure that you understood and followed the 
instructions, you can contact me thru e-mail.

Any item longer than specified length will be automatically truncated and an 
indication will show up in browser if user is editing his/her entry.  If it 
happened during converion, an error log will be generated.
********************************************************************************

