New Horizons Shareware Collection/HORIZONS1.BIN/WM4FILES.DAT/AREAREQ.HLP

Text File | 1994-07-30 | 18KB | 465 lines

--------------------------------------------------------------------------
              AreaRequest Automated Help Information File
                         Revised: 07/30/94
--------------------------------------------------------------------------

The mail processor that creates the mail you receive from your uplinks
address uses a system called AreaRequest.  This allows you to use
specially formatted Netmail messages that when properly interpreted, allow
you to perform a wide variety of modifications to your current conference
configuration without requiring human intervention on your uplinks part.

Features like activating conferences, changing your compression method,
rescanning a conference and a host of other options.  This provides you
with a totally automated mechanism of changing the way you receive mail as
well as "what" you receive all by simply creating a Netmail message to
AreaRequest.


SECURITY
--------

Due to the power of this capability, AreaRequest employs built-in security
methods preventing unauthorized systems from gaining access and performing
operations they shouldn't.  Any attempts to activate options you don't
have sufficient access to will produce a response message back to your
system informing you of this while at the same time generate a message to
the SysOp of the uplink system that an illegal attempt had been made.

All security level definitions and configuration is handled at the uplinks
system, so any changes with regard to security must be made directly by
the uplinks SysOp.  If you have any questions in this regard, you should
contact him/her directly.


SPECIALLY FORMATTED NETMAIL MESSAGE
-----------------------------------

AreaRequest makes use of Netmail messages that have been specially
formatted which controls what AreaRequest should do.  When defining this
message there are two distinct sections to configure.  The message header
(to/from addressing etc) and the message body.

The message body is considered optional because if you use the -Q option
(conference query), then nothing needs to be in the message body.  However
if you wanted to turn on/off conferences, change passwords and so on, then
these commands must be specified in the message body.


MESSAGE HEADER
--------------

When defining the message header, the 5 basic sections are described
below.

  TO: ADDRESS    The netmail message should be addressed to your uplinks
                 primary or any one of his AKAs (alternate addresses).

  TO: NAME       The most common name to use would be AREAFIX, but since
                 these names may vary from system to system, if AREAFIX
                 doesn't work for you, you should contact the uplink SysOp
                 for the specific name to use here.

  FROM: ADDRESS  The FROM: address of the message should be your address
                 that has access to the related functions this request
                 is being configured for.  In other words, you should use
                 your correct AKA address relative to the network you're
                 requesting conferences for.  You wouldn't want to use
                 your Fido address for conferences within OCRNET, instead
                 you would use your OCRNET address.

  FROM: NAME     Normally you would use your regular name here.  This
                 field is not used by AreaRequest.

  SUBJECT LINE   This is one of the most crucial definitions because here
                 is where you specify your password which could optionally
                 be followed by a -Q.  The most important part here is
                 that the password MUST BE THE FIRST WORD ON THE LINE. All
                 the remaining parameters must be separated by a space and
                 any combination may be used together.

                             Example Usage: PASSWORD -Q

                 Upper/lowercase characters are insignificant.

                 The -Q option is functionally equivalent to the %QUERY
                 command except that it is placed on the subject line
                 instead of in the body of the message.  For additional
                 information, please refer to the %QUERY definition.


MESSAGE BODY
------------

The message body portion of the Netmail message can be used for various
different purposes.  The activation/deactivation of conferences, using the
extended command set and for specifying which conferences are to be
rescanned, requesting help and so one.

When AreaRequest processes these messages, it will read each line as a
single command along with any "parameters" and execute it accordingly.  So
each command is read on a line by line basis, interpreted and then
executed.  Blank lines are ignored, upper/lowercase characters are
insignificant and commands may not extend past a single line.

Any commands which are read that AreaRequest can't understand, an attempt
to execute options your node address doesn't have access to, as part of
the response message thats sent back to your system, it will contain
information relative to the inability to execute that command.


Shown below is a description of the available commands.

Area Activation/De-activation
-----------------------------

By specifying the area name of the conference, you may activate it by
either of 2 methods as shown below:

              Example Usage: +WILDCAT
                                or
                              WILDCAT

Notice here that you may include the + character in front of the area name
if desired.  It's not a requirement, but is used either with or without
the plus sign.  Only one area name may be specified per line of the
message.


NOTE:

If the requested conference is not configured on your uplinks system, then
AreaRequest will make the necessary changes to your uplinks system and
then forward a request to your uplinks main feed address (node that your
uplink gets their mail from) requesting the conference(s).  Once mail for
the requested conference(s) starts flowing to your uplinks address, then
those messages will automatically be forwarded on to your system at the
same time.

Now, to de-activate the conference, you would use:

               Example Usage: -WILDCAT

This is exactly the same as with the activation option only now you MUST
specify the - (minus) character in front of the area to be deactivated.


EXTENDED COMMAND SET
--------------------

The extended commands are easily distinguished by the percent sign at the
beginning of the command name.  Since each of these commands are
configurable by the SysOp of your uplinks system, you may or may not have
access to all of the ones listed below.  If you attempt to use one and you
are informed you don't have access to its use, you should contact the
uplink systems SysOp and discuss the situation with him/her.

As previously mentioned, each of these commands are interpreted/executed
on a line by line basis so if you wish to execute a command more than
once, you'll need to make additional lines accordingly.

Shown below is a description of the available commands


%COMPRESSION <format>

Allows a node to change the compression method that they currently have.
The <format> must be a valid compression scheme supported by WM such as
ARC, ARJ, PAK, LZH, ZIP and ZOO.

              Example Usage:  %COMPRESSION ZIP


%PASSWORD <name>

Allows a node to change the value of the AreaRequest password that they
currently use. The <name> must be not be larger than 8 characters.  If it
is larger, WM will only use the first 8 characters.

              Example Usage:  %PASSWORD JoeM


%ACTIVE

This command that has no parameters and allows you to reactivate your node
address that has been previously toggled inactive via the use of the
%PASSIVE command.

              Example Usage:  %ACTIVE


%PASSIVE

This command has no parameters and allows you to temporarily toggle all
mail flow "off" for your address. For example, if a you were going away on
vacation for awhile, using the %PASSIVE command would temporarily halt
mail flow and then when you return from vacation, using the %ACTIVE
command would re-enable mail flow.

              Example Usage:  %PASSIVE

You should note that this option does not toggle your conferences on or
off, rather it toggles your entire node definition to inactive leaving
your configuration completely intact.  Then using the %ACTIVE restores
your node definition.


%-ALL

This single option command allows you to toggle all of the conferences
that you're currently receiving from your uplink off.  This command is
very powerful so you should be careful when using it.

              Example Usage:  %-ALL

Normally this command is only used when you will no longer be picking mail
up from that system.


%HELP

This single option command will send you the contents of this information
file.  It will be compressed using your selected compression format,
attached to a netmail message and then sent off to your address.

              Example Usage:  %HELP

Depending on your uplinks configuration, this file may also be sent to
your system automatically if you attempt to execute a command that is
invalid or use a improper format with a valid command.


%RESCAN <areaname> [<value or ALL>]

This command allows you to extract messages from a particular conference
that your uplinks system has message bases for and have those messages
resent to your system.  This is very handy when you first activate a
conference and would like get your system "caught up" on the messages for
this conference.

You should note, if this conference is configured on your uplinks system
as a "passthough" conference, you will be unable to extract any messages.

This option must have at least one parameter specified, with that being
the area name.  If you don't specify the area name, nothing will be
rescanned. The second parameter is the number of messages "backward" that
will be counted and then extracted out.  Such as:

              Example Usage:  %RESCAN WILDCAT 100
                                      or
                              %RESCAN WILDCAT ALL

In the above example, the area name is WILDCAT and the last 100 messages
will be extracted.  The second definition means take ALL of the messages
that are in your uplinks message base for the WILDCAT conference, extract
them and send them to you.  Since this second parameter is optional,
leaving this off will be interpreted exactly the same as using the ALL
parameter.

All of your usual definitions are maintained such as maximum messages per
PKT file as well as maximum archive size will be properly maintained when
using the %RESCAN command.


NOTE:

Unlike other systems, you will need to create multiple definitions for the
various different conferences you'd like to rescan such as:

                   %RESCAN WILDCAT 100
                   %RESCAN FOR-SALE 50


CONTROL LINE INFORMATION
------------------------

When performing a %RESCAN, certain control line information such as
SEEN-BY: and PATH: line information is properly maintained.  This means
that during a rescan, an Origin line will be added (if the message
originated on your uplinks system, all the nodes that your uplink forwards
this conference to will be added to the SEEN-BY: lines and a new PATH:
line will be created containing just your uplinks address.

Caution is advised here because you should make sure you don't forward ANY
of these rescanned messages on to systems that feed your uplinks address.
The rescanning messages may be forwarded to your downlink systems, just
make sure they don't get somehow refed to your uplinks address.

While adding this control info to each "rescanned" message is not a
complete "cure-all" for preventing duplicate messages, it does provide an
extra measure of safety.


%LIST

This command will create a paginated report based upon your security
setup, listing all of the conferences your node address has access to.  It
doesn't matter whether the conferences are selected or not, whether your
uplink address has their system configured for them or not, this is a
complete list that will be generated for all conferences in all the
networks you have sufficient access to.

              Example Usage:  %LIST

This paginated report is then compressed using your configured compression
format and then attached to a Netmail message and sent to your address.
This information is handy when trying to determine what conferences are
available to you based upon your security level.


%QUERY

This command allow you to instruct AreaRequest to generate a listing of
all the conferences that your system is currently receiving on a network
by network basis from your uplink address.

              Example Usage:  %QUERY

This information is handy when you want to find out what conferences you
are currently receiving.


%UNLINKED

This command will create a list of all conferences that your address has
access to which your uplink system already has configured on his/her
system.  In other words, these are the conferences that your uplink
address is already receiving mail for in order to either add to their
message bases or forward on to other downlink systems.

              Example Usage:  %UNLINKED

This option differs from the %LIST command in that it will only list those
conferences based upon your security setup that you have access to which
your uplink address is "already" carrying (not something they "could"
request).


%PKTPSWDIN <name>

This command allows you to change your outbound PKT level password.  This
password is the same password your system puts on its "outbound" mail PKTs
destined for your uplinks address.

              Example Usage:  %PKTPSWDIN NewPswd

If you wish to remove the password entirely, just use the %PKTPSWDIN
without a replacement password.


%PKTPSWDOUT <name>

This command allows you to change your inbound PKT level password.  This
password is the same password that your uplink address puts on its
"outbound" mail PKTs destined for your address.  (These are PKT files that
appear in your inbound directory)

              Example Usage:  %PKTPSWDOUT NewPswd

If you wish to remove the password entirely, just use the %PKTPSWDOUT
without a replacement password.


%PKTFORMAT <format>

This command allows you to change the PKT file format that your uplink
creates mail destined for your address in.  Currently there are three
different types to choose from.

                 TYPE2      - Type 2 PKT format
                 TYPE22     - Type 2.2 PKT format
                 TYPE2PLUS  - Type 2Plus PKT format

There is a limitation here.  If you are a point off of your uplinks
address, then you will be unable to select TYPE2 as your new PKT format
because TYPE2 PKTs don't support point addressing.

              Example Usage:  %PKTFORMAT TYPE22

By far the most commonly used format is TYPE2PLUS.


%UNCOMPBYTES <size in bytes>

When your uplink creates mail destined for your system, it places the
messages into PKT files and then compresses those PKT files into archives
for transmission to your system.  This option allows you to specify the
maximum bytes the archive should uncompress "to" when your system
uncompresses the mail.

Basically the option works like this, when your uplink packs up mail for
you, it will keep a running total of all PKT sizes and when this maximum
is reached, a new archive will be created.

              Example Usage:  %UNCOMPBYTES 3000000

This option is extremely handy when your system is low on disk space and
you need to prevent uncompressing a huge archive that will use more free
space than your system has.  It should be pointed out that this is a "best
guess" setting because the check is done on a PKT basis, so the PKT totals
at the point which exceed the value specified here will trigger an archive
creation.


%MSGSPERPKT <count>

This command allows you to specify the maximum number of messages per PKT
file that your uplink should add to a PKT before creating a new one.

              Example Usage:  %MSGSPERPKT 300

Typical values are 200 to 300.  If you specify a large value here, if mail
somehow gets corrupted, you could potentially lose a larger amount than if
the PKT file was smaller.


SIGNALING THE END OF COMMANDS
-----------------------------

A special group of characters called a tear line should be placed after
the last command to signal AreaRequest that it has reached the end of the
message and to ignore any remaining text.

This tear line consists of three dashes (---) together starting on column
1 of a blank line. Although the tear line is not required, it should be
there as a matter of course.  So if you would like to include text to the
SysOp in the same AreaRequest message, you may do so after the tear line
as it will simply be ignored.


SAMPLE AREAREQUEST MESSAGE
--------------------------

The actual AreaRequest message may be created by using either your front
end mailers editor or the one built into your BBS.  Shown below is a
sample message.


[1]     15 Jun 94  19:24:32                                      Cost: 0
By: Joe Martin, The Power Station BBS (1:161/123)
To: AREAFIX, (1:161/55)
Re: Password
St: Kill  Del/sent Local
─────────────────────────────────────────────────────────────────────────
+FOR-SALE
-WILDCAT

%RESCAN FOR-SALE 50
%RESCAN GAMING ALL
%RESCAN WOODWORKING 100

%QUERY
%UNCOMPBYTES 2000000
%COMPRESSION ARJ

---
Any text below this line will be ignored by AreaRequest and signals the
end of the commands.




--------------------------------------------------------------------------
          End of AreaRequest Automated Help Information File
--------------------------------------------------------------------------