FAQs (Frequently Asked Questions)

Installation

Structure and Performance of this Software

Usage and Customization

Troubleshooting

  


 

Installation

[ top ]  Q: System requirements - what software and hardware I need to run it successfully?
- web hosting account that allows cgi scripts, perl version 5, FTP or Telnet access. Should work on any OS.

[ top ]  Q: What is mod_perl and how to install it?
mod_perl is a module for Apache web server which can make perl cgi-scripts run up to 20 times faster than in the standard CGI mode. This is possible thanks to its property to compile the script only once and cache it in the RAM. Download and install it as recommended by its documentation.

[ top ]  Q: What is FastCGI and how to install it?
FastCGI is a very similar to mod_perl technology but is available not only for Apache web server and is not limited only to Perl scripts. To use it you need FastCGI enabled web server and Perl. There is a module for Apache which will enable the FastCGI mode. Also Perl needs FCGI.pm module. Look in their documentation to find out how to install it.

 

Structure and Performance of this Software

[ top ]  Q: Files, directories and their purpose.

Directories:
    DBPUB1/STD -
perl modules with relatively standard functionality (could be used in other projects too)
    DBPUB1/NAVG - perl navigation modules specific for the current project
    DBPUB1/NAVG/en - perl navigation modules specific for English language (default)
    ..... - and more languages
    DBPUB1/ADMIN - perl modules used by the administration script: admin.cgi
    data - data files
    docs - documentation
    logs - log files
    tests
- some test scripts which can confirm the perl version for certain standard locations
    templates/admin - html template files for the admin.cgi script
    templates/en - html template files in English (default)
    templates/de - html template files in German
    ..... - and more languages: it=Italian, sp=Spanish, pt=Portuguese, bg=Bulgarian, fr=French. Please note than not all of these templates might be provided.

Files:
    admin/admin.cgi - your Admin Panel; (Tip: protect the admin directory with http access password)
    x.cgi - standard cgi script wrapper
    nph-x.cgi - nph-cgi script wrapper
    nph-x-no-header.cgi - nph-cgi script wrapper (will not return full http response header)
    x.fcgi - FastCGI script wrapper
    DBPUB1/STD/Parameters.pm - your parameters (updatable via Admin Panel)
    DBPUB1/NAVG/Sample.pm - use this module as a template if you write extensions to this software   

[ top ]  Q: How this software works?
When you call the script(for example: x.cgi) from browser the web server will execute the script. You should pass to the script the following parameters:
    NAVG - the navigation destination. The script will use its value as a perl module name from DBPUB1/NAVG directory. The requested module is designed as a object with a method run() which implements the main work for this request. If no NAVG value is passed the module Main.pm is used by default.
    lng - which language we use. Possible values: en, sp, it, bg ... and whatever subdirectories are available under NAVG directory. If no value is provided english language (en) is considered.
    For example calling http://.../x.cgi?NAVG=Sample&lng=de  will produce the output programmed by the DBPUB1/NAVG/Sample.pm module and will use german language related templates(from templates/de directory).

[ top ]  Q: What is a nph-script?
NPH(Non-Parsed-Header) script means that the web server will not buffer the cgi script output. It is used usually when we have to receive from the script streamed data rather an immediately generated html response. To run it this way use either nph-x.cgi or nph-x-no-header.cgi

[ top ]  Q: How to improve the performance? Some test results.
    - run it as FastCGI application or under mod_perl (Apache::Registry mode)
    - to find out how much CPU seconds your script requires use either the Chatologica HTTP Benchmark test utility or if you run it in plain cgi mode open x.cgi file, look in the comments at bottom of the file and uncomment the correspondent part of code which will show on the screen the CPU usage in seconds. Use this information to monitor the CPU usage especially if you write custom extensions to this software.
    - use latest versions of Apache, mod_perl and FastCGI
    - install Apache::DBI perl module. It will make database connections persistent under mod_perl.
    - if you notice that the swap memory space is used on your server add some more RAM.
    - mod_perl and FastCGI as memory hungry technologies. Using proxy servers for these interfaces may reduce the RAM usage but with cost of few CPU milliseconds per request.

Below are some performance test results made on the following platform:
CPU: AMD K6-2/300Mhz, RAM: 128MB 8ns, EIDE, Linux RedHat 6.0, perl v.5.00503, Apache v1.3.9, mod_perl v1.21, mod_fastcgi v2.2.2; Tested with Chatologica HTTP Benchmark test utility v1.0

 
Compilation Times 
Standard Perl modules:

Compilation time:

CGI.pm

118 ms

CGI/Carp.pm

67 ms

lib.pm

63 ms

vars.pm

10 ms

diagnostics.pm

520 ms

strict.pm

6 ms

IO/File.pm

160 ms

FCGI.pm

350 ms

Exporter.pm

30 ms

DBI.pm

210 ms

DBD/mysql.pm + DBI.pm

250 ms

   
Optimized Chatologica Perl modules:
(used as replacements of the standard Perl modules)
 
CGI_Parser.pm (replaces the standard CGI.pm)

8 ms

MyCarp.pm (replaces the standard Carp.pm)

4 ms

   
More curious CPU times:  
spawning a Perl interpreter to execute a perl script

27 ms

compilation of 1KB Perl code

3 ms

compilation of 1KB PHP3 code

2 ms

processing of one plain html page of 5KB (Apache 1.3.6)

8 ms

processing of one plain html page of 5KB (Apache 1.3.9)

5 ms

"File not Found" Error

4 ms

 
Navigation Destination Tests 

URI/execution time

FastCGI mode

mod_perl
(Apache::Registry mode)

mod_perl
(Apache::PerlRun mode)

plain CGI mode

x.cgi?NAVG=Sample
(direct access - no proxy)

15 ms

15 ms

20 ms

76 ms

x.cgi?NAVG=Sample
(proxing with Apache1.3.9)

+3.5 ms

+3.5 ms

+3.5 ms

+3.5 ms

x.cgi?NAVG=Sample
(proxing with Apache1.3.6)

+17 ms

+17 ms

+17 ms

+17 ms

 
DataBase Tests 

Database

FastCGI mode

mod_perl
(Apache::Registry mode)

mod_perl
(Apache::PerlRun mode)

plain CGI mode

Flat-file (1000 records)
update a record and
show 50 records

540 ms

500 ms

520 ms

620 ms

Flat-file (1000 records)
show 50 records

340 ms

340 ms

360 ms

480 ms

Flat-file (10,000 records)
update a record and
show 50 records

3600 ms

3600 ms

3600 ms

3700 ms

Flat-file (10,000 records)
show 50 records

2420 ms

2260 ms

2400 ms

2530 ms

MySQL (18,000 records)
update a record and
show 50 records

160 ms

160 ms

180 ms

520 ms

MySQL(18,000 records)
update a record and
show 50 records
+ Apache::DBI (persistent database connection)

 

153 ms

163 ms

 

 

Usage and Customization

[ top ]  Q: Can I rename files and directories?
Generally spoken it's not recommended because this software may fail to find some of its components if you rename them. However feel free to rename any of the script file names: admin/admin.cgi, x.cgi, nph-x.cgi, .... For example if your system do recognize only .pl files as perl scripts you can rename x.cgi to myscript.pl. This software would work without problems with the changed script name. It's not recommended to remove the nph- prefix in the nph-script filenames because for some web servers it is the only mark the a script have to function as a NPH.

[ top ]  Q: How to make my own design? Templates usage.
Use the Templates Manager in Admin Panel to edit/delete/create your html template files. As a principle we insert in any template special strings like $out{'my_data_field_1'} which will be replaced with dynamically generated html stuff during the execution of the script. These strings $out{'key1'}, $out{'key2'} , $out{'key3'}, ... are in fact elements of Perl hash variable %out which we use to store in these dynamically generated html codes. If you wish to add some more dynamic data within this template have it produced in the %out hash in the correspondent perl module and then put the correspondent $out{'my_new_data_key'} string in the template. Major strings that wish use in almost every html templates are:
    $out{'script_url'} - url to the current script (usually used within the <FORM> tags)
    $out{'nph_script_url'} - url to the current script but with nph- prefix (usually used within the <FORM> tags)
    $out{'lng'} - current language we use (used to promote it between different script invocation by same user)
To find which $out{...} strings are allowed by a template open its original version and look through for $out occurrences. A smart way to do this is to use the "Find" function of your Notepad or WordPad.
Some standard template files:
    header.htm - html code that we show at the beginning of each page
    footer - html code that we show at the end of each page
    notice.htm - custom error/warning message shown to client

[ top ]  Q: How to use it in multilanguage mode?
Call the script with additional parameter lng. Possible values are the two-character directory names under your templates directory. it=Italian, sp=Spanish, pt=Portuguese, bg=Bulgarian, fr=French, en=English(default), de=German.
Example: Call http://..../x.cgi?lng=fr will show you a page in french. As well You can add your own languages adding the corresponded directories under NAVG and templates. To create a template for this language get the correspondent template file from the default templates/en directory, translate and save it through the Templates Manager. You may need to write and language specific perl modules under NAVG too. It is possible when you request a page with language different than the default (en) to see blank page. This is because there is no template created for this language or there is a problem with reading the template file.

[ top ]  Q: How to add banners?
Just copy and paste the html code of the banners in your templates. Also a good idea is to put it in the header.htm or in the footer.htm file in you wish to edit only one file. There is a special string $out{'random'} which have random values from 1 to 100. You can use it within your LinkExchange or SmartClicks banner exchange html code to make more effective random distribution of the banners through the pages. To set different interval of random numbers modify eval_template() procedure in DBPUB1::STD::Templater module.

[ top ]  Q: How to use it in mod_perl or FastCGI mode? Examples.
Here is an example of my test platform on one Linux machine. I ran 3 Apache web servers this manner:

- 1st is a plain Apache web server running on port 80 and serving static objects as html files and images. It use mod_proxy and mod_rewrite modules.
- 2nd is a mod_perl enabled Apache server running on port 8080. It can serve requests to the cgi scripts for optimal performance. It is configured to work this way:
   http://localhost:8080/registry/x.cgi - it runs the script under Apache::Registry mode
   http://localhost:8080/perlrun/x.cgi - it works through Apache::PerlRun handler
   http://localhost:8080/cgi-bin/x.cgi - runs in standard cgi mode
- 3rd is a FastCGI enabled Apache server running on port 7777. It is configured to work this way:
   http://localhost:7777/cgi-bin/x.fcgi - it runs the script as dynamic FastCGI application
   http://localhost:7777/cgi-bin/x.cgi - it runs the script in standard cgi mode

I have configured the 1st Apache server to work as proxy server for the cgi script requests to the 2nd and 3rd web servers in order to hide the port numbers in the urls. Now I can run the x.cgi script in 4 modes just by changing the path to script in the url:
   http://localhost/registry/x.cgi - runs the script under mod_perl (Apache::Registry mode)
   http://localhost/perlrun/x.cgi - runs the script under mod_perl (Apache::PerlRun mode)
   http://localhost/fastcgi/x.cgi - runs in FastCGI mode
   http://localhost/cgi-bin/x.cgi - runs in standard cgi mode
I have configured the 1st Apache to do this proxing through adding the following lines in httpd.conf file in Apache's conf directory:

RewriteEngine on
ProxyRequests on
ProxyReceiveBufferSize 65535
RewriteLogLevel 0
RewriteRule ^/(perlrun/.*)$ http://localhost:8080/$1 [proxy]
RewriteRule ^/(registry/.*)$ http://localhost:8080/$1 [proxy]
RewriteRule ^/fastcgi/(.*)$ http://localhost:7777/cgi-bin/$1 [proxy]
RewriteRule ^proxy:.* - [F]
NoCache *


This will work only if You enabled Apache's mod_rewrite and mod_proxy modules.
Note: Run the software under mod_perl only in one of its two modes because switching from Registry to PerlRun mode and back may produce "Undefined Apache::Perl handler" error.

[ top ]  Q: How to extend this software functionality?
Write additional perl modules under DBPUB1/NAVG/ directory. Use Sample.pm file as a template. It is a kind of object with method run() which must implement the actual work for this new extension module. For example it may produce some html components based on the input and some data. Have stored this in a %out hash. Also make template file(s) with similar name which will be used for the html response. Examine the current modules in your DBPUB1/NAVG/ directory to use them as examples.

[ top ]  Q: What I have to know if I write extension modules for this software? Tips.
To preserve the compatibility with mod_perl and FastCGI and keep this software flexible, pay attention on the following items:
   - always write the extensions as perl modules with protected namespaces
   - use strict pragma with your code
   - test the script with perl warnings On. Just add -w switch in the first line of the script. Example: #!/usr/bin/perl  -w
Remove the -w switch in the production release.
   - do not export scalars from your modules. Apache::PerlRun may not remember the exported values (probably a bug)
   - do not use exit() or die() functions. Under FastCGI this will terminate the application defeating the whole idea of running the cgi script as a persistent process. Instead use FCGI->finish to exit from the request but not from the application.
    - limit the usage of various standard Perl modules in order to have this software run fastly as well in plain cgi mode. Use the Chatologica's optimized replacements or try to make your own optimized modules if possible.

[ top ]  Q: How to password protect my admin directory?
Here are instructions for Apache web server. Upload to your admin directory in ASCII mode a file .htaccess like this one:

AuthUserFile /usr/home/chatologica/www/cgi-bin/myscript/admin/.htpasswd
AuthGroupFile /dev/null
AuthName "Admin Panel"
AuthType Basic
<Limit GET POST>
require valid-user
</Limit>

You have similar file in some of your directories. Use the list command: ls -la to see it. Replace the sample path above:  /usr/home/chatologica/www/cgi-bin/myscript/admin/.htpasswd  with the full path to your own admin directory. Then from shell prompt type the command:
     htpasswd -c .htpasswd administrator
This will create a password file .htpasswd and will ask you to enter a password for username administrator. Enter the password and then when you access http://.../admin/admin.cgi you will get a message box on the screen asking to enter username/password pair. Enter your username (administrator in this example) and the password and you will access your Admin Panel.

 

Troubleshooting

[ top ]  Q: Error message: "Forbidden. You do not have right to access this file." or what file permissions I have to set?
This error indicates that the web server user (usually nobody) do not have permission to read or execute the requested file. Set world 'read' and/or 'execute' permission to avoid this problem. Look at README.TXT to see which are the right file permissions that you have to set in order to run successfully this software.

[ top ]  Q: Error message: "Internal Server Error" and some suggestions how to fix similar problems.
This error indicates that the script has not produced valid output. Check the following:

  • your perl is version 5

  • the file is uploaded in ASCII mode

  • it does not have syntax errors, use: perl -c the_file.pl to check

  • look in the web server error log to see what errors are registered there, may be there is a missing perl module

  • check if all files are uploaded properly in full (100%)

[ top ]  Q: "core" file - what is this?
This is so called 'core dump' and happens during memory faults. The operating system writes down the current state of memory in a file named 'core' and kills the failed process. Happens if something in the data or code area of the process gets corrupted, read/write access outside the process area, very fast forks making the operating system confused, low resources. Don't worry to delete this file from your hard drive.

[ top ]  Q: MySQL connection error.
This is caused usually if you run it in mod_perl + Apache::DBI mode which makes the database connection persistent. If there is no database requests for a certain time the MySQL may close the connection because of inactivity timeout. To avoid this error setup MySQL with higher idle timeout threshold. For example 72 hours should work.

[ top ]  Q: "Undefined subroutine Apache::Registry::handler" error.
I noticed this error when switch multiple times between Apache::PerlRun and Apache::Registry modes. The cure is to run this script only in one of these modes. However if you get this error just restart the mod_perl enabled web server.