ReadMe File for Free "Simple Search Engine" Software ################################################################## # # Free Web Based "Simple Search Engine" Software # # This is an easy-to-install Web based search engine software # designed to search any flat ASCII database files which can be # generated by most popular PC database and spreadsheet software # such as MS Access and MS Excel. Definition of the database fields # and Web page layouts are controlled by Html templates. No CGI # programming knowledge required other than some basic Html # knowledge to develop the necessary search and report templates. # # No technical support will be provided for this FREE software. Please # use it at your own risk. We will only provide support to the paying # customers who has a valid order number attached along with their # technical support request. # # If you need a more powerful database solution, please consider # to order one of our BizDB database packages. # BizDB Demo Web Site - http://www.cnctek.com/bizdb-html/ # ################################################################## # # Free Web Based "Simple Search Engine" Software # URL: http://www.cnctek.com/bizdb-free-search-engine # E-mail: cnctek@cnctek.com # # MINIMUM SERVER REQUIREMENTS: # # Runs on any Unix, Linux or Windows NT Operating System; # Provides full FTP access (or access via a Control Panel); # Supports Perl and cgi-bin; Allows creation of files and # directories by cgi programs. # # COPYRIGHT NOTICE # # This Software is a product of CNC Technology. All rights reserved. # Only the user with our permission can use and modify this software. # Without CNC Technology's permission, no part of this software can be # reproduced ( other than the backup copy ), resold or redistributed to # any other individuals, companies and organizations. # # DISCLAIMER: # # This software is provided on a "As Is" basis. CNC Technology # will not be liable ( nor responsible ) whatsoever for any direct # or indirect damages caused by the use of this Software # ( or Scripts ). # ################################################################## Please read the following paragraphs carefully. This is essential if you want to have a smooth and successful installation. When you read this file, we know that you have successfully decompressed our ZIP file using a 32 bits WinZip (or equivalent) program. ################################################################## TABLE OF CONTENTS: A. Contents in our ZIP file B. System Configuration Parameters C. Webpage / Database Interface Templates D. Defining Html Template Filenames E. Database Format and Definition of Database Fields F. Other Parameters used by Input-Control Templates G. How to Display Database Field Values on the Search Report H. Installation Procedures I. Calling the CGI programs by "GET Method" J. Important notes for Windows NT Server Users K. Notes on Supporting Non-English Character Set L. Notes on Supporting Large Number of Database Records M. More Support Notes If You Have Problems During Installation N. Upgrade to Search Engine Plus to support Complex Search O. Please Help Us to Help You ################################################################## A. Contents in our ZIP file You should have at least the following files for our software: (1) free-search.cgi - CGI script used to Search and Display multiple database records at one time. (2) free-search.html - The sample Search DB records Html template. You will use this template to specify search criteria ( keywords ) for the free-search.cgi program. (3) free-search-summary.html - The sample Display DB Records Html template. You will use this template to define which and how DB fields are to be displayed in the search report. Fields belonging to the same record will be displayed in a group. This will be repeated for each record until all records or a group of x records are displayed. (4) free-search-detail.html - This sample Html template is used to display details of a given record. This, in conjunction with the "free-search-summary.html" template, can be used to construct a simple search engine. (5) ReadMe.txt - It's this document. (6) sampledb.txt - Sample flat ASCII database file. (7) testing.cgi - Execute this test script to see if your cgi-bin directory is working properly. This script will also help you to find out the absolute pathname of your Website's home directory. (see Section M for more details) B. System Configuration Parameters: You will have to modify a number of System Configurations Parameters in the Scripts before you can upload them to your CGI-BIN directory. These parameters are CGI script specific, therefore you should read our following sections or the notes on our scripts very carefully. Parameter Name Where Description (1) $charset free-search.cgi Define the character set to be used by your database software and Html templates. This is required for some foreign languages. Also see section K. (2) $delimitor search-plus.cgi Field delimitor of the database File. Only the following characters are accepted: - "\t" (for tab character) - "\|" (for pipe character) - "," (for comma character) Please make sure no tab (if $delimitor="\t";) or pipe (|) (if $delimitor="\|";) or comma (if $delimitor=",";) characters exist in your database fields. (We have a free software for you to convert your database to make sure this won't happen. See Section E - Data Conversion) (3) $maxfields free-search.cgi Maximum number of DB Fields. (4) $maxdisplay free-search.cgi Maximum number of records to be extracted in each search. (5) $maxdispscreen free-search.cgi Max Records to be displayed per screen. (6) $database_dir free-search.cgi Full pathname of the directory in which your database is stored. If possible, location of your database file should be stored outside the Html directories. (7) $template_dir free-search.cgi Full pathname of directory in which your Html templates are stored. (8) $upload_dir free-search.cgi Full pathname of directory where the image files associated with each database record are stored. (9) $this_cgi_url free-search.cgi Url of the CGI script you are working on (10)$return_url free-search.cgi Return URL link used by OK and error messages. (11)@valid free-search.cgi These are the urls (separated by comma) that are allowed to execute this database system. This prevents any of our programs to be accessed by unauthorized Websites. C. Webpage / Database Interface Templates: You will need to set up a number of Html templates to take search requests and control search repeat layouts. These templates will be the key interface between users and the search engine software. You can use the same CGI script to handle different databases with different field definitions simply through the use of different sets of interface templates. Eplanation could be difficult without referring to the real examples. We have therefore developed a set of sample templates which we suggest that you should display them on a second window on your screen. As you read this document, we recommend that you switch to your template screen and try to understand its concepts and logics. When you develop your Html templates, we strongly recommend that you start from our sample templates, add and modify the database fields as well as comments to meet your own needs. It is important to backup a copy of the original sample templates before you make your modifications. Please use the following statements to display the "Search Selection" template on the screen: http://www.yourdomain.com/your_cgibin/free-search.cgi?free-search.html OR http://www.yourdomain.com/your_directory/free-search.html only if your record search page has an .htm or .html ending. where free-search.html is the Html template filenames. Please also see Section D. *** NOTE *** Your only job is to construct a set of workable and beautifully formatted Web based Html templates to search your flat database file. We strongly recommend that you use a standard text editor ( such as wordpad ) or a text-based html editor ( such as cmed ) to do this job. Object based Webpage generator/editor will sometimes create unexpected errors. When you prepare your templates, please make sure that your top priority is to make the system work. Do not spend too much time on producing beautiful-look pages which you can do it later. Our CGI program is a text editor. Everytime when it is called, it will read your Html template, line by line, and replace the **f??** by its actual value in the database. ******************* Handle your typing with care ********************* ****** UNIX is a case sensitive operating system, so does Perl. ****** **** Applies to all database field names and special control tags **** ******************* Handle your typing with care ********************* ************ (C-1) How to use Html Templates to call CGI programs: In our sample, we use the following form control statements: (1) "Search Database Records" HTML Template (Input-Control Template) Filename = free-search.html This template provides an interface for inputting keywords to the CGI program for searching the database records. If any one of the keywords ( full words or partial-words accepted ) is found on the database record, the record is said to be located. This template will call the "free-search.cgi" program when the user hits the "submit" button.
The output template file for the "free-search.cgi" program to substitute data and to display report on the browser is "free-search-summary.html". (2) "Display Search Summary Report" Layout Definition Template (Output-Control Template) Filename = free-search-summary.html This template defines which database fields are to be displayed, and in what layouts, for the search report. The CGI program will search for any occurrence of **xxx** ( 'xxx' is a database field name or some other reserve words ) in the template and replace it by its actual field value. (Also see section G below. There are certain rules to follow.) (3) "Display Detail Record Report" Layout Definition Template (Output-Control Template) Filename = free-search-detail.html (Also see section G below. There are certain rules to follow.) This is another sample template defining which database fields are to be displayed, and in what layouts, for a specific record found on a database search. (C-2) Defining database location, i.e. database filename The "dbname" statement is used to tell the CGI program which database file has to be processed. Specifying the filename is enough. There is no need to tell the directory pathname of the file. The directory pathname is defined within the CGI scripts. The "dbname" statement has the format of: Example: The dbname filename must be made up of the following characters only: a-z, A-Z, 0-9, space (" "), hyphen ("-"), underscore ("_"), dot (".") (C-3) How to instruct CGI program to execute a function or subroutine: If you read the contents of our HTML Templates, you will observe that we are using the following form statements to instruct the CGI program to execute the appropriate subroutine: Sample template - "free-search.html" The "searchdbdisplay" action code is defined in the program "free-search.cgi". It is used to search the database based on the keywords specified by the user. A search report will then be displayed on the screen according to the layout specified in the "free-search-summary.html" template. D. Defining Html Template Filenames: The "template" statement is used to tell the CGI program which template file has to be processed. You can find it in almost all templates. The CGI program will read in the content of the template, replace certain tags by the actual values determined by the CGI program, and then output the template to the browser. The "template" statement has the format of: Example: In our "free-search.html" template, we use: to tell the CGI program that the report format will be defined by the template "free-search-summary.html". You can also use other names such as "summary.htm" or "summary.tmpl": The template filename must be made up of the following characters only: a-z, A-Z, 0-9, space (" "), hyphen ("-"), underscore ("_"), dot (".") E. Database Format and Definition of Database Fields: All database record fields have a naming convention of "f??" where "f??" can range from "f1" to "f99" or more. The maximum number of database fields accepted by the system is defined by the system configuration parameter $maxfields. Field #1 is reserved for the unique record ID (alphanumeric only). It is recognized by the "free-search.cgi" program as record key. User fields will start from field #2 (i.e. f2) onwards. You may use these generic field names (f??) to relate to any database fields and their contents. For example, you may use f2 to represent Company Name, and f3 for Company Address, etc.. It is important to make sure that you do not use the same name fxx to name other database fields. Our programs will use this name to point to a unique field in your database. For real examples, please refer to our sample Html templates that come with this System. < < < DATA CONVERSION > > > All ASCII files exported from the MS Excel and MS Access software are in csv (ASCII comma separated values) format. Under this format, if a field contains tab, pipe (|) or comma characters, the text content of the whole field will be bracketed by a pair of " character as shown below: Example: ID0001,ABC Trading Ltd,Trading,"We import and export computers, stationery, furnitures, electronics, etc..",info@abc.com,abc-banner.jpg If you use our "Search Engine" software to read this file without any data conversion, it will turn up to contain 10 fields ("f1" to "f10") with "f10" containing the image filename "abc-banner.jpg". This is incorrect as the original record is supposed to contain only 6 fields. To overcome this problem, we have developed a free data conversion utility for you. You can download it from: http://www.cnctek.com/bizdb-addons/free-utilities/unquote-fields.zip using "guest" as both the login userid and password. The "unquote-fields.cgi" program in this utility will convert each of the comma characters found in the field text into the text string " _COMMA_ ". The same applies for the tab character which will be converted into " _TAB_ ", and the pipe (|) character which will be converted into " _PIPE_ ". After this conversion, the " characters which bracket the field string will also be removed. Example of the converted record: ID0001,ABC Trading Ltd,Trading,We import and export computers _COMMA_ stationery, furnitures _COMMA_ electronics _COMMA_ etc..,info@abc.com,abc-banner.jpg When this record is processed by our "Search Engine" software, it will be treated correctly as containing only 6 fields ("f1" to "f6"). On the search reports, the " _COMMA_ ", the " _PIPE_ ", and the " _TAB_ " strings will be displayed as comma, pipe (|) and tab characters. < < < DATABASE FIELD DEFINITIONS > > > Our "Search Engine" will detect the following tags in the "Search Report" template and replace them by the corresponding value of the database fields during report generation. Total fields = 6 **key** = ID0001 --> unique record key (must be the 1st field) **f2** = ABC Trading Ltd --> Company Name **f3** = Trading --> Industry Category **f4** = We import and export .... --> Short Description **f5** = info@abc.com --> e-mail address **f6** = abc-banner.jpg --> user image file to be uploaded manually to your "upload-img" directory by yourself (if specified). F. Other Parameters used by Input-Control Templates Parameters used by the Search Criteria Template: The only input field name you can use in the search form for accepting search keywords are "keywords". The whole database is searched for the specified keywords. The default keyword separator is a space character. If you want to search a number of keyphrases, you may use either "++" (the OR operator) or "&&" (the AND operator) as your boolean operator. Enter 2001/06 to display all entries entered in June 2001. Example: Possible inputs: 1. enter nothing 2. art business computers 3. cnc technology++ (this is a keyphrase search) 4. internet++virtual servers++web hosting 5. internet&&Web database **** Using "Comma" as the keyword separator - a better method **** You can change the keyword separator to "comma" (,) by adding the following form statement in front or after the "keywords" form statement: The possible inputs now become: 1. enter nothing 2. art,business,computers 3. cnc technology (this is a keyphrase search) 4. internet++virtual servers++web hosting 5. internet&&Web database If you are only interested in letting users to search full words, please add the following statement to your search form: In the absence of this statement, both full and partial words in the database file will be searched. With this version of software, you cannot use Complex Search. Only Standard and Advanced version of our software can perform Complex Search ( please see our Demo Site ). Also you cannot sort the search report by a given field name. G. How to Display Database Field Values on the Search Report: For the "Search Report" template, such as "free-search-summary.html" or "free-search-detail.html", the software uses the following method to display the value of a database field name: The CGI program will search for any occurrence of **xxx** in this template and replace it by its actual value. where **xxx** can be one of the following: **matchcnt** - will be replaced by the number of records found **usdate** - will be displayed as the US date, i.e. month/day/year, **europedate** - will be displayed as the European date, i.e. day/month/year, **dbname** - will be displayed as the database name used, **key** - will be displayed as a record key, **f2** - will be replaced by the value of the 2nd field of the database record currently handled, **f3** - will be replaced by the value of the 3rd field of the database record currently handled, **f??** - will be replaced by the value of the ??th field of the database record currently handled. **bgcolor** - See Note 2 below. Any HTML commands between and will be evaluated and repeated for each record found. In other words, if you want to display the value of a number of database fields repeatedly on the same report, you must bracket the name of those fields ( in the form of **f??** ) by a pair of "repeat" and "endrepeat" comment lines as indicated in the example below: We have found **matchcnt** records

Company Name: **f2**
Tel: **f3**
See more detail

Note 1: Your Summary Page and Detail Page templates must not be framed. All Html codes must be totally contained in a single page and must not contain SSI (server side included) codes. Note 2: Under the current design, it is essential to insert the statement between and , and the statement between and , otherwise the "Previous Page" and "Next Page" buttons would not be generated properly. Note 3: The bgcolor="**bgcolor**" clause included in the statement above is an optional feature which is very useful to control the background colors of the database items displayed on the search report. If you use it, you must make sure that you have assigned a proper value to the $bgcolor0 and $bgcolor1, both of which are located in the "free-search.cgi" cgi script. (You can also use your own bgcolor clause eg. .) Note 4: Use **usdate**, **europedate**, **key**, **f??** and **dbname** only within Html statements bracketed by and . Do not use **matchcnt** within Html statements bracketed by and . * * * * * * * * * * * * * * * * * * * * * * * * AVOID BROKEN LINKS FOR IMAGE AND URL FIELDS <<< If you do not want broken links for URL, E-mail address or Image, you could use the command line pair to bracket the line(s) containing the URL ( or E-mail or Image ) fieldname "f??". If f?? is empty, the html statements bracketed by the "check-display" command lines will be treated as comments, otherwise the "check-display" command lines will be removed. H. Installation Procedures: (H-1) Decompress the 32 bit "freesearchengine" ZIP file using 32 bit WinZip ( available from http://www.shareware.com/ ). (H-2) Read this ReadMe.txt carefully. Do not change the contents of the cgi codes unless you have backed it up. (H-3) In order to explain the installation clearly, we have assumed the following directory structures: /base_dir/ --> Full directory pathname, relative to the ROOT directory of your server /base_dir/bizdb/ --> chmod 0777 sampledb.txt --> stores database data file --> Note: If your site does not support this directory, copy your database to your Html directory /base_dir/cgi-bin/ --> cgi scripts, chmod 0755 free-search.cgi /base_dir/html/ --> Base Html directory storing Web Pages of your site --> Copy any image files that come with our software to this directory /base_dir/html/bizdb/ --> Stores Database Html Templates /base_dir/html/bizdb/upload-img/ --> Stores any user record images used by the database. The filenames must be unique for each image in the database. You could use imagenr-recordkey.gif or imagenr-recordkey.jpg where imagenr is the image number within the record and recordkey is the record key of the record. Your site configurations could be different from the above. If you have problems in installing the Software on your site, you can contact us to obtain technical assistance at US$60/hour, payable in advance. (H-4) Create on your server any necessary directories/subdirectories for storing database files and HTML templates. This can be done via Telnet or FTP. For Example: (H-4.1) You can store your HTML templates ( or all sample HTML templates that come with this package ) on a directory called "bizdb" created under your main Html directory. (H-4.2) We suggest that you store your database file ( or the sample database file ) on a directory also called "bizdb" created outside your Html directory. This is desirable for security purpose so that no one can access your database file directly through Web browsers. If your server doesn't allow you to do this, you can install your database files on a password-protected Html directory. In this case no one would be able to access the contents of your directory without knowing the directory userid and password. (H-5) Copy the sample database file to the database directory (H-4.2). This can be done via FTP. (H-6) Adjust all URL references, pathnames and input output control parameters used by the Html files and sample templates so that they will work in your environment. Copy the sample templates to the HTML Directory (H-4.1). This can be done via FTP. (When uploading files to your server, use ASCII transfer for text files, and binary transfer for image and sound files.) (H-7) If your database file stores image filenames, then all the associated images must be uploaded manually by yourself and have to be stored in a Html dirctory (eg "upload-img") on your server (H-4.1). Use chmod Unix command to change the access mode of this directory to 0777, i.e. rwxrwxrwx . This can be done via Telnet or FTP. (Do not create this "upload-img" directory under any password-protected directory, such as your database directory.) (H-8) Adjust system configuration parameters on the "free-search.cgi" cgi script to match your server and database environments. ( This must be done carefully. ) (H-9) Copy the "free-search.cgi" file to the cgi-bin directory of your server. Use chmod Unix command to change their access modes to 0755, i.e. rwxr_xr_x . This can be done via Telnet or FTP. Example: cd /cgi-bin ( some servers use a different name ) chmod 0755 free-search.cgi (H-10) Use chmod Unix command to change the access mode of the database directory ( i.e. the directory containing your database file ) to 0777. Then change the access mode of the database file to 0777. Example: cd /bizdb ( some servers use a different name ) chmod 0777 sampledb.txt (H-11) Connect to the Internet and open a Web browser to execute the sample index.html. I. Calling the CGI programs by "GET Method": If you have experience in CGI programming, you may appreciate that there is another method of calling a cgi program other than the use of the POST Form method. This is known as the GET method. With the "GET" method, you have the advantage of calling a cgi program via the hyperlink. The format of the calling statement is as follows: Call Programname Now where the character & is the parameter separater. A good example is: List Profile However when you use this method with our software, you must not include any non-alphanumeric characters ( including space ) in the parameter values. The presence of a space character in the parameter value will cause the CGI program to stop processing any characters including and after the space character of the Query string. J. Important notes for Windows NT Server Users While our software was originally developed for Unix and Linux platform servers, a number of our clients have successfully installed it on their Windows NT servers. If you wish to install this server into your NT Web server, please follow the rules below: For Unix/Linux Servers: The directory pathnames are in the form of: $database_dir = "/opt2/cnctek/bizdb-db/"; $template_dir = "/opt2/cnctek/httpd/htdocs/bizdb-free-search-engine/"; All relative to your server's ROOT directory. For Windows NT Web Servers: The directory pathnames will have to be changed to: $database_dir = "c:\\opt2\\cnctek\\bizdb-db\\"; $template_dir = "c:\\opt2\\cnctek\\httpd\\htdocs\\bizdb-free-search-engine\\"; The drive number must be specified followed by a ":", and the "/" used for separating the directories must be replaced by "\\". K. Notes on Supporting Non-English Character Set The procedures mentioned in this section is optional. It is required only if you want to accept, store and search non English language characters, such as Chinese, Korean, Japanese, German, French, etc.., for your BizDB database. Under this situation, please perform the following steps: (1) set the $charset variable in all CGI scripts to a correct Language Set ID. Example: $charset = "us-ascii"; Here are the charset codes for some languages: Chinese Simplified (China): gb2312 Chinese Traditional (HK & Taiwan) : Big5 US ASCII : us-ascii For other languages, please check with your local ISP. (2) add to each of your static Web pages used by this software (eg the page containing your Search Form or "Get Method" Search URLs) a Meta Html statement with the "charset" variable set to the same value defined in the cgi scripts. Example: ............. ............. ............. ** NOTE: Do not include into your Html templates, i.e. those template files stored in the templates directory. (3) set the $match_special_chars variable in "free-search.cgi" script to "yes" if the language you are using is not English. L. Notes on Supporting Large Number of Database Records Under normal situation, the maximum size of a flat database file should be kept under 3MB (this could be much smaller if your server is a shared one and has very limited capacity) for optimal performance. Assuming that the average size of a record is 500 bytes, your database file should be able to support a maximum of 6,000 records. What happen if you want to support 20,000 or more records? You can do this by splitting your database records into categories and then store each category of your records into a given database file through the use of a "dbname" drop-down selection list. Example: (Note: You must include this "dbname" drop-down list into each of your "SEARCH" Html templates. Each time when a user issues a "SEARCH" request, a valid "category/database" filename must be selected. Please use alphanumeric characters only for the category/database filenames.) M. More Support Notes If You Have Problems During Installation If you encounter problems during installation, please check the followings: (1) If you have Server Error Message displayed on the screen during execution of your CGI scripts: - check if you have uploaded the scripts to your server using ASCII transfer mode, - check if the Perl location defined on the 1st line of your script is correct, - check if you have modified the script incorrectly. Modification can only be carried out and saved via a ASCII text editor. (2) If your cgi script have problems to display the Html templates on the screen, check the settings of parameters requiring the absolute pathnames, eg. $database_dir, $template_dir and $upload_dir. You can install the "testing.cgi" script that comes with this software on your "cgi-bin" directory and execute this script through your browser to display the absolute pathname of your Home Directory. "testing.cgi" script installation procedure: - change the 1st line of the script to reflect correct location of Perl - upload the script to your cgi-bin directory using ASCII transfer mode - apply chmod 0755 testing.cgi to allow for script execution If the URL of your templates directory is http://yourdomain.com/templates/ and the output of "testing.cgi" is /home/xyz/public_html/, the setting of your $template_dir should be "/home/xyz/public_html/templates/" . (3) If your server supports password-protected directory and you want to password-protect your database directory (i.e. the directory containing all your flat database files), make sure your "upload-img" directory (i.e. the directory containing all the user record images) is not located inside this directory. (4) If you still can't solve the problems, you can consider to use our technical assistance service at cost. Please contact us for a quote. (We will not offer any technical support for this software if you have not paid us.) (5) NOTE: No software customization will be offered for this software. N. Upgrade to Search Engine Plus to support Complex Search If you want to support more powerful search features other than a simple keywords search, you can consider to upgarde to our Search Engine plus for a cost of just US$60/Website. For detailed software descriptions and demonstration, please visit: http://www.cnctek.com/search-engine-plus O. Please Help Us to Help You Since the launch of our Web Database Website in 1998, we have already helped many small businesses to setup simple and easily manageable database oriented Websites. Most feedbacks are encouraging. Your constant support is important to us. So if you are happy with our software, please do us a favour by adding a link pointing to our site from your site. Title: Free Web Based Search Engine Software URL: http://www.cnctek.com/bizdb-free-search-engine Description: Free Web based search engine for any flat ASCII database files. Banner: http://www.cnctek.com/cncban03.gif -------------------------------------------------------------------------- Now you are on your online Web database business. Good Luck! Best regards, Webmaster CNC Technology Web Site Design, Hosting and Marketing Services -------------------------------------------------------------------------- Perl CGI Scripts Developer, Quality & affordable Web Servers Web Database, Shopping Cart and Website Generation Solutions BizDB and its add-ons - http://www.cnctek.com/bizdb-html Order Page: https://www.multicards.com/800140/order.htm Download our free Simple Search Engine and File Uploader today http://www.cnctek.com/bizdb-free-search-engine Your guide on e-commerce, online shopping and Web resources Affordable Web hosting, software and templates. Free Web Tools! Make quick money from our Internet and e-commerce partners It's FREE! Don't forget to bookmark our site! http://www.cnctek.com/