Additional instructions for troubleshooting your install and modifying display properties are available at:
http://flattext.com/help/

• Check the top line of the script and make sure that it is at the very top, flush left.
• Modify the script at all parts of Step B (use relative paths where possible) to match your server configuration.
• Rename your script to something like dbase.cgi or dbase.pl (don't use the current name) and send your script to your cgi-bin or other scripting directory.
• Chmod 755 your script, see here.
• Create web pages from HTML snippets and point them to script (if you have multiple forms, you can break them up and put them in any page or pages of your choice).
• Create a display template with +++ where you want the search results inserted and send it to the server at the place you specified in Step B of your script.

  Unless you have installed Perl scripts before on your server, the above instructions may be too abbreviated to be helpful and you should see the detailed instructions below. There is extensive treatment of the installation problems and how to fix them in the help files, see http://flattext.com/help/

You have created a script that is addable, editable, and deletable using a single password set in Step B of your script. When sending all FLATTEXT files (including the script, the template, and your data file), make sure that you always send them in ASCII mode.

Your script contains the following fields in the following order. If you have an existing database on your PC that you plan to use as your base data, you need to make sure that you export these fields in this order:

Title
Role
Purpose
Description
Release Date
Sample File
URL
Client Comments
General Comments

Your script is configured to search the following fields:

Title
Role
Purpose
Description
Release_Date

Your script is configured to display following fields in the following order:

Title
Role
Purpose
Description
Release_Date
Sample_File
URL
Client_Comments

You should save your files from our server using the SAVE AS option on your browser (do not copy and paste, since this has caused problems for some users in the past). Note that most browsers will automatically attach the extension .txt to the end of the filename, so you will need to rename your Perl file so that it will have the correct extension (.pl on some servers, .cgi on others).

A good FTP program will make the installation process for your script much, much, easier. If you are an IBM-compatible user, We strongly recommend WsFTP. It can be downloaded from http://shareware.com or it can also be downloaded from ftp://ftp.mediex.com/pub/mediex/ws_ftp32.zip. This FTP program should be all you need to install your script (provided you know the location of Perl on your server). The instructions throughout are based on WsFTP. FrontPage and the control panel that might come with your web site will almost certainly corrupt your script and waste your time... download an FTP program.

Equally important, you need a good text editor. Do not use Notepad, which comes with Windows and is often the default program FTP programs use to view files. We use Anansi (also available from http://shareware.com, which is a basic HTML editor but serves well as a text editor too). You can use WordPad, which is often located at c:\windows\write.exe (but it has the annoying feature of always saving text files with the .txt extension, whether you want it to or not). If you open any of your downloaded files in your text editor and all the lines run together (or rectangular blocks appear at the ends of lines), you need to switch text editors and redownload your script.

Many people who have difficulty installing their scripts, try to do too many things at once. We highly recommend that you first follow the instructions below carefully. Once you get your initial script working on your server, you can start customizing both it and your template file. If you begin by modifying and tweaking your Perl script, it is harder for us (if you need our assistance) to determine whether the problem is with the script, its configuration, installation, or a problem you accidentally introduced.

The first line of your script is called the command interpreter and it is crucial because it contains the location of Perl on your server. It must be completely flush with the left margin and be located at the very top line of your script and must begin with the pound sign, followed by an exclamation point, followed by the path beginning with a forwardslash. The default command interpreter that was generated with your script was created may not be the location of Perl on your server. If you have Telnet access to your server, you can find the location of Perl by Telnetting to your account and typing: which perl Since your script requires Perl 5 or greater (and there is a possibility that your server is running both Perl 4 and Perl 5), you should also type which perl5. If which perl5 returns a path different than which perl, use it. If you don't have Telnet access to your account, contact your server administrator and ask "What do I need to use as the command interpreter at the first line of my Perl scripts to reference the location of Perl 5 on the server?" This is a question that server administrators get several times per week and they should respond quickly and definitively. For 95% of Unix type servers, the command interpreter will be one of the following:

#!/usr/bin/perl
#!/usr/local/bin/perl
#!/usr/bin/perl5

This is the most difficult and tricky part, so please follow these instructions carefully.

• Create a new directory on your server and FTP your data file (if you have one) into this directory in ASCII mode (if you transfer any of your files in BINARY mode, your script will not work). If you don't want your data to be publicly accessible, then create this directory parallel with your public_html directory. (Note, there is a very good chance that you will not need to change permissions for your data file or the directory your data file is in. If you do receive permission related errors when adding or editing records, then chmod your data directory and data file to 777). Do not upload your files using FrontPage or any similar program... it will corrupt your script with almost 100% certainty.

  Also, if you are allowing users to add records to your data file through the browser, do not put your data file inside (nor in any subdirectory of) your cgi-bin directory. This can be a serious security risk in certain server configurations. If your data file is not addable by users, but is updated by the administrator using FTP only, then your script and data file can go in the same scripting directory.

• After sending your data file to the server you need to figure out the full system path OR relative path to this file (which you will supply at Step B1 of your script).

  How to Determine Relative Paths

  When your script runs, paths to files are relative from directory that the script is located in. Suppose that you created a directory named data that is parallel to your cgi-bin. Suppose also that you put your data file inside the data directory and named it datafile.txt:

  |..
  |-cgi-bin
     |-dbase.cgi
  |-data
     |-datafile.txt
  |-public_html
     |-index.html, etc
  
  

  Your Step B1 would look like:
  

  $data="../data/datafile.txt";
  

  The ../ part tells the server to move one directory up. You can use multiple ../ to move up the server tree multiple directories. Note that relative paths NEVER begin with a forwardslash.

  How to Determine Full Paths

  You should use relative paths (above), if you can. Or, you can provide full paths to your data and template files (you cannot trust your FTP or telnet program to tell you the full system path to your web space). Full system paths always begin with a / and often contain three or more directories BEFORE your web directories. They often look something like:

  $data="/home/server/yourid/public_html/";
  

  If you can telnet to your web space, you can type "pwd" at the command prompt and that may tell you the full path to your files. We also have a test script available in the help files at: http://flattext.com/help that may help determine the full path to files on your server.

Your script will often generate HTML code that links back to itself (i.e. the button to get more matches, etc). Therefore, you need to provide the full URL of your script or the relative path to the script at Step B2. If your script is named datasearch.pl and all scripts go inside your cgi-bin directory, the full URL might look like

$thisurl="http://yourdomain.com/cgi-bin/datasearch.pl";

Alternatively, if your script is named datasearch.pl, you could simply use:

$thisurl="datasearch.pl";

The above relative path works because all paths are relative from the directory that the script runs in, and simply providing the name of the script is sufficient (remember that filenames may be case sensitive on your server).

Your script uses optional HTML templates that can be formatted to make the style of your search results conform to the style of the rest of your web pages. Step B3 tells the script where this file is, so it can be opened and displayed. For ease, FTP your template to the same directory as your data file (again, send in ASCII or text only mode) and reference the path the same way you did in Step B1, just changing it to reflect the different file name (note again, filenames are case sensitive). Also to ease the installation process, send your HTML template as is and customize it after your script is working properly. You must enter a full or relative path in Step B3, not a URL.

After making the above alterations in Step B of your script, save your file. Then, send your Perl file to the appropriate directory on your server in TEXT (ASCII) mode only. In most cases, this is your cgi-bin directory. Note that some servers (particularly those who don't require Perl scripts to be inside the cgi-bin directory) require your script to have the extension .cgi, rather than .pl.

Once there, you need to change the permissions of your Perl file to 755 so that it can be executed. Detailed instructions for changing a file's permissions using Telnet or using WsFTP are available under the heading Permissions at http://flattext.com/help/

Once you have set the script's permissions, you can check to see if it contains any fatal errors by simply entering the URL of the script into your web browser. If you get system errors of any type (server 500 errors), see the troubleshooting guide at: http://flattext.com/help under the heading: I Keep Getting an Internal Server Error If you get a Can't find Data File related error, see the help file at http://flattext.com/help under that topic.

Your script is designed to be invoked by the HTML snippets that were generated with your other files (there may be multiple forms in this file, which you can split up and put into different web pages of your choice). You need to change the URL in each form to point to your Perl script on your server. You should also feel free to move the fields around, and change the labels for these fields that are displayed to the user. Do not, however, change the names of the fields that are inside the input HTML codes that are passed to the script. If you do, your script won't work properly. Feel free to change any field type from a regular input box to a select menu or any other type of field (except select multiple or checkboxes), but the actual field names must not be changed. Once you get your search HTML configured the way you like, you can paste it into your HTML template so that users can do new searches from the search results page itself.

Your script can also be invoked and searches made from hyperlinks (see below).

There are many, many, ways that your server can be configured. Most people will have no problem at all with the installation. Others won't be so lucky. If you are simply "stumped," try not to take is personally or get too frustrated. For general help and customization information, start with the help files located at: http://flattext.com/help/. If you are still stumped, contact us at: http://flattext.com/contact.htm. Always send us your File ID 235y-e2cc. We will not be able to help you if you do not send us your File ID. We often reply to queries the same day.

Your script is designed to be invoked using the HTML forms that were generated with your script. However, you can also invoke your script using hyperlinks using the following rules for your particular search interface style:

http://yourdomain.com/cgi-bin/yourperlfile.pl?FieldName1=Words+to+find&FieldName2=More+Words

And where your searchable Field Names are:

Title
Role
Purpose
Description
Release_Date

You must use plusses instead of spaces in any hyperlink you construct! There can't be any blank inside the URL at all.

Your search results are displayed in Step K using print statements. If you are familiar with HTML, many parts of Step K should look familiar, with two major exceptions:

1. The HTML formatting appears inside print statements. Actually, the HTML appears between print " and \n";
2. Quotation marks that appear inside the print statements have a backslash \ immediately before them, like: print "<A href=\"$url\">$url</A><BR>\n";

Most of Step K is a loop that displays all matching records according to the preferences you initially set for the script. Feel free to change the HTML elements. It is easy to add bold face, font faces, insert hyperlinks by combining a field that contains text with a field that contains a URL, provided you remember to add a backslash before all quote marks!

If you are consolidating fields, you can delete print statements that are no longer needed. However, keep an eye out for the brackets of if statements. For example, if you have lines that looks like:

if ($Name){
print INST "$Name\n";}

You can't just delete the whole print statement because the closing } of the if statement on the previous line needs the closing }, or your script will not run. In the above instance, you could simply delete both lines.

You need not limit your editing to Step K, you can easily edit print statements throughout the script. Just work in small increments and send your file to the server after every change you introduce, so you can quickly track down any errors you might have introduced.

Also, when you make changes to the script, be sure to add lines like #NEW, so that you can easily find your changes later transfer these changes to a new script if you need to upgrade down the road.