**************************************************************************************************************
Readme for Online Database cgi script

Copyright Mingyi Liu, 2000
This c++ cgi script is primarily used as either an addressbook or guestbook, However,
it's very easy to customize it to be a guestbook, customer record, sales record, 
or other personal online databases. Just be sure to read readme file and use IniFileMaker
software that comes with the package to customize the configuration file (.ini file).

Requirement: It is compatible with Win32 platforms, Win95/98/NT, but it will not work
on UNIX or LINUX (due to my busy schedule, I cannot write code to support those UNIX 
platforms any time soon). For this program to run, you also need to have or have access to
a webserver running on the win32 platforms.  

NOTE: You will need to put .exe, .ini and other files into the cgi-bin directory of 
  your webserver.  You can choose that directory during the installation of the program. Please
  follow the step-by-step instructions below to set up the program!

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,
		   2000 line on the title of your database 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.
***********************************************************************************************
A few important points before you start the setup:

1. It is probably a good idea to read this readme file thoroughly before you start changing
  settings for the program.
2. Whether you use password or not, you better add "password" as your last entry item, that
  is because if in the future, you want to use password to protect your database, you would
  have to convert the database to add this item.  It is usually easier and less error-prone
  to use password protection when you already have a password item in the database. Also 
  please remember:
  password MUST be the LAST item because it's hardcoded in the program.  At present time,
  a legitimate password can be any printable string that is shorter than 10 characters.
3. Be sure you agree to the license agreement (or rather, disclaimer) before you install
  my program.
4. Please try to back up the previous database file first before you try running the new 
  version of the program in case the program didn't function the way it's supposed to do.
  If you find any bug in this program (or have any suggestions, you may e-mail me at 
  mingyiliu@yahoo.com.  Reply is not garanteed, but I'll try my best to put out bug fixes). 
  New versions will be put out on download sites 
  (http://members.xoom.com/mingyiliu/FLDB/OnlineDB.exe should have the latest version. I will
  also put the program on shareware.com, http://www.zdnet.com/downloads/, 
  http://www.simtel.net/simtel.net/, http://www.windows95.com/ etc.

File list: FLDB.exe, FLDB.html, FLDB.ini, FLDB.txt, Readme.txt, IniFileMaker.exe, DBAdmin.html, 
	OldbHelp.html, Source.txt, conversion.exe.
***********************************************************************************************
Step by step setup instructions:
1. If you downloaded the self-extracting zip file or plain zip file (i.e., OnlineDB.exe or 
  Addressbook.zip), extract the compressed file to a temporary directory (e.g., C:\temp).
2. Launch the setup.exe program under that temporary directory and choose your webserver's 
  cgi-bin directory as the destination directory you install the program to (i.e., in one setup
  screen, the setup program asks you about the destination folder, you should browse to find
  (or type in) the path of your webserver's cgi-bin directory and make that directory the 
  destination folder).
3. Go to the the destination folder assigned by you during setup, you should find a program 
  named IniFileMaker.exe and a .ini file named FLDB.ini.  Rename the .ini file and .exe file to 
  whatever you want to name your database as (i.e., guestbook.exe and guestbook.ini. The only 
  rule here is that the .exe and .ini file should have the same name).  Launch the IniFileMaker.exe
  program and browse to find the .ini file you just renamed, choose it and say OK.
4. Now IniFileMaker.exe opens up a window that has several tabs for you to set options with.
  If you decide to use IniFileMaker.exe to configure your .ini file (I call it local 
  administration), you should go through every tab carefully.  Read the help at lower right corner on 
  the tab if you find some option hard to understand.  If you still cannot understand what to
  input in that option, try find it in detailed instructions section in this readme file.  You
  can also leave the sample .ini file you just renamed as is, and let the program run once and
  see what happens, then configure option by option to check it out.  You do, though, need to
  at least modify the following option: "DB program URL" on "File Options" tab.  In this option,
  you should put in the path of the .exe program you just renamed in step 3.  Let's assume that
  your webserver's cgi-bin directory's URL is: http://mysite.com/cgi-bin and you just renamed
  the .exe program to addressbook.exe, then input http://mysite.com/cgi-bin/addressbook.exe in
  this option.  Without this option set correctly, the html file generated in step 5 will not
  be able to find the database program on the webserver to let it perform requested operations.
  If you decide to use DBAdmin.html to configure the DB settings in the .ini file (I call it
  remote administration), you should at least set these settings using IniFileMaker.exe before
  you use remote administration:
  a. Set "DB program URL" on "File Options tab" as described above.
  b. Set "DB Administration Help Page URL" on "File Options" tab as follows:
    First copy the OldbHelp.html to the path you want, i.e., if you wish to be able to read the
    help page at http://mysite.com/myname/OldbHelp.html, then you should copy the OldbHelp.html
    to that path on mysite.com.  Then you should fill in "http://mysite.com/myname/OldbHelp.html"
    in "DB Administration Help Page URL" on "File Options" tab.  You should not rename this html
    file! In addition, copy the readme.txt file into the same directory as OldbHelp.html.
  c. Set "remote administration password" on "Password Options" tab to whatever password you 
    like it to be.
  d. Check "enable remote administration" checkbox on "Password Options" tab.
  e. Use an editor (e.g., notepad) and edit the html code on DBAdmin.html.  Specifically, you
    should change "<form action="http://MySever.com/cgi-bin/test.exe" method="POST" name="">" 
    in the first form to "<form action="http://MySever.com/cgi-bin/Adrsbk.exe" method="POST" 
    name="">".  Then copy the DBAdmin.html to the path you want on your webserver, and type 
    that path in your web browser, enter the password you set in c. and now you're ready to 
    use remote administration.  The instructions below for IniFileMaker.exe usage also applies
    to remote administration, even though "tab" in IniFileMaker becomes sections on the html 
    page for remote administration.
5. In IniFileMaker.exe, go to "file options" tab.  At the top of this tab there is a choice -
  "let the program make an html file for me".  Check it.  This way, after program quits, you 
  will be able to find a file named IniFileMaker.html under C:\windows.  That will be the html
  file for your user to access your database.  You can rename it and move it to wherever you 
  want on your webserver.
6. On HTML display options tab, under "items width in characters..." there's an box that 
  contains multiple key value pairs (i.e. name=20).  You must set a length for every item
  except for password (you can either set or not set the length for the password).
7. Press "OK" on IniFileMaker window and quit the program.  Rename IniFileMaker.html and move
  it to where you want.
8. Now the program is set up and you'll be able to run it!!! (well, you need to make sure that
  the webmaster of your webserver granted you permission to run a cgi program first. If your 
  webmaster let you access the cgi-bin directory of the webserver, I guess you have permission
  already).  You can then launch the web browser of your choice and access the renamed 
  IniFileMaker.html to see how program works.

After the program starts to work, you can fine-tune the program to fit the specific need of your
databases using either local administration or remote administration.  Just remember, FTP and
sending password over the net are not secure, only SSL is supported.  This program does not 
support SSL (yet).
***********************************************************************************************
A few things that the program can do for you (that you may not be aware of yet):
1. IniFileMaker.exe will create an ini file under the same name at your C:\windows directory.
  Do not delete it.
2. You can always derive as many online databases as you want from this program. All
  you need to do is just copy the program into your webserver's cgi-bin directory,
  rename it to the name you want.  Also copy the .ini file and .html file there, change
  names and make changes to settings if you want.  Just make sure the .exe, .ini file
  are using the same name (except for suffix part ".exe or .ini"). Do not worry about 
  make the database file itself.  The program will make it for you (and it will do the
  job right because the first line of the database is very important for internal usage).
  For this reason, I deliberately left out the .txt in this version so that there is no
  need to modify the database file yourself, and there's no chance of any error.
3. When you derive a new database from the program, just copy and rename files as described
  above.  Do not run installation program again. That will not give you a new database.
  When you uninstall the program, you will need to clean up these files yourself by
  manually deleting them.
4. You don't have to make an HTML file manually for each database you created. If you want,
  you can simply choose "let the program make an HTML file for me" in the "File Options" tab
  of the IniFileMaker program. After you pressed "OK" and quit that program, IniFileMaker.exe
  will make a file named "IniFileMaker.html" based on your .ini file configuration settings 
  at c:\Windows.  You can then move the file to your cgi-bin directory and rename it to suit
  your new database (this is a new feature of version 4.02).
5. Because the database file is a fixed-length text file, you can manually modify it.
  However, it is very important that you make sure your modification does not change
  the length of the entry you are modifying.  Or else it will generate an error when
  program starts, and program will quit afterwards without performing any operations.
6. I apologize for the buggy 4.xx version.  I did not have enough time to thoroughly test
  it before submitting. But now, with version 4.2, functions are improved and mostly all
  bugs were removed.  Please report to me if you find any other bugs. Thanks.
7. Scalability & security of the program: In theory, this program can handle infinite number 
  of entries if the system has enough memory. In reality the program would easily handle over
  100,000 entries without taking more memory than several Mb.  However, the lack of guarding 
  against server/connection/software failure and encrypting data before sending over internet
  makes this program more suitable for personal/small business online databases that are not 
  ridiculously large or handling too much traffic.
***********************************************************************************************
OnlineDB 4.12 has the following features:
***Automatically produces a fully customizable html interface that give you great power over 
  how your database entries are displayed to your users.  The html output of the program is
  highly customizable as well.
  
***A fully searchable and sortable database that does not need external database engines.

***Various password protection modes of the database supported.  You can even let user chooses
  his/her own password! 

***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).

***Conversion module included that can convert your previous databases to format recognized by
  this program. (for details of the usage of conversion.exe see below).

***Smooth upgrade of previous versions.

***IniFileMaker.exe file for easy manipulation of .ini configuration file and DBAdmin.html for
   remote administration of the database.

***Conversion of entry items, deletion or addition of them even after the database was generated.

***Primitive concurrency handling, preventing database corruption.

***Installation and uninstallation support.

***Produces a sorted .csv file for analyzing your database in other softwares such as MS Excel.

***Support automatic time labeling of entry or user-entered time stamp.

***Various other options such as time format, color of html table display, sort ascending or
  descending, etc.

***Best of all, it's free!

***********************************************************************************************
Files copied to destination directory after installation:

**FLDB.ini : This is where the customizable data is stored.  It must be put into your
  webserver's cgi-bin directory

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

**FLDB.txt: A sample databse file, you can delete it because the program will create a
  new database file for you if no existing database is found.

**FLDB.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 it needs to be the same name as the .ini file.
  
**IniFileMaker.exe: This is the program that customizes .ini file.  It is recommended that you
  always use this program to access .ini file to prevent errors.

**FLDB.html: This is the interface b/w users and the program.  You can let the IniFileMaker.exe
  make one for you (which will save you a lot of html writing) instead of modifying this one.

**DBAdmin.html: This is the access page for remote administration of your database.  You should
  not let anybody other than your database administrator (e.g., yourself) access this page.
  
**DBAdmin.html: This is the page to help you configure the .ini file (i.e.,FLDB.ini or whatever
  name you renamed FLDB.ini to) of your database.  
  
**readme.txt: The file you're reading.

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

***********************************************************************************************
Detailed Instructions for customizing options (in addition to the help in IniFileMaker.exe or 
OldbHelp.html):

On "File Options" tab: 
  *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)

On "Password Options" tab:
  *You must choose "use 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.
  *NOTE: 1. 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 also designate a 
  masterpassword which allows you to change the entry no matter what password 
  the user had specified.  In the case that you specified "use own password" it doesn't matter
  which password you put at the "change entry password=..." line, because it will not be used.  
  However, you need to at least input something (say, "1" or "yes") to tell the DB program that
  this operation should be password protected.  If you do not specify to use own password, the
  password you input at "change entry..." will be used to protect "change entry" operation, 
  while the password you input at "add entry..." will be used to protect "add entry" 
  respectively.

On "DB Entry Info" tab:
  *entry item name line specifies the names of the items of your entry.
  *You must use "e-mail" or "email", "web site" or "homepage" (all case-insensitive) in order
  for the program to produce an automatic link to be attached to these items.  You should always
  make "password" your last item and do not change its name!  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.

On "Output File Options" tab:
  *File path indicates where your old database is (your old database has to 
  be text files with values separated by the separator character you indicate. 
  If you indicate ',' as separator character, that means your old database is 
  "comma separated value" file (.csv files). 
  Destination file is the same as designated in File Options Configuration section, 
  so you don't need to worry about that. 
  *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 ','.

On "Html Display Options" tab:
  *database name 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.
  *"items to be displayed..." 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" displays name first, time stamp be displayed the second, etc.
  *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.
  *"item width in characters..." specifies the length of each item to be displayed in 
  the html file.  Each line (seperate by a return or a non-printable character) indicates
  the length of one item.  You may test it at will because these numbers should never result in crash 
  of the program.  They may make the html layout ugly though, if the numbers are not 
  designed well.  '(' 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.exe 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.  First you need 
to make a copy of your ini file and rename it as addressbook.ini and put it under 
c:\windows.  Then double click 
conversion.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 conversion.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 conversion.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).

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.
***********************************************************************************************
