home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 35 Internet / 35-Internet.zip / srev13g.zip / COUNTER.DOC < prev    next >
Text File  |  1999-06-18  |  33KB  |  782 lines
  1. 22 April 1999:  Description of the SRE-http COUNTER.RXX addon.
  2.  
  3. Abstract:
  4.   COUNTER.RXX is a flexible "number of hits"  generator and 
  5.   request-information recorder. It can be invoked in a number of 
  6.   different manners.
  7.  
  8.                 ----------------------------------------------
  9.  
  10. Contents:
  11.  
  12. A) Introduction
  13. B) How to Use COUNTER.RXX
  14. C) Parameters that can be set in COUNTER.RXX
  15. D) Options that can be set when COUNTER.RXX is invoked
  16. E) Matching characters to GIF files -- the "match file"
  17. F) Calling COUNTER.RXX as a procedure.
  18. G) Miscellaneous topics
  19. H) A simple example
  20.  
  21.  
  22.                 ----------------------------------------------
  23.  
  24.  
  25. A) Introduction
  26.  
  27. COUNTER.RXX is a flexible "number of hits"  generator and request-information
  28. recorder. It can be invoked in a number of different manners:
  29.  
  30.  1) As a server side include for textual counters, or multiple-IMG odomoters.
  31.     This is an alternative to using <!-- REPLACE HITS -->.
  32.  
  33.  2) As an in-line image to create a simple, black and white single-IMG odometer.
  34.     This is an alternative to the XCOUNT cgi-bin script (that comes with
  35.     SRE-http).
  36.  
  37.  3) In conjunction with SENDFILE, as a means of keeping track of
  38.     requests.
  39.  
  40.  The principal advantages of COUNTER.RXX are:
  41.    i) In text mode, it has several display options, including
  42.       inclusion of commas and a "st", "nd", etc. suffix
  43.   ii) Document unique ".CNT" file are used to store results
  44.       (rather then the COUNTER_FILE used by REPLACE HITS, or the ACCESS.CNT 
  45.       file used by the XCOUNT and JCOUNT cgi-bin scripts).
  46.  iii) Request specific information (such as IP address, time of request,
  47.       and referer) can be stored.
  48.  iv)  Suppression of hits from "owners" and from "recent requesters"
  49.       can be invoked.
  50.   v)  Flexible odometer style counters, using one of the zillion gif-digit
  51.       collections available on the WWW, are easily created.
  52.  
  53. In addition to using COUNTER.RXX as a "counter", as of SRE-http ver 1.3d,
  54. you can also use COUNTER.RXX as a simple "graphical message" generator.
  55. This requires a bit more setup (you have to obtain "character GIFS",
  56. and create a "match file") -- details explained in section E 
  57. Acknowlegments: this is a heavily adapted from "The SSI Hit Counter" of William 
  58.                 Herrin  (http://www.why.com/herrin).
  59.                 Steve Ryckman (http://www.simsware.com) contributed several ideas.
  60.  
  61.                 ----------------------------------------------
  62.  
  63.  
  64. B) How to use COUNTER.RXX
  65.  
  66.   1) Double check that COUNTER.RXX has been installed in your
  67.      SRE-http "addon" directory (perhaps \GOSERVE\ADDON).
  68.  
  69.      You should also double check that there is a  ddir\DIGITS directory,
  70.      where ddir is the GoServe data directory.
  71.  
  72.      If there isn't, you can use DIGITS.ZIP (in ddir\DIGITS)
  73.      to create one (see the READ.ME in DIGITS.ZIP for installation 
  74.      instructions).
  75.        
  76.   2) Create a (set of) .CNT files -- one for each "document" you wish
  77.      to "count requests for".
  78.  
  79.      NOTES:
  80.        *  If you set CREATE_FILE=1, then COUNTER.RXX will create a
  81.           .CNT file if none exists (see below for details)
  82.           Otherwise,, you should create these .CNT files beforehand --
  83.           COUNTER.RXX will FAIL if the indicated .CNT file does not exist
  84.           (and CREATE_FILE=0)
  85.        *  When you create them, you should leave the .CNT files empty.
  86.        *  Several documents can "share" a single .CNT file.
  87.        *  The "filename" option is used to specify which .CNT file to use.
  88.  
  89.   3) As mentioned above, there are several ways you can invoke COUNTER.RXX
  90.  
  91.     a1) As a "server side include" to create a text counter.
  92.        Place  keyphrases into  your  HTML documents. 
  93.        These keyphrases should have the form:
  94.           <!-- INTERPRET FILE COUNTER.RXX  option_list , noaugment-->
  95.        where:
  96.             * option_list: a space delimited list of formatting instructions
  97.             * noaugment: if 1, do not augment the count (the current value  is
  98.                          used).
  99.  
  100.     a2) As a "server side include" to create a multi-IMG graphical odometer
  101.        Place  keyphrases into  your  HTML documents. 
  102.        These keyphrases should have the form:
  103.             <!-- INTERPRET FILE COUNTER.RXX  option_list , noaugment-->
  104.        where:
  105.             * option_list: a space delimited list of formatting instructions
  106.                            that contains an DIGITS=gif_set option
  107.         This will cause several <IMG SRC= > elements to be inserted into
  108.         the HTML document, each of which points to an appropriate gif-digit 
  109.         image.
  110.  
  111.      b) As an in-line image (a simple, single-image black on white "odometer").
  112.         Place "in-line images" elements in your HTML documents. For example:
  113.               <IMG SRC="/COUNTER.RXX?option_list"> 
  114.         elements in your HTML documents, where:
  115.             * option_list is an & delimited list of formatting instructions
  116.               that contains the XBITMAP=arg option
  117.         This will create a x-bitmap (black and white) image.
  118.  
  119.      c) In conjunction with the SENDFILE facility.
  120.         Place a "SENDFILE URL" in your HTML documents. For example:
  121.            <a href="/SENDFILE?filename&counter=option_list">Send file </a>
  122.          *  option_list is a  + delimited list of formatting instructions
  123.  
  124.   4) You may also want to change a few variables in COUNTER.RXX (described 
  125.      below).
  126.  
  127.      Actually, you may wish to have several versions of COUNTER.RXX,
  128.      (such as COUNTER1.RXX, COUNTER2.RXX, etc.); each with different
  129.      values for the various "COUNTER.RXX variables". 
  130.  
  131.      Note: the EDITSREF.CMD utiltiy can be used to edit COUNTER.RXX
  132.  
  133.  
  134.                 ----------------------------------------------
  135.  
  136. C) Parameters in COUNTER.RXX 
  137.  
  138. COUNTER.RXX contains several parameters that you may wish to modify. These
  139. include:
  140.  
  141.  
  142.    common_log_format -- use common-log format when recording client info
  143.    counter_dir -- where to place .CNT files
  144.    counter_image_dir -- the location of sets of gif-digit images
  145.    create_file -- create a .CNT file if none exists
  146.    digits_nobr -- Add a <NOBR> element around the digits. or put 'em in a table
  147.    force_break -- Add a <BR> after each digit
  148.    frame -- Use special left and right end "framed" digits
  149.    suppress_recent -- do not augment repetitive hits from the same client
  150.    suppress_loguser -- ignore the LOGUSER option
  151.    suppress_owners -- do not augment hits from OWNERS
  152.    save_xxx -- several variables (xxx) that specify information to record
  153.    use_queue -- use sre-http queues to store recent requests
  154.    write_users -- record client information in the .CNT file
  155.  
  156. The following provides details on these COUNTER.RXX parameters:
  157.  
  158.  
  159.  * Common_log_format.
  160.       There are two output formats: Common-log format, and customized.
  161.       For common log format, set common_log_format=1.
  162.       For further details, see the description of  the save_ variables below.
  163.  
  164.  * Create_file: 
  165.      If create_file=1, will create a .CNT file if none already exists. 
  166.      Otherwise, when no .CNT file exists, COUNTER will return nothing.
  167.      If the requested .CNT file does exist, create_file is ignored.
  168.  
  169.  *  Counter_dir :
  170.     If counter_dir=0 the '.CNT' files  are expected to be in 
  171.     the "requesting documents" own directory.
  172.     Otherwise, counter_dir should contain a fully qualified directory name.
  173.     By default, counter_dir=0.
  174.     For example, if:
  175.       > counter_dir=0,
  176.       > a selector of /DIR1/FOOBAR.HTM invokes  COUNTER.RXX, 
  177.       > the GoServe data directory is D:\WWW; 
  178.     then the .CNT file should be in D:\WWW\DIR1 (say, D:\WWW\DIR1\FOOBAR.CNT).
  179.  
  180.  * Counter_image_dir:
  181.     The "selector" that points to  the "DIGIT gif images" used when COUNTER.RXX
  182.     is used to create a multi-IMG odometer.
  183.     The counter_image_dir should be set to a "URL" that points to the root
  184.     of the image directories.  Each different set of GIF-digit images should
  185.     be in it's own directory.  For example:
  186.              counter_image_dir='http://foo.bar.net/cntimgs/'
  187.     or, more simply
  188.              counter_image_dir='/cntimgs/'
  189.  
  190.     Notes:
  191.         * To prevent COUNTER.RXX from creating these multi-IMG odometers,
  192.           set counter_image_dir=0
  193.         * By default, SRE-http sets COUNTER_IMAGE_DIR='DIGITS', and
  194.           installs several DIGIT sets to the /DIGITS subdirectory of 
  195.           the GoServe data directory.
  196.  
  197.  * Digits_nobr
  198.    If digits_nobr=1, then a <NOBR> ... </nobr> will be placed around the
  199.    <IMG SRC= > elements. On modern browsers, this will guarantee that
  200.    the gif-digit image will not wrap to a new line
  201.  
  202.    Alternatively, if digits_nobr=2 then use a one-cell <TABLE> to display 
  203.    digits. Since <NOBR> is not in the html 4.0 spec, this may be preferred.
  204.  
  205.  * Force_break
  206.    Add a <BR> before or after each digit in the message.  
  207.  
  208.       0 = Normal, don't force <BR> before/after digits.
  209.       1 = Place a <BR> in front of each digit.
  210.       2 = Place a <BR> after each digit. 
  211.  
  212.     Note that if FORCE_BREAK>0, then DIGITS_NOBR is ignored.
  213.  
  214.  * Suppress_recent: 
  215.     Used to suppress generation of false "new hits".
  216.     If suppress_recent>0, and if either Write_users=1 or use_queue=1, 
  217.     then the user list is checked  against the client's ip address. 
  218.     If:
  219.         i) a matching entry (by ip address) exists
  220.        ii) it is less then suppress_recent minutes old,
  221.     Then:
  222.         i) the counter is NOT incremented
  223.        ii) the current value is used in the server-side include
  224.  
  225.  * Suppress_loguser:
  226.      If suppress_loguser=1, then suppress the LOGUSER option.  That is, 
  227.      if suppress_loguser=1, then always use the value of the write_users
  228.      variable, and ignore the LOGUSER option (see section D for
  229.      details on LOGUSER).
  230.  
  231.  * Suppress_owners:
  232.      If suppress_owners=1, then if the request is from an owner (as 
  233.      listed in the OWNERS variable), the counter will not be incremented.
  234.  
  235.  * save_ variables (and common_log_format):
  236.       There are two output formats: Common-log format, and customized.
  237.        a)  To select "common-log" format, set common_log_format=1.  When
  238.            enabled, entries of the form:
  239. 151.121.65.143, 729109.895139, someone.clients.org - USERNAME [27/Mar/1997:21:29:58 -0500] "GET /status.sht HTTP/1.0" - 0
  240.            will be written (note that the status code is always set to -, and 
  241.            the size will be non-zero only if COUNTER.RXX is invoked via 
  242.            SENDFILE).
  243.  
  244.        b) For customized fornat, you enable (by setting =1) one, several, 
  245.           or all of the following variables:
  246.               save_ipname:    Write the "dotted" IP Name (if none available,
  247.                               save IP address)
  248.               save_username:  Write the SRE-http "logon" name (if available)
  249.               save_time:      Write the time, in 13:01:33 format
  250.               save_date:      Write the date, in 5 Feb 1996 format
  251.               save_docname:   Write the "request selector"
  252.               save_bytes:     Write the number of bytes written, and 
  253.                                       the size of the file.
  254.                                If a premature disconnection occurs, the number 
  255.                                of bytes written will be less then the size of 
  256.                                the file.
  257.               save_referer:   Write the "referer (if available)
  258.               save_browser:   Write the "user-agent"
  259.  
  260.           Note: in both cases, the client's ip address and the "julian" 
  261.                 date/time are always written (given that write_users=1)
  262.  
  263.  * Use_queue:
  264.    
  265.     As of version 1.2L, COUNTER.RXX will use "queues" to store information.
  266.     In most cases, the use of queues can speed up response time. However,
  267.     if you have lots (hundreds) of files that use counter.rxx, this may
  268.     lead to an overabundance of information stored in memory. In such cases,
  269.     it may be better to suppress the use of queues (and use the disk files
  270.     instead).
  271.          use_queue=1 : Enable the use of queues
  272.          use_queue=0 : Suppress the use of queues.
  273.      Note: if you want to use suppress_recent, either write_users or use_queue
  274.            must be enabled.
  275.  
  276.  * Write_users :
  277.     If write_users=1, then along with the "number" of hits, client specific 
  278.     information is recorded -- with the common_log_format and save_ variables
  279.     specifying what & how to write.
  280.  
  281.     Notes:
  282.         * if you enable the write_users option, privacy concerns lead
  283.           us to strongly recommend using a web-inaccessible
  284.           counter_dir (i.e.; by setting COUNTER_DIR='\GOSERVE\DATA')
  285.         * you may want to reset these .CNT files every so often
  286.           (since large files will impact response time). This is
  287.           less important if you have enabled use_queue
  288.         * only the count is written to the "requesting document".
  289.           The "user information" is written for the sake of
  290.           the server administrator.
  291.  
  292.  
  293.                 ----------------------------------------------
  294.  
  295.  
  296. D) Description of COUNTER.RXX "option list" options
  297.  
  298. The simplest option list is no option list.  If there is no option
  299. list, a .CNT file (with the same name as the requested document) will
  300. be used.
  301. Notes:
  302.         * If you are using a counter_dir (say, counter_dir='d:\goserve'),
  303.           and you have files with the same name in several directories, they
  304.           will end up augmenting the same counter.
  305.         * For the "simple, single-image odomoter" (IMG SRC="/COUNTER.RXX..">
  306.           variant, you MUST include the XBITMAP option in the option list.
  307.  
  308. The options are:
  309.      frame -- put "left and right" frame bars on ends
  310.   duration -- number of days to count hits from
  311.       file -- name of the .CNT file to use
  312.    xbitmap -- type of single-IMG odometer to create
  313.   imgalign -- how to align the multi-IMG odometer
  314.    digits  -- the gif-digit images directory to use for multi-IMG odometers
  315.  increment -- Quantity to increment counter by
  316.        ith -- add a 'st, 'nd, etc. to textual counters
  317.    loguser -- record client info to the .CNT file
  318.        min -- minimum value
  319.        max -- maximumu value
  320.   nocommas -- do not include commas
  321.   rollover -- reset to min when max is hit
  322.        sel -- selector to use when recording information
  323.     silent -- augment but do not display
  324.  table_digits -- put graphic digits in a small table (modified digits_nobr)
  325.      value -- integer value -- use this instead of reading a value fron file
  326.      width -- # of digits to use (padded with zeros if necessary)
  327.  
  328. Note that either file or value MUST be specified; all other others are
  329. optional.
  330.  
  331. In greater detail:
  332.  
  333.  
  334.  * frame:
  335.    If frame=1, then special left and right "frame bars" gifs will be
  336.    placed on the the left and right characters ends of the 
  337.    multi-IMG (DIGITS variant) odometer.
  338.    This should be used with "framed" digits; which typically come with
  339.    special left-end and right-end (or perhaps a single "both ends") bars.
  340.    The names of the left bar should be L.GIF, and R.GIF for the right-end
  341.    bar -- if only one bar is provided, copy it to L.GIF and R.GIF.
  342.    
  343.  
  344.  *  duration=#days :
  345.     If duration>0, then the number of hits in the last "#days" will be displayed.
  346.     For example, duration=1 means that the "number of hits today" is displayed.
  347.     Similarly, duration=7 means "the number of hits in the last 7 days"
  348.     is displayed.
  349.     Notes on duration=#days:
  350.       >  For duration=#days to work, you MUST set  write_users=1. 
  351.          If write_users<>1, then a value of 000 is displayed.
  352.       >  The actual number of hits is displayed (minval,  rollover,
  353.          etc. are ignored).
  354.       >  If duration=0, it is ignored (i.e.; it's the same as not including
  355.          a duration option).
  356.       >  Hint: 
  357.            to report the total # of hits, and the hits in the last n days,
  358.            use two calls, with the second containing an increment=0
  359.            option.
  360.       >  Example:
  361.            If duration = 7, and today is monday, then the number of
  362.            hits since last Tuesday (inclusive) is displayed.
  363.  
  364.  *  file=filename 
  365.     The name of the .CNT file; relative to the counter_dir, or relative to 
  366.     the document's own directory if counter_dir=0. 
  367.     You should NOT include a .CNT extension in the filename.
  368.     You can included relative path information. 
  369.     Examples:
  370.         file=thisone
  371.         file=cnts/thatone
  372.     In the second example, a cnts/ subdirectory must exist (under the COUNTER_DIR
  373.     directory, or under the "invoking files" directory)
  374.  
  375.  *  xbitmap=arg  
  376.     If xbitmap=REVERSE then a white on black background single-IMG odometer 
  377.                     graphic will be created and sent to the client. 
  378.     If xbitmap=NORMAL, then a black on white background single-IMG odometer 
  379.                        graphic will be created.  
  380.     Notes on xbitmap
  381.       > this "xbitmap" variant of COUNTER.RXX must be used in an
  382.         <IMG element. It should NOT be used as an SSI-style counter.
  383.       > xbitmaps are simple black on white (or white on black) images.
  384.       > when xbitmap is specified, nocommas is set to 1, and ith is set to 0.
  385.       > If you specify xbitmap, and write_users=1, it is strongly recommended
  386.         that you also specify a SEL option 
  387.       > The old syntax (prior to SRE-http version 1.3b) of "graphic=NORMAL"
  388.         and "graphic=YES" is still supported.
  389.  
  390.  *  loguser=arg
  391.     If ARG=YES or NO, and SUPPRESS_LOGUSER=0, then override the WRITE_USERS 
  392.     variable. Note that YES = record client,  NO=Do NOT record client.
  393.  
  394.  * digits=arg   
  395.    If arg is the name of a "gif-digit images subdirectory",
  396.    then a series of IMG elements are returned to the client 
  397.    that point to the appropriate images. 
  398.  
  399.    Note that the old syntax (prior to sre-http ver 1.3b) of "imgtype=arg"
  400.    is still supported.
  401.  
  402.  * imgalign=arg   
  403.    arg should be MIDDLE, TOP, or BOTTOM -- it effects the alignment
  404.    of digits created when DIGITS is specified.
  405.  
  406.  * increment=inc
  407.    Add inc at each hit (typically, inc=1).
  408.    If increment=0, then the counter is NOT augmented, and a user-entry is NOT added.
  409.  
  410.  * ith="" 
  411.    If an ith="" is specified, append a th,rd,st, or nd "suffix"
  412.    to the number (1st, 2nd, 3rd, 4th, etc).
  413.    The default is to NOT add this suffix.
  414.  
  415.  * min=min_value
  416.    Minimum value to count from (the default is 0)
  417.  
  418.  * max=max_value
  419.    Maximum value to count to (the default is 2147000000)
  420.  
  421.  * nocommas=""   
  422.    If a nocommas="" is specified, every 3rd digit commmas are NOT written
  423.    This is implied if width>0. By default, commas WILL be included.
  424.  
  425.  * rollover=""
  426.    If rollover="" is specified, will reset counter to min when max is hit.
  427.    Default is to not rollover.
  428.  
  429.  * sel=selector 
  430.    If write_users is enabled, the value of SEL will be  
  431.    written to the "selector" field (in the .CNT file).
  432.    If SEL is not specified, the selector of the document that "invoked"
  433.    COUNTER.RXX will be used.  
  434.    Note: If you are using the XBITMAP option,  you should also use the SEL option.
  435.  
  436.  *  silent=""  
  437.     If a silent="" is present, the .CNT file will be updated, but nothing 
  438.     will be displayed.
  439.  
  440.  *  table_digits=arg
  441.     arg is 0 or 1: 0 means "use <NOBR> ... </NOBR>,
  442.                    1 means "use <TABLE>...</TABLE>
  443.      table_digits is used ONLY when digits_nobr>0: if digits_nobr=0, then
  444.      table_digits is ignored.
  445.  
  446.      Note: <NOBR> is not part of the formal HTML 4.0 specc
  447.            (see  http://www.w3.org/TR/REC-html40/)
  448.  
  449.  * value=nnnnnn
  450.    IF value=nnn is specified, where nnnnnn is an integer (of any length),
  451.    the COUNTER will NOT attempt to find the "hit count". Instead, it will
  452.    just use the value of nnnnn.
  453.        
  454.    Note: if you've specified a "font" (such as GOLDBLOK), then nnnnnn
  455.          can be a text string (not just numbers)
  456.  
  457.  * width=ndigits 
  458.    Minimum width of counter (padded with 0's if need be).
  459.    The default is 0 -- which means "don't try to pad".
  460.  
  461.                 ----------------------------------------------
  462.  
  463.  
  464. E) Matching characters to GIF files -- the "match file"
  465.  
  466.  
  467. New to SRE-http ver 1.3b, COUNTER.RXX and (SREF_DIGITS) can now
  468. display non-digit characters. To enable this capability, a
  469. special "match file" must be specified. This match file
  470. instructs COUNTER.RXX (and SREF_DIGITS) as to how to display
  471. the various characters in a message.
  472.  
  473.   For example, if you wanted to display a digital clock, 
  474.   you can use a match file to specify the GIF files to use for 
  475.   the  numeric digits and for the  :, A, P, and M character.
  476.  
  477. Match files are ascii (text) files.  They must be:
  478.  
  479.  i) located in the same directory as the digit (and/or
  480.     character) .GIF files
  481. ii) named DDD.IND, where DDD is the name of the subdirectory
  482.     (the "digit name").
  483.  
  484. For example, for the "TWOTURT" digits and characters 
  485.   a) digit and character.GIF files are located in the MBC subdirectory 
  486.      of the directory pointed to by COUNTER_IMAGE_DIR
  487.   b) the "match file" for TWOTURT must be named TWOTURT.IND, and must
  488.      be located in this TWOTURT subdirectory
  489.  
  490. The structure of "match file" is fairly simple. Each line of 
  491. the match file is an entry (except for blank lines and comment lines
  492. that begin with 2 semi-colons).  Each entry consists of a single
  493. character, followed by a file name (the file name should NOT contain
  494. path information). For example:
  495.  
  496.       ;; comment lines start with 2 semi colons
  497.       A  A.GIF
  498.       B  B.GIF
  499.       b  BLC.GIF
  500.  
  501. In addition, you should have 4 special files:
  502.   SPACE.GIF -- used for spaces
  503.   DEFAULT.GIF -- used for  missing characters
  504.   LFRAME.GIF -- the "left frame". 
  505.                 Note: if a match file is not available, L.GIF is
  506.                       used as the "left frame"
  507.   RFRAME.GIF -- the "right frame"
  508.                 Note: if a match file is not available, R.GIF is
  509.                       used as the "right frame"
  510.  
  511. Notes:
  512.  
  513.   * All the .GIF files MUST be in the "digit name" directory. Thus,
  514.     you must NOT specify path names!
  515.  
  516.   * CaSe matters --  no attempt is made to match lower case
  517.     characters to upper case entries in the match file. However,
  518.     see the next note ....
  519.  
  520.  * If no matching entry exists for a given character,
  521.     then a x.GIF file is assumed for; where x is
  522.     the character to be displayed. For example:
  523.         if no entry exists for the Z (or z) character,
  524.         then Z.GIF will be used.
  525.     
  526.   * If the specified (either explicit, or default) .GIF file does not
  527.     exist, DEFAULT.GIF is used. If DEFAULT.GIF can not be found, 
  528.     the character is ignored.
  529.  
  530.   * For a much richer "character to image" utility, see the GIF_TEXT
  531.     addon for SRE-http.
  532.  
  533.  
  534.                 ----------------------------------------------
  535.  
  536.  
  537. F) Calling COUNTER.RXX as a REXX procedure
  538.  
  539. As a convenience to ambitous webmasters who'ld like to create addons
  540. that contain graphical counters, it's easy to call special versions of
  541. COUNTER.RXX as a REXX procedure.  In particular, you can use the 
  542. SREF_DIGITS or the SREF_XBITMAP "macrospace" procedures.
  543.  
  544.   * SREF_XBITMAP will produce a "xbitmap" (black and white) image
  545.     of a string of digits, and return it to the client.  
  546.          SREF_XBITMAP is akin to using COUNTER.RXX with an XBITMAP option,
  547.  
  548.   * SREF_DIGITS will produce a text string of URLS that point to the 
  549.     appropriate set of digits.
  550.          SREF_DIGITS is akin to using COUNTER.RXX with a DIGITS option.
  551.  
  552. Both of these "macrospace procedures" are available to all SRE-http addons; 
  553. and can be called just like any other REXX procedure.
  554.  
  555. SREF_XBITMAP is  called with:
  556.  
  557.   astatus=SREF_XBITMAP(anumber,ndigits,doreverse)
  558.  
  559. where
  560.    astatus  : status message
  561.    anumber : a number to display (a string of digits)
  562.    ndigits : optional -- the number of digits to display. 
  563.              If ndigits is longer then the number of characters in anumber,
  564.              then 0's will be used as a padding character.
  565.   doreverse: optional -- if 1, then a white on black image is created. 
  566.              Otherwise, a black on white image is created.
  567.  
  568. Note that the sref_xbitmap returns the x-bitmap image directly to the client
  569.  
  570.  
  571. SREF_DIGITS is called with:
  572.  
  573.     txtstring=SREF_DIGITS(amess,digit_name,nd,useframe,nobr,opts,imgdir)
  574.  
  575. where:
  576.   txtstring :  a text string containing a sequence of <IMG elements, that
  577.                point to the appropriate graphical digits
  578.  
  579.       amess : a string of characters, typically-but-not-always digits,
  580.                   to display 
  581.  digit_name : the name of the subdirectory containing the digit, 
  582.               and/or character-image, .GIF files.  
  583.               This subdirectory must be relative to the
  584.               imgdir directory (as specified below).
  585.  
  586.               If digit_name is not specified, WHITBLAK is used.  
  587.  
  588. The remaining arguments are optional.
  589.  
  590.          nd : the number of characters to display. 
  591.               If nd is longer then the number of characters in amess...
  592.                 a) if amess only contains digits, then 0's will be
  593.                    used as a padding character 
  594.                 b) if amess contains non digit charcters, the "default"
  595.                    character (specified in the "match file") is used
  596.                    as a padding character
  597.    useframe : if 1, then include a "left and right" frame
  598.               around the characters (see the "frame" option above for details)
  599.        nobr : if 0, then do NOT put a <NOBR> and </NOBR> around the
  600.               IMG elements (that comprise the message)
  601.      opts   : a string to be included in the IMG elements. 
  602.               For example:
  603.                 ' ALIGN=CENTER VALIGN=TOP'
  604.                 ' VALIGN=MIDDLE WIDTH=12 HEIGHT=12 '
  605.               In other words, opts can be a list of any IMG element
  606.               modifers.
  607.               Note that this "opts" list is included in all IMG elements,
  608.               including "frame" elements.
  609.      imgsel : the "counter_image_dir" selector.
  610.               If not specified, a value of "DIGITS" is assumed.
  611.      imgdir : Absolute path pointed to by the imgsel. If not specified, 
  612.               the DIGITS subdirectory of the GoServe data directory
  613.               is used.
  614.         
  615. Notes:
  616.  
  617.    * SREF_DIGITS will look for, and use-if-found, a "match file" (as
  618.      described in section E above).
  619.  
  620.    * For an example of how these procedures can be used, see the 
  621.      description of the TSTDIGIT.CMD addon (in section H below).
  622.  
  623.  
  624.  
  625.                 ----------------------------------------------
  626.  
  627. G) Miscellaneous topics 
  628.  
  629.  
  630.  * The following "digit/character" sets are installed with SRE-http
  631.         
  632.     BRUSH (digits only) : white on black, italic style brush strokes
  633.     MBC   (digits only) : white letters on black balls
  634.     GARA  (digits only) : black on white font (garamond?)
  635.     GOLDODO (digits only) : Black letters on an gold "odometer" background
  636.     PDP    (digits only) : Pink on black, 2d calculator style 
  637.     CALC     : Purple on black, 3d calculator style
  638.     GOLDBLOK : 3d, shiny gold on black (somewhat blocky style)
  639.     WHITBLAK : White on black, sort of fat characters
  640.  
  641.  
  642.  * Using COUNTER.RXX with SENDFILE 
  643.  
  644.    To augment these .CNT files via the SENDFILE facility, simply
  645.    include, as part of the args (in SENDFILE?filename&args)
  646.    a &COUNTER=file=cntfile.  Since SENDFILE just uses COUNTER.RXX
  647.    to augment the .CNT file, there is no point in specifying
  648.    additional options (however, you may wish to tinker with the SAVE_xxxx
  649.    variables in COUNTER.RXX). For example: 
  650.  
  651.        sendfile?srefiltr/ver12/srev12L.zip&counter=file=srev12
  652.  
  653.    Note: SENDFILE will record all attempts in the .CNT file. However,
  654.          if an attempt failed (due to a prematurely closed connection),
  655.          SENDFILE will write a "failed" record that notes how
  656.          many bytes were sent.
  657.  
  658.  * Example of use as a simple, black and white single-IMG odometer
  659.  
  660.        <IMG src="/counter.rxx?file=test1&width=5&xbitmap=REVERSE">
  661.        <IMG src="/counter.rxx?file=test2&increment=0&xbitmap=NORMAL">
  662.  
  663.     Note the use of & as an argument seperator!
  664.  
  665. *  Using COUNTER.RXX to return a fancier, multi-IMG odometers.
  666.  
  667.   To use COUNTER.RXX to return multi-img odomoters, consisting of a 
  668.   series of <IMG SRC= > links to gif-digit images on your server,
  669.   you should use the DIGITS option.
  670.   For example:
  671.  
  672.       <!-- INTERPRET FILE COUNTER.RXX FILE=bar1 DIGITS=FLAME -->
  673.  
  674.   will  use the "flame" digits to display the current count.  For example,
  675.   if the count (as stored in bar1.cnt) is 12, the following would be included
  676.   in the document that invoked COUNTER.RXX:
  677.       <img src="/cntimg/FLAME/1.gif" alt="1">
  678.       <img src="/cntimg/FLAME/2,gif" alt="2">  
  679.   where "/CNTIMG" is the value of the counter_image_dir variable.
  680.  
  681.   Thus, to use this option, you must obtain a set of (at least) ten
  682.   .GIF files with the names 0.GIF,..,9.GIF.  Fortunately, these
  683.   are common on the web -- a great resource for these beasts is 
  684.          http://www.digitmania.holowww.com.
  685.   Note that if you use the FRAME option, you'll need 12 files.
  686.  
  687.   For a small sampler, check out the stuff in  the DIGITS.ZIP file packed 
  688.   with SRE-http -- it should have been installed into a DIGITS directory of
  689.   your GoServe data directory (see the  READ.ME file in  DIGITS.ZIP for 
  690.   details, and DIGSAMPL.HTM  (located in your counter_image_dir directory)
  691.   for a sample of how to use these  digits with COUNTER.RXX).
  692.  
  693.   For a "framed counter, try:
  694.       <!-- $ COUNTER.RXX file=foobar2 digits=goldodo frame=1  -->
  695.  
  696.  
  697.  * Examples of use as a textual server side include:
  698.  
  699.    <!-- INTERPRET FILE COUNTER.RXX file=foobar -->
  700.    <!-- INTERPRET FILE COUNTER.RXX file=foobar2 silent="" -->
  701.    <!-- INTERPRET FILE COUNTER.RXX file=foobar3 min=10 max=20 inc=2 width=5
  702.                                   rollover="" ith="" -->
  703.    <!-- INTERPRET FILE COUNTER.RXX file=foobar2 nocommas="" , 1  -->
  704.    <!-- INTERPRET FILE COUNTER.RXX file=foobar  duration=10 -->
  705.  
  706.    <!-- INTERPRET FILE COUNTER.RXX file=foobar2 digits=mbc  -->
  707.  
  708.  
  709.    Note that when called as a server side include, you don't need to
  710.    enclose the values in double quotes (").  Also note that space is used as an
  711.    argument seperator.
  712.  
  713.  * In .CNT files: blank lines, and lines starting with a semi-colon,
  714.    are ignored (they are treated as comments)
  715.  
  716.  * Suppress_recent is ignored if write_users does not equal 1
  717.  
  718.  * Hint: If 
  719.             you want some create different types of counters for
  720.             different selectors (say, some that retain "individual information",
  721.             some that suppress recent hits, etc.), 
  722.          then
  723.             you can create multiple versions of COUNTER.RXX
  724.             (say, CNT1.RXX and CNT2.RXX); and call the appropriate one.
  725.          For example, use INTERPRET FILE CNT1.RXX or INTERPRET FILE CNT2.RXX;
  726.          where CNT1.RXX has suppress_recent=0 and CNT2.RXX has 
  727.          suppress_recent=15.
  728.  
  729.                 ----------------------------------------------
  730.  
  731.  
  732. H) Miscellaneous
  733.  
  734.  
  735. A demo:
  736.   You can use the CNTDEMO2.SHT file, that is shipped with SRE-http, to
  737.   demonstrate COUNTER.RXX>
  738.  
  739.  
  740. The TSTDIGIT.CMD addon:
  741.  
  742. The TSTDIGIT.CMD addon (which should have been installed in your SRE addon
  743. directory) demonstrates how one can use SREF_DIGITS and SREF_XBITMAP.
  744. It's fairly well commented, and should help illustrate how one can
  745. use these two functions.
  746.  
  747. To see what TSTDIGIT does, you should hit your web server with:
  748.      /TSTDIGIT?my+message
  749.  
  750. This will cause:
  751.  a) "my message" (without the quotes) to be displayed using
  752.      the "GOLDBLOK" character set; 
  753.  b) the current request number to be displayed using:
  754.        i) the GOLDODO digits
  755.       ii) a normal x-bitmap
  756.      iii) and a reversed x-bitmap
  757.  
  758. Actually, TSTDIGIT understands a few options; which can be invoked using
  759.      /TSTDIGIT?option_list
  760. Where option list has the form:
  761.    opt1=val1&opt2=val2&..
  762.  
  763. Valid options, and the values they expect, include:
  764.  
  765.    MESS = a message (with + used for spaces)
  766.    FONT = font to display MESS with 
  767.    FONT2 = font to display request number with
  768.    XBITMAP = create an xbitmap file (FONT and FONT2 are ignored)
  769.              of the current request number. valn is 0 (plain) or
  770.              1 (reversed)
  771.  
  772. For example:
  773.     /TSTDIGIT?mess=hello+world&font=Goldblok&font2=goldodo
  774.  
  775. Whey XBITMAP is specified, then TSTDIGIT will return an X-Bitmap image.
  776. Otherwise, TSTDIGIT will return a text/html document, which will contain
  777. IMG elements that point back to TSTDIGIT.
  778.  
  779.  
  780. .end of COUNTER.DOC
  781.  
  782.