1 May 1998. Disclaimer and contact at the bottom of this document.

                WWWCOUNT: A Text & Graphical Counter for OS/2 Web Servers

WWWCOUNT provides a counter for OS/2 web servers.  It's major strength is 
it's display flexibility: you can use it to display textual counters 
(with a number of formatting options), or graphical digits (with a multitude 
of digit styles to choose from). And it's free; use it however you like 
(please let me know if you find it useful, or if you have problems with it).

WWWCOUNT can be invoked as a CGI-BIN script or as server side include.  
Each method has it's own strengths and weaknesses:

 * As a CGI-BIN script.
      When invoked as a CGI-BIN script, you MUST have RXGDUTIL.DLL installed 
      on your web server.  RXGDUTIL is freeware that is available from 
      http://www.bearsoft.com/abs/rexxgd.html, or from 
      http://www.srehttp.org/pubfiles/

 * As a server side include.  
      WWWCOUNT can produce both text and graphical output.
      However, your web server must understand the NCSA/HTTPD style of server 
      side includes.  In particular, the EXEC cmd=  syntax must be supported.

*  In either method, to  display graphical digits, you'll need a set of digits.
      WWWCOUNT comes with several sets, but there are lots more out there.
      A great place to look is  http://www.digitmania.holowww.com; see
      section V below for details on acquiring and using new graphical digits.        

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

II. Installing WWWCOUNT

Installation of WWWCOUNT is fairly simple:

1) UNZIP WWWCOUNT to an empty temporary directory.

2) Copy WWWCOUNT.CMD to your server's CGI-BIN script directory.  If you intend 
   to use WWWCOUNT as an EXEC server side include, some servers may expect 
   to see such "ssi scripts" stored in a seperate directory; but most 
   servers will look in the CGI-BIN script directory.

3) Create a DIGITS directory under the root directory of your web tree.  
   For example,  GoServe users should create a DIGITS sub-directory just under 
   the GoServe Data Directory.

4) Copy DIGITS4.ZIP to this DIGITS directory.

5) UNZIP DIGITS4.ZIP.  Several subdirectories will be created, each containing
   a set of "digit .GIFs".

6) Optional: copy WWWCOUNT.HTM to you web directory (it's a demo).

7) Configure WWWCOUNT.CMD.  In particular, you'll need to set the COUNTER_DIR,
   ABS_COUNTER_IMAGE_DIR, and REL_COUNTER_IMAGE_DIR parameters (described 
   below)

You are now ready to try it out -- WWWCOUNT.HTM is a good start, take a peek
at it after you've seen it work

-------------------------------------
III.  Parameters and Options

WWWCOUNT is controlled through user-configurable parameters contained in 
WWWCOUNT.CMD, and through options you supply when invoking WWWCOUNT.  
Options are specified in the URL that invokes WWWCOUNT, with each option 
seperated (in the usual HTTP fashion) by a &.

IIIa. Short descriptions of user-configurable parameters (set in WWWCOUNT.CMD)

counter_dir : Where to store counter files
no_path_translated : always use the counter_dir (ignores counter_dir 
                     info in the options)
rel_counter_image_dir : relative (to www root) directory containing "digit .GIFS"
absl_counter_image_dir : fully qualified directory containing "digit .GIFS"
create_file : create a counte file flag
digits_nobr : add a <NOBR> to graphical SSI digits
write_users : record address and time of each request
suppress_logusers : always use write_users (ignore the loguser option)
suppress_recent : Do no record "repetitive" requests from the same client

IIIb. Short descriptions of options (specified in the request)

  file : the name of the counter file (REQUIRED)
  silent : If a silent is present, the .CNT file will be updated, but nothing
           will be displayed.
  nocommas : If present, every 3rd digit commmas are NOT written. Only used in
             text mode.
  width : minimum width of counter (padded with 0's if need be).
  min : minimum value to count from (the default is 0)
  max : maximum value to count to (the default is 2147000000)
  rollover : if present, will reset counter to min when max is hit.
  increment : add increment at each hit (typically, inc=1).
  ith : if present, append a th,rd,st, or nd "suffix"
  frame: if present, include a left and right frame around an SSI "graphical counter"
  loguser : overrides the WRITE_USERS
  graphic : Name of directory containing "digit .GIFS" (relative to 
            REL_COUNTER_IMAGE_DIR)
  img : CGI-BIN flag (REQUIRED for CGI-BIN invocations, ignored for SSI 
        invocations)
  imgalign : Image alignment (used with SSI graphical counter)
  duration: Timespan that # of hits is computed over 


IIIc. Longer descriptions of parameters

counter_dir=directory
   A fully qualified name of a directory in which to store .cnt files.

    Example: counter_dir='d:\myserver\cntfiles'

   This is used when the PATH_TRANSLATED CGI-BIN variable is unspecified.

   To specify a PATH_TRANSLATED, use URLS of the form
          <IMG SRC="/CGI-BIN/WWWCOUNT/DIR1/DIR2?options"
   or
          #Exec cmd="wwwcount/dir1/dir2?options"

   In both cases, the PATH_TRANSLATED would be: x:www\DIR1\DIR2
   where x:\www is the root of your web tree.

no_path_translated=i
  If you want to ignore PATH_TRANSLATED, and always put .CNT files in
  the counter_dir (this may be a security/privacy measure), then set
  no_path_translated=1 

        Example: no_path_translated=0


rel_counter_image_dir 

    Set the "web" directory that contains the "digit images". This is
    used when an EXEC ssi is used to create a graphics counter.
    REL_COUNTER_IMAGE_DIR is used to form the several (digit specific)
    IMG SRC=...   urls to be included in the html document.

    Note: Each different set of "digits"  should  be in it's own directory.
          under the rel_counter_image_dir. 

                Example: rel_counter_image_dir ='/digits'

abs_counter_image_dir
     The fully qualified version of rel_counter_image_dir (used when
     WWWCOUNT is invoked via an in-line image).

                Example: abs_counter_image_dir ='d:\www\digits'

     WARNING: To use the "in-line" image mode of WWWCOUNT, you MUST
              first install RXGDUTIL ( http://www.bearsoft.com/abs/rexxgd.html)

Create_file
      1=create a .cnt file if none exists,
      0=do not
   If the counter file (passed to counter.rxx using the FILE= option) does 
   not exist, and create_file=0, nothing will be returned.

                Example: create_file=1

digits_nobr
    Used when an EXEC ssi is use to create a graphics counter.
       1 = do NOT allow line breaks in strings of  "graphical digits".
       0 = Allow line breaks within the string of "graphical digits"
     Note: if =1, the <NOBR>  element is used -- but note that webex 
           and other html 2.0  browsers ignore <NOBR>.

                Example: digits_nobr=1

Write_users
 Store info on each request. 0=no, 1=yes.
 Can be overridded by a LOGUSERS option.
                Example: write_users=0

suppress_logusers:
     1 : Supress the "log users" option 
         (a logusers option will override write_users)
    0= do not suppress  

                Example: suppress_logusers=0

suppress_recent
   suppress inrementing if request is from a same client within
   suppress_recent minutes. If 0, or if write_users=0, this is ignored 
   (all requests are recorded)

                Example: suppress_recent=0



IIId. Longer descriptions of options

 Otherwise, the options are:
  file="filename" : Either value or file is REQUIRED.
                    The name of the .CNT file (relative to the counter_dir).
                    See below for a description of how to set the counter_dir.
       value=num  : An integer value. No recording or incrementing, just display the value.
       silent=""  : If silent=1, the .CNT file will be
                    updated, but nothing will be displayed.
    nocommas=""   : If nocommas=1, every 3rd digit commmas are NOT written
                    This is implied if width>0. If not specified,
                    commas WILL be included.
    width=ndigits : minimum width of counter (padded with 0's if need be).
                    Default is 0 -- which means "don't try to pad".
    min=min_value : minimum value to count from (the default is 0)
    max=max_value : maximum value to count to (the default is 2147000000)
    rollover=""   : If  rollover=1, will reset counter to min when max is hit.
                    Default is to not rollover.
    increment=inc : add inc at each hit (typically, inc=1). 
                    If increment=0, then the counter is NOT augmented, and
                    a user-entry is NOT added.
    ith=""        : If ith=1, append a th,rd,st, or nd "suffix"
                    to the number (1st, 2nd, 3rd, 4th, etc).
                    Default is do NOT add this suffix.
    frame=""      : If frame=1, and an SSI graphical counter is being created, then
                    put a left and right frame image on the ends of the counter.
   loguser=arg    : If ARG=YES or NO, and SUPPRESS_LOGUSER<>1, then 
                    override the WRITE_USERS variable. YES = record client,
                    NO=Do NOT record client.
     graphic=arg  : The name of the directory (relative to the REL_COUNTER_IMAGE_DIR)
                    containing the desired "digit GIFS". Note, you can 
                    use digit=arg instead of graphic=arg.
        img=xxx   : XXX can be anything -- the prescence or an img= option
                    signals that this is an "in-line image"; hence, WWWCOUNT
                    will return a .GIF file.  One convenient trick is to have
                    IMG=name.gif as the late option; since some browsers get
                    upset if a .gif does not appear at the end of an in-lined
                    image's URL.
                    WARNING: To use the "in-line" image mode of WWWCOUNT, 
                             you MUST first obtain RXGDUTIL
                             (http://www.bearsoft.com/abs/rexxgd.html)
     imgalign=arg : Arg should be MIDDLE, TOP, or BOTTOM -- effects the alignment
                    of digits created when imgtype is specified.
  duration=#days  : If duration>0, then the number of hits in the last "#days" will be displayed.
                    For example, duration=1 means that the "number of hits today" is displayed.
                    Similarly, duration=7 means "the number of hits in the last 7 days"
                    will be displayed.
                    Notes:
                         *  For this to work, you MUST set  write_users=1. 
                            If write_users<>1, then a value of 000 is displayed.
                         *  The actual number of hits is displayed (minval,  rollover,
                            etc. are ignored).
                         *  If duration=0, it is ignored (i.e.; it's the same as not including
                            a duration option).
                         *  Hint: to report the total # of hits, and the hits in the last n days,
                                  use  two calls, with the second containing an increment=0
                                  option.
                         *  Example:
                             If duration = 7, and today is monday, then the number of
                             hits since last Tuesday (inclusive) is displayed.
 

IIIe. Some examples


This example produces an in-line image containing the counter
(requires RXGDUTIL.DLL).
     <img src="/cgi-bin/wwwcount?file=index&graphics=MBC&width=6&img=foo.gif">

  Note the inclusion of  IMG=foo.gif -- you must  include an IMG=a_value to
  signal that "this is a CGI-BIN request".
  Furthermore, some browsers  get upset if in-line image URLS don't end with
  a .GIF.

This example produces at textual counter
     <!-- #exec cmd=/cgi-bin/wwwcount?file=gotme&ith=1 -->

This example produces a graphical digits counter -- it returns a sequence of 
<IMG elements, and does NOT require RXGDUTIL.DLL
  <!-- #exec CMD=wwwcount?&file=wwwcdemo4&logusers=0&graphic=goldodo&frame=1 -->

IV. Specifying directories.

WWWCOUNT needs to be informed about several directories.  These include:

   * the location of "counter" files
   * the location of "digit gifs"

Counter files are files used to store the number of hits, and other 
information (such as a list of requesters).  There are basically two ways
of specifying where the "counter" files are to be stored                                                                    

    i) With the counter_dir parameter.  Counter_dir should contain a
       fully qualified directory name.

    ii) By including extra path information in the request.  Extra path
        information follows the wwwcount/ and precedes the ?. For
        example:
              <img src="/cgi-bin/wwwcount/dir1/sub2?file=joe"
        has /dir1/sub2 as the "extra path information".
        This is appended to the  web root directory to form the CGI-BIN
        PATH_TRANSLATED variable.  Thus, if your web root directory is D:\www, 
        the "counter" file would be D:\WWW\DIR1\SUB2\JOE.CNT

        If you want to store these counter files in a secure place, we
        recommend not including extra path information.  This is especially
        relevant if you are recording requesters (WRITE_USERS is enabled) --
        you probably don't want to allow the smarter-then-average surfer to
        have access to such private information.

The REL_COUNTER_IMAGE_DIR and ABS_COUNTER_IMAGE_DIR are used to tell WWWCOUNT
where the "digit GIFS" are.  REL_COUNTER_IMAGE_DIR is used to form URL's 
pointing to these GIFS.  For example:
     REL_COUNTER_IMAGE_DIR='http://mysite.net/digits'
or, more succinctly
     REL_COUNTER_IMAGE_DIR='/digits'
Note that REL_COUNTER_IMAGE_DIR is used when an EXEC ssi requests "digit GIFS".

ABS_COUNTER_IMAGE_DIR should point to the "fully qualified" directory refered
to by REL_COUNTER_IMAGE_DIR.   Note that ABS_COUNTER_IMAGE_DIR is used
when an in-line imaage is being created.

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

V. Setting up a new digit set.

It's quite easy to use a new set of digits -- well, it takes a few steps,
but none are difficult. The basic trick is to find a set of files named 0.GIF,
1.GIF,...,9.GIF; with each file containing a picture of the appropriate digit.

The following outlines the necessary steps:

  1) First, you need to find a source for "gif-digits". As mentioned above,
     a great place to look is  http://www.digitmania.holowww.com. 
     Let's go there now ....

  2) Hmmm, so may choices. How about  katt 005 from the "katt collection" 
    (http://www.digitmania.holowww.com/zip/katt005.zip). 
 
  3) After downloading the digit files (or .ZIP file), place them in their "own"
     subdirectory under  REL_COUNTER_IMAGE_DIR directory.  
     For example, if REL_COUNTER_IMAGE_DIR=D:\WWW\DIGITS, 
        i) Create D:\WWW\DIGITS\KATT005
        ii) Copy KATT005.ZIP to D:\www\DIGITS\KATT005
        iii) CD to D:\WWW\DIGITS\KATT005, and UNZIP KATT005

  4) Change the names to be 1.GIF, 2.GIF, etc.  The easy way to do this is with:
             D:\WWW\DIGITS\KATT005>ren ?*.GIF ?.GIF
    
  5) If the digit set has a "left" and/or "right" pieces, name them L.GIF and
     R.GIF (see the GOLDODO digits, that comes with WWWCOUNT, for an example).
     Note that KATT005 does NOT have left and right pieces; so the frame=1
     option should NOT be used.

  6) You are now ready to use your new digits.  For example, include the following
     in an HTML document:
     <!-- #exec CMD="wwwcount?&file=cnt_file&graphic=katt005" -->
     Note that the results will be stored in CNT_FILE.CNT.


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

Disclaimer:

  Copyright 1997 by Daniel Hellerstein. Permission to use this program
  for any purpose is hereby granted without fee, provided that
  the author's name not be used in advertising or publicity
  pertaining to distribution of the software without specific written
  prior permision.


    THIS SOFTWARE PACKAGE IS PROVIDED "AS IS" WITHOUT EXPRESS
    OR IMPLIED WARRANTY.
    THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE PACKAGE,
    INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS.
    IN NO  EVENT SHALL THE AUTHOR (Daniel Hellerstein) OR ANY PERSON OR
    INSTITUTION ASSOCIATED WITH THIS PRODUCT BE LIABLE FOR ANY
    SPECIAL,INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER
    RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION
    OF CONTRACT,NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR
    IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE PACKAGE.


   WWWCOUNT and associated files were developed on the personal time of
   Daniel Hellerstein, and are not supported, approved, or in any way an 
   official product of my employer (USDA/ERS).


Questions or comments? Contact Daniel Hellerstein, danielh@econ.ag.gov