27 Apr 1998
This describes FORUM: SRE-http's multi-threaded discussion group facility.
------------- INTRODUCTION:
SRE-http's FORUM is a "discussion group" web aware program, with
the capability of hierarchically displaying a multi-threaded
(and sub-threaded) "news-group" like list of messages.
The FORUM facilty consists of four files:
FORUM.CMD : The main program, it reads the message box file,
and structures the response to the client.
FORUM.HTM : A simple example demonstrating how to create and
view messages in the "FORUM1" message box.
FORUMRSP.HTM : An example of a customized "response" document
(it's used by FORUM.HTM)
FORUM1.RXX : REXX code, used as a server side include (in FORUM.HTM)
to display links to new messages and subject - reply fields.
To understand the basics on how to use the FORUM facility, please examine
the FORUM.HTM file (it is well documented). For most purposes,
FORUM.HTM can be used as a template for your own "discussion list"; with
appropriate modifications to the descriptive material, and perhaps
the addition of other "fields" (using INPUT elements).
A note on CEILIDH:
CEILIDH is CGI-BIN script, written in C, that also
provides a multi-threaded forum. It has a "prettier" user interface,
with more double checks, but currently only supports one discussion
group (though you can buy a version that supports more then one group).
It also requires long file names (that is, it won't work under FAT).
For more information, check out http://www.g0rvx.demon.co.uk.
------------- FORUM AND MESSAGE BOXES
FORUM is built around SRE-http message boxes.
These message boxes, which are simple ascii files
created using the MESSSAGE facility of SRE-http,
have a simple (SMTP-like) structure. FORUM uses a variety
of information contained in the message box file to decide
how to display the information contained in the messages
comprising the message box.
The files used as "message boxes" are located in the MESSBOX_DIR directory
(for example, D:\GOSERVE\MESSBOX); and have a .LOG extension. For example,
a message box of FORUMX might correspond to D:\GOSERVE\MESSBOX\FORUMX.LOG.
One convenient way of choosing a message box is with the "hidden"
element in a FORM, for example:
.
As an alternative, you can explicitily point to a message box in
an link), see FORUMRSP.HTM for an example.
In addition to the .LOG file, FORUM creates/modifies an .IDX file as an
"index". This "REXXLIB-formatted" file substantially speeds up
the display of the message list, as well as the display of
selected messages.
Note that FORUM reads, but does not write, to the .LOG file.
Writing to the .LOG file (that is, adding messages) is done by
SRE-http's MESSAGE facility. If you are interested in creating
your own forum's, we recommend reading the MESSAGE section
in SREFILTR.HTM (or examining FORUMRSP.HTM).
One convenient feature of message box files is the ability to
specify an HTML "header". That is, FORUM reads the text before
the first message (where messages are seperated by special "seperator"
lines of text), and displays it at the top of the message list.
Thus, when creating a message-list, one should first create the appropriate
.LOG file, and include an (arbitrarily long) descriptive header at
the top of the file (using HTML).
------------ SPEED CONSIDERATIONS:
The processing of the message box file can be quite time consuming.
To speed things up, FORUM uses index files (with .IDX extension).
These contain a subset of the information contained in the .LOG file.
When a simple message list is requested (that is, a list containing
the subject, name, and the date of the message), the .IDX file is used.
Similarly, when a specific message is requested, the .IDX file is used
to help find it.
If any FIELD statement is used (see below), the .IDX files is NOT used.
Since parsing the .LOG file is MUCH slower then reading the .IDX file,
there is a noticeable lag in response (especially if there are more
then a dozen or so messages).
Therefore: In general, we do NOT recommend use of FIELD statements
when displaying the message list. However, you can use the ABSTRACT
statement to allow display of an "abstract" of the contents (which
is stored in the .IDX file), with little throughput penalty.
This provides some flexibility.
Note that use of FIELD statements, along with the FIELDS_ONLY statement,
to control display of "specific messages" does not adversely impact
throughput.
The .IDX file is refreshed whenever the .LOG file is updated (that
is, whenever a message is added). It is also refreshed whenever
a message deletion occurs (either from a DELETE_MESSAGE request,
or due to a DURATION expiration).
If the .IDX file is older then the .LOG file, FORUM will be forced
to read the .LOG file. Therefore, the response to the first "request to see
the message" list (after the addition of a new message) may be quite slow.
To avoid this, you can include a INDEX=YES field when invoking
the MESSAGE facility. This tells MESSAGE to update the .IDX
file after writing the message (and after responding to the
request).
Note that a "message deletion" update occurs after the response
is sent to the client -- response will not be effected (although
other clients may be effected by the increase in system load).
------------ DELETED MESSAGE DETAILS
FORUM provides two mechanisms for deleting messages. The first
uses the DELETE_MESSAGE statement, in conjunction with a "message
specific" password. This is meant to provide the poster with the
ability to delete a message at any time; provided a non-empty
PASSWORD field was included in the message (and she remembers
what it is!).
The second means is via the DURATION field (included in the message).
Whenever FORUM reads a message box, it compare (non-empty) value of
the duration field against the current date and the message's date.
If the current date is more then DURATION days older then the
posted date, the message is marked as expired (and not displayed).
To handle these deleted messages, FORUM will rewrite the message
box file and remove deleted (or expired) messages. There is
one complication: if the message is at the "head" of a thread,
removal of it will destroy the thread -- all following messages
in the thread will be "orphaned" (they will be displayed,
but not as a thread).
To avoid this problem, a placeholder record is inserted in the
message box file. When such a placehold is encountered, FORUM
will create a non-linked, subject only element in the display, which will
serve as the "root" of the thread.
Note that if a message is NOT the head of a thread (or subthread),
it will be completely removed from the message box.
Furthermore, "placeholder" records may be deleted at a later date, say if
a "response" message expires at a later date.
------------ FORUM OPTIONS:
The following options are understood by the FORUM procedure. They
can be specified explicitily in an type of link,
or as elements in an HTML FORM. Note that as an aid to programmers,
some of these options have synonyms, which will be listed between
{parenthesis}.
MESSBOX {MESSAGE-BOX, MESSAGE_BOX, MESSTYPE}.
This indicates which message box to use, which may be in a
subdirectory. If you are using FAT, keep the name component to
less then 8 characters, and do NOT include an extension.
Examples (say, as coded into a link):
/FORUM?MESSBOX=FORUM1
or, /FORUM?MESSAGE_BOX=RESEARCH/PROJECT1.
... where the RESEARCH subdirectory (of the MESSBOX_DIR directory)
must exist!
If you do not specify a MESSBOX, the ANYONE message box will be used.
FORM {FORM_NAME FORMNAME FORM-NAME}:
Used to indicate a URL pointing to a "front-end" that should be
used when FORUM asks for new messages. If no FORM is specified,
FORUM will NOT provide the opportunity to respond to messages.
Example:
&FORM=/SAMPLES/FORUM.HTM
Note that you can use any legitimate URL (such as one that points
to a virtual directory). Be aware that the usual access controls
apply to this URL.
LIST_ALL {LISTALL LIST-ALL LIST}:
Used to display the entire message box as a text file. No
formatting is done, and all fields are displayed.
Since this may be more than you want the average client to
view, the client must have a "VIEWMESS" (or SUPERUSER) privilege
for this to work (see SREFILTR.HTM or INITFILT.DOC
for details on privilege assignation).
The following options control what information is written when the message
list is displayed.
ABSTRACT_LENGTH {ABSTRACT_LENGTH}:
Used in conjunction with the FIELD fields to limit the length of
the "field abstract" written when a message list is displayed.
By default, an ABSTRACT_LENGTH of 100 is used.
Example:
&ABSTRACT_LENGTH=70
(the first 70 characters, with extra spaces and CRLFs removed,
are displayed).
ABSTRACT:
Used to indicate that an "abstract" (the first 120 characters of
the CONTENTS) should be displayed when the message list is displayed.
Example:
&ABSTRACT=YES
The result of ABSTRACT=YES is very similar to
that of a FIELD=CONTENTS statement. There may be a big difference
in response time -- since the ABSTRACT=YES statement uses the
.IDX file if possible (a much faster solution). However, if
you want to display other fields (say, an E-MAIL field),
ABSTRACT=YES is exactly equivalent to FIELD=CONTENTS.
Note that when the .IDX file is used, ABSTRACT_LENGTH statements
are ignored (the first 120 character are always displayed).
FIELD {FIELD_LIST}:
Used to choose which FIELDs to display. You can specify several
seperate FIELD statements, or specify several fields in a
FIELD statement.
Examples:
&FIELD=CONTENTS&FIELD=E-MAIL
or
&FIELD=CONTENTS+E-MAIL
(note the use of the + character as a URL encoded space character)
Note that certain values in a FIELD statement have synonyms:
CONTENTS: MESSAGE and CONTENT are synonyms.
FIELDS_ONLY {FIELD_LIST_ONLY}:
When a FIELDS_ONLY statement is present, then only fields listed
in FIELD statements will be shown WHEN A SPECIFIC MESSAGE IS
DISPLAYED. That is, by default ALL fields in the message box
are displayed when a specific message is requested. FIELDS_ONLY
can limit this to just the requested list of fields.
Example:
FIELDS_ONLY=YES
Note that the ABSTRACT_LENGTH statement does not apply to
"specific message display"; the entire contents of a field
are always displayed.
DELETE_MESSAGE {DELETE-MESSAGE}:
Used in conjunction with MESSAGE_ID and PASSWORD fields to
request deletion of a message.
Example:
&DELETE_MESSAGE=YES
PASSWORD:
Used, with the DELETE_MESSAGE statement, to instruct FORUM
to remove a message from the message box. This password
must match a PASSWORD saved with the message. If no
PASSWORD exists for a particular message, the message can NOT
be deleted.
Example:
&PASSWORD=JONES2
Note that the PASSWORD is stored in an encrypted format (as
done by the MESSAGE facility) -- the encrypted value of
the PASSWORD statement is compared to the encrypted value
stored in the message box.
These next options are rarely need by casual document writers,
but are extensively used by the FORUM procedure when creating
"read and write specific message" links to be included in responses.
MESSAGE_ID {MESSAGE-ID MESSAGEID}.
Used to select which "message" to display. It is used by the
FORUM procedure when creating and viewing messages.
Example:
&MESSAGE_ID=19961003015036.80.77@131.21.565.43
THREAD_ID {THREAD-ID}:
Used to indicate which thread this message is part of.
It is used by the FORUM procedure when creating and viewing messages.
Example:
&THREAD_ID=19961003193612.80.15@151.121.65.143
---------- SPECIAL FIELDS IN THE MESSAGE BOX:
The message box file (typically created by SRE-http's MESSAGE
facility) can contain a number of fields. Some of these have
special meaning for the FORUM procedure:
These are used when displaying the message list, or have other special
uses:
NAME: The name of the message poster (as provided by the message poster).
A is used if not present.
SUBJECT: The subject of the message. A is used if not present.
DATE: Used to indicate the posting date. Note that a DATE field is
always added by the MESSAGE facility.
CONTENTS: The contents of the message -- the last field in the message,
with everything following it (to the end of the message) used
as the "contents" of the message.
E-MAIL: If present, FORUM will provide a "mail a response directly to"
link.
The following have special meaning. FORUM will not display these
fields, even if specifically requested (say, with FIELD statement).
DURATION: Delete this message after DURATION number of days (uses
the DATE field).
PASSWORD: The "encrypted" password, used if message deletion is requested.
ORIGINATOR: IP address of the message poster. FORUM suppresses
display of this field.
MESSAGE_ID: Used to identify specific messages. Note that a
MESSAGE_ID is always added by the MESSAGE facility.
THREAD_ID: Used to identify which thread this message is in.
If missing, this is assumed to be the "head" of a new thread.
THREAD_SUBJECT: Used to identify the "subject" of the thread (in
contrast to the "subject" of the message). Used when
FORUM provides a "add message to this thread" link.
--------- Using FORUM with the SRE-http "broadcast and recieve" facilities
One of the features of the SRE-http "MESSAGE" facility
is the ability to "broadcast" a recieved message to a (pre-established)
list of E-Mail addresses. This augments (and can even replace) the addition
of the message to a message box file.
The combination of the "broadcast" option of MESSAGE, the READMAIL and
MAILLIST facilities, and FORUM allows for the creation of a simple
list server, with automatic archiving of messages! Note that FORUM is
a passive actor in this scenario, since it merely reads the message box.
For further information on how to set up such a "list server with archive",
see the discussion of the BROADCAST_LIST option in the MESSAGE section
of SREFILTR.HTM. For discussion of the READMAIL and MAILLIST facilities,
see READMAIL.DOC
Note that for both programs, some setup (of SRE-http parameters,
or internal variables) may be required.