Every script comes with detailed installation instructions generated specifically for that script. The information on this page picks up where your custom instructions leave off.

Installation Troubleshooting
1. How to Set Unix Type Permissions
2. Your Custom Instructions are For Unix and My Server is an NT or Running MacPerl!
3. I Have Followed the Instructions, But I Keep Getting a "Can't Find Data File Error" or "Can't Open State File Error" or "Can't Open keyfile.txt," or Related Error
4. I Keep Getting an Internal Server Error
5. The Script Itself Works, but It is Not Opening My Template File
6. The Links and/or Images on my Template File Do Not Work
7. The Script Runs, But is Produces All Results Rather Than Only Those I Searched For Or It Tells Me To Provide More Information for a Field That is Not Empty
8. I Have Pointed my HTML Forms to the Script, But the Browser Keeps Saying that It Can't Find the Script When the Form is Submitted
9. My Script Works Great for the First Page, But the "Next Matches" Button Does Not Work
10. My Script Does not Find My Locations and I Know that There are Some Nearby
11. My Script Finds Only the Very First Record in the Database
12. I Have Set Permissions for the Script, But I Keep Getting a Permissions Related Error for For the Script Itself
13. I Keep Getting a Can't Rename Data File Error when Editing
14. My Script Runs Sporadically. Some Times it Runs and Other Times I Get Internal Server Errors
15. Everything Works but the Darn US Map!
16. I Wasn't Able to Upload My Zip Code Field and Mark the Map. What Went Wrong?
17. Where is the Yahoo Map or MapQuest Patch for Street Level Mapping?
18. Where is the Patch to Allow Users to Select their Own Search Radius?

Modifying How the Script Displays Results

1. I Need to Remove the "Search Results by FLATTEXT" Link at the Bottom of My Search Results
2. The Script Seems to Run, But I Get a Blank Page or My Search Results Don't Seem to Be Showing Up
3. I Set HTML Font Size or Color Codes in My Template File, but They are Ignored When the Search Results are Displayed
4. I Don't Want the Full URL for my Hyperlink to an Image to Be Displayed on the Screen, but Something Else
5. I Want One Field to be the URL to Link to and the Contents of Another Field to Be What is Displayed on the Screen as the Hyperlink
6. I Want to Remove the "You Search For" And Related Text

Your Custom Instructions are For Unix and My Server is an NT or Running MacPerl!

It is often very difficult to determine why an NT machine running Perl will not execute properly. There are simply too many different ways that the server can be configured. The best bet is to ask your server administrator and to consult your server documentation. You can ask your ISP, but often they will tell you that they don't support other people's CGI scripts. If they tell you this, try to install this test script and ask them why it doesn't work. If you are using the ActiveState version of Perl, see here. We'll also try to install the script for you from our Installation Troubleshooting Page.

There are several thing to keep in mind when using NT. First, paths to files may require two backslashes, like:
  $data="c:\\datafiles\\mydata.txt";
Because the backslash is an escape character in Perl. In some versions, you can reference files the same way you do in Unix, with forwardslashes:
  $data="c:/datafiles/mydata.txt";

If you are using MacPerl, the script should work except that you will have to use colons between directories and files (consult your server documentation or contact your server administrator).

If you are getting an error produced by the script (not an "Internal Server Error"), then chances are that your script is complaining because the paths to one or more of your files is incorrect. The good news is that you are not getting an "Internal Server Error." This means, at least, that you are properly pointing to Perl and that your script contains no fatal errors. In order to resolve this problem, you have to provide full or relative paths to your files.  Path information never begins with http://, but often looks like the following for full paths:

  $data="/home/userid/public_html/directory/data.txt";

or:

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

for relative paths.

When you connect using FTP or telnet, your server may tell you the full path to your directories. For instance, if you think your full path is /public_html or /home/public_html/, we can most guarantee you that this is incorrect. Full system paths almost always have several elements before your web space. If you have Telnet access to your account, you can connect there and type pwd at the command line, although this may not necessarily tell you full path information either.

Often the fastest way to get full path information (if you can't determine this otherwise) is to install the Unix test Perl script. It will echo back server values. We have this test script installed on our server. You can see it in operation here.

In many ways, it is better to use relative paths if you can.  Relative paths allow your script to be more easily moved from server to server (and some major hosting companies switch servers for your account without telling you--which can change your full system path and cause your script not to work).

To specify a relative path, the path is relative from your cgi-bin directory (or the directory that your script is located in).  Suppose that your directories look like the following:

The full system path to a file named data.txt in the data directory in the above example might be something like:

$data="/home/site502/htdocs/html/files/data/data.txt";

In the above example, if your script is installed in the cgi-bin directory and your data file is named data.txt and is located in the data directory, then your path to your data file would simply be:

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

Note that ../ means to move up one directory (i.e. move out of the cgi-bin directory, open the data directory, and access the file data.txt) .  You can use multiple ../ to move up multiple directories, if you are storing your data file farther up the server tree.  Note, that relative paths do not begin with a forwardslash.  In the above example, if we used:

$data="/data/data.txt"; #does not work!

the script would look for the directory /data as far up the server directory structure as possible and it would not be found there.

Often when you get an Internal Server type Error, there will some indication of the problem in the error logs, but this information is not always useful and few people on virtual servers have access to their error logs. Your script itself will produce errors if it can't find files at locations you specified in Step B, so if you are getting an Internal Server error, don't spend a lot of time trying to fix locations in Step B, because this is not your problem. The problem is that the server doesn't know what to do with your Perl file because it wasn't able to execute it properly. Any one of the following could cause this error, so be sure to check them in this order.

• Your command interpreter (the first line of the script that specifies the location of Perl) is not located at the very top line of your script. If it is even one line down, it won't work. This error is especially common if you use Internet Explorer, since it inserts two hard returns by default.
• Your command interpreter does not begin with #!/   You must leave the # in front of this line.
• Your command interpreter is not pointing to Perl 5.0 or greater on your server. If your server is running both Perl 4 and Perl 5, you have to point to Perl 5. FLATTEXT scripts require Perl 5.0 or greater, so try adding a 5 to the command interpreter if you suspect that this is your problem. If you see an error related to lc( in your error logs, then you know that the top line of your script is not pointed to Perl5 because lc (lowercase) was first supported in Perl 5. If you have telnet access to your server, you can find Perl by typing which perl. Also type: which perl5 to see if your server is running both versions and be sure to point location specified by which perl5.
• You edited the program in a text editor that broke long lines when the script was saved. Your text editor must never break lines with hard returns.
• You accidentally uploaded the script in Binary mode rather than ASCII mode (sending a file to the server in Binary mode and then sending it from your server back to your desktop computer will replace the good version of your script on your desktop with one that will never run because of invalid line endings. Always send your script using WsFTP (or another major FTP client). Do not use Front Page or any other HTML editor to upload Perl or data files to your server. You can use Front Page to work with your HTML pages, but you should never use Front Page or any program like it to edit your script.
• When providing information in Step B of your script, you accidentally deleted a quote mark or semicolon around the values you were asked to provide.
• You attempted to do modifications to how the script displays and you introduced errors. Any time that you insert HTML inside a print statement, you have to make sure that any quote marks and @ symbols that you introduce have a \ immediately in front of them, like \" and \@. It is always best to get the script working without modifications first, then do one small modification at a time so you can quickly track your errors down.
• When you saved the file from our site, you accidentally saved the file before the whole thing loaded into your browser. If this is the case, edit your script and jump to the end and view your file on our server using your browser. If it doesn't end where your script ends, then you know why.
• When you set permissions for your script, you set permissions to 777. For security reasons, most servers that are running wrapper programs (which are most of them) will not execute a script if its permissions are set at 777. Permissions for scripts and directories where the script is located must be set at 755. For this reason, your script and data file should not be in the same directory.
• When you saved the file, your browser thought you were saving an HTML file and added a lot of stray formatting that completely corrupted the script. Always select text as the file type when saving, not HTML, particularly in newer versions of Explorer. Connect to our server and compare the text of your script with with what we have on our server.
• Contact us if you have done all of the above and still are stuck. There are, of course, other things that could be going on... these are just the most likely culprits.

There is really only one thing that could be causing this. You did not specify the the exact location of your template file in Step B where the script asks you for it. Most people who write us and swear that they are pointing to the correct location of the template have a small typo or case mismatch somewhere in the assignment line in Step B. Files on Unix servers are case sensitive. You will have better success if you put your template file and data file in the same directory and use the same information for both, only changing the filename itself for each file. Do not chmod 777 your template file.

Template files are regular HTML files with two major exceptions, both of which you need to understand in order to get this issue resolved. First, the template file is the file that your script will open and insert search results into. Search results are inserted where +++ appears. It is important that close all HTML elements that you open on the template and that you not delete the +++. Second, because this file is opened by the script and not by your browser directly, the template file is displayed on the browser screen of the user as though it were located in the same directory as your script. Because of this, relative links that work fine when you point your browser to your template will not work when the script displays this file from a completely different directory. There are two easy solutions. The first is to build the relative links inside your template file as though your template file were located in your scripting directory--in fact, you can even put it in your scripting directory in some cases (although you should never put your script and data file in the same directory). The second and more reliable way to get your links and images to work is to use full URL's for all links and images. Full URL's begin with http://

This almost always happens when the variables that your HTML form is passing do not match the variables that your script is expecting and was designed to work with. The HTML snippets that were generated with your script can be modified, but when your or your HTML editor changes the names of the fields that are passed to the script, then the script does not see any search terms. If you did not set search restrictions, then the result is that your script will find all matches, otherwise it will complain about insufficient search terms.

You can fix this by returning to the search html pages that were generated by our site and reediting your script, making sure not to change any of the field names.

If you are getting an error saying that you did not provide enough information in a field, you should also check the search requirements that you set for that field. For instance, it is possible that you required five characters, but are only entering four.

You will know that the Post method is working and that your forms are passing the right information is your search criteria appear under the "You Searched For" part of your search results page.

Your server may require that you use the "www" part of your domain name for form variables to be properly forwarded to your script.

Make sure and then check again that your form is pointing where you think it is. To be absolutely sure, type the URL into the Internet browser you are using. If the script runs, copy and paste that URL into your forms. Filenames on Unix servers are case sensitive.

It is also possible with some wrappers that your server may be running to have a completely different scripting directory somewhere on the server other than where you may be expecting. It is also possible that you may need to use a nonstandard URL's to access scripts on some servers. Consult your server documentation and ask your server administrator.

There is generally one thing that could cause the problem of your script working from the initial form, but the next matches button producing a 404 Page Not Found Error. You need to check Step B very carefully where your script asks for the URL of the script itself. To make sure that you get it right, copy the value from your HTML form and paste it into the script in Step B where it asks for the URL of your script. If you are absolutely sure you got it right, investigate any other form commands that may be on your template file. Overlapping form elements will produce problems. Likewise, on some browsers, if one of the form elements on the page is not properly closed, all of the form elements on the page could be affected adversely.

Your server may require that you use the "www" part of your domain name for all URL's specified at Step B in order for your form variables to be properly forwarded to the script.

This error could occur if you accidentally transferred the data file in binary mode rather than ASCII mode or if the delimiter that your script is using does not match the delimiter that actually separates the fields of your database. It could also occur if the field order that your script is expecting no longer matches the field structure of your actual data file because you deleted a column from your spreadsheet or otherwise moved fields around. Your Zip code field is explicitly set inside the script, so moving columns around means that you need to reconfigure the script so that it can work with the new field order.

This error could occur if you accidentally transferred the data file in binary mode rather than ASCII or if some how the hard returns that separate each record have been cut or otherwise corrupted. If you are using a Macintosh, make sure that you always save your data file as MS Dos Text, since Macs and PC's terminate lines differently.

Any time that you move or rename a script, you have to reset its permissions to 755. If you install a script in a directory where CGI scripts are not permitted, the server will often abort and complain in terms of permissions. Ask your server administrator what directories your scripts should go in. This could also happen if your files have the wrong file extension. Some servers expect file extensions of .cgi, others .pl, and others can work with both.

When a record is edited, the script writes the whole data file to a temporary file to make sure that everything with the edit went OK. If everything went well, then the temporary file is renamed so that it replaces the existing data file. In order to do this, the directory that your data file is in must be accessible to the script for writing.  This may mean that you need to chmod 777 the directory that your data file is in.

Sometimes, we have encountered problems where the web server is running as a user other than the user who owns that particular slice of the account. Look at all the files in the directory where your data file is located. Do they all have the same User and Group assignments. You will need to resolve this issue with your server administrator.

If your script runs when you search for some things and crashes when you search for others and you have not modified the script between it working and not and seems to crash at totally random times, then you need to see how large your data file is. If it is big, there is a chance that your server is killing it off because it is exceeding the allowable resources. The resources that a server is willing to devote to your application may depend on the other jobs it is process at that particular instant, which is why it seems to crash randomly. Since FLATTEXT files are already optimized about as much as they can be, there is not a whole lot that you can do short of decreasing the size of your data or migrating to an SQL solution. Also see the technical information page for a more comprehensive treatment of this.

There are instructions in your custom instructions page that tells you how to hook the map up. If it doesn't work or if you need more features, just contact us and we'll take a look.

The map generator at http://flatmaps.com is very particular about the contents of files that you upload because of issues of security. If you weren't able to upload your list of zip codes, then there is a good chance that one of the following is to blame:

• The file you are uploading contains information other than the Zip code. The file that is uploaded that actually places marks on the map for each of your locations must contain only Zip codes, one per line.
• Your file contains something other than Zip codes, including stray spaces, Canadian postal codes, etc.

The Yahoo patch is located here. The MapQuest patch is located here. This patch goes in the script where your search results are displayed, usually in Step K10 or K15 (depending on the configurations of your script). Please contact us for advice about using the patch and where to install it. Please see the disclaimers at the street level mapping page.

It is located here. Please read cautions about the maximum and minimum recommended distance settings.

I Need to Remove the "Search Results by FLATTEXT" Link at the Bottom of My Search Results

Your license allows this. Just comment out this whole line in Step L7 by putting a # as the first character of the line.

View the source of this blank search results page using your browser under the "View" menu in Netscape or Explorer. Do you see a web page there or is the source blank too? If you see the code of a web page, then you need to check your template file carefully to make sure that you closed every table that you opened, etc. If something else is going on, contact us and we'll take a look.

If you have set opening and closing font HTML codes around your +++ in your template, your search results should conform to these settings, unless your search results are inside a table generated by the script. One of the limits in how HTML is implemented is that font instructions inside a table have to be set in each cell. The good news is that you simply need to enclose each variable in the table cells of Step K15 of your script with the proper font codes and it will work. An important note, however, make absolutely sure that any HTML you insert into any print statement in the script has a backslash before each and every quote mark:
   print "...<font face="Arial">$Variable</font>...\n";
will cause the script to crash every time. It must be the following instead:
   print "...<font face=\"Arial\">$Variable</font>...\n";
You must put a backslash immediately before each and every quote mark that you insert into a print statement. The same thing goes for the @ symbol inside print statements!

You can include CSS statements in your template file to quickly and easily handle table formatting.

<style>
TD {font-family: Verdana; font-size: 12pt}
</style>

 

Often, with scripts in the generator, the default action is to simply show the full URL of the image or page that you are linking to. Often, having a simple "Click Here" will do. The first thing that you need to do is find which step in Step K this line is being printed at. You should be able to quickly find it by reading the comment lines. Once you find it, you may recognize the elements of a regular hyperlink inside part of a line:
  ...<a href=\"$Variable\">$Variable</a>...

The actual format will vary and your field will not be named $Variable, but you get the picture... It is the second occurence of $Variable, the one that is boldfaced in the example above that you can change to whatever text you want to appear in the screen. To keep the link going where we want it, we don't modify what is inside the a href part. If we want to keep the link going to the same place, but display "Click Here" instead of the filename or full URL, we would use:
  ...<a href=\"$Variable\">Click Here</a>...

The same general idea applies here as in the previous example. Suppose that you have two fields in your database, one is named LinkText and the other is named LinkURL. You can combine the two into a single step in Step K of your script by modifying the line to look like:
  ...<a href=\"$LinkURL\">$LinkText</a>...
Modifications of this type can be complicated, especially if you are working inside a search results format that is a table. Contact us, we'll be glad to help.

Easy enough. Search near G4 or G5 for these lines. Make sure that when you comment them out that you make sure that you are also commenting out the closing } of if ($Variable){ statements that may be a part of these lines.