synchro.net/synchro.net.tar/synchro.net/modem.madness/SMMNETML/SCAIL203.ZIP/SCAIL.DOC

Text File | 1992-03-19 | 22.2 KB | 502 lines

/*************************************************************/
/* SCAIL 2.03Ω     Personal Echomail Scanner             */
/* Written by Alex Brodsky and Vulkan Technologies Inc.      */
/* Copyright (c) 1991. All rights reserved.                  */
/*************************************************************/

Table of Contents

     Legal Stuff....................................Page 2
     Purpose and General Overview...................Page 3
     Operations.....................................Page 4
     Command Line Parameters........................Page 5
          <first name>..............................Page 5
          <last name>...............................Page 5
      </n($):path>..............................Page 5,6
      </f:path>.................................Paeg 6
     Examples.......................................Page 7,8
     Example Batch Files............................Page 9
     Error Messages.................................Page 10
     Bug Reports, Contacting the Author,
        Famous Last Words.......................Page 11

1.0 Legal Stuff                        PAGE 2
     -----------
     This program is freeware. You have the right to use this software
     as much as you want on as many machines as you want, whenever you
     want.  You may distribute this software freely in its original
     form.  You may modify your personal copy of SCAIL and release it
     to public use under the following conditions:

          1.   You must send the author the complete source of all
               the  modifications you have made.
          2.   You must retain the original copyright notice and
               add your own.
          3.   You must clearly specify in your documentation the
               date(s) and type(s) of the modification(s) you have
               made to the program.
          4.   You must include a copy of this license with your
               release.
          5.   You MUST release it as freeware.  You may NOT release
               it into the shareware or commercial market.

     This program comes with no warranty of any kind.  It has been
     tested on several machines and works with no problems.  However,
     the author is not responsible for any damage caused by this
     software.

     You may not charge more than three Canadian dollars for
     transferal or copying services.  This program may be included in
     any non-commercial package as long as the three dollar rule is
     not violated.

     Commercial users may use this program in their organization's
     internal operations, but may not release this software as part of
     their commercial packages.  If a commercial organization wishes
     to sell this software as part of their package they must contact
     the author and purchase a license to do so.

     Any other software or companies mentioned in this document are
     trademarks of those respective companies and are used only to
     facilitate the explanation of this software.

     This concludes the legal part of this documentation.

     For a donation of ten dollars or more, you will receive the
     source code to this program.

     If you do use this program, I would really apreciate you sending me
     a quick netmail message saying so.  Just to let me know that my
     efforts have not gone to total waste. <grin>

2.0 Purpose and General Overview                PAGE 3
     ----------------------------
2.1  General Assumptions
     This document assumes that the user is familiar with the software
     and principles of point operation.  The user should have a basic
     knowledge of batch files and should be well versed in DOS.  It is
     assumed that the user knows the basics of FidoNet operation and
     is operating a point (or will be in the near future).

2.2  System Requirements
     The requirements for this software are a basic point set-up,
     using the *.MSG (FTSC) or SQUISH(tm) format for message storage,
     and DOS 2.0 or greater. However, DOS 3.3 or greater is preferable.

     An AREAS.BBS file is required. If you do not already use
     AREAS.BBS with your mail processor, you will need to create one.
     Please check the examples section of this manual.

2.2  What is SCAIL?
     SCAIL is a personal echomail scanner for point systems. It scans
     through your newly received mail and tells you whether any
     echomail addressed to you has arrived.  This is especially useful
     if you read high-traffic echoes, since it saves you the trouble of
     manually scanning them.

2.3  General Operation
     SCAIL examines AREAS.BBS to determine which message areas you
     have, and then scans each message directory in the order they are
     listed.  Only the header of each message is read.  If the ToName
     of a message matches your name, SCAIL displays a description of
     the message on the screen and (optionally) records it in a
     message addressed to you.    SCAIL can either save this message in
     FTSC or SQUISH format.  If you use a log file when tossing mail,
     SCAIL can use this file to scan only the echos that were tossed
     increasing its speed of operation.

     For (FTSC) *.MSG:
     SCAIL uses the LASTREAD file in each message directory to figure
     out where the new messages start (to avoid rescanning old mail).
     If SCAIL cannot find LASTREAD it will start scanning at 1.MSG.

     For SQUISH:
     For SCAIL uses the *.SQL file to determine the last read message.
     If SCAIL does not find the *.SQL file, it will use an internal
     Last-Read marker, however in the process some old messages might be
     rescanned.  Therefore it is recomended that you use the *.SQL file.

     When saving the result message SCAIL assumes that the path is
     correct.  If it does not find the message base, be it SQUISH or
     FTSC format, SCAIL will create the message base.

     If the echo-toss log option is used, and SCAIL does not find the
     echo-toss log, it will assume that no messages have been tossed and
     therefore none need to be scanned.

3.0 Operations                         PAGE 4
     ----------
3.1  Operating Procedures
     SCAIL will be most useful if it is run right after the mail is
     tossed.  This ensures that all new messages are scanned.  It is
     best to call SCAIL from the batch file which tosses the mail.
     (See examples section for a TOSS.BAT file.)  SCAIL runs only as
     fast as your disk drive.  To ensure compatibility with most IBM
     (tm) compatible systems SCAIL uses DOS's file handles.  It does
     not do low level FAT reads.  Although this reduces its speed
     slightly, it ensures a higher degree of reliability and
     compatibility with other systems.

3.2  Description of Operational Requirements
     As mentioned above, SCAIL requires AREAS.BBS to operate.  If it
     does not find the file in the directory from which it is run, it
     will issue an error message and end. All SQUISH message bases must
     have a '$' sign preceed the path to the message base, otherwise
     SCAIL and most utilities that are used for SQUISH message bases and
     use the AREAS.BBS will not know the difference between an FTSC
     *.MSG and SQUISH message bases. If your mailer does not use
     AREAS.BBS, you will have to create one and put it in the SCAIL
     directory. (See the examples section for a sample AREAS.BBS.)

     SCAIL works only with the FTSC *.MSG and SQUISH format.  It
     assumes that the FTSC message headers look like those defined in
     the FTS-0001 document and the SQUISH messages headers as defined in
     the SQUISH API released by Scott Dudley.  If the SQUISH format is
     modified in the future, SCAIL is designed to adapt, a recompiled
     version of SCAIL should be released soon after any modifications to
     the existing SQUISH headers.  Although no damage will result if SCAIL
     is run with other message formats, the results are unpredictable, and
     could range from a simple program termination with an error message
     to an incorrect assessment of what the message contains.

3.3  Recommendations
     Using a disk cache to increase the speed of SCAIL is recommended
     and is theoretically quite safe.  This is due to the fact that
     SCAIL only reads the message files and does no writes to its
     reply message file until it has completed scanning.

3.4  Warning
     At this time SCAIL is not "share" friendly, if you are running in a
     multitasking environment make sure that when SCAIL is run, the
     files it requires are NOT being used by  another process.


4.0 Command Line Parameters                    PAGE 5
     -----------------------
     SCAIL must be run with command line parameters.  The first 2
     command line parameters must be in the correct order, the next 2
     parameters are interchangable and can come in any order.

     The first 2 command line parameters must be given in the order shown
     below. If parameters are not used in the required order then the
     results are unpredictable but will usually result in an error
     message being displayed and program termination.  The order of
     the parameters is:

     SCAIL <first name> <last name> [/n($):result msg path] [/f:echotoss log]

     < >  - Necessary command line parameter
     [ ]  - Optional  command line parameter
     ( )  - Internal Switch associated with that parameter

4.1  <first name>
     The <first name> is a required parameter.  It does not matter
     whether it is entered in CAPS, lower case, or a mIx.

4.2  <last name>
     The <last name> is also a required parameter.  It does not matter
     whether the name is entered in CAPS, lower case, or a mIx.   This
     is the most important part of your name; SCAIL assumes that the
     sender of a message might not have entered your full name
     correctly, so that if after checking the full name string the
     names don't match, SCAIL will look for your name inside the string
     in the hope that the sender got that part of the message right.

4.3 The next 2 parameters can come in any order you like.  e.g.:

      SCAIL firstname lastname /n:path /f:path

     is no different from:

      SCAIL firstname lastname /f:path /n:path

4.4  This command line parameter has 2 different states.  The first
     state, /n:path, tells SCAIL to store the result message in an FTSC
     message based system.  The second state, /n$:path, tells SCAIL to
     store the result message in a SQUISH format message base.    NOTE:
     if SCAIL does not find the message base it will create it.

4.4A </n:path>
     This optional parameter tells SCAIL to save the results of its
     mail scan in an FTSC message, and specifies the directory to put it
     in.  (The netmail directory is recommended.)

     The switch is used like this:

          SCAIL <first name> <last name> </n:path>

     e.g. SCAIL Alex Brodsky /n:C:\POINT\MSG\NET

     As with the first two parameters the case of the text does not
     matter.  The directory specified must be valid, or SCAIL will
     abort with an error.  SCAIL prints the results of its scan only
     when it has found messages addressed to you;  otherwise no
     message is written.

4.0 Command Line Parameters Continued                PAGE 6
     ---------------------------------
4.4B </n$:path>
     This optional parameter tells SCAIL to save the results of its
     mail scan in a SQUISH message, and specifies the message base file
     to put it in.  (The netmail message base file is recommended.)
     NOTE: You myst not specify the extention, just the path and name of
     the message base.

     The switch is used like this:

      SCAIL <first name> <last name> </n$:path>

     e.g. SCAIL Alex Brodsky /n$:C:\POINT\MSG\NET
                           /|\
       In the MSG directory there are the    |
       NET.SQD, NET.SQI and NET.SQL files --|

     As with the first two parameters the case of the text does not
     matter.  The message basespecified must be valid, or SCAIL will
     create it, itself.  SCAIL prints the results of its scan only
     when it has found messages addressed to you;  otherwise no
     message is written.

4.5  /f:path
     This optional parameter must come after the first two parameters,
     (First and Last Names).  It does not matter after that in which
     order it follows, e.g. it can come before or after the /n($):
     parameter.  This parameter tells SCAIL to use the echotoss log in
     performing its message scan.  Most mailers, have an option to store
     the tags of the echos they have tossed in a file, usually called
     ECHOTOSS.LOG.  This file is a simple ascii file with the echo tags
     in upper case letters.  by using this command line parameters you
     save SCAIL the work of checking all echos for mail, hence saving
     time and improving efficiency.
     The command line parm is used like this:

      SCAIL <first name> <last name> </f:path>

     e.g. SCAIL Alex Brodsky /f:c:\point\echotoss.log

     The path must be to a valid echo toss file, otherwise SCAIL simply
     decides that no messages have been tossed and hence does nothing.
     Please see the examples section for different ways of implementing
     SCAIL.

4.6  General
     It is strongly recommended that SCAIL be run from a batch file.
     Because it takes long parameters it is easy to make a mistake
     while entering them at the command prompt.  A batch file will
     ensure that SCAIL is run with the same parameters every time it
     is run.

5.0 Examples                            PAGE 7
     --------
5.1  Modes of operation of SCAIL

          SCAIL <first name> <last name>

     e.g. SCAIL Alex Brodsky

     SCAIL searches all the directories listed in AREAS.BBS for any
     messages addressed to the user.  In this example it looks for all
     messages addressed to Alex Brodsky.

          SCAIL <first name> <last name> </n:path>

     e.g. SCAIL Alex Brodsky /n:C:\POINT\MSG\NET

     SCAIL searches through all directories listed in AREAS.BBS for
     any messages addressed to the user.  In this example it looks for
     all messages addressed to Alex Brodsky.  If it finds any messages
     for him, it will list them in the next available message file in
     the directory specified (in this case in Alex Brodsky's netmail
     directory).

      SCAIL <first name> <last name> </n$:path>

     e.g. SCAIL Alex Brodsky /n$:C:\POINT\MSG\NET

     SCAIL does the same thing as above except it saves the result
     message in SQUISH format.

      SCAIL <first name> <last name> </f:path>

     e.g. SCAIL Alex Brodsky /f:C:\POINT\ECHOTOSS.LOG

     SCAIL scans only the message bases that have been tossed and hence
     listed in the ECHOTOSS.LOG file and displays the results on the screen.

      SCAIL <first name> <last name> </n:path> </f:path>
                  or
      SCAIL <first name> <last name> </f:path> </n:path>

     e.g. SCAIL Alex Brodsky /n:C:\POINT\MSG\NET /f:C:\POINT\ECHOTOSS.LOG
                  or
     e.g. SCAIL Alex Brodsky /f:C:\POINT\ECHOTOSS.LOG /n:C:\POINT\MSG\NET

     SCAIL scans all the echos that have been tossed and hence listed in
     the ECHOTOSS.LOG file and saves the results to an FTSC *.MSG
     message file. As you can see the order of the last 2 parameters is
     inconsequential.

      SCAIL <first name> <last name> </n$:path> </f:path>
                  or
      SCAIL <first name> <last name> </f:path> </n$:path>

     e.g. SCAIL Alex Brodsky /n$:C:\POINT\MSG\NET /f:C:\POINT\ECHOTOSS.LOG
                  or
     e.g. SCAIL Alex Brodsky /f:C:\POINT\ECHOTOSS.LOG /n$:C:\POINT\MSG\NET

     SCAIL scans all the echos that have been tossed and hence listed in
     the ECHOTOSS.LOG file and saves the results to a SQUISH message
     base message file. As you can see the order of the last 2 parameters
     is inconsequential.

5.0 Examples Continued                     PAGE 8
     ------------------

5.2  AREAS.BBS

     The Dinosaur Pen ! Alex Brodsky
     $c:\point\msg\c_echo      C_ECHO     247/205
     c:\point\msg\80xxx        80XXX     247/205
     c:\point\msg\dr_debug     DR_DEBUG  247/205
     $c:\point\msg\tech        TECH     247/205

     The first line in AREAS.BBS is your system's name, followed by an
     exclamation mark and then by your name.  Each subsequent line
     describes a single echomail area.  The message directory is
     listed first, followed by the echo tag (in CAPS) and the address
     of the node which sends you the echo.  Other items may follow,
     but SCAIL uses only the directory and tag information. SCAIL uses
     the tag to identify the areas in which it has found messages to
     you.  Notice that if the area is in SQUISH format, then a '$'
     preceeds the path to the message base.  Therefore in this example,
     the C_ECHO and TECH are both in SQUISH format, while the 80XXX and
     the DR_DEBUG echo are in the stone-aged FTSC *.MSG format.

5.3  Format of a result message

     AREA->DPS
     MSG #     From:           Subject:
     35        John Giesbrecht Next DPS meeting

     This format is repeated for every message area.

6.0 Batch File Examples                    PAGE 9
     -------------------
6.1  TOSS.BAT

     @echo off
     echo Tossing  . . .
     squish in link -fc:\point\echotoss.log
     scail alex brodsky /n:c:\point\msg\net /f:c:\point\echotoss.log
     if exist echotoss.log del echotoss.log

     This batch file is run whenever the system receives mail.  SQUISH
     (by Scott J. Dudley) is the mail processor I use, but any mail
     tosser will do.

     As you can see SCAIL is run right after the mail is tossed. This
     allows for the most efficient mail scan possible, and notifies
     you immediately if you have received any mail.

     As the author of this software I strongly recommend that you
     run it right after the mail tossing process.

7.0 Error Messages Glossary                    PAGE 10
     -----------------------
7.1  Memory allocation Error:  This error is fatal, that is scail will
     imediately terminate its operations.  This is usually caused by
     insufficient memory to run SCAIL.    To correct this problem simply
     flush some of your TSRs from memory to allow SCAIL more memory.

7.2  File Open Error:  If SCAIL does not find the files it requires it
     has 2 options.  If it cannot find a file during it's scan of one of
     the message areas, it will stop scanning the message area and
     proceed to scan the next one, if SCAIl cannot open a file during
     it's initialization or termination phases, it will produce a fatal
     error and immediately terminate.  The solution to this problem is
     to make sure that all required file are available.  In some cases
     when a new squish area has been added and has had no message flow,
     SCAIl might report that it could not open certain files due to the
     fact that they do not yet exist.  Also make sure that all the paths
     in AREAS.BBS and command line parameters are correct.  Finally,
     this version of SCAIL is NOT share friendly, and therefore running
     it in a "share" environment will cause it to terminate if it
     accesses a file, which has been already accessed.

7.3  File Read Error:  If SCAIL encounters a problems during the reading
     of a file, e.g. a bad disk sector, it will return a read error,
     just like in the case of the File Open Error, SCAIL will either
     exit with a fatal termination error if the error occured during the
     initialization or termination phases.  Or SCAIl will proceed to
     scan the next message base if the error occured during one of its
     scanning phases.

7.4  File Seek Error:  Same as File Read Error except the error
     occured on a file seek action instead of a file read action, same
     criteria apply.

7.5  File Write Error: Same as File Read Error except the error
     occured on a file write action instead of a file read action, same
     criteria apply.

8.0 Bug reports, Contacting the Author, and Famous Last Words    PAGE 11
     ---------------------------------------------------------
8.1  Bug reports
     If you find any bugs, please report them to me as soon as
     possible.  I have done my best to ensure that SCAIL is as bug-
     free as possible.  However no program is perfect, so if you do
     find any bugs please let me know.

     If you are getting an abnormal termination (which you shouldnt),
     and you don't know why, send me a netmail with the termination code
     and I'll try to help you.

8.2  Contacting me
     You may contact me at the following BBSes.

     DPSHQ     [phone]  (1:247/205)
     DOB       [phone]  (1:247/101)

     You may send me netmail at 1:247/191

     You may also write to me at:

     38 Elma St. #11,
     St. Catharines, ON,
     Canada, L2N 6Z3.

8.3  Author's Note
     SCAIL was written in C and to learn how the squish base worked, I
     wrote all the squish access code myself instead of using Scott
     Dudley's API.  Since I now know how the squish base works, the next
     version of SCAIL will use the MSGAPI, to save me, in the future a
     lot of work.

9.0  Famous Last Words
     -----------------
     Well, this is the end of this manual.  I would like to thank
     John Giesbrecht (1:247/190) who helped test SCAIL, made
     recommendations, and proofread this document, and Peter
     Danevicius (1:247/205) for the information he provided on the
     workings of FidoNet.  I would also like to thank Scott Dudley,
     Author of SQUISH and MAXIMUS, for putting up with my question
     during the writing of this software.  I wish him the best of luck
     with his next project.

     Many thanks to Don Dawson for alerting me to a couple of bugs in
     SCAIL which are hopefully now fixed.  Thanks Don!

     I would like to dedicate this program to the Dead Programmers'
     Society (DPS), and to all programmers out there who have been
     forced to write documentation.

     My final dedication goes to our Net's (247) Daisy Chain link, I wish
     them as much luck with it as I do our Canadian Postal system.

     And finally: It is always wise to remember if some thing is not
          insured, it will break.