26 Dec 2002:  Description of the SREhttp/2 COUNTER.REX addon.

Abstract:
  COUNTER.REX is a flexible "number of hits"  generator and 
  request-information recorder. It can be invoked in a number of 
  different manners.

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

Contents:

A) Introduction
B) How to Use COUNTER.REX
C) Parameters that can be set in COUNTER.CFG
D) Options that can be set when COUNTER.REX is invoked
E) Matching characters to GIF files -- the "match file"
F) Using the COUNTER procedures
G) Miscellaneous topics
H) A simple example


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


A) Introduction

COUNTER.REX is a flexible "number of hits"  generator and request-information
recorder. It can be invoked in a number of different manners:

 1) As a server side include for textual counters, or multiple-IMG odomoters.
    This is an alternative to using <!-- REPLACE HITS -->.

 2) As an in-line image to create a black and white single-IMG odometer.


 The principal advantages of COUNTER.REX are:
   i) In text mode, it has several display options, including
      inclusion of commas and a "st", "nd", etc. suffix
  ii) Document unique ".CNT" file are used to store results.
      In contrast, the <!-- REPLACE HITS --> SSI uses a single "database"
      file for all hit-counters (HITS.CNT).
 iii) Request specific information (such as IP address, time of request,
      and referer) can be stored in these .CNT files.
 iv)  Suppression of hits from "superusers" and from "recent requesters"
      can be invoked.
  v)  Flexible odometer style counters, using one of the zillion gif-digit
      collections available on the WWW, are easily created.

Furthemore, you can also COUNTER.REX to create simple "graphical messages".
This requires a bit more setup (you have to obtain "character GIFS",
and create a "match file") -- the details are explained in section E. 

Acknowlegments: COUNTER.REX is heavily adapted from "The SSI Hit Counter" of 
                William  Herrin  (http://www.why.com/herrin).
                Steve Ryckman (http://www.simsware.com) contributed several 
                ideas.

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


B) How to use COUNTER.REX

  1) Note that a number of "digit" files should have been installed to your
     SRE2K\SREHTTP2\IMGS\DIGITS subdirectory (under the SRE2003 
     "data directory").
     See the READ.ME (in SRE2K\SREHTTP2\IMGS\DIGITS) for details on adding 
     new digit files!

  2) You may  want to change a few variables in COUNTER.CFG (described 
     below).

     Actually, as with other SREhttp/2 configuration files (such as 
     SRE_UTIL.CFG), you can have host-specific versions of COUNTER.CFG -- 
     just place the desired version of COUNTER.CFG in the appropriate 
      "host-specifc" subdirectory of SREHTTP2\CFG.

     Note: the SREhttp/2 configurator contains an on-line configurator for
            COUNTER.CFG.

 3) As mentioned above, there are several ways you can invoke COUNTER.REX

    a) As a "server side include" to create a text counter.
       Place  keyphrases into  your  HTML documents. 
       These keyphrases should have the form:
          <!-- INTERPRET FILE COUNTER.REX  option_list , noaugment-->
       where:
            * option_list: a space delimited list of formatting instructions
            * noaugment: if 1, do not augment the count (the current value is
                         used).

    b) As a "server side include" to create a multi-IMG graphical odometer
       Place  keyphrases into  your  HTML documents. 
       These keyphrases should have the form:
            <!-- INTERPRET FILE COUNTER.REX  option_list , noaugment-->
       where:
            * option_list: a space delimited list of formatting instructions
                           that contains a DIGITS=gif_set option
        This will cause several <IMG SRC= > elements to be inserted into
        the HTML document, each of which points to an appropriate gif-digit 
        image.

     c) As an in-line image (a simple, single-image black on white "odometer").
        Place "in-line images" elements in your HTML documents. 
        For example:
              <IMG SRC="/COUNTER.REX?option_list"> 
        elements in your HTML documents, where:
            * option_list is an & delimited list of formatting instructions
              that contains the XBITMAP=arg option
        This will create a x-bitmap (black and white) image.

      d) As a procedure called by an addon.
         COUNTER.REX is basically a front-end to the SREH2_COUNTER 
         procedure. You can call SREH2_COUNTER directly (say, from
         an addon), or you can use several simpler procedures.
         See section F for the details.
        
                ----------------------------------------------

C) Parameters in COUNTER.CFG 

COUNTER.CFG contains several parameters that you may wish to modify. 
These include:

   common_log_format -- use common-log format when recording client info
   counter_dir -- where to place .CNT files
   counter_image_dir -- the location of sets of gif-digit images
   create_file -- create a .CNT file if none exists
   digits_nobr -- Add a <NOBR> element around the digits. or put 'em in a table
   force_break -- Add a <BR> after each digit
   frame -- Use special left and right end "framed" digits
   suppress_recent -- do not augment repetitive hits from the same client
   suppress_loguser -- ignore the LOGUSER option
   suppress_superusers -- do not augment hits from SUPERUSERS
   save_xxx -- several variables (xxx) that specify information to record
   write_users -- record client information in the .CNT file

In greater detail ...

 * Common_log_format.
      There are two output formats: Common-log format, and customized.
      For common log format, set common_log_format=1.
      For further details, see the description of  the save_ variables below.

 * Create_file: 
     If create_file=1, will create a .CNT file if none already exists. 
     Otherwise, when no .CNT file exists, COUNTER.REX will return nothing.
     If the requested .CNT file does exist, create_file is ignored.

 *  Counter_dir :

     An absolute directory: where to store .cnt files. 
       Examples  D:\SRE2003\SREHTTP2\COUNTERS
     Or, use 0 to use defaults....
    The default is determined by several factors:
      I) If neither FILE or FILE_WWW are specified
             i)  For <!-- INTERPERT ---> : use documents own directory 
                 (and name.cnt)
            ii) Otherwise, use SREHTTP2\LOG\DEFAULT.CNT
     II) If FILE is specified, relative to SREHTTP2\LOG
    III) If FILE_WWW is used, relative to the possibly host-specific 
          data directory  

    For example, if:
      > counter_dir=0,
      > a selector of /DIR1/FOOBAR.HTM invokes  COUNTER.REX, 
      > the SRE2003 data directory is D:\WWW; 
    then the .CNT file should be in D:\WWW\DIR1 (say, D:\WWW\DIR1\FOOBAR.CNT).

 * Counter_image_dir:
    Specify where to find "DIGIT gif images".
    These "digit gif images" are used when COUNTER.REX creates multi-image
    "odometer" style counters. They can also be used by COUNTER.REX to
    create explicit messages.

    Counter_image_dir can either be:
        i) a URI that points to the root of the image directories. 

       ii) A space delimited list containing the URI that points to the root 
           of the image directories, AND the  absolute directory corresponding 
           to this URI 

    The second form is especially useful on  a multi-site server -- you can
    specify a fully qualified URI (starting with http://) pointing to
    the site (and directory) containing the DIGIT images, and its fully
    qualified directory. When you do this, you won't have to replicate the
    DIGIT files (you can use the same files for all the sites supported
    by your server).
   

    Examples:

    * counter_image_dir=http://foo.bar.net/cntimgs/
        or, more simply
      counter_image_dir=/cntimgs/

    * counter_image_dir=http://site1.myplace.org/images/digits F:\SITE1\IMG\DIG
         (where SREhttp/2 will map site1.myplace.org/images/digits to 
          F:\SITE1\IMG\DIG)

    *   to use the default of /sre2k/srehttp2/imgs/digits (under the possibly host
        specific default directory)
      counter_image_dir=0
    
    

    Notes:
        * Each different set of digit (or alphanumeric) GIF images should
          be in its own sub-directory under the COUNTER_IMAGE_DIR.
        * To prevent COUNTER.REX from creating these multi-IMG odometers,
          set counter_image_dir=-1
        * The default directory contains several subdirectories, each of which
          contains a set of "gif digits". See the READ.ME,
          in SRE2K\SREHTTP2\IMGS\DIGITS,for the details

 * Digits_nobr
   If digits_nobr=1, then a <NOBR> ... </nobr> will be placed around the
   <IMG SRC= > elements. On modern browsers, this will guarantee that
   the gif-digit image will not wrap to a new line

   Alternatively, if digits_nobr=2 then use a one-cell <TABLE> to display 
   digits. Since <NOBR> is not in the html 4.0 spec, this may be preferred.

 * Force_break
   Add a <BR> before or after each digit in the message.  

      0 = Normal, don't force <BR> before/after digits.
      1 = Place a <BR> in front of each digit.
      2 = Place a <BR> after each digit. 

    This is useful if you want a vertical array of digits (rather then
    a horizonal array).

    Note that if FORCE_BREAK>0, then DIGITS_NOBR is ignored.

 * Suppress_recent: 
    Used to suppress generation of false "new hits". 
    SUPPRESS_RECENT is ignored if WRITE_USERS <> 1.

    If enabled, the user list is checked  against the client's ip address. 
    If:
        i) a matching entry (by ip address) exists
       ii) it is less then suppress_recent minutes old,
    Then:
        i) the counter is NOT incremented
       ii) the current value is used in the server-side include

 * Suppress_logusers:
     If suppress_loguser=1, then suppress the LOGUSER option.  That is, 
     if suppress_loguser=1, then always use the value of the write_users
     variable, and ignore the LOGUSER option (see section D for
     details on LOGUSER).

 * Suppress_superusers:
     If suppress_superusers=1, then if the request is from an SUPERUSER (as 
     listed in the possibly host-specific SUPERUSERS parameter in SREHTTP2.CFG), 
     the counter will not be incremented.

 * save_ variables (and common_log_format):
      There are two output formats: Common-log format, and customized.
       a)  To select "common-log" format, set common_log_format=1.  When
           enabled, entries of the form:
121.61.65.143, 4284.87433, someone.clients.org - USERNAME [21/Sep/2002:21:29:58 -0500] "GET /status.sht HTTP/1.0" - 2633
           will be written (note that the status code is always set to -, and 
           the size is the size of the requesting document).

       b) For customized format, you enable (by setting =1) one, several, 
          or all of the following variables:
              save_ipname:    Write the "dotted" IP Name (if none available,
                              save IP address)
              save_username:  Write the  "username"  (if available)
              save_time:      Write the time, in 13:01:33 format
              save_date:      Write the date, in 5 Feb 1996 format
              save_docname:   Write the "request selector"
              save_bytes:     Write the  size of the file.
              save_referer:   Write the "referer (if available)
              save_browser:   Write the "user-agent"

          Note: in both cases, the client's ip address and the 
                SREH2_CURRENT_SECOND style of date/time are always written 
                (given that write_users=1)


 * Write_users :
    If write_users=1, then along with the "number" of hits, client specific 
    information is recorded -- with the common_log_format and save_ variables
    specifying what & how to write.

    Notes:
        * if you enable the write_users option, due to privacy concerns
          we STRONGLY recommend using a web-inaccessible counter_dir 
          (i.e.; set COUNTER_DIR='x:\sre2003\srehttp2\workdata\counters')
        * you may want to reset these .CNT files every so often (since large 
          files will impact response time). 
        * only the count is written to the "requesting document".
          The "user information" is written for the sake of the webmaster


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


D) Description of COUNTER.REX "option list" options

The simplest option list is no option list.  If there is no option
list, a .CNT file (with the same name as the requested document) will
be used.

Notes:
 * If you are using a counter_dir 
   (say, counter_dir='x:\sre2003\srehttp2\workdata\counter'),
   and you have files with the same name in several directories, they
   will end up augmenting the same counter.
 * For the "simple, single-image odomoter" (IMG SRC="/COUNTER.REX..">
   variant, you MUST include the XBITMAP option in the option list.

The options are:
   digits  -- the gif-digit images directory to use for multi-IMG odometers
  duration -- number of days to count hits from
     frame -- put "left and right" frame bars on ends
      file -- name of the .CNT file to use
  imgalign -- how to align the multi-IMG odometer
 increment -- Quantity to increment counter by
       ith -- add a 'st, 'nd, etc. to textual counters
   loguser -- record client info to the .CNT file
       min -- minimum value
       max -- maximumu value
  nocommas -- do not include commas
  rollover -- reset to min when max is hit
       sel -- selector to use when recording information
    silent -- augment but do not display
 table_digits -- put graphic digits in a small table (modified digits_nobr)
   xbitmap -- type of single-IMG odometer to create
     value -- integer value -- use this instead of reading a value fron file
     width -- # of digits to use (padded with zeros if necessary)

Note that either file or value MUST be specified; all other others are
optional.

In greater detail:

 *  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"
    is displayed.
    Notes on duration=#days:
      >  For duration=#days 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 is 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.



 * frame:
   If frame=1, then special left and right "frame bars" gifs will be
   placed on the the left and right characters ends of the 
   multi-IMG (DIGITS variant) odometer.

   This should be used with "framed" digits; which typically come with
   special left-end and right-end (or perhaps a single "both ends") bars.
   The names of the left bar should be L.GIF, and R.GIF for the right-end
   bar -- if only one bar is provided, copy it to L.GIF and R.GIF.
   

 *  file=filename 
    The name of the .CNT file; relative to the counter_dir, or relative to 
    the default counter_dir directory (if counter_dir=0). 
    You should NOT include a .CNT extension in the filename.
    You can include relative path information. 
    Examples:
        file=thisone
        file=cnts/thatone
    In the second example, a cnts/ subdirectory must exist (under the COUNTER_DIR
    directory, or under the "invoking files" directory)

 * file_www=filename
    The name of the .CNT file -- relative to the possibly host specific
    data directory!  Contrast this to FILE=, which (if COUNTER_DIR=0)
    may place .CNT files in the SREHTTP2\LOG directory.

 *  xbitmap=arg  
    If xbitmap=1 then a white on black background single-IMG odometer 
                    graphic will be created and sent to the client. 
    If xbitmap=0, then a black on white background single-IMG odometer 
                       graphic will be created.  
    Notes on xbitmap
      > this "xbitmap" variant of COUNTER.REX must be used in an
        <IMG element. It should NOT be used as an SSI-style counter.
      > xbitmaps are simple black on white (or white on black) images.
      > when xbitmap is specified, nocommas is set to 1, and ith is set to 0.
      > If you specify xbitmap, and write_users=1, it is often wise to
        specify a SEL option 

 *  loguser=arg
    If ARG=YES or NO, and SUPPRESS_LOGUSER=0, then ...
        YES = Record client,  
        NO  = Do NOT record client.

 * digits=arg   
   If arg is the name of a "gif-digit images subdirectory",
   then a series of IMG elements are returned to the client 
   that point to the appropriate images. 

 * imgalign=arg   
   arg should be MIDDLE, TOP, or BOTTOM -- it effects the alignment
   of digits created when DIGITS is specified.

 * 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.
   This is the same as using a 0 as the second argument (the NOAUGMENT argument)
   in an <!-- interpret  --> SSI.

 * ith="" 
   If an ith="" is specified, append a th,rd,st, or nd "suffix"
   to the number (1st, 2nd, 3rd, 4th, etc).
   The default is to NOT add this suffix.

 * min=min_value
   Minimum value to count from (the default is 0)

 * max=max_value
   Maximum value to count to (the default is 2147000000)

 * nocommas=""   
   If a nocommas="" is specified, every 3rd digit commmas are NOT written
   This is implied if width>0. By default, commas WILL be included.

 * rollover=""
   If rollover="" is specified, will reset counter to min when max is hit.
   Default is to not rollover.

 * sel=selector 
   If write_users is enabled, the value of SEL will be  
   written to the "selector" field (in the .CNT file).
   If SEL is not specified, the selector of the document that "invoked"
   COUNTER.REX will be used.  
   Note: If you are using the XBITMAP option,  you should also use the
         SEL option.

 *  silent=""  
    If a silent="" is present, the .CNT file will be updated, but nothing 
    will be displayed.

 *  table_digits=arg
    arg is 0 or 1: 0 means "use <NOBR> ... </NOBR>,
                   1 means "use <TABLE>...</TABLE>
     table_digits is used ONLY when digits_nobr>0: if digits_nobr=0, then
     table_digits is ignored.

     Note: <NOBR> is not part of the formal HTML 4.0 specc
           (see  http://www.w3.org/TR/REC-html40/)

 * value=nnnnnn
   IF value=nnn is specified, where nnnnnn is an integer (of any length),
   the COUNTER will NOT attempt to find the "hit count". Instead, it will
   just use the value of nnnnn.
       
   Note: if you've specified a "font" (such as GOLDBLOK), then nnnnnn
         can be a text string (not just numbers)

 * width=ndigits 
   Minimum width of counter (padded with 0's if need be).
   The default is 0 -- which means "don't try to pad".

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


E) Matching characters to GIF files -- the "match file"


COUNTER.REX can also display non-digit characters. To enable this capability, a
special "match file" must be specified. This match file instructs COUNTER.REX 
as to how to display the various characters in a message.

  For example, if you wanted to display a digital clock, 
  you can use a match file to specify the GIF files to use for 
  the  numeric digits and for the  :, A, P, and M character.

Match files are ascii (text) files.  They must be:

 i) located in the same directory as the digit (and/or character) .GIF files
ii) named DDD.IND, where DDD is the name of the subdirectory  (the "digit name").

For example, for the "TWOTURT" digits and characters 
  a) digit and character.GIF files are located in the MBC subdirectory 
     of the directory pointed to by COUNTER_IMAGE_DIR
  b) the "match file" for TWOTURT must be named TWOTURT.IND, and must
     be located in this TWOTURT subdirectory

The structure of "match file" is fairly simple. Each line of 
the match file is an entry (except for blank lines and comment lines
that begin with 2 semi-colons).  Each entry consists of a single
character, followed by a file name (the file name should NOT contain
path information). For example:

      ;; comment lines start with 2 semi colons
      A  A.GIF
      B  B.GIF
      b  BLC.GIF

In addition, you should have 4 special files:
  SPACE.GIF -- used for spaces
  DEFAULT.GIF -- used for  missing characters
  LFRAME.GIF -- the "left frame". 
                Note: if a match file is not available, L.GIF is
                      used as the "left frame"
  RFRAME.GIF -- the "right frame"
                Note: if a match file is not available, R.GIF is
                      used as the "right frame"

Notes:

  * All the .GIF files MUST be in the "digit name" directory. Thus,
    you must NOT specify path names!

  * CaSe matters --  no attempt is made to match lower case
    characters to upper case entries in the match file. However,
    see the next note ....

 * If no matching entry exists for a given character,
    then a x.GIF file is assumed for; where x is
    the character to be displayed. For example:
        if no entry exists for the Z (or z) character,
        then Z.GIF will be used.
    
  * If the specified (either explicit, or default) .GIF file does not
    exist, DEFAULT.GIF is used. If DEFAULT.GIF can not be found, 
    the character is ignored.

  * For a much richer "character to image" utility, see the GIF_TEXT
    addon --- http://srehttp2.srehttp.org/apps/gif_text/


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


F) Using the SREH2_COUNTER procedures

As a convenience to ambitous webmasters who'ld like to create addons
that contain graphical counters, it's easy to call special versions of
COUNTER.REX as a REXX procedure.  In particular, you can use the
sreh2_COUNTER, sreh2_DIGITS or  sreh2_XBITMAP "macrospace" procedures.

  * sreh2_XBITMAP will produce a "xbitmap" (black and white) image
    of a string of digits, and return it to the client.  
         sreh2_XBITMAP is akin to using COUNTER.REX with an XBITMAP option,

  * sreh2_DIGITS will produce a text string of URLS that point to the 
    appropriate set of digits.
         sreh2_DIGITS is akin to using COUNTER.REX with a DIGITS option.

Both of these "macrospace procedures" are available to all SREhttp/2 addons; 
and can be called just like any other REXX procedure.

sreh2_XBITMAP is  called with:

  astatus=sreh2_XBITMAP(anumber,ndigits,doreverse)

where
   astatus  : status message
   anumber : a number to display (a string of digits)
   ndigits : optional -- the number of digits to display. 
             If ndigits is longer then the number of characters in anumber,
             then 0's will be used as a padding character.
  doreverse: optional -- if 1, then a white on black image is created. 
             Otherwise, a black on white image is created.

Note that the sreh2_xbitmap returns the x-bitmap image directly to the client


sreh2_DIGITS is called with:

    txtstring=sreh2_DIGITS(amess,digit_name,nd,useframe,nobr,opts,imgsel,imgdir)

where:
  txtstring :  a text string containing a sequence of <IMG elements, that
               point to the appropriate graphical digits

      amess : a string of characters, typically-but-not-always digits,
                  to display 

 digit_name : the name of the subdirectory containing the digit, 
              and/or character-image, .GIF files.  
              This subdirectory must be relative to the
              imgdir directory (as specified below).

              If digit_name is not specified, WHITBLAK is used.  

The remaining arguments are optional.

         nd : the number of characters to display. 
              If nd is longer then the number of characters in amess...
                a) if amess only contains digits, then 0's will be
                   used as a padding character 
                b) if amess contains non digit charcters, the "default"
                   character (specified in the "match file") is used
                   as a padding character

   useframe : if 1, then include a "left and right" frame
              around the characters (see the "frame" option above for details)

       nobr : if 0, then do NOT put a <NOBR> and </NOBR> around the
              IMG elements (that comprise the message)

     opts   : a string to be included in the IMG elements. 
              For example:
                ' ALIGN=CENTER VALIGN=TOP'
                ' VALIGN=MIDDLE WIDTH=12 HEIGHT=12 '
              In other words, opts can be a list of any IMG element
              modifers.
              Note that this "opts" list is included in all IMG elements,
              including "frame" elements.

     imgsel : the "counter_image_dir" selector.
              If not specified, a value of "SRE2K/SREHTTP2/IMGS/DIGITS" 
              is used.

     imgdir : Absolute path pointed to by the imgsel. If not specified, 
              the SRE2K\SREHTTP2\IMGS\DIGITS subdirectory (of the SRE2003 
              data directory) is used.
        
Notes:

   * sreh2_DIGITS will look for, and use-if-found, a "match file" (as
     described in section E above).

   * For an example of how these procedures can be used, see the 
     description of the TSTDIGIT.CMD addon (in section H below).



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

G) Miscellaneous topics 


 * The following "digit/character" sets are installed with SREhttp/2
        
    BRUSH (digits only) : white on black, italic style brush strokes
    MBC   (digits only) : white letters on black balls
    GARA  (digits only) : black on white font (garamond?)
    GOLDODO (digits only) : Black letters on an gold "odometer" background
    PDP    (digits only) : Pink on black, 2d calculator style 
    CALC     : Purple on black, 3d calculator style
    GOLDBLOK : 3d, shiny gold on black (somewhat blocky style)
    WHITBLAK : White on black, sort of fat characters

    The DIGSAMPL.HTM, in SRE2K/SREHTTP2/IMGS/DIGITS, demonstrates the use of
    several of these digits sets.


 * Example of use as a simple, black and white single-IMG odometer

       <IMG src="/COUNTER.REX?file=test1&width=5&xbitmap=REVERSE">
       <IMG src="/COUNTER.REX?file=test2&increment=0&xbitmap=NORMAL">

    Note the use of & as an argument seperator!

*  Using COUNTER.REX to return a fancier, multi-IMG odometers.

  To use COUNTER.REX to return multi-img odomoters, consisting of a 
  series of <IMG SRC= > links to gif-digit images on your server,
  you should use the DIGITS option.
  For example:

      <!-- INTERPRET FILE COUNTER.REX FILE=bar1 DIGITS=FLAME -->

  will  use the "flame" digits to display the current count.  For example,
  if the count (as stored in bar1.cnt) is 12, the preceding

  <!-- INTERPRET ... --> would lead to the following SSIs (in the document 
  that invoked COUNTER.REX):

      <img src="/cntimg/FLAME/1.gif" alt="1">
      <img src="/cntimg/FLAME/2,gif" alt="2">  

  where "/CNTIMG" is the value of the counter_image_dir variable.

  Thus, to use this option, you must obtain a set of (at least) ten
  .GIF files with the names 0.GIF,..,9.GIF.  Fortunately, these
  are common on the web -- a great resource for these beasts is 
         http://www.digitmania.holowww.com.
  Note that if you use the FRAME option, you'll need 12 files.

  For a "framed counter, try:
      <!-- INTERPRET COUNTER.REX file=foobar2 digits=goldodo frame=1  -->


 * Examples of use as a textual server side includes:

   <!-- INTERPRET FILE COUNTER.REX file=foobar -->
   <!-- INTERPRET FILE COUNTER.REX file=foobar2 silent="" -->
   <!-- INTERPRET FILE COUNTER.REX file=foobar3 min=10 max=20 inc=2 width=5
                                  rollover="" ith="" -->
   <!-- INTERPRET FILE COUNTER.REX file=foobar2 nocommas="" , 1  -->
   <!-- INTERPRET FILE COUNTER.REX file=foobar  duration=10 -->

   <!-- INTERPRET FILE COUNTER.REX file=foobar2 digits=mbc  -->


   Note that when called as a server side include, you don't need to
   enclose the values in double quotes (").  Also note that space is 
   used as an argument seperator.

 * In .CNT files: blank lines, and lines starting with a semi-colon,
   are ignored (they are treated as comments)

 * Suppress_recent is ignored if write_users does not equal 1


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


H) Miscellaneous


A demo:
  You can use CNTDEMO1.SHT and CNTDEMO2.SHT to demonstrate COUNTER.REX


The TSTDIGIT.CMD addon:

The TSTDIGIT.CMD addon demonstrates how one can use sreh2_DIGITS and 
sreh2_XBITMAP. It's fairly well commented, and should help illustrate
how one canuse these two functions.

To see what TSTDIGIT does, you should hit your web server with:
     /TSTDIGIT?my+message

This will cause:
 a) "my message" (without the quotes) to be displayed using
     the "GOLDBLOK" character set; 
 b) the current request number to be displayed using:
       i) the GOLDODO digits
      ii) a normal x-bitmap
     iii) and a reversed x-bitmap

Actually, TSTDIGIT understands a few options; which can be invoked using
     /TSTDIGIT?option_list
Where option list has the form:
   opt1=val1&opt2=val2&..

Valid options, and the values they expect, include:

   MESS = a message (with + used for spaces)
   FONT = font to display MESS with 
   XBITMAP = create an xbitmap file (FONT and FONT2 are ignored)
             of the current request number. valn is 0 (plain) or
             1 (reversed)

For example:
    /TSTDIGIT?mess=hello+world&font=Goldblok

Whey XBITMAP is specified, then TSTDIGIT will return an X-Bitmap image.
Otherwise, TSTDIGIT will return a text/html document, which will contain
IMG elements that point back to TSTDIGIT.


.end of COUNTER.TXT
