  TNOS FORWARD.BBS File Format
  Brian A. Lantz, brian@lantz.com
  v0.08, 25 May, 1997

  This is a description of the FORWARD.BBS File Format used by TNOS. It
  has been made as flexible as possible to provide the individual SYSOP
  with as many tools to effectively handle traffic as possible.  This
  specification is updated as the work progresses, so it is a dynami-
  cally changing document.  This document is NOT meant to deal with for-
  warding in an exhaustive manner, nor is it meant to be a HOW-TO on
  forwarding. It's sole purpose is to document the file format for the
  FORWARD.BBS file.  This document, part of the TNOS Documentation Pro-
  ject (TDP), reflects a complete description this file format for TNOS
  Release 2.22 and later.
  ______________________________________________________________________

  Table of Contents:

  1.      THE FORWARD.BBS FILE

  2.      COMMENTS

  3.      BBS ENTRY DEFINITIONS

  4.      FILE DIRECTIVES

  4.1.    File Inclusion Directive

  4.2.    Conditional Processing Directives

  4.2.1.  Use of Conditionals

  4.2.2.  Supported Conditionals

  5.      BBS ATTRIBUTES

  5.1.    Syntax for Attributes

  5.2.    Simple Attributes

  5.3.    Compound Attributes

  5.3.1.  The SCRIPT Attribute

  5.3.2.  Supported SCRIPT Commands

  5.3.3.  The AREAS Attribute

  5.3.3.1.        Format of the AREAS Attribute

  5.3.4.  The AREAS Attribute's 'ALT' Parameter
  ______________________________________________________________________

  1.  THE FORWARD.BBS FILE

  The FORWARD.BBS file is used to control outgoing forwarding sessions
  on a TNOS system. TNOS will only start outgoing forwarding sessions
  with PBBSs having entries in this file.

  (-- The format of the FORWARD.BBS file changed in TNOSRelease 2.00
  from the way that JNOS uses it. There is a utility, cnvfwd, that will
  convert a JNOS FORWARD.BBS file, or a TNOS 1.xx forward file.--)

  The file is a simple ASCII file. Each line can be either a comment, a
  BBS entry definition, a file directive, or a BBS attribute.  Any other
  lines can (and probably will) cause you grief, and unexpected results.

  2.  COMMENTS

  Any blank lines, or lines beginning with a '#' or ';' are ignored and
  treated as comments. Comments can be located anywhere within the file.

  You should use comments to document anything in the file that may NOT
  be obvious to you. All comments are ignored by the forward file
  parser.

  3.  BBS ENTRY DEFINITIONS

  Each entry for a BBS is made up of a name in square brackets (the
  entry definition), followed by any needed attributes for that BBS.
  While any name can be used for a BBS, it is better to use the callsign
  of the BBS for this.

  An entry ends when either a line starting with a '-' is found, a new
  entry definition is found, or at the end of the file.

  A sample of two BBS entry definitions, would be:

          [k0zxf]
          ......          (attributes go here)
          ......
          [w4dph]
          .......         (and here)
          .......

  4.  FILE DIRECTIVES

  There are several file directives that can be used within the
  FORWARD.BBS file. Directives are special commands that can alter the
  normal processing of the file.

  4.1.  File Inclusion Directive

  At any time within the forward.bbs file, you can include the contents
  of another file, by using the 'include' directive.  This allows you to
  compose a file with common information, and include it easily at
  several places. Then you only have one place to make any changes at,
  and less chances of having incorrect information in a section due to
  forgetting to update several places in the file.

  (-- The file inclusion directive was added in TNOS 2.02pl2, and can be
  found in any release after that release.--)

  Once the included file is completed, the original file will continue
  being processed from the place where the 'include' directive was
  found. You CANNOT 'include' a file WITHIN an included file, though.

  An example of including a common file of area names from within a
  BBS's AREA attribute would look like:

          AREAS = {
           k0zxf
           include /nos/etc/public.areas
          }

  4.2.  Conditional Processing Directives

  There are several directives that allow you to have conditional
  statements in the FORWARD.BBS file. These conditional directives allow
  you to have a greater deal of flexibility, in that they permit you to
  set different attributes based on the number of connect attempts, the
  time of day, and the 'forward mode' setting.

  4.2.1.  Use of Conditionals

  The IF conditional directive allows you to test certain conditions,
  and (if they match a desired value) allow you to act differently based
  on this condition. You can also reverse the condition, with the use of
  the ELSE conditional directive. Each IF directive must end with a
  ENDIF directive.  The ELIF directive is a shortcut for ELSE followed
  by a second IF, and eliminates an ENDIF in the process.

  The use of 'if-else-elif-endif' to conditionally process the file is
  allowed anywhere in the file, except WITHIN an attribute (like AREAS
  or SCRIPT). You can nest conditional processing within other
  conditional processing up to 20 levels deep. Both of the following
  styles are supported:

          if xxxxxx               if aaaaaaa
           attributeA              attribute1
           if yyyyyy              elif bbbbbbb
            attributeB             attribute2
           else                   elif ccccccc
            attributeC             attribute3
           endif                  else
          else                     attribute4
           attributeD             endif
          endif

  While conditions are *NOT* allowed within a SCRIPT Attribute and an
  AREAS Attribute, multiple SCRIPT/AREAS Attributes can be in a BBS's
  entry, with some being contained completely WITHIN conditional
  processing. Multiple SCRIPT/AREAS Attributes are appended in the order
  found.

  4.2.2.  Supported Conditionals

  The following are the presently supported conditions that can be
  tested with conditional directives:

     if TIME = hhmm-hhmm
        checks to see if the current time is within the time range
        given.

     if TRY = xx
        checks to see if the connection attempt matches the number 'xx'.
        This can be used to set up multiple connection methods.  The
        first attempt is 'TRY = 1'. (-- When a message from a specific
        area is to be placed in a BBS's forwarding queue, it ALWAYS
        processes that BBS's entry with 'TRY = 1' and the time set to
        the current time.--)

     if MODE = xx
        checks to see if the forwarding mode matches the number 'xx'.
        This can be used to set up different forwarding profiles, such
        as for emergencies, etc. (-- The MODE conditional directive was
        added in TNOS 2.02pl1, and can be found in any release after
        that release.--)

     if DAYOFWEEK = xx (or: if DAYOFWEEK = xx-yy)
        checks to see if the current day of the week is acceptable. If
        the first form of this conditional is used, it must be the given
        day of the week. If the second form is used, then the current
        day of the week must be within the range specified.  The values
        are numeric. Sunday is 0, and Saturday is 6. (-- The DAYOFWEEK
        conditional directive was added in TNOS 2.20, and can be found
        in any release after that release.--)

  5.  BBS ATTRIBUTES

  Each BBS in the FORWARD.BBS file has certain attributes associated
  with it. Almost ALL of them have defaults which as assigned to a BBS
  as the parsing of its entry begins. Any defined attributes will
  override the default attributes for that BBS.

  5.1.  Syntax for Attributes

  All BBS Attributes are of the format 'KEYWORD = parameters'. There can
  be any amount of whitespace before the KEYWORD, and surrounding the
  '='. The parameters do not start till the first non-whitespace
  character after the '='. If more than one of an certain Attribute is
  processed, then only the last is used.

  5.2.  Simple Attributes

  Most of the available attributes are simple attributes. Simple
  attributes are attributes which either set a boolean value (yes or
  no), a numeric value, or a string. Only one value is set for each
  simple attribute.

  Currently supported simple attributes include:

     ALTTIME = xxx
        sets the default delay time (in minutes) to be used for any
        Alternate BBS routings that do not specify a time. The default
        for this attribute is '720' minutes (12 hours).

     ALWAYSUPDATE = [YES | NO]
        determines whether or not the 'laston' time will always be
        updated on connection.  If this is set to 'NO' then the 'laston'
        value is only updated when a value SID has been exchanged
        between the two PBBSs (or TNCs). This should normally be set to
        'NO', and should only be needed if you are communicating with an
        extremely dumb TNC's messaging system, which does NOT use SID's
        on startup. The default for this attribute is 'NO'. (-- The
        ALWAYSUPDATE attribute was added in TNOS 2.22, and can be found
        in any release after that release.--)

     BULLETINS = [YES | NO]
        sets whether or not bulletin messages are are to be forwarded.
        This can be used to restrict bulletins being forwarded only
        during certain hours or only by certain connect methods, or only
        in certain forwarding modes, etc. Bulletins are messages in
        areas defined in the 'etc/areas' file. The default for this
        attribute is 'YES'. (-- The BULLETINS attribute was added in
        TNOS 2.02pl2, and can be found in any release after that
        release.--)

     CLOCKOFFSET = xx
        determines how to adjust your local time before sending it, when
        setting a remote TNC's clock. This is only used in connection
        with the CLOCKSET Attribute. If the remote station does NOT have
        a 'C' in their SID, then this attribute is ignored. Use a '1' to
        add one hour to localtime, a '-1' to subtract one hour, etc. The
        default for this attribute is '0'.

     CLOCKSET = [YES | NO]
        determines whether or not you will send a command to the remote
        TNC to set their clock, if they request it. Many TNC's (like
        PacComm's) Mailboxes send out a 'C' in their SID, which says,
        'set my clock'.  TNOS will do this on forwarding sessions, if
        this Attribute is 'YES'. If the remote station does NOT have a
        'C' in their SID, then this attribute is ignored. The default
        for this attribute is 'YES'.

     CONNECT = constr
        sets the connection string 'constr' to be used in setting up the
        connection for forwarding. This can be one of the follow:

     o   ax25 <ifc> callsign [optional digis]
        for an ax25 connection (with optional digis).

     o   connect <ifc> callsign [optional digis]
        for an alternate way of specifying an ax25 connection (with
        optional digis).

     o   netrom <nodename>
        for a netrom connection

     o   telnet <hostname>
        for a telnet connection
     o   export
        for an export file based on the BBS name

     o   incoming
        for BBSs that only have incoming connects. This should NOT be
        used with conditionals for 'TRY'

        *IF* a valid connect is NOT found (either due to omission or
        conditional processing), the BBS will not be processed. There is
        NO default for this attribute.

     DUMBPMS = [YES | NO]
        indicates that this 'PBBS' is actually a TNC with a dumb PMS
        (dumb meaning that it does NOT send a 'SID' upon connection).
        This should ONLY be used if (indeed) this is a dumb PMS, since
        it disables some code which prevents the possibility of
        duplicate messages entering your TNOS. Before using this
        attribute, use the 'forward trace' command, to ensure that the
        SID is not being sent by the TNC. If it IS being sent, but TNOS
        is not seeing it, then you have a flawed SCRIPT section, which
        is eating the needed SID. This should normally be set to 'NO',
        and should only be needed if you are communicating with an
        extremely dumb TNC's messaging system, which does NOT use SID's
        on startup. The default for this attribute is 'NO'. (-- The
        ALWAYSUPDATE attribute was added in TNOS 2.22pl2, and can be
        found in any release after that release.--)

     FBBSIZE = xx
        sets the maximum size for the FBB data proposal to queue for
        sending.  Normally, with the default for this attribute being
        '0', there will be up to 5 messages sent during the negotiation
        (assuming you have at least 5 to send). If this attribute is
        non-zero, then after added a message to the negotiation, a check
        is made to see if the total size of the negotiation is now
        larger than the 'FBBSIZE', and if so, no more messages will be
        added to the negotiation block. This means that the 'actual
        maximum' size of your block *could* be:

                                ('FBBSIZE' - 1) + ('SIZE' - 1)

     This is *IF* the negotiation packet was at least one byte less than
     the 'FBBSIZE' attribute, and the next message was one byte less
     than the 'SIZE' attribute.
     For example, if the 'SIZE' attribute is 6K, and the 'FBBSIZE'
     attribute is 6K, and message 1 is 2K, message 2 is 2K, and message
     3 is 5K, then it will not attempt to add a 4th message to the nego-
     tiation, as it already has a negotiation size of 9K.

     LIMITTIME = xxx
        sets the maximum forwarding session time (in minutes) to be used
        on forwarding sessions.  The default for this attribute is the
        value set by the 'forward limittime' command. (-- The LIMITTIME
        attribute was added in TNOS 2.11al, and can be found in any
        release after that release.--)

     LIMITTYPE = type
        This allows you to limit the forwarding protocol type used with
        this BBS. Values for 'type' are:

     o  FBB for FBB compressed forwarding

     o  FBB-NONCOMPRESSED for FBB non-compressed forwarding

     o  X-FWD for W0RLI X-compressed forwarding

     o  MBL or RLI for non-FBB forwarding.

        This only sets the BEST protocol available, (in the order listed
        above from best to worst), and any lesser protocol CAN be used.
        The default for this attribute is 'FBB', or any available
        protocol, with no limitation. (-- The LIMITTYPE attribute was
        added in TNOS 2.02pl2, and can be found in any release after
        that release.--)

     MINIDLE = xxx
        sets the minimum idle time (in seconds) to be used between
        outbound forwarding sessions.  The default for this attribute is
        the value set by the 'forward minidle' command. (-- The MINIDLE
        attribute was added in TNOS 2.11al, and can be found in any
        release after that release.--)

     PERSONALS = [YES | NO]
        sets whether or not personal messages are are to be forwarded.
        This can be used to restrict personal messages being forwarded
        to only during certain hours or only by certain connect methods,
        or only in certain forwarding modes, etc. Personal messages are
        messages in areas NOT defined in the 'etc/areas' file. The
        default for this attribute is 'YES'. (-- The PERSONALS attribute
        was added in TNOS 2.02pl2, and can be found in any release after
        that release.--)

     POLL = [YES | NO]
        determines whether to poll the BBS, even if no outbound data is
        waiting.  The default for this attribute is 'NO'.

     REVINCOMING = [YES | NO]
        determines whether or not reverse forwarding will be asked for
        to the remote BBS, after sending any outbound data. This MUST be
        set to 'YES' if POLL is 'YES'. Also, this Attribute has NO
        EFFECT, if you are using FBB-style forwarding with this BBS. The
        default for this attribute is 'YES'.

     SIZE = xxx
        sets the maximum message size allowed, in bytes. The default for
        this attribute is '0', which means any size message will be
        allowed.

     SUBCHANNEL = xx
        sets the BBS to use subchannel number 'xx'.  The default for
        this attribute is no subchannel (-1).  Valid subchannel numbers
        start with 0.

     TRIES = xx
        sets the maximum number of different connection methods defined
        for this BBS, with conditional processing. This is read and used
        to re-process the BBS for as many times as needed. The default
        for this attribute is '1'.

  5.3.  Compound Attributes

  There are two attributes that do not define simple variables, but
  instead define attribute lists. There are currently only two compound
  attributes.

  5.3.1.  The SCRIPT Attribute

  The SCRIPT attribute has several script commands available to help
  make a successful forwarding connection.  A SCRIPT attribute is
  optional. There is NO default for this attribute. This is not needed
  for most people, but can be quite useful for traversing NODES, logging
  into telnets, etc.  The SCRIPT attribute CANNOT have conditional
  processing WITHIN the attribute, but it is acceptable to have several
  SCRIPT attributes that are totally contained WITHIN conditional
  processing.  Multiple SCRIPT attributes (if defined) are appended in
  the order found.

  The format of the SCRIPT Attribute is:

          SCRIPT = {
            command
            command
          }

  5.3.2.  Supported SCRIPT Commands

  Each SCRIPT atribute can have many commands in its definition,
  enabling you to set up as detailed of a connection script as you
  require.

  Current available commands that can be used within a SCRIPT attribute
  are:

     SEND string
        sends the specified 'string' to the BBS

     WAIT nnn string
        waits up to 'nnn' seconds for the remote BBS to send the string
        'string'.

     SID [sidstr]
        this 'fools' TNOS into believing it just received the SID
        'sidstr', and gets it to process that SID.  TNOS will reply with
        IT'S SID, *to* the remote BBS. This is not needed, usually.

  5.3.3.  The AREAS Attribute

  The AREAS attribute is used to define which areas are to be sent to
  the BBS being defined. Only messages within these areas will be sent.
  While this is an OPTIONAL attribute, a BBS defined without an AREAS
  attribute does not serve much of a purpose.

  The AREAS attribute has several options available for each area
  defined.  The AREAS Attribute CANNOT have conditional processing
  WITHIN the Attribute, it is acceptable to have several AREAS
  attributes that are totally contained WITHIN conditional processing.
  Multiple AREAS attributes (if defined) are appended in the order
  found.

  5.3.3.1.  Format of the AREAS Attribute

  The format of the AREAS Attribute is:

          AREAS = {
            areaname [rewrite] [ALT[=bbsname[,time]]]
            areaname [rewrite] [ALT[=bbsname[,time]]]
          }

  The areaname is required on each line. There can be any amount of
  whitespace preceeding the areaname, and surrounding the optional
  rewrite address. The 'rewrite' address is an address that all mail
  send from this area can have 'forced' upon it, changing the original
  'To:' address to this rewrite address.

  5.3.4.  The AREAS Attribute's 'ALT' Parameter

  The ALT parameter of an AREAS line can have one of three forms:

     ALT
        marks this BBS to be an Alternate BBS for this area. New mail
        does not automatically get added to this BBSs forwarding queue
        until it has reached it's alternate time from the original BBS.
        At that time, it is removed from the original BBS, and placed
        into the Alternate BBSs queue.

     ALT=bbsname
        marks this area to have 'bbsname' as an Alternate BBS, and have
        it's alternate time be this BBSs 'ALTTIME' Attribute's value.
        When the alternate time has passed and a message still remains
        on the BBS, it will be added to 'bbsname's forwarding queue.

     ALT=bbsname,time
        same as above, except the alternate time is overridden with
        'time'

  There can be any number of 'ALT=' parameters on an area line, but the
  'ALT' and 'ALT=' parameters are mutually exclusive.

