This is the ArBot Help Text file, version 1.0.
This text is wrapped at 78 characters.

ArBot is an automated email reply bot for searching Microsoft Outlook personal
folders. ArBot was born in May of 2004. ArBot is written in Visual Basic 6.
It's primary mission is to search the VRF Archive and return messages and
attachments from days past.

The search engine is very simple yet hopefully flexible enough to allow fast,
simple data mining from the extensive archive of messages available.

If you can't find what you're looking for but you are certain it went out over
the VRF, remember that my archive only dates back to September of 1998 and it
is not complete. I have the means to improve it but it will take time.

MAKING AN ARBOT REQUEST
To request information from ArBot, send email to vrf_archive@comcast.net with
the subject set to the word ARBOT. ArBot will not reply to any message who's
subject field contains anything other than or in addition to ARBOT.

ARBOT COMMANDS
The body of the request specifies commands and parameters to the ArBot search
engine. A blank body returns this help text. The HELP command also returns
this help text. ArBot commands are not case sensitive. Parameters are also
not case sensitive. Currently ArBot does not provide a case sensitivity switch
Example searches are detailed after the command and parameter lists.

ARBOT PARAMETERS
A parameter is a named value that ArBot recognizes, followed by an equal sign,
followed by some text. Date parameters must be given in a form that Visual
Basic can handle, but for simplicity MM/DD/YYYY form is recommended.

COMMANDS
Notes are preceeded with an asterisk *. ArBot commands include the following:

  Help   *A blank message is interpreted as a Help command.
  Search *Parameters define search, Search command is always implied.
  Fetch  *MessageID parameter defines search, Results = Full is implied.

PARAMETERS
Angle brackets <> are used to indicate text taken from the body of the
request message. Where default or implied parameters exist, they are indicated
in curly braces {}. Words in parentheses () indicate that these words must be
used as parameters. Mutually exclusive options are separated with a pipe
symbol |. Notes are preceeded with an asterisk *.

ArBot parameters include the following:

  Results         = <(full) | (summary)>  {summary}

  From            = <email_address> *Partial matches always succeed.
  Before          = <date> *Use MM/DD/YYYY format to avoid parser problems.
  After           = <date>
  Between         = <date (-) date> *Hyphen is required
  SubjectIs       = <string> *Exact match succeeds.
  SubjectContains = <string> *Partial match succeeds.
  BodyIs          = <string> *Exact match succeeds.
  BodyContains    = <string> *Partial match succeeds.
  HasAttachment   = <(yes) | (no)>
  AttachmentName  = <string> *Partial match always succeeds.
  MessageID       = <string> *Exact match required.

Using an AttachmentName implies HasAttachment = Yes. When searching for
attachment names, any partial match to any attachment always succeeds.

Any parameter that is omitted from the search request is not considered for
matching. The fewer parameters supplied, the broader the match range will be.

EXAMPLES
Search for all messages from Complete Test in 2003 with "GPIB" in the subject:

From = completetest.com
Between = 1/1/2003 - 12/31/2003
SubjectContains = GPIB

* NOTE: Unfortunately I was not aware that Outlook mail objects do not expose
email addresses. There currently is no way to search for messages from a
particular domain. This will be fixed ASAP.

---

Search for -SHAWN-'s DefaultPrinter example:

From = shawn@testech-ltd.com
AttachmentName = DefaultPrinter

* NOTE: Unfortunately I was not aware that Outlook mail objects do not expose
email addresses. To search for messages from me, use From = Shawn Fessenden.
This will be fixed ASAP.

---

Search for any message from May of 2002 to the present with "SICL" in the
subject and "INIT" somewhere in the body text:

After = 5/1/2002
SubjectContains = sicl
BodyContains = init

*Notice that search targets are not case sensitive. Commands are not case
sensitive either.

---

Search for any message with "Excel" somewhere in the body that has at least
one attachment of any name:

BodyContains = EXCEL
HASATTACHMENT = Yes

*Parameter names are not case sensitive.

---

Search for any message with "Word Automation" somewhere in the body:

BodyContains = Word Automation

---

RESULTS FORMAT
When you receive the results of your search, note the message ID of the
message or messages you wish to fetch with the fetch command and send
another request to ArBot:

MessageID = 0000000011C77702B4B2CB4A9FD20D99053FF73024662200
Fetch

Note that the fetch command must have a MessageID set and there must be
an exact match. Only one message can be returned at a time. You must send
multiple requests to fetch multiple messages. Do not send a fetch request
as a reply to a search request. If the subject field contains anything other
than or in addition to the word "ARBOT" ArBot will not reply. Furthermore,
if the subject includes the word "ARBOT" along with something else (i.e.,
"RE: ArBot") ArBot will automatically delete the message.

All of the previous examples with the exception of the last return summary
information, the default result format. The purpose of the summary is to
give you complete information on the message or messages that matched your
search. What you're really interested in is the MessageID. This is a unique
tag that is used to fetch the message and any attachments it has.

When you receive a reply from ArBot, the first thing you'll notice is that
"RE:" has been added to the subject so that it now reads "RE: ARBOT" (the
word ArBOT is not case sensitive). In the body of the message, your request
text is copied back to you. Next is a tear line (---) and ArBot's header
info.

This header information includes:

The words "Do not reply to this message". If a message with the subject "RE:
ARBOT" ever shows up in the inbox, it is automatically deleted. I always
welcome comments, questions and suggestions, but please do not include the
word "arbot" (not case sensitive) in the subject. I will never see them.

The words "ArBot AutoReply from vrf_archive@comcast.net". This is just to
confirm the fact that the message was originated from ArBot.

Then you get ArBot's copyright information on two lines.

Next is ArBot's major, minor and revision numbers in the format "ArBot version
xx.xx rev xx". These numbers are taken from the ArBot executable and will
increment from time to time as bugs are fixed and features are added.

Next is a complete listing of search parameters. These parameters are repeated
back so you can familiarize yourself with how the parser works and help you to
refine your search if necessary.

The last two lines read "Search returned xxxx results in xx:xx.xx minutes.
Results follow:". The number of results is reported along with the total
number of minutes and seconds of CPU time the search took. This is not the
total time the search took in real time, just how long the CPU worked on it.
Windows does an awful lot of stuff and ArBot runs on my Internet gateway
computer so there are going to be many tasks running concurrently.

The bottom line is that a request can take a few minutes of real time while
occupying only seconds of CPU time. Initial tests indicate the entire archive
of over 8,000 messages can be searched in under a minute of CPU time.
Depending on CPU load, this works out to about 10 minutes of real time. If
you do not receive a reply back from ArBot in roughly 20 minutes, then either
my computer has gone offline, ArBot has a huge backlog of searches or it has
crashed.

In the event that backlogs become common, I will add a confirmation reply when
your request is received with an estimated completion time. If this completion
time is habitually over 15 or 20 minutes, I will upgrade the software when I
can.

Next are listed each of the results. Their format is as follows:

From        = [email_address] *Email address of the original poster.
Date        = [date_received] *The date that I received the original post.
Subject     = [subject]       *The complete subject of the original post.
MessageID   = [message_id]    *The message's unique id.
Attachments = [filenames]     *Complete list of attached files.

* NOTE: Unfortunately I was not aware that Outlook mail objects do not expose
email addresses. Consequently the "From" information will be the Microsoft
Outlook "Display Name" of the original poster. In some cases the display name
*is* the email address. Those who use Outlook or Outlook Express for a mail
client are identified by their "Display Name". This will be fixed ASAP.

When Results = summary, this result record will be followed by a tear line and
the next result, and so on for each result match.

When Results = full, the result header is followed by the original message
body text and files are attached to the reply.

I can't stress enough how important it is to search with the default case of
results = summary. If you request full results for a search that could
potentially match tens, hundreds or even thousands of messages, all the
messages and all the attachments will be returned.

First off I have a limit of 10M on my Comcast account. Any outgoing message
that is larger than that will be bounced and I'll never know about it because
ArBot will automatically delete the bounce notice. Second I don't think I need
to caution anybody about trying to download 10M over a dial-up connection.

INTERPRETING ARBOT'S HEADER
ArBot returns it's search parameters header in the following form:

Search parameters:
  From     : $FROM (Always partial matching)
  Subject  : $SUBJECT (If SubjectIs is True, then exact match)
  SubjectIs: $SUBIS
  Before   : $BEFORE
  After    : $AFTER
  Between  : $BETWEEN
  BodyText : $BODY (If BodyIs is True, then exact match)
  BodyIs   : $BODIS
  HasAtt   : $HASATT
  Attachmnt: $ATTIS (Implies HasAtt = Yes; always partial matching)
  MessageID: $MSGID
  Results  : $RESTYP
  Command  : $CMDTYP

The formal params (with dollar signs $) are replaced with actual parameters
from the search object parsed from your request. The format is not exactly the
same as the command and parameter lists given earlier. An explanation of how
to interpret the header follows.

String parameters are From, Subject, BodyText, Attachmnt and MessageID. These
parameters should be set to those given in your request. If they are not, then
spelling may be a problem. Check the ARBOT PARAMETERS section for exact
spelling of the parameters. Also, there must be an equals sign between the
parameter name and the parameter value.

From is always partially matched. If a partial match occurs the archive msg
is considered to have fulfulled the match criteria.

Before and After are date parameters. If they are set to 12/30/1899 don't
worry about it. This means they are not initialized and will not be used as
match criteria. If you did specify a Before or After parameter and they are
not equal to the dates you specified then spelling or equals may be a problem.
In the case of Between, a hyphen (-) must separate the Before and After dates.

Between is a boolean parameter. If it is true then the search is to match only
messages after the After date and before the Before date.

SubjectIs and BodyIs are boolean parameters that, if true, indicate that the
searches for subject and body matter are to be exact. If they are false, then
the match is to be partial.

HasAtt is an enumeration of values "Don't Care", "Yes" and "No". They indicate
that messages will be matched based on those criteria.

Attachmnt comes from the AttachmentName parameter. It is always partially
matched. If any attachment to any message partially matches a request, the msg
is considered to have fulfulled the match criteria.

ARBOT AVAILABILITY
The Comcast network is in pretty bad shape here in Aurora, IL. Since I have
become a Comcast customer I have experienced many problems. I will do my best
to make sure that ArBot is available 24/7 but many of these issues are out of
my hands completely. Also, I have not completely recovered from the collapse
of Oswego Software, Inc. I rent an apartment in a pretty run-down home on
Aurora's East side and there are frequent power interruptions.

Theoretically everything should come back when the power comes back, but I
have seen instances where the modem does not reset properly. I can only
apologise in advance for these inconveniences.

As of the release of ArBot, after patiently explaining to those who should
know better that you can't feed two dozen devices off a single drop Comcast
*finally* agreed to give me my own drop and all connectivity issues should
now be solved. We shall see though. The network is still in pretty bad shape
around here.

In any case, please do not post multiple requests for the same information. If
ArBot does not reply the first time it will certainly not reply on the second
or any subsequent attempt. You can ping the ArBot server at 67.167.88.209. If
it does not reply then it is offline. If it *does* reply then ArBot has
crashed or is very busy and I will fix it as soon as I can.

ArBot a single-threaded Visual Basic application and processes requests on a
first-come first-served basis. There's always the chance that a late reply
simply means that ArBot has a lot of requests to process. If this becomes a
problem I will upgrade the software accordingly.

BUG REPORTS, QUESTIONS AND COMMENTS
Send bug reports, questions and comments to vrf_archive@comcast.net. DO NOT
INCLUDE THE WORD "ARBOT" IN THE SUBJECT. I will assume any messages that post
to vrf_archive@comcast.net that are not search or fetch requests will be ArBot
comments and are intended for me.

Any message who's subject does not exactly equal the word "arbot" but does
include that word will be automatically discarded. Any other message I will
see and reply to when time permits.

The VRF Archive will have a home page as soon as I can find time to publish
one and there will be a form included to send me bug reports, questions and
comments. This could be months away though.
-SHAWN-
