How to set up Perl/CGI scripts

CGI scripts are a cheap way of adding content to your site - they only cost the labour of setting them up in most cases. You just have to:

  1. Use a text editor like Wordpad or Notepad in Windows to edit .cgi or .pl files. Simply put, your editor should not insert anything beyond the bare text that you type on screen, or mess with the rest of the text if YOU don't touch it.

  2. Read the README file, and have them open on-screen when you're setting up the script(s).

  3. Define the correct path to Perl (a server scripting language used by cgi-scripts) in the first line of your script. Yes, you DO leave in the # sign at the line #!/usr/bin/perl, 'though in every other line of the script the hash sign # is used to stop that line being read by the server. Find out where Perl is on your server by typing 'which Perl' or 'whereis Perl' (without the ' ') at the command prompt in a telnet session.

  4. Do not wrap lines. Check that your editor is not set to do this.

  5. Do not put characters like " , ' \ in if you don't know what you're doing.

  6. If the script doesn't work type: perl -cw scriptname.cgi at the prompt in the directory where the script is, to get a clue. If it says 'syntax ok', the problem probably lies elsewhere. This command only shows that the script hasn't got missing characters, or has or has not been 'wrapped' by uploading in Binary instead of Ascii mode.

  7. To test the script's operation type: ./scriptname.cgi whilst in the script's directory in a telnet session. This will execute the script until it requires input from a form, and will report errors.

  8. Get the paths (to required files) correct in the script itself and in the html files involved. Use the pwd command - pwd somename - to find where directories and programs are on your server.

  9. Set permissions of the cgi-scripts to 705 (e.g. 'chmod 705 yourscript.cgi' in a telnet session), chmod 707 for any file OR sub-directory that needs to be written to, to make the script operate, chmod 606 for some text files the script may need to read or write to, and the rest can usually be left at the default 604.

  10. Upload scripts in ASCII mode only, or you'll get errors in them (the text will be shifted around if you upload in Binary, and that is bad. If a comma or a forward slash or whatever is out of place or missing in your script, it won't work properly).
     

  11. Check you've not put a trailing backslash / where you're not supposed to, or not inserted one when you're supposed to!

  12. Email addresses in a script that requires Perl 5 may need to be written tom\@tigertom.com, to work. Your readme file should tell you to do this.

  13. Don't put an apostrophe or other computer language character in any title in your script when first trying it out e.g Tigertom's Site, as it may conflict with the apostrophes in the rest of the line. Apostrophes and other characters can be 'escaped' out of a script by putting a \ in front of them e.g. TigerTom\'s Site.

  14. Windows (MS-DOS) may insert carriage returns which cause errors in Unix. You need to have a line break after #!/usr/bin/perl. It appears to be there, but you may have to insert it manually via Telnet. Otherwise you may get an error.

  15. Don't change too many things at once. Do the absolute minimum to get the script working, then change one thing at a time. Then go to point 7 above.

  16. Start an ftp and a telnet session. Change one thing in the script, upload, type ./scriptname.cgi in the cgi-bin directory, if it works ok repeat the process.

  17. Clear your browser's cache if you are also changing the HTML code of a form page that posts to the script. You may still be loading an old version of your page, with tags that your script won't recognise.

  18. The more complicated Perl scripts, like discussion boards, often require Perl modules, like CGI.pm or LWP.pm. Try to find out from the script vendor if his scripts need them, and from your web-host if they've got them.

  19. The error 'document contains no data' in your browser usually means a path or a file name is wrong. It can also mean the file you're calling is 0 bytes in size.

  20. Don't try setting scripts up when you're tired. If you've been working for hours, take a break, or go to bed!

  21. Read these tips, in detail, again, before you start wailing 'why won't it work?!'.

  22. It's a fact that, after all this, your script might have a bug. Report exactly what problems you're having, and your server set-up, to the programmers. Check any discussion boards at the vendor's website, or Usenet, or general webmaster forums, to see if this is a common problem. It's unlikely you're the first person to have it.