22 April 1999: Description of the SRE-http COUNTER.RXX addon. Abstract: COUNTER.RXX 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.RXX C) Parameters that can be set in COUNTER.RXX D) Options that can be set when COUNTER.RXX is invoked E) Matching characters to GIF files -- the "match file" F) Calling COUNTER.RXX as a procedure. G) Miscellaneous topics H) A simple example ---------------------------------------------- A) Introduction COUNTER.RXX 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 simple, black and white single-IMG odometer. This is an alternative to the XCOUNT cgi-bin script (that comes with SRE-http). 3) In conjunction with SENDFILE, as a means of keeping track of requests. The principal advantages of COUNTER.RXX 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 (rather then the COUNTER_FILE used by REPLACE HITS, or the ACCESS.CNT file used by the XCOUNT and JCOUNT cgi-bin scripts). iii) Request specific information (such as IP address, time of request, and referer) can be stored. iv) Suppression of hits from "owners" 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. In addition to using COUNTER.RXX as a "counter", as of SRE-http ver 1.3d, you can also use COUNTER.RXX as a simple "graphical message" generator. This requires a bit more setup (you have to obtain "character GIFS", and create a "match file") -- details explained in section E Acknowlegments: this is a 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.RXX 1) Double check that COUNTER.RXX has been installed in your SRE-http "addon" directory (perhaps \GOSERVE\ADDON). You should also double check that there is a ddir\DIGITS directory, where ddir is the GoServe data directory. If there isn't, you can use DIGITS.ZIP (in ddir\DIGITS) to create one (see the READ.ME in DIGITS.ZIP for installation instructions). 2) Create a (set of) .CNT files -- one for each "document" you wish to "count requests for". NOTES: * If you set CREATE_FILE=1, then COUNTER.RXX will create a .CNT file if none exists (see below for details) Otherwise,, you should create these .CNT files beforehand -- COUNTER.RXX will FAIL if the indicated .CNT file does not exist (and CREATE_FILE=0) * When you create them, you should leave the .CNT files empty. * Several documents can "share" a single .CNT file. * The "filename" option is used to specify which .CNT file to use. 3) As mentioned above, there are several ways you can invoke COUNTER.RXX a1) 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). a2) 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 an DIGITS=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. b) 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. c) In conjunction with the SENDFILE facility. Place a "SENDFILE URL" in your HTML documents. For example: Send file * option_list is a + delimited list of formatting instructions 4) You may also want to change a few variables in COUNTER.RXX (described below). Actually, you may wish to have several versions of COUNTER.RXX, (such as COUNTER1.RXX, COUNTER2.RXX, etc.); each with different values for the various "COUNTER.RXX variables". Note: the EDITSREF.CMD utiltiy can be used to edit COUNTER.RXX ---------------------------------------------- C) Parameters in COUNTER.RXX COUNTER.RXX 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_owners -- do not augment hits from OWNERS save_xxx -- several variables (xxx) that specify information to record use_queue -- use sre-http queues to store recent requests write_users -- record client information in the .CNT file The following provides details on these COUNTER.RXX parameters: * 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 will return nothing. If the requested .CNT file does exist, create_file is ignored. * Counter_dir : If counter_dir=0 the '.CNT' files are expected to be in the "requesting documents" own directory. Otherwise, counter_dir should contain a fully qualified directory name. By default, counter_dir=0. For example, if: > counter_dir=0, > a selector of /DIR1/FOOBAR.HTM invokes COUNTER.RXX, > the GoServe data directory is D:\WWW; then the .CNT file should be in D:\WWW\DIR1 (say, D:\WWW\DIR1\FOOBAR.CNT). * Counter_image_dir: The "selector" that points to the "DIGIT gif images" used when COUNTER.RXX is used to create a multi-IMG odometer. The counter_image_dir should be set to a "URL" that points to the root of the image directories. Each different set of GIF-digit images should be in its own directory. For example: counter_image_dir='http://foo.bar.net/cntimgs/' or, more simply counter_image_dir='/cntimgs/' Notes: * To prevent COUNTER.RXX from creating these multi-IMG odometers, set counter_image_dir=0 * By default, SRE-http sets COUNTER_IMAGE_DIR='DIGITS', and installs several DIGIT sets to the /DIGITS subdirectory of the GoServe data directory. * 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. Note that if FORCE_BREAK>0, then DIGITS_NOBR is ignored. * Suppress_recent: Used to suppress generation of false "new hits". If suppress_recent>0, and if either Write_users=1 or use_queue=1, then 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_loguser: 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_owners: If suppress_owners=1, then if the request is from an owner (as listed in the OWNERS variable), 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: 151.121.65.143, 729109.895139, someone.clients.org - USERNAME [27/Mar/1997:21:29:58 -0500] "GET /status.sht HTTP/1.0" - 0 will be written (note that the status code is always set to -, and the size will be non-zero only if COUNTER.RXX is invoked via SENDFILE). b) For customized fornat, 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 SRE-http "logon" name (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 number of bytes written, and the size of the file. If a premature disconnection occurs, the number of bytes written will be less then 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 "julian" date/time are always written (given that write_users=1) * Use_queue: As of version 1.2L, COUNTER.RXX will use "queues" to store information. In most cases, the use of queues can speed up response time. However, if you have lots (hundreds) of files that use counter.rxx, this may lead to an overabundance of information stored in memory. In such cases, it may be better to suppress the use of queues (and use the disk files instead). use_queue=1 : Enable the use of queues use_queue=0 : Suppress the use of queues. Note: if you want to use suppress_recent, either write_users or use_queue must be enabled. * 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, privacy concerns lead us to strongly recommend using a web-inaccessible counter_dir (i.e.; by setting COUNTER_DIR='\GOSERVE\DATA') * you may want to reset these .CNT files every so often (since large files will impact response time). This is less important if you have enabled use_queue * only the count is written to the "requesting document". The "user information" is written for the sake of the server administrator. ---------------------------------------------- D) Description of COUNTER.RXX "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='d:\goserve'), 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.RXX.."> variant, you MUST include the XBITMAP option in the option list. The options are: frame -- put "left and right" frame bars on ends duration -- number of days to count hits from file -- name of the .CNT file to use xbitmap -- type of single-IMG odometer to create imgalign -- how to align the multi-IMG odometer digits -- the gif-digit images directory to use for multi-IMG odometers 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) 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: * 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. * 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. * file=filename The name of the .CNT file; relative to the counter_dir, or relative to the document's own directory if counter_dir=0. You should NOT include a .CNT extension in the filename. You can included 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) * xbitmap=arg If xbitmap=REVERSE then a white on black background single-IMG odometer graphic will be created and sent to the client. If xbitmap=NORMAL, then a black on white background single-IMG odometer graphic will be created. Notes on xbitmap > this "xbitmap" variant of COUNTER.RXX 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 strongly recommended that you also specify a SEL option > The old syntax (prior to SRE-http version 1.3b) of "graphic=NORMAL" and "graphic=YES" is still supported. * loguser=arg If ARG=YES or NO, and SUPPRESS_LOGUSER=0, then override the WRITE_USERS variable. Note that 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. Note that the old syntax (prior to sre-http ver 1.3b) of "imgtype=arg" is still supported. * 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. * 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.RXX 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" New to SRE-http ver 1.3b, COUNTER.RXX and (SREF_DIGITS) can now display non-digit characters. To enable this capability, a special "match file" must be specified. This match file instructs COUNTER.RXX (and SREF_DIGITS) 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 for SRE-http. ---------------------------------------------- F) Calling COUNTER.RXX as a REXX procedure 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.RXX as a REXX procedure. In particular, you can use the SREF_DIGITS or the SREF_XBITMAP "macrospace" procedures. * SREF_XBITMAP will produce a "xbitmap" (black and white) image of a string of digits, and return it to the client. SREF_XBITMAP is akin to using COUNTER.RXX with an XBITMAP option, * SREF_DIGITS will produce a text string of URLS that point to the appropriate set of digits. SREF_DIGITS is akin to using COUNTER.RXX with a DIGITS option. Both of these "macrospace procedures" are available to all SRE-http addons; and can be called just like any other REXX procedure. SREF_XBITMAP is called with: astatus=SREF_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 sref_xbitmap returns the x-bitmap image directly to the client SREF_DIGITS is called with: txtstring=SREF_DIGITS(amess,digit_name,nd,useframe,nobr,opts,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 "DIGITS" is assumed. imgdir : Absolute path pointed to by the imgsel. If not specified, the DIGITS subdirectory of the GoServe data directory is used. Notes: * SREF_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 SRE-http 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 * Using COUNTER.RXX with SENDFILE To augment these .CNT files via the SENDFILE facility, simply include, as part of the args (in SENDFILE?filename&args) a &COUNTER=file=cntfile. Since SENDFILE just uses COUNTER.RXX to augment the .CNT file, there is no point in specifying additional options (however, you may wish to tinker with the SAVE_xxxx variables in COUNTER.RXX). For example: sendfile?srefiltr/ver12/srev12L.zip&counter=file=srev12 Note: SENDFILE will record all attempts in the .CNT file. However, if an attempt failed (due to a prematurely closed connection), SENDFILE will write a "failed" record that notes how many bytes were sent. * Example of use as a simple, black and white single-IMG odometer Note the use of & as an argument seperator! * Using COUNTER.RXX to return a fancier, multi-IMG odometers. To use COUNTER.RXX 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 following would be included in the document that invoked COUNTER.RXX: 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 small sampler, check out the stuff in the DIGITS.ZIP file packed with SRE-http -- it should have been installed into a DIGITS directory of your GoServe data directory (see the READ.ME file in DIGITS.ZIP for details, and DIGSAMPL.HTM (located in your counter_image_dir directory) for a sample of how to use these digits with COUNTER.RXX). For a "framed counter, try: * Examples of use as a textual server side include: 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 * Hint: If you want some create different types of counters for different selectors (say, some that retain "individual information", some that suppress recent hits, etc.), then you can create multiple versions of COUNTER.RXX (say, CNT1.RXX and CNT2.RXX); and call the appropriate one. For example, use INTERPRET FILE CNT1.RXX or INTERPRET FILE CNT2.RXX; where CNT1.RXX has suppress_recent=0 and CNT2.RXX has suppress_recent=15. ---------------------------------------------- H) Miscellaneous A demo: You can use the CNTDEMO2.SHT file, that is shipped with SRE-http, to demonstrate COUNTER.RXX> The TSTDIGIT.CMD addon: The TSTDIGIT.CMD addon (which should have been installed in your SRE addon directory) demonstrates how one can use SREF_DIGITS and SREF_XBITMAP. It's fairly well commented, and should help illustrate how one can use 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 FONT2 = font to display request number 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&font2=goldodo 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.DOC