home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 35 Internet / 35-Internet.zip / wwwcount.zip / wwwcount.doc < prev    next >
Text File  |  1997-12-01  |  17KB  |  377 lines
  1. 28 Nov 1997. Disclaimer and contact at the bottom of this document.
  2.  
  3.                 WWWCOUNT: A Text & Graphical Counter for OS/2 Web Servers
  4.  
  5. WWWCOUNT provides a counter for OS/2 web servers.  It's major strength is 
  6. it's display flexibility: you can use it to display textual counters 
  7. (with a number of formatting options), or graphical digits (with a multitude 
  8. of digit styles to choose from). And it's free; use it however you like 
  9. (please let me know if you find it useful, or if you have problems with it).
  10.  
  11. WWWCOUNT can be invoked as a CGI-BIN script or as server side include.  
  12. Each method has it's own strengths and weaknesses:
  13.  
  14.  * As a CGI-BIN script.
  15.       When invoked as a CGI-BIN script, you MUST have RXGDUTIL.DLL installed 
  16.       on your web server.  RXGDUTIL is freeware that is available from 
  17.       http://www.bearsoft.com/abs/rexxgd.html.
  18.  
  19.  * As a server side include.  
  20.       WWWCOUNT can produce both text and graphical output.
  21.       However, your web server must understand the NCSA/HTTPD style of server 
  22.       side includes.  In particular, the EXEC cmd=  syntax must be supported.
  23.  
  24. *  In either method, to  display graphical digits, you'll need a set of digits.
  25.       WWWCOUNT comes with several sets, but there are lots more out there.
  26.       A great place to look is  http://www.digitmania.holowww.com; see
  27.       section V below for details on acquiring and using new graphical digits.        
  28.  
  29. ----------------------------------------
  30.  
  31. II. Installing WWWCOUNT
  32.  
  33. Installation of WWWCOUNT is fairly simple:
  34.  
  35. 1) UNZIP WWWCOUNT to an empty temporary directory.
  36.  
  37. 2) Copy WWWCOUNT.CMD to your server's CGI-BIN script directory.  If you intend 
  38.    to use WWWCOUNT as an EXEC server side include, some servers may expect 
  39.    to see such "ssi scripts" stored in a seperate directory; but most 
  40.    servers will look in the CGI-BIN script directory.
  41.  
  42. 3) Create a DIGITS directory under the root directory of your web tree.  
  43.    For example,  GoServe users should create a DIGITS sub-directory just under 
  44.    the GoServe Data Directory.
  45.  
  46. 4) Copy DIGITS4.ZIP to this DIGITS directory.
  47.  
  48. 5) UNZIP DIGITS4.ZIP.  Several subdirectories will be created, each containing
  49.    a set of "digit .GIFs".
  50.  
  51. 6) Optional: copy WWWCOUNT.HTM to you web directory (it's a demo).
  52.  
  53. 7) Configure WWWCOUNT.CMD.  In particular, you'll need to set the COUNTER_DIR,
  54.    ABS_COUNTER_IMAGE_DIR, and REL_COUNTER_IMAGE_DIR parameters (described 
  55.    below)
  56.  
  57. You are now ready to try it out -- WWWCOUNT.HTM is a good start, take a peek
  58. at it after you've seen it work
  59.  
  60. -------------------------------------
  61. III.  Parameters and Options
  62.  
  63. WWWCOUNT is controlled through user-configurable parameters contained in 
  64. WWWCOUNT.CMD, and through options you supply when invoking WWWCOUNT.  
  65. Options are specified in the URL that invokes WWWCOUNT, with each option 
  66. seperated (in the usual HTTP fashion) by a &.
  67.  
  68. IIIa. Short descriptions of user-configurable parameters (set in WWWCOUNT.CMD)
  69.  
  70. counter_dir : Where to store counter files
  71. no_path_translated : always use the counter_dir (ignores counter_dir 
  72.                      info in the options)
  73. rel_counter_image_dir : relative (to www root) directory containing "digit .GIFS"
  74. absl_counter_image_dir : fully qualified directory containing "digit .GIFS"
  75. create_file : create a counte file flag
  76. digits_nobr : add a <NOBR> to graphical SSI digits
  77. write_users : record address and time of each request
  78. suppress_logusers : always use write_users (ignore the loguser option)
  79. suppress_recent : Do no record "repetitive" requests from the same client
  80.  
  81. IIIb. Short descriptions of options (specified in the request)
  82.  
  83.   file : the name of the counter file (REQUIRED)
  84.   silent : If a silent is present, the .CNT file will be updated, but nothing
  85.            will be displayed.
  86.   nocommas : If present, every 3rd digit commmas are NOT written. Only used in
  87.              text mode.
  88.   width : minimum width of counter (padded with 0's if need be).
  89.   min : minimum value to count from (the default is 0)
  90.   max : maximum value to count to (the default is 2147000000)
  91.   rollover : if present, will reset counter to min when max is hit.
  92.   increment : add increment at each hit (typically, inc=1).
  93.   ith : if present, append a th,rd,st, or nd "suffix"
  94.   frame: if present, include a left and right frame around an SSI "graphical counter"
  95.   loguser : overrides the WRITE_USERS
  96.   graphic : Name of directory containing "digit .GIFS" (relative to 
  97.             REL_COUNTER_IMAGE_DIR)
  98.   img : CGI-BIN flag (REQUIRED for CGI-BIN invocations, ignored for SSI 
  99.         invocations)
  100.   imgalign : Image alignment (used with SSI graphical counter)
  101.   duration: Timespan that # of hits is computed over 
  102.  
  103.  
  104. IIIc. Longer descriptions of parameters
  105.  
  106. counter_dir=directory
  107.    A fully qualified name of a directory in which to store .cnt files.
  108.  
  109.     Example: counter_dir='d:\myserver\cntfiles'
  110.  
  111.    This is used when the PATH_TRANSLATED CGI-BIN variable is unspecified.
  112.  
  113.    To specify a PATH_TRANSLATED, use URLS of the form
  114.           <IMG SRC="/CGI-BIN/WWWCOUNT/DIR1/DIR2?options"
  115.    or
  116.           #Exec cmd="wwwcount/dir1/dir2?options"
  117.  
  118.    In both cases, the PATH_TRANSLATED would be: x:www\DIR1\DIR2
  119.    where x:\www is the root of your web tree.
  120.  
  121. no_path_translated=i
  122.   If you want to ignore PATH_TRANSLATED, and always put .CNT files in
  123.   the counter_dir (this may be a security/privacy measure), then set
  124.   no_path_translated=1 
  125.  
  126.         Example: no_path_translated=0
  127.  
  128.  
  129. rel_counter_image_dir 
  130.  
  131.     Set the "web" directory that contains the "digit images". This is
  132.     used when an EXEC ssi is used to create a graphics counter.
  133.     REL_COUNTER_IMAGE_DIR is used to form the several (digit specific)
  134.     IMG SRC=...   urls to be included in the html document.
  135.  
  136.     Note: Each different set of "digits"  should  be in it's own directory.
  137.           under the rel_counter_image_dir. 
  138.  
  139.                 Example: rel_counter_image_dir ='/digits'
  140.  
  141. abs_counter_image_dir
  142.      The fully qualified version of rel_counter_image_dir (used when
  143.      WWWCOUNT is invoked via an in-line image.
  144.  
  145.                 Example: abs_counter_image_dir ='d:\www\digits'
  146.  
  147.      WARNING: To use the "in-line" image mode of WWWCOUNT, you MUST
  148.               first install RXGDUTIL ( http://www.bearsoft.com/abs/rexxgd.html)
  149.  
  150. Create_file
  151.       1=create a .cnt file if none exists,
  152.       0=do not
  153.    If the counter file (passed to counter.rxx using the FILE= option) does 
  154.    not exist, and create_file=0, nothing will be returned.
  155.  
  156.                 Example: create_file=1
  157.  
  158. digits_nobr
  159.     Used when an EXEC ssi is use to create a graphics counter.
  160.        1 = do NOT allow line breaks in strings of  "graphical digits".
  161.        0 = Allow line breaks within the string of "graphical digits"
  162.      Note: if =1, the <NOBR>  element is used -- but note that webex 
  163.            and other html 2.0  browsers ignore <NOBR>.
  164.  
  165.                 Example: digits_nobr=1
  166.  
  167. Write_users
  168.  Store info on each request. 0=no, 1=yes.
  169.  Can be overridded by a LOGUSERS option.
  170.                 Example: write_users=0
  171.  
  172. suppress_logusers:
  173.      1 : Supress the "log users" option 
  174.          (a logusers option will override write_users)
  175.     0= do not suppress  
  176.  
  177.                 Example: suppress_logusers=0
  178.  
  179. suppress_recent
  180.    suppress inrementing if request is from a same client within
  181.    suppress_recent minutes. If 0, or if write_users=0, this is ignored 
  182.    (all requests are recorded)
  183.  
  184.                 Example: suppress_recent=0
  185.  
  186.  
  187.  
  188. IIId. Longer descriptions of options
  189.  
  190.  Otherwise, the options are:
  191.   file="filename" : Either value or file is REQUIRED.
  192.                     The name of the .CNT file (relative to the counter_dir).
  193.                     See below for a description of how to set the counter_dir.
  194.        value=num  : An integer value. No recording or incrementing, just display the value.
  195.        silent=""  : If silent=1, the .CNT file will be
  196.                     updated, but nothing will be displayed.
  197.     nocommas=""   : If nocommas=1, every 3rd digit commmas are NOT written
  198.                     This is implied if width>0. If not specified,
  199.                     commas WILL be included.
  200.     width=ndigits : minimum width of counter (padded with 0's if need be).
  201.                     Default is 0 -- which means "don't try to pad".
  202.     min=min_value : minimum value to count from (the default is 0)
  203.     max=max_value : maximum value to count to (the default is 2147000000)
  204.     rollover=""   : If  rollover=1, will reset counter to min when max is hit.
  205.                     Default is to not rollover.
  206.     increment=inc : add inc at each hit (typically, inc=1). 
  207.                     If increment=0, then the counter is NOT augmented, and
  208.                     a user-entry is NOT added.
  209.     ith=""        : If ith=1, append a th,rd,st, or nd "suffix"
  210.                     to the number (1st, 2nd, 3rd, 4th, etc).
  211.                     Default is do NOT add this suffix.
  212.     frame=""      : If frame=1, and an SSI graphical counter is being created, then
  213.                     put a left and right frame image on the ends of the counter.
  214.    loguser=arg    : If ARG=YES or NO, and SUPPRESS_LOGUSER<>1, then 
  215.                     override the WRITE_USERS variable. YES = record client,
  216.                     NO=Do NOT record client.
  217.      graphic=arg  : The name of the directory (relative to the REL_COUNTER_IMAGE_DIR)
  218.                     containing the desired "digit GIFS". Note, you can 
  219.                     use digit=arg instead of graphic=arg.
  220.         img=xxx   : XXX can be anything -- the prescence or an img= option
  221.                     signals that this is an "in-line image"; hence, WWWCOUNT
  222.                     will return a .GIF file.  One convenient trick is to have
  223.                     IMG=name.gif as the late option; since some browsers get
  224.                     upset if a .gif does not appear at the end of an in-lined
  225.                     image's URL.
  226.                     WARNING: To use the "in-line" image mode of WWWCOUNT, 
  227.                              you MUST first obtain RXGDUTIL
  228.                              (http://www.bearsoft.com/abs/rexxgd.html)
  229.      imgalign=arg : Arg should be MIDDLE, TOP, or BOTTOM -- effects the alignment
  230.                     of digits created when imgtype is specified.
  231.   duration=#days  : If duration>0, then the number of hits in the last "#days" will be displayed.
  232.                     For example, duration=1 means that the "number of hits today" is displayed.
  233.                     Similarly, duration=7 means "the number of hits in the last 7 days"
  234.                     will be displayed.
  235.                     Notes:
  236.                          *  For this to work, you MUST set  write_users=1. 
  237.                             If write_users<>1, then a value of 000 is displayed.
  238.                          *  The actual number of hits is displayed (minval,  rollover,
  239.                             etc. are ignored).
  240.                          *  If duration=0, it is ignored (i.e.; it's the same as not including
  241.                             a duration option).
  242.                          *  Hint: to report the total # of hits, and the hits in the last n days,
  243.                                   use  two calls, with the second containing an increment=0
  244.                                   option.
  245.                          *  Example:
  246.                              If duration = 7, and today is monday, then the number of
  247.                              hits since last Tuesday (inclusive) is displayed.
  248.  
  249.  
  250. IIIe. Some examples
  251.  
  252.  
  253. This example produces an in-line image containing the counter
  254. (requires RXGDUTIL.DLL).
  255.      <img src="/cgi-bin/wwwcount?file=index&graphics=MBC&width=6&img=foo.gif">
  256.  
  257.   Note the inclusion of  IMG=foo.gif -- you must  include an IMG=a_value to
  258.   signal that "this is a CGI-BIN request".
  259.   Furthermore, some browsers  get upset if in-line image URLS don't end with
  260.   a .GIF.
  261.  
  262. This example produces at textual counter
  263.      <!-- #exec cmd=/cgi-bin/wwwcount?file=gotme&ith=1 -->
  264.  
  265. This example produces a graphical digits counter -- it returns a sequence of 
  266. <IMG elements, and does NOT require RXGDUTIL.DLL
  267.   <!-- #exec CMD=wwwcount?&file=at4&logusers=0&graphic=goldodo&frame=1 -->
  268.  
  269. IV. Specifying directories.
  270.  
  271. WWWCOUNT needs to be informed about several directories.  These include:
  272.  
  273.    * the location of "counter" files
  274.    * the location of "digit gifs"
  275.  
  276. Counter files are files used to store the number of hits, and other 
  277. information (such as a list of requesters).  There are basically two ways
  278. of specifying where the "counter" files are to be stored                                                                    
  279.     i) With the counter_dir parameter.  Counter_dir should contain a
  280.        fully qualified directory name.
  281.     ii) By including extra path information in the request.  Extra path
  282.         information follows the wwwcount/ and precedes the ?. For
  283.         example:
  284.               <img src="/cgi-bin/wwwcount/dir1/sub2?file=joe"
  285.         has /dir1/sub2 as the "extra path information".
  286.         This is appended to the  web root directory to form the CGI-BIN
  287.         PATH_TRANSLATED variable.  Thus, if your web root directory is D:\www, 
  288.         the "counter" file would be D:\WWW\DIR1\SUB2\JOE.CNT
  289.  
  290.         If you want to store these counter files in a secure place, we
  291.         recommend not including extra path information.  This is especially
  292.         relevant if you are recording requesters (WRITE_USERS is enabled) --
  293.         you probably don't want to allow the smarter-then-average surfer to
  294.         have access to such private information.
  295.  
  296. The REL_COUNTER_IMAGE_DIR and ABS_COUNTER_IMAGE_DIR are used to tell WWWCOUNT
  297. where the "digit GIFS" are.  REL_COUNTER_IMAGE_DIR is used to form URL's 
  298. pointing to these GIFS.  For example:
  299.      REL_COUNTER_IMAGE_DIR='http://mysite.net/digits'
  300. or, more succinctly
  301.      REL_COUNTER_IMAGE_DIR='/digits'
  302. Note that REL_COUNTER_IMAGE_DIR is used when an EXEC ssi requests "digit GIFS".
  303.  
  304. ABS_COUNTER_IMAGE_DIR should point to the "fully qualified" directory refered
  305. to by REL_COUNTER_IMAGE_DIR.   Note that ABS_COUNTER_IMAGE_DIR is used
  306. when an in-line imaage is being created.
  307.  
  308.                         ---------------------------
  309.  
  310. V. Setting up a new digit set.
  311.  
  312. It's quite easy to use a new set of digits -- well, it takes a few steps,
  313. but none are difficult. The basic trick is to find a set of files named 0.GIF,
  314. 1.GIF,...,9.GIF; with each file containing a picture of the appropriate digit.
  315.  
  316. The following outlines the necessary steps:
  317.  
  318.   1) First, you need to find a source for "gif-digits". As mentioned above,
  319.      a great place to look is  http://www.digitmania.holowww.com. 
  320.      Let's go there now ....
  321.  
  322.   2) Hmmm, so may choices. How about  katt 005 from the "katt collection" 
  323.     (http://www.digitmania.holowww.com/zip/katt005.zip). 
  324.  
  325.   3) After downloading the digit files (or .ZIP file), place them in their "own"
  326.      subdirectory under  REL_COUNTER_IMAGE_DIR directory.  
  327.      For example, if REL_COUNTER_IMAGE_DIR=D:\WWW\DIGITS, 
  328.         i) Create D:\WWW\DIGITS\KATT005
  329.         ii) Copy KATT005.ZIP to D:\www\DIGITS\KATT005
  330.         iii) CD to D:\WWW\DIGITS\KATT005, and UNZIP KATT005
  331.  
  332.   4) Change the names to be 1.GIF, 2.GIF, etc.  The easy way to do this is with:
  333.              D:\WWW\DIGITS\KATT005>ren ?*.GIF ?.GIF
  334.     
  335.   5) If the digit set has a "left" and/or "right" pieces, name them L.GIF and
  336.      R.GIF (see the GOLDODO digits, that comes with WWWCOUNT, for an example).
  337.      Note that KATT005 does NOT have left and right pieces; so the frame=1
  338.      option should NOT be used.
  339.  
  340.   6) You are now ready to use your new digits.  For example, include the following
  341.      in an HTML document:
  342.      <!-- #exec CMD="wwwcount?&file=cnt_file&graphic=katt005" -->
  343.      Note that the results will be stored in CNT_FILE.CNT.
  344.  
  345.  
  346.                         ---------------------------
  347.  
  348. Disclaimer:
  349.  
  350.   Copyright 1997 by Daniel Hellerstein. Permission to use this program
  351.   for any purpose is hereby granted without fee, provided that
  352.   the author's name not be used in advertising or publicity
  353.   pertaining to distribution of the software without specific written
  354.   prior permision.
  355.  
  356.  
  357.     THIS SOFTWARE PACKAGE IS PROVIDED "AS IS" WITHOUT EXPRESS
  358.     OR IMPLIED WARRANTY.
  359.     THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE PACKAGE,
  360.     INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS.
  361.     IN NO  EVENT SHALL THE AUTHOR (Daniel Hellerstein) OR ANY PERSON OR
  362.     INSTITUTION ASSOCIATED WITH THIS PRODUCT BE LIABLE FOR ANY
  363.     SPECIAL,INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER
  364.     RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION
  365.     OF CONTRACT,NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR
  366.     IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE PACKAGE.
  367.  
  368.  
  369.    WWWCOUNT and associated files were developed on the personal time of
  370.    Daniel Hellerstein, and are not supported, approved, or in any way an 
  371.    official product of my employer (USDA/ERS).
  372.  
  373.  
  374. Questions or comments? Contact Daniel Hellerstein, danielh@econ.ag.gov
  375.  
  376.  
  377.