---------------------------------------------------------------

DESCRIPTION:
===========

  WWW-page Access Counter for Windows NT
  Version 2.0

  A CGI-program keeping track of the number of times a
  HTML-page is visited. This is done through a small
  GIF-image which is inserted into the HTML-page.
  Allows up to 32 separate counters and different
  digit styles of any size.

  Tested with 
    EMWAC's HTTP server V 0.96
    SAIC's HTTP server V 1.0

  Henn Saar, henn@assert.ee
  October 30, 1995

---------------------------------------------------------------

INSTALLATION:
============

1. Copy the package into directory 'cgi-bin' or some other directory
   from where CGI-s could be started and unzip it using -d option. 
   This creates following components:
      - counts.exe, copyrite.txt, readme.txt and counter.dat 
        in the 'cgi-bin' directory
      - 0.gif, ..., 9.gif in the 'cgi-bin\digits\a' directory

2. Please read the copyrite.txt file.



HOW TO USE (the first try)
==========================

1. Insert something like the following into your HTML-page
   to activate the counter:

   <IMG SRC="/cgi-bin/counts.exe?link=test">

2. Load the page and the counter should be appear.



HOW TO USE (details)
====================
The program can maintain multiple (up to 32) counters. Each counter
is identified by its ID. For each counter following data are saved:
   - ID
   - total access count
   - last access date and time
   - last accessing host's IP address
   - last accessing host's name (optional)
These data are saved in the COUNTER.DAT file in the 'cgi-bin' directory.
It is a ordinary text file and can be modified using a text editor.
The first line of this file represents the number currently used counters,
i.e. there should be follow one line for each counter. The data items on
the line can be separated by spaces or TABs.


1. Parameters passed to COUNTS.EXE V 2.0
   All the parameter names and argument values are case insensitive.
   <> around the argument values in their description are notation
   constants only and should NOT be used in the calling sequence.

link=<link_id> 
   This is the only mandatory parameter!
   the <link_id> argument should be different for different counters.
   A good choice for the link argument is the URL of a certain
   page.

width=<w>
   The width of counter image in digits. Max value 10, default value 5.

style=<style_id>
   The <style_id> is the name of the 'cgi-bin\digits' subdirectory where
   the gif images of digits are stored. You can have as many different
   styles as you want. Default value is A.

increase=<i>
   The value by which the counter value is changed every time the program is
   called. Can be any postive or negative integer value. Default value 1.

show=NO
   If show=NO, the counter value will be incremented by <i>, but no image
   will appear on the page. By default the counter will be shown.

loghost=ON
   If loghost=ON, the contacting host's name will be saved along with other
   data. By default only IP address will be saved. Note, that using this
   feature adds some delay in the response time. If the host's name can't
   be resolved it takes the value of IP address.

debug=on
   Returns a HTML page with useful information for problem determination.
   When using debug parameter, the program should be called as direct URL like
   http://charon.assert.ee/cgi-bin/counts.exe?debug=on&link=test and NOT from
   <IMG SRC=...>

transparent=on
   Enables to create transparent counter image even from nontransparent
   digit sources. It is assumed, that the pixel (0,0) of the counter image
   represents the background color.

ref=<reference>
   Enables to log all references to particular counter. If ref parameter
   is present then a line will be appended to the COUNTREF.LOG file in the
   following format (items are separated with a space):
   <date> <time> <link> <host> <reference>

   where
      <date> is in format mm/dd/yy
      <time> is in format hh:mm:ss
      <link> is the value of the 'link' parameter
      <host> is the name of the referring host, if 'loghost=ON' was not
          specified the value is 'Unknown'
      <reference> is the value of the 'ref' parameter. If it is empty the
          program tries to get the reference from environment variables
          HTTP_REFERER and REFERER_URL. If no references can be found, the
          substituted value is 'Unknown'

   Note: If your server supports some sort of includes for referrer you can use
      it in the 'ref' parameter. For SAIC's server it looks like 
      <img src="/cgi-bin/counts.exe?link=counters&increase=1&loghost=on&ref=<!#include $referrer>">

   Sample lines in the COUNTREF.LOG file
   10/05/95 12:44:18 leisure 193.40.231.15 venus.assert.ee Unknown
   10/16/95 05:01:21 counters 140.174.162.93 d-93.dnai.com http://search.yahoo.com/bin/search?p=access

beep=on
   Sounds a short beep when counter is accessed. Disabled by default.


NB!
Additional features might be added into later versions! See below.


2. The program automatically prevents sharing of COUNTER.DAT file between
multiple instances of the program. If the program fails to obtain exclusive
ownership of the file during 10 seconds, it terminates without maintaining
the counters value.

3. In the case of fatal errors the messages are written in the file like
Txxx.LOG in the default HTTPS directory. The xxx in the file name represents
the main thread ID of the program, which had created the file.

4. Different styles with different metrics can be used, all the digits
in the style must have the same metrics, of course. For hints see
http://charon.assert.ee/counters.htm in our Web server http://charon.assert.ee

5. The program sets its working directory to that it is called from by parsing
the argv[0]. Thereby, if the program is moved to some other directory, the
underlying related directory 'digits' and its subdirectories should be moved also.

6. The version 2.0 and later supports protection against counter-terrorists!
To disable the automatic adding new counter links you should do following:

   6.1 Edit the 'counter.dat' file and add to the end of the first line after
   the link counter following text
      protect=<some image>;
         where <some image> is the full path name of some GIF file, which
         will be sent back instead of each digit GIF, when an unknown counter
         link is referenced.
   So, the first line should look something like that
0 protect=e:\saic\htdocs\pics\beavis.gif;

   6.2 Add manually lines for each counter link (only the name of the link is
   required) and change the link count to correspond the value of the links
   and save the file.

   6.3 Each time you want to add a new link you should repeat the action in 6.2

   6.4 To remove some link delete the appropiate line and decrement the 
   link counter value.

   6.5 To enable the automatic mode again just remove the protect=... keyword
   from the first line and save the file.

If anti-terrorist protection is enabled, the logging facility (see ref parameter)
is automatically turned on when an unknown counter link is referenced. 
The string 'TERRORIST!' will be appended to the <reference> string.

---------------------------------------------------------------

CREDITS:
=======

  - This package makes use of the gd graphics library 
    by Thomas Boutell, see http://siva.cshl.org/gd/gd.html
    COPYRIGHT 1994 BY THE QUEST CENTER AT COLD SPRING HARBOR LABS.

  - Heini Withagen, heini@w4.nl
    For basic access counter sources.

  - Ryan Terri Sammartino for the basic ideas.


If you find this program useful, some credit is expected from you.
---------------------------------------------------------------
