OS/2 Shareware BBS: 2 BBS/02-BBS.zip/XGRP_000.LZH/XGROUP.DOC

Text File | 1991-08-23 | 18KB | 507 lines

Documentation for XGROUP v0.0, an XBBS Groupmail/Echomail/Netmail
                  Scanner/Tosser copyright (c) 1991 by M. Kimes
                                 all rights reserved


 Overview, disclaimer, restrictions, BS...

XGroup is a fast 5-D echo/net/groupmail processor for XBBS (MS-DOS
and OS/2) message bases.

XGroup is free for the using in non-commercial environments.  That
means if you make money using it, or use it within commercial
walls, you are violating my copyright.  "Commercial" includes
businesses, government agencies and religious groups.  Go away.  If
you think you're an exception, ask *first*.  You can make XGroup
available for download if you don't charge anything for access to it
or the time to get it as long as you don't alter the original archive.
If that's too much trouble, don't do me any favors; don't keep it
around.

XGroup has no warranty whatsoever.  If it breaks, you have two pieces.
I guarantee only that it will take up space on your storage media at
least until deleted.  Other old sayings.

XGroup makes no attempt to support crappy topology.  Don't make dupes
or you will probably become familiar with the word "excessively"
followed by the word "annoying."  Stars are good topology.

Do you feel alienated yet?  Did I mention there's no warranty?


 Brief primer:

Fidonet-technology mail (echomail, netmail, and groupmail) arrive on
your system in the form of packets.  This is called the "transport
layer."  Packets have a specific pre-defined format so that every
node that receives packets knows how to disassemble them into messages.
A packet consists of a header followed by zero or more packed messages.

Netmail refers to a message (usually private) from one node to another,
or more specifically, from a user at one node to a user at another node.
Netmail usually goes direct (sender calls receiver to deliver), but
routing schemes are becoming more common (where sender calls another
node that calls another node, and so on, until finally the receiver is
called and the route is complete).

Echomail is the more common of the two types of broadcast mail (groupmail,
while superior, is less popular.  This seems common in computerland where
MS-DOS is more popular than OS/2 for no good reason at all).  Echo
messages literally "echo" from one node to another in a sometimes-huge
moebius loop.  The difference between routed netmail and echomail is that
echomail may exist in readable form on all or some of the transit nodes;
each node can be a recipient.  Netmail is normally only unpacked and
placed into the message base on the receiving node.  Due to problems with
hardware, software, topology and the base technology of echomail, duplicate
messages (dupes) tend to be a problem.  Echomail also requires "customized"
packets built specifically for each recipient (this is more a requirement
of existing echomail processing software than the technology itself).
Although most echomail conferences have moderators (someone responsible
for and in charge of the conference), echomail is by nature rather wild
and wooly (some might say uncontrolled and uncontrollable).  But, for all
its faults, it works.  Remember that echomail was kludged together before
the idea of broadcast mail, at least in a Fidonet technology network, was
commonplace.

Groupmail attempts to rectify some of echomail's problems, with a fair
degree of success.  It falls into the "cracks" of typical net and
echomail processing.  "Upbound" groupmail (headed toward the moderator,
or "topstar") is sent as pseudo-netmail so that it avoids echo processing.
At the topstar a common packet is compiled and shipped back out to all
participants.  In this way, messages on all systems are identical.  Dupes
are rare in groupmail due to the method of disseminating these packets,
called "update requesting."  Groupmail can also do without a lot of the
control information echomail carries in a vain attempt to circumvent dupes.
Finally, groupmail conferences can actually be policed by their moderators,
though there is no technological requirement to do so.  Groupmail can also
allow files to follow messages.

For more information on packets and netmail, see FTS-0001, FSC-0039,
FSC-0045 (the packet header format XGroup uses) and FSC-0048.  For more
info on echomail and topology, see FTS-0004.  Groupmail is discussed in
more detail in FSC-0036.  These FTS-* and FSC-* documents are available
from the FTSC (Fidonet Technical Standards Committee) chair; see your
nodelist or ask your bossnode, whichever applies.


 Back to XGroup...

Version 0.0 is a bound executable (runs under both MS-DOS and OS/2).
Although parts of XGroup are still in beta stages (particularly the
groupmail support), the functions used in day-to-day Fidonet
technology net and echomail processing have worked fine for an
extended testing period.  It shouldn't spit garbage out onto the
net if you don't screw up its setup (like telling it to forward to
someone you shouldn't).  If it does, put XST back online and send
me a detailed bug report.  Relax, there's nothing wrong with XST.
I only wrote this because XST doesn't run under OS/2.

XGroup uses those asshole files that HeadEdit can create, so if you
mark your assholes noimport, you won't waste any more time on them
than absolutely necessary.


 OS/2 users note:

Only one instance of XGroup may run at one time.  XGroup should take
care of this on its own and refuse to run if it's already active in
another process.  XGroup will wait for the OS/2 XMsg to finish working,
and vice versa.  XGroup supports full record locking while importing
and exporting, however, and should run fine with other programs that
access the XBBS message areas that also support record locking.  Note
that XMsg is *not* one of those, for reasons that'll be obvious once
you think about it.



 Usage:  XGROUP [configfile] [command]

[configfile] defaults to XGROUP.CTL and must be included if passing a
[command]



 Command line options:

E (xport only)

XGroup will export from your XBBS message areas.  No importing will take place.


I (mport only)

XGroup will import mail.  No exporting will take place.


C (leanup only)

XGroup will tidy up the groupout (see below) directory only.


A (ll of the above)

XGroup will Import, then Export, then Cleanup (same as no command line
command).


M (ake Update Requests)

XGroup will make update requests for groupmail conferences based on the
group date files in the groupin (see below) directory.


P (artially moderated group export okay)

Allows partially moderated group conferences to be exported.


F (ully moderated group export okay)

Allows fully moderated group conferences to be exported.


NE (no echoes)

Performs no echomail processing.


NG (no groups)

Performs no groupmail processing.


? (print help)


Examples:
    XGROUP ALTCFG.CTL E F
    XGROUP XGROUP.CTL NE E




 Configuration file keywords/data:

;

Begins a comment.  Comments are ignored by XGroup.  You can place the
comment indicator anywhere; everything after the semi-colon on the line
will be ignored.


GROUPOUT  <drive:/directory>

This is the directory that groupmail files available for update request
will be placed in.


GROUPIN   <drive:/directory>

This is the directory that groupmail files are moved to just prior to
processing.  Note that if this directory is on the same drive as
GROUPOUT a "move" instead of a "copy" can be used to transfer files
between these areas.  Group date files are also kept in this directory
(these marker files are stamped with the date of the last groupmail you
received; they are used when generating update requests).


GROUPHOLD <drive:/directory>

This is the directory where groupmail files that seem to be damaged in
some way are stored for you to inspect manually.  If this parameter is
omitted XGroup deletes files it can't process.


INBOUND   <drive:/directory>

This is the directory into which you receive mail.  Normally it's the
same directory that your mailer places incoming files into.


OUTBOUND  <drive:/directory>

This is the directory where XGroup will place *.OUTs (Opus/Bink-style
packets) or P.* (XBBS-OS/2 packets).  In the case of *.OUTs, this
directory should *not* have an extension.  BinkleyTerm uses similarly
named directories with extensions to designate different zones.  For
instance, if this directory is C:\BT\OUT and your primary zone is zone
1, mail destined for zone 2 will be placed into C:\BT\OUT.002 and mail
destined for zone 255 will go into C:\BT\OUT.0FF.  I know it's
confusing.  Get AMAX and BOOM if you have to use Opus/Bink-style
outbounds; they'll help.


MSGDIR    <drive:/directory>

The directory for your XBBS message bases.  In case you don't know (and
care), XBBS stores its message areas as two files per area, one of
headers and one of text.  The headers contain pointers into the text
file.  It seemed the best compromise; it's fairly fast, but you don't
have all your eggs in one basket.


MESSAGES  <drive:/directory>

The directory for *.MSGs (if req'd by TONAME entry).  Note that XBBS
doesn't use *.MSGs; this facility is provided to allow you to link
directly to programs that rely on the old, slow, wasteful and, last
but not least, braindead *.MSG format.


LOGFILE   <drive:/directory/filename>

This is the file where XGroup will write informational entries.


ADDRESS   <FTN address(es)>

An FTN address has the form  "zone:net/node.point@domain"
Examples:
            1:380/100.0@Fidonet 2:4177/1.0@Fidonet 1:380/16.1@Fidonet

Note that XGroup is 5-D and addresses must be complete (actually,
guessing takes place if an incomplete address is encountered.  But at
least the first address *must* be complete so we can have some basis
to guess from).


ARCHIVE   <create archive command>

The command that XGroup will spawn to create an archive.  Simple
example:    ARC mwn


UNARCHIVE <extract archive command>

The command that XGroup will spawn to crack an archive.  Simple
example:    ARC ewn


NETAREA   <# of netmail area>

The number corresponding to your XBBS netmail area.  Messages without
AREA: tags are placed here.  Hopefully they're really netmail and not
something some broken software spewed forth.


PACKSIZE  <# bytes at which to compress msgs>

The minimum message size to LZSS compress.  1024 bytes is the minimum
you can set this to.  If omitted, no compression will be performed.


XBBSOS2

This OS/2-only keyword tells XGroup to use XBBS-OS/2 conventions when
naming files.  It enables the ROUTE command below.  Note that this
keyword cannot be used under DOS.  Further note that the outbound
directory must be on an HPFS partition as long filenames are used.


ROUTE     <mask> <type> <FTN address or SAME> <archive command>

This is an XBBS-OS/2 only keyword.  It requires an HPFS drive to work.
<mask> is a partial filename mask.  XBBS-OS/2 uses filenames that are
a type-indicating character followed by the destination FTN address.
For instance, a packet destined for 1:380/100.0@Fidonet will be named
P.1.380.100.0.FIDONET in the outbound.  To archive this packet as
Crashmail you might use the following line:

    ROUTE 1.380.100.0.FIDONET C SAME ARC mwn

Note that the "P." isn't prepended to the filename in the example;
XGroup does that for you.  To hostroute this packet (in fact, all mail
to net 1:380@Fidonet) you might use the following line:

    ROUTE 1.380.*.*.FIDONET N 1:380/1.0@Fidonet ARC mwn

To simply archive all mail on hold (that wasn't processed by previous
route statements--route statements are processed sequentially) use
something like:

    ROUTE *.*.*.*.* H SAME ARC mwn


PRIORITY  <#> <#>

This is an OS/2-only keyword.  The first <#> is the priority class
(1-3), the second the priority within that class (0-31).  XGroup will
set its priority accordingly and run at that priority (handy for making
it run at idle class:  PRIORITY 1 31).


NOTINY

Tells XGroup not to use Tiny Seenbys (Tiny Seenbys are the default).
Since SEEN-BYs are pretty much useless, even dangerous (they're 2-D),
don't use this keyword unless you have some overriding (read: political
BS) reason to do so.  It wastes space (read: your money on the phone
bill).


NOFORWARD

Don't forward mail to "foreign" nodes (nodes outside your net).


NOLOCALFORWARD

Don't forward mail to "local" nodes (nodes inside your net).  Please
don't use this without a really good reason.


FORWARDFILES

Not implemented yet, but remember that groupmail will do it already...


MAXDUPES <# of dupe recs/echo area to keep>

Dupe records require 8 bytes each.  The maximum you can set this to is
8150; the default is 1000.  To turn it off completely use NODUPES.

XGroup uses MSGID kludge lines for dupe checking.  Don't you think we
have too many one-purpose kludge lines?


NODUPES

Turns off dupe checking, letting you reclaim the space those XDUPES.*
files take up.


KEEPPATH

Retain ^aPATH lines locally.  Mainly for debugging.  XGroup uses 5-D
^aNPTH lines on forwarded messages.


KEEPSEENBYS

Retain SEEN-BY lines locally.  Mainly for debugging.  Who would want
the useless things around just to look at?


KEEPDUPES

Places dupe msgs into AREDUPES.$$$ in the inbound directory for your
inspection (it's a packet).  If you suspect the dupe checker is killing
valid messages, turn it on and take a look.


KILLBADDATES

Causes XGroup to unceremoniously kill messages with non-Fidonet-
compatible date fields (some software is broken; ain't it amazing?)
XGroup "fixes" bad dates as they pass through by padding them to
the proper length with "Q"s, to indicate what probably fouled them
up to begin with.  Note that the node you received the packet from
might not be responsible, and the messages's originating node might
likewise be blameless.


ALLOWBADAREAS

Allows echo messages with ^a in front of the AREA: tag to pass through.
Also sends the node that built the packet a message informing them that
their software is (surprise) broken.  The default is to ignore AREA:
tags with ^a in front.  BTW, nodes sending out messages with ^a in front
of the SEEN-BYs also get a nice message from XGroup.  Either of these
conditions are caused by the software that built the packet.  Aren't you
sick of putting up with broken software yet?  I guess you haven't written
a scanner/tosser, then...


TONAME <"to name"> <ROUTE or PROG (OS/2 only) or MSG> [FTN address or prgname]

This allows messages addressed to a certain name to be treated specially.
Only
    TONAME "to name" MSG
and
    TONAME "to name" ROUTE <address>
are available under DOS.  Under OS/2 you can also spawn a detached
process to act on the message.  In this case XGroup first creates a
*.MSG containing the message, then spawns the detached process with the
*.MSG's filename as an argument.

Examples:
    TONAME "AREAFIX" MSG
    TONAME "John Doe" ROUTE 1:380/16.65500@Fidonet
    TONAME "Route Request" PROG ROUTER.EXE


ECHO      <tag> <#> [<FTN address(es)>]

ECHO prefaces information that tells XGroup about an echo.  <tag> is the
"name" of the echo (what follows the AREA: tag; i.e. FLAME for
AREA:FLAME or C_ECHO for AREA:C_ECHO).  You can get this information
from your echomail link.  <#> is the number of the XBBS message area
that this echo is tied to.  The <FTN address(es)> are your links for the
echo (where you get it from and anyone you give it to).

Note that XGroup is a "secure" echo processor.  It won't import mail
from anyone not listed as a link.  If you get mail from someone you
shouldn't it's stored in INSECURE.$$$ (a packet) in the inbound area.
If it's from someone you forgot to add to the links, add them, rename
INSECURE.$$$ to INSECURE.PKT and rerun XGroup.  Otherwise, better think
about passwording out the node in question.

The exceptions to secure processing are "read-only" echo areas.  This
is any area with no forwarding nodes listed.  Also handy for importing
local areas from a mailerless point.  Messages will never be scanned
or forwarded from a read-only echo area.

Examples:
    ECHO  UGH      12 1:380/100.0@Fidonet 1:380/20.0@Fidonet 380/5
    ECHO  SCHWARTZ 32 2:4177/1.0@Fidonet 1:380/16.12@Fidonet
    ECHO  READONLY 51


GROUP     <id> <#> <numdays> <FTN address or !topstar option>

GROUP prefaces information that tells XGroup about a groupmail
conference.  <id> is similar to ECHO's <tag>; it's the AREA: name of the
conference which you can obtain from your uplink.  <#> is the XBBS
message area associated with the conference.  <numdays> is the number of
days that you want to keep downbound groupmail bundles available for
update request by your downlinks.  XGroup <ctlfile> C cleans up the
groupout directory based on these numbers.  The final data item is the
address of your uplink or, if you're the topstar for a conference, the
"topstar option:"

    [F]ully moderated, [P]artially moderated, [N]o moderation
             (only use first letter)).

Fully moderated conferences are never exported from unless you use the
"XGroup <ctlfile> E F" command line.  Partially moderated conferences
are never exported from unless you use the "XGroup <ctlfile> E P"
command line. Non-moderated conferences behave "normally," they export
without a special command line option.

Examples:
    GROUP XBBS     7  1:380/100.0@Fidonet
    GROUP MOJO     25 !N ;we're the topstar for this one


That's a lot of info.  If you need a reminder, type XGROUP ? | MORE



 More BS...

If you have a bug report or suggestion, here's where to reach me.  If
you have a flame for me, sit on it.  What do you expect, a refund?

Note that support, such as it is, is on your nickel.  Poll for answers
a few days after leaving a question (or send an SASE or whatever).  The
program is free; don't expect me to foot the bill for support.

Hope you find XGroup useful.  It was kind of a kick to write.


M. Kimes
542 Merrick
Shreveport, LA  71104
[phone] data