OS/2 Spezial

home *** CD-ROM | disk | FTP | other *** search

/ OS/2 Spezial / SPEZIAL2_97.zip / SPEZIAL2_97.iso / ANWEND / ONLINE / SREFV12J / COUNTER.DOC < prev next >

Wrap

Text File | 1997-06-10 | 15KB | 289 lines

25 May 1997: Description of the SRE-Filter COUNTER.RXX add-on A) Introduction ------------------ COUNTER.RXX is a flexible "hits" counter generator and request-information recorder. It can be invoked in a number of different manners: 1) As a server side include (instead of ): COUNTER.RXX can generate a textual counter when "called" as a server side include. 2) As an in-line image (instead of the XCOUNT cgi-bin program): COUNTER.RXX can generate a simple "odometer" style counter graphic. 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, 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. Acknowlegments: this is adapted from "The SSI Hit Counter" of William Herrin (http://www.why.com/herrin). B) How to install & use COUNTER.RXX -------------- 1) Copy COUNTER.RXX to your GoServe "addon" directory 2) Create a (set of) .CNT files -- one for each "document" you wish to "count requests for" (though it is permissible to have several documents "share" a single .CNT file). NOTES: * In general, you should create these .CNT files beforehand -- COUNTER.RXX may FAIL if the indicated .CNT file does not exist (for details, see the description of CREATE_FILE below) * When you create them, you should leave the .CNT files empty. 3) As mentioned above, there are three ways you can invoke COUNTER.RXX a) As a "server side include" (a text counter is written) Place keyphrases into your HTML documents. For example: 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 an in-line image (a simple black on white "odometer"). Place "in-line images" elements in your HTML documents. For example: <IMG SRC="/COUNTER.RXX?option_list"> elements in your HTML documents, where: * option_list is an & delimited list of formatting instructions (see below for details) * option_list must include a GRAPHICS=value option in the option_list (along with the FILE=filename option) c) In conjunction with the SENDFILE facility. Place a "SENDFILE URL" in your HTML documents. For example: <a href="/SENDFILE?filename&counter=option_list">Send file </a> * option_list is a + list of formatting instructions (see below for details) 4) You may also want to change a few variables in COUNTER.RXX: a) Counter_dir : If set to 0 (the default), the '.CNT' files are expected to be in the "requesting documents" own directory. Otherwise, counter_dir should contain a fully qualified directory name. b) Counter_image_dir: Set "URL" that points to the "digit images". The counter_image_dir should be set to a "URL" that points to the root of the image directories. Each differant type of counter images should be in it's own directory. For example: counter_image_dir='http://foo.bar.net/cntimgs/' Note: To suppress-- set to 0 b) Write_users : If write_users=1, then along with the "number" of hits, client specific information is recorded. See f) below for details. Notes: * if you use the write_users option, privacy concerns lead us to strongly recommend using a web-inaccessible counter_dir (i.e.; by setting COUNTER_DIR='\GOSERVE') * 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 server administrator(s). c) Suppress_recent: If non zero, and if Write_users=1, then the user list is checked against the client's ip address. If: i) if 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 d) Suppress_loguser: If equal to one, then suppress the LOGUSER "option". That is, if one, then always use the value of write_users. e) Suppress_owners: If equal to one, then if the request is from an owner (as listed in the OWNERS variable), the counter will not be incremented. f) Create_file: If equal to one, will create a .CNT file if none already exists. Otherwise, if no .CNT file exists, COUNTER will return nothing. g) 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.htm 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 "output field" variables: save_ipname: Write the "dotted" IP Name (if none available, save IP address) save_username: Write the SRE-Filter "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 write_users=1) C) 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 "odomoter" (IMG SRC="/COUNTER.RXX.."> variant, you MUST include the GRAPHICS option in the option list. Otherwise, the options are: file="filename" : The name of the .CNT file (relative to the counter_dir, or relative to the the document's own directory if counter_dir=0). silent="" : If a silent is present, the .CNT file will be updated, but nothing will be displayed. nocommas="" : If present, every 3rd digit commmas are NOT written This is implied if width>0. If not specified, commas WILL be included. width=ndigits : minimum width of counter (padded with 0's if need be). Default is 0 -- which means "don't try to pad". min=min_value : minimum value to count from (the default is 0) max=max_value : maximum value to count to (the default is 2147000000) rollover="" : if present, will reset counter to min when max is hit. Default is to not rollover. 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 present, append a th,rd,st, or nd "suffix" to the number (1st, 2nd, 3rd, 4th, etc). Default is do NOT add this suffix. 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 that "invoked" COUNTER.RXX will be used. Note: If you are using the GRAPHIC option, you should also use the SEL option. loguser=arg : If ARG=YES or NO, and SUPPRESS_LOGUSER<>1, then override the WRITE_USERS variable. YES = record client, NO=Do NOT record client. graphic=arg : If arg=YES, then a white on black background odometer graphic will be created. If arg=NORMAL, then a black on white background odometer will be created. Note that if either a graphic=YES or graphic=NORMAL argument is included, nocommas is set to 1, and ith is set to 0. THIS ARGUMENT IS REQUIRED IF YOU ARE INVOKING COUNTER.RXX AS AN INLIME IMAGE. Note: it is strongly recommended that you include a SEL option when you use the GRAPHIC option. imgtype=arg : If arg is the name of a "digit gif containing subdirectory", then a series of IMG elements are returned to the client that point to the appropriate images. For details, see the miscellaneous topics section. imgalign=arg : Arg should be MIDDLE, TOP, or BOTTOM -- effects the alignment of digits created when imgtype is specified. 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" will be displayed. Notes: * For this 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's 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. D) Miscellaneous topics ----------- * 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). Example: sendfile?srefiltr/ver12/srefv12i.zip&counter=file=sref12 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 an in-line image <IMG src="/counter.rxx?file=test1&width=5&graphic=YES"> <IMG src="/counter.rxx?file=test2&increment=0&graphic=NORMAL"> Note the use of & as an argument seperator! * Using COUNTER.RXX to return "fancy" counters. To use COUNTER.RXX to return fancy counters, consisting of a string of graphical digits, you should use the IMGTYPE 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 returned: <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. Hint: you can find lots of "digit gif files" at http://www.digitmania.holowww.com. Or, for a small sampler, check out the DIGITS.ZIP file packed with SRE-Filter (see the READ.ME file in DIGITS.ZIP for details). * Examples of use as a 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 counters to retain "individual information", and some not to, you can create 2 versions of COUNTER.RXX (say, CNT1.RXX and CNT2.RXX); and call the appropriate one: say; use INTERPRET FILE CNT1.RXX or INTERPRET FILE CNT2.RXX.