QUOTA: A Quote of the Day addon for sre-http.  5 Jan 2000

Introduction:
------------

QUOTA.RXX is a simple Sre-http add-on that returns a "quote of 
the day" (QOD) text string that can be inserted into any HTML page
(actually, QUOTA is used as an "INTERPRETable SSI").

QUOTA can retrieve quotes from several sources:
   1) randomly retrieve QOD from a given data file.
   2) randomly retrieve QOD from set of data files defined in index file.
   3) retrieve QOD from standard QOD server using TCP/IP socket calls

That data file format is very simple.
Each quote should be on one line, ending with a "# author name" (not including
the quotes". For example:

    In Heaven an angel is nobody in particular.#George Bernard Shaw

Note: Lines starting with a semicolon (";") are treated as comments.

QUOTA.RXX comes with several Russian quote files in (in the KOI8-R codepage),
and one small English quote file. We encourage you to create your own -- let 
us know and we'll post'em on the sre-http web site.


Installation:
-------------

1) Copy QUOTA.RXX file into Sre-http add-on's directory (for example,
   D:\GOSERVE\ADDON)
2) Create a directory to place data and index files that will be used
   by default.
3) Edit QUOTA.RXX to change default parameters (i.e. parameters will be
   used when no one is specified when calling).

   In particular, you should change the DataDir parameter -- it should point
   to the directory you created in step 2.  Note that the default value
   of DataDir is D:\GOSERVE\ADDON\QUOTA.


Usage:
------

To use QUOTA.RXX,  you need to add  INTERPRET keyphrase(s) to an 
HTML document.

The format to use is:

 <!-- INTERPRET FILE QUOTA.RXX param1=value1 param2=value2 ... -->

The simplest format of calling is:

 <!-- INTERPRET FILE QUOTA.RXX -->

In this case add-on will return a QOD randomly chosen from the data file 
defined by the DataFile parameter in QUOTA.RXX. If you want to retrieve QODs 
some other file, you can use the FILE parameter. For example:

 <!-- INTERPRET FILE QUOTA.RXX FILE=C:\MYDIR\OWNQUOTE.TXT -->
or
 <!-- INTERPRET FILE QUOTA.RXX FILE=OWNQUOTE.TXT -->

If you leave out drive and directory, QUOTA.RXX will look for the file in
it's DataDir parameter.

There is another way to organize your QOD's data files. Instead of having one
big file, you can use a small index file that points to a set of QOD files.
The format of this index file is simple: each line should contain a
data file name, followed by the number of line. For example:
  QUOTA01.DAT 6
  QUOTA02.DAT 9
  QUOTA04.DAT 15

You can use this index file by specifying:

 <!-- INTERPRET FILE QUOTA.RXX INDEX=C:\MYDIR\OWNQUOTAS.IDX -->
or
 <!-- INTERPRET FILE QUOTA.RXX FILE=OWNQUOTAS.IDX -->

Again, if you leave out drive and directories, QUOTA.RXX will use
it's DataDir parameter.

Laslty, you can retrieve QODs from a QOD server by using a QUOTA_SERV
parameter. By default, all such servers use 17 port, but you can change this
by using a QUOTA_PORT parameter. For example:

 <!-- INTERPRET FILE QUOTA.RXX QUOTA_SERV=rsb.sax.mmbank.ru -->
or
 <!-- INTERPRET FILE QUOTA.RXX QUOTA_SERV=rsb.sax.mmbank.ru QUOTA_PORT=2017 -->


Plans:
------

1) Anything else you may need :-)


Contacts:
  Timur Kazimirov  timurk@sax.mmbank.ru
  Daniel Hellerstein (danielh@crosslink.net) helped edit the documentation.


Changes at 6 Jan 2000:

1) Added call of SockClose function
2) Added codepage translation:

Now about codepage translation... Very often the contents of quotas data
file(s) is stored in one codepage while client's browser uses another.
To perform codepage translation there are another two parameters - SRC_CP
and DEST_CP. So, if quota file was created in Windows's Notepad it will
probably have 1251 codepage, while most of the browsers use 878 (KOI8-R)
codepage as default, you can perform translation using following syntax:

 <!-- INTERPRET FILE QUOTA.RXX FILE=WINQUOTE.TXT SCR_CP=1251 DEST_CP=878 -->

Note: RXCPAGE.DLL is required to enable this feature!!!


Changes at 6 Jan 2000:

1) Added stripping of HTML tags from the quotes
2) Little correction of code

To strip HTML tags from retrieved quotes and return quota as a plain text
there is parameter STRIP_HTML. By default there is no HTML stripping. Example
of using this parameter:

 <!-- INTERPRET FILE QUOTA.RXX STRIP_HTML=1 -->

Note: If there is an author he will be separated from quote by line break.