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 . 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 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: 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: where: * option_list: a space delimited list of formatting instructions that contains a IMGTYPE=gif_set option This will cause several 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: 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 element around the digits. or put 'em in a table force_break -- Add a
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 : 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 ... will be placed around the 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 to display digits. Since is not in the html 4.0 spec, this may be preferred. * Force_break Add a
before or after each digit in the message. 0 = Normal, don't force
before/after digits. 1 = Place a
in front of each digit. 2 = Place a
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: 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 imgtype -- the gif-digit images directory to use for multi-IMG odometers 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 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. * imgtype=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 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 ... , 1 means "use
...
table_digits is used ONLY when digits_nobr>0: if digits_nobr=0, then table_digits is ignored. Note: 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 and 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 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 links to gif-digit images on your server, you should use the DIGITS option. For example: will use the "flame" digits to display the current count. For example, if the count (as stored in bar1.cnt) is 12, the preceding would lead to the following SSIs (in the document that invoked COUNTER.REX): 1 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: * Examples of use as a textual server side includes: 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