                            THE MAGIC ORACLE V10.0
                            Written by Sean Dennis
                         (C)1998-2007 by Sean Dennis
                             All rights reserved.
                      Another fine Cheepware production!
                            http://outpostbbs.net

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=

 WHAT IS THE MAGIC ORACLE?
 -------------------------

 Do you have questions in your life that you need answered?  The Magic Oracle
 is here to help you!

 The Magic Oracle is a BBS door that can be run locally or through a BBS
 that is capable of running 16-bit DOS doors.  TMO does not need a FOSSIL
 driver nor an ANSI driver (such as ANSI.SYS) to be loaded to work.  Some of
 TMO's features:

  -Autodetects the caller's graphics rather than relying on drop file info.
  -Supports ANSI/AVATAR/TTY/RIP/MAX graphics.
  -Supports DOOR.SYS and DORINFOx.DEF drop files.
  -Full monitoring of carrier dropping and user inactivity time-outs.
  -DOS, DesqView, Windows, and OS/2, multi-tasker friendly.
  -Supports FOSSIL, UART, and DigiBoard communications routines.
  -Full support for non-standard port and IRQ settings.
  -Ability to run in "online mode", such as between a front-end mailer and
   a BBS without the use of a dropfile.

-------------------------------------------------------------------------------

 UPGRADING FROM A PREVIOUS VERSION OF THE MAGIC ORACLE
 -----------------------------------------------------

 If you are upgrading from a previous version of The Magic Oracle, you need
 to know the following:

    - If you have customized your install of TMO, DO NOT UNARCHIVE THIS IN
      YOUR CURRENT TMO DIRECTORY.  FILES WILL BE OVERWRITTEN!  There are
      some changes you will have to make to your current install of TMO.

    - Pipe color codes are no longer used.  TMO now supports TDK's internal
      color code support (see further in this document).  You'll need to
      convert your color codes in ANSWERS.DAT and LANGUAGE.DAT to the new
      format.

    - The *.CFG files as used previously are no longer needed.  TMO now uses
      typed control files, meaning you will need to create these NODEx.CTL
      files using the included MAKECTL.EXE program for each node.  Note that
      there MUST ALWAYS be a NODE1.CTL in the door's directory or else TMO
      will not run, even in local mode.

    - I no longer support the OS/2 and Win32 versions of TMO.  I now will only
      support this DOS version.  This is more than likely the last version of
      TMO I will release, so it's best to upgrade to this version.

-------------------------------------------------------------------------------

  DISCLAIMER:
  -----------

  The author, Sean Dennis, has taken every precaution to insure that no harm or
  damage will occur on computer systems operating this package. Nevertheless,
  the author shall NOT be held liable for whatever may happen on your computer
  system or to any computer systems which connects to your own as a result of
  operating this package. The user assumes full responsibility for the correct
  operation of this software package, whether harm or damage results from any
  software error, hardware malfunction, or operator error. NO warranties are
  offered, expressly stated or implied, including without any limitation or
  restriction any warranties of operation for a particular purpose and / or
  merchantability. If you do not agree with this, then absolutely do NOT use
  this program!

-------------------------------------------------------------------------------

  LICENSE AGREEMENT:
  ------------------

  The door program, support files, and documentation are copyrighted products
  of Sean Dennis/Cheepware. The author reserves all rights to these products.
  This is protected by the United States of America (USA) and international
  copyright laws. In no way shall the components of the door software package
  be reproduced or modified in any form or method without prior expressly
  written permission from the author.

  Tampering with or altering the contents or integrity of the door software
  package is prohibited. No fee may be charged by any agency other than the
  author beyond the cost of distributing freeware copies without prior
  expressly written permission from the author.

  This program MAY NOT be used on a pay ("for-profit") BBS!

-------------------------------------------------------------------------------

  INSTALLATION:
  -------------

 NOTE: When you unarchive this program, you should have seen an authenticity
 verification from me.  IF YOU DON'T SEE THAT, DON'T USE THIS ARCHIVE!  Please
 go to my website or see the other ways to get my doors in the "Contacting
 The Author" section at the end of this document.

 1. Create a directory for the door (example: "C:\DOOR").

 2. Copy all the contents of this archive into that directory.

 3. Run the door configuration program.  Simply type MAKECTL <node number>.

 4. To insure proper multinode use in a DOS based multitasking environment,
    SHARE.EXE must be installed prior to the door, and prior to the OS.
    If you're running Windows 9x and above or OS/2 Warp 3 or above, you
    don't have to worry about SHARE.EXE as it's already loaded when you
    open a DOS shell.

 5. In order to run the door program online, the following parameters may
    be used. For a list of all available command line parameters, simply
    execute the door program with no parameters on the command line.

    Dropfile Specifiers:
    --------------------
    "/D={Node Work Path}\DOOR.SYS" - This tells the program to use the
    DOOR.SYS drop file and the {Node Work Path} points to the proper
    directory where the drop file is to be created or found.

    "/R={Node Work Path}\DORINFO#.DEF" - This tells the program to use the
    DORINFO#.DEF drop file and the {Node Work Path} points to the proper
    directory where the drop file is to be created or found.

    Optional Parameters:
    --------------------
    "/S#####" - (Where ##### is the user's actual baud rate) - This specifies
    the online caller's actual baud rate. You use this parameter to force a
    new baud rate if you are running the door with the DOOR.SYS drop file
    and would like to force the door to use the actual baud rate rather than
    the locked port speed.

    "/N###" - (Where ### is 0..255) - This specifies the current node number
    and tells the door which NODE###.CTL file to use.

    "/L" - This tells the door to load up in LOCAL mode.  You must have
    NODE1.CTL created in order for you to use local mode or the door will
    not work.

    "/O" - This tells the door to load up in ONLINE mode. This is useful if
    you are running the door online without a drop file. Such is the case if
    you wanted to run the door between your BBS and a front end mailer or a
    waiting for caller program where no drop files are created in advance.

    "/X" - This tells the door to send a !|1K|*|#|#|# at exit time to either
    clear the remote screen in RIPterm or to flip MAXterm back to text mode.

    "/G[Emulation]" - This is used to force the terminal emulation to any
    emulation you please thus bypassing the auto detection routines in the
    door. Valid arguments are: ANSI, ASCII, TTY, AVATAR, RIP, MAX. Keep in
    mind that ASCII and TTY are the same thing. You may also use "DROPFILE"
    to force the door to obtain the emulation from the drop file itself or
    use the redundant parameter "AUTO" to force autodetection on. Most of
    all, keep in mind that not all drop files are created equal. DOOR.SYS
    in one BBS package may not be that same as one from another BBS. Also,
    DORINFO1.DEF only has provisions for indicating ANSI, TTY and AVATAR.

    There has been problems reported to me about Windows XP not being able
    to properly autodetect ANSI emulation, so you may have to force it if
    it's not working correctly for you.

    "/V" - This will turn off the door's "announcing" of what OS the system
    is running and what type of connection (UART, FOSSIL, etc.) is being
    used.  This is primarily for those sysops who wish to not let people
    know what kind of OS and/or connection type they use.

-------------------------------------------------------------------------------

  THE CONTROL FILE EDITOR:
  ------------------------

    |---------------------------------------------------------------------|
    | Editing Control File For Node #1                                    |
    |---------------------------------------------------------------------|
    | SysOp First Name:[Your First Name_____]                             |
    |  SysOp Last Name:[Your Last Name______]                             |
    | Name Of This BBS:[Your BBS Name___________________________]         |
    |   SysOp Security:[500__]                                            |
    |    Serial Number:[__________]                                       |
    |    BBS Home Path:[C:\MX\______]                                     |
    |---------------------------------------------------------------------|
    |     Using FOSSIL:[Y]         Input Buffer Size:[4096]               |
    | Locked Port Rate:[38400_]   Output Buffer Size:[4096]               |
    |   Digi Over Ride:[N]         Non-Standard Port:[N]        Save |    |
    |   Comm Data Bits:[8]            Comport Number:[1_]       ------    |
    |      Comm Parity:[N]           Port IRQ Number:[4_]       Quit |    |
    |   Comm Stop Bits:[1]          Port Hex Address:[03F8]     ------    |
    |---------------------------------------------------------------------|

    SysOp First Name: self-explanatory
     SysOp Last Name: "              "
    Name Of This BBS: "              "

      SysOp Security: Set this to the same numeric value as the sysop
                      security level on your BBS.

       Serial Number: Not needed for this program.

       BBS Home Path: Not needed for this program.

        Using FOSSIL: Are you using a FOSSIL driver? [Y/N]

    Locked Port Rate: Enter the speed here in which your comport is
                      locked at.

      Digi Over Ride: Do you want this program to use DigiBoard over-
                      ride comm routines? [Y/N]

      Comm Data Bits: Set to the same as your BBS's data bits setting.

         Comm Parity: Set to the same as your BBS's parity setting.
                      N=None, O=Odd, E=Even

      Comm Stop Bits: Set to the same as your BBS's stop bits setting.

   Input Buffer Size: Set this to the same as your BBS or FOSSIL driver.

  Output Buffer Size: Set this to the same as your BBS or FOSSIL driver.

   Non-Standard Port: Are you using a non-standard IRQ setting? [Y/N]

      ***** NOTE: You still MUST set the following three items!  A
            quick reference list:

        COM1 IRQ4 3F8 * COM2 IRQ3 2F8 * COM3 IRQ4 3E8 * COM4 IRQ3 2E8

      Comport Number: The comport number for this node (if non-standard).

     Port IRQ Number: The IRQ number for this node (if non-standard).

    Port Hex Address: This port's address in hex (if non-standard).

-------------------------------------------------------------------------------

  SAMPLE BATCH FILES FOR RUNNING THE DOOR:
  ----------------------------------------
  CD\DOOR
  DOOR.EXE /D=C:\BBS\NODE1\DOOR.SYS
  CD\BBS
  EXIT

  or:

  CD\DOOR
  DOOR.EXE /N2 /S14400 /R=C:\BBS\NODE2\DORINFO2.DEF
  CD\BBS
  EXIT

  This is the exact batch file I use on my multinode BBS:

  @echo off
  d:
  cd\doors\tmo
  oracle /d=d:\pb\node%1\door.sys
  cd\pb\node%1

  The %1 is the environmental variable used to pass the node number to the
  door from the BBS.

  Here's a couple of set up examples (for ProBoard and Maximus):

  ProBoard
  --------
  I use ProBoard BBS, so using ProCFG under the door menu, I have this screen:

    0        1         2         3         4         5         6         7
  12345678901234567890123456789012345678901234567890123456789012345678901234
  <^T^> The Magic Oracle

  Color    : White on Black             Example Text

  Hotkey   : O
  Function :  7 - Shell
  Data     : *D*Z*Soracle.bat *#

  Min.Level: 0                               Nodes: All nodes
  Max.Level: 0
  Flags    : --------------------------------
  Min. Age : 0                   Password required: No
  Max. Age : 0                            Password:
  Sex      : Don't Care
  Time Left: 0                          +-RIP---------------+
  Time Onl.: 0                           Show remote : No  
  Timeframe: Fully enabled               Show local  : Yes 
  Min.Speed: 0                           Reset screen: Yes 
  Max.Speed: 0                          +-------------------+

  (Please look up in the ProBoard manual for explaination of the control
   codes used in the data line.)


  Maximus
  -------
  Here is how to set up TMO in a Maximus BBS in MENUS.CTL:

  NoDsp Display_File    misc\doorsys            Normal "The Magic Oracle"
        Xtern_OS2       runtmo.bat_%k           Normal "The Magic Oracle"

  (Note that this is for the OS/2 version of Maximus.  If you're running
   the DOS version, use Xtern_DOS instead.  Please refer to your Maximus
   manual for explaination of the control codes used in the above example.)


  Other BBSes
  -----------
  If you have a setup for a different BBS, please copy it and send it to
  me so I can add it to the door's documentation.

-------------------------------------------------------------------------------

  CUSTOMIZING TMO
  ---------------

  You can customize TMO in various ways.  Here's how you can make it your
  own door:

   - ORACLE.ANS: This is a standard ANSI (.ANS) file.  You can do what you
     want with it, but try not to make it any bigger than its current size
     as the door uses absolute references to write its text on the screen.
     You can use the global system variables in the file (see below) if
     you want to.  The file MUST be named ORACLE.ANS.

   - LANGUAGE.DAT: This file holds the prompts that TMO uses.  You can use
     the color codes (see below) in the file.  Please read the file to see
     what prompts are what as they're all defined in that file.  You
     shouldn't make the prompts longer than 79 characters (excluding
     color codes).

   - ANSWERS.DAT: You can use up to 32,767 one-line "answers" in this file.
     You can use the inline color codes (see below) in this file.  They
     should all be under 80 characters (excluding color codes) otherwise
     unpredictable results may occur.

     If you modify ANSWERS.DAT in any way, delete the INDEX.DAT file.  TMO
     will rebuild this file the next time it's run.  If this file is not
     correct, TMO will not run as planned.

  NOTE: All of the above files are required for TMO to operate (except for
  INDEX.DAT which is generated by the program).  TMO will stop with an error
  message if any of the above files are missing.

-------------------------------------------------------------------------------
   
  OTHER GENERAL INFORMATION:
  --------------------------

  Global System Variables Used By The Door:
  -----------------------------------------
  {TIME}      = The Current Time
  {DATE}      = The Current Date
  {NODE}      = The Current Node Number
  {BAUD}      = The Current Baud Rate
  {MINS}      = Time Left Online In Minutes
  {EVENT}     = Minutes Until Next Event
  {PORT}      = The Current Comm Port In Use
  {SEC}       = The User's Security Level
  {BBS}       = Your BBS Name
  {USER}      = User's Full Name
  {SYSOP}     = SysOp's Full Name
  {UFIRST}    = User's First Name
  {ULAST}     = User's Last Name
  {SFIRST}    = SysOp's First Name
  {SLAST}     = SysOp's Last Name
  {PROG}      = The Program Name and Version Number
  {ADDR}      = The Port Address Stored In The .CTL File
  {IRQ}       = The Port IRQ Stored In The .CTL File
  {SYSSEC}    = SysOp Security Stored In The .CTL File
  {SERIAL}    = The Serial Number Stored In The .CTL File
  {INSERT1}
   Through
  {INSERT5}   = These are system variables that change from
                time to time through out the program. Check
                your screen files to see what their purpose
                is at the time.

  These variables can also be used in text files and screen files used by
  your program. You will also want to look at your ANSI and RIP files with
  a text editor to make sure that any Global System Variables you have used
  have not been split as this will cause them to display incorrectly.

  There is a neat little feature incorporated in the variables called Padding
  that is used to allign text on your screen, or to ensure that variables will
  only take up X amount of characters on the screen. Any underscores "_" in a
  variable are translated into spaces at run time and can be used on either
  side of the variable. The way to look at it is a "Pad Left" and "Pad Right"
  sort of feature.

  Let's try an experiment with the {USER} variable, we'll just use some
  short strings of text to demonstrate the usage of variables and padding.
  Let's say that the user's real name is "Jimi Hendrix". (Just because...)

    Actual Text: Hello {USER}, how are you today?
  Translates To: Hello Jimi Hendrix, how are you today?

    Actual Text: Hello {USER________________________}, how are you today?
  Translates To: Hello Jimi Hendrix                  , how are you today?

    Actual Text: Hello {________________________USER}, how are you today?
  Translates To: Hello                   Jimi Hendrix, how are you today?

  Now, granted that these aren't really practical examples, but it shows you
  how padded and non-padded variables work. Padding would be especially handy
  if you were creating something like a user statistics screen. You could put
  the padded variables on an ANSI background, and since there is padding in
  there, the screen will always be displayed in a uniformed fashion. As you
  can see in the above example, the variable {USER} is padded so there is a
  total of 30 spaces on the screen. If you were to chop it down to 20, even
  if the user's name was longer than 20 characters, only 20 characters will
  be displayed on the screen at once.

  If you have ever noticed with other programs that use variables of any kind,
  to make sure that your screens always display perfectly alligned is to use
  ANSI animation to go to a specific X/Y coordinate and then plot the variable
  on whatever backdrop you are using. Guess what...ASCII callers are out of
  luck in this case because there is no cursor control in ACSII/TTY emulation.

  Inline Color Tokens:
  --------------------
  Inline Color Tokens are similar to Global System Variables with just one
  exception....They don't work in screen files. These are used for adding
  color to text files. Your ANSI colors range from 0 to 31, any number above
  15 forces ANSI blink on. If you want to change the color anywhere in a text
  file, simply add a color code in a pair of fancy brackets before your text.
  An example would be, to change your text to yellow add the token: {14} just
  before it. You have as many color changes that you can fit into a 256
  character line. Padding has no effect on inline color tokens.

-------------------------------------------------------------------------------

  MULTINODE USE:
  --------------

  This door supports multinode use and provides automatic multi-tasker
  support (time slice releasing) for a wide variety of multi-taskers
  such as DesqView, OS/2, and Windows. You will need to run the program
  configuration to create all of the needed control files and node work
  directories. The only thing left to do after that is create batch files
  for each node.

  If you are using one of the Cheepware doors that use this same development
  system, you may simply copy the CTL files from one door to the other to
  avoid having to retype them over and over.

  My doors are generally well-behaved on any BBS.  However, I have had
  reports of strange behavior under Windows 2000, but unfortunately, it's
  not the door that's causing problems.

-------------------------------------------------------------------------------

  TROUBLESHOOTING:
  ----------------

  This door will create an error log (ERROR.LOG) in the same directory that
  the executable is in if you're having problems and want to track them down.

  1. This door DOES NOT REQUIRE a FOSSIL driver to run correctly.

  2. If you are running a high speed modem (9600 baud or above), then I
     suggest you run your BBS/mailer/doors at a locked baud rate. On high
     speed error correcting modems, locking the baud rate will have a
     noticable increase on the speed of text that is sent. It's beyond
     the scope of this document to discuss configuring your BBS and
     mailer for a locked baud rate, you may wish to consult your BBS docs
     for information on that. Here are a couple things to keep in mind
     when setting up door with a locked baud rate:

    a.  If you are using a FOSSIL, then make sure to tell the FOSSIL
        that the port is locked. For BNU, to lock COM1 at 38,400, you
        would use something like "L0=38400,8N1" on BNU's command line.

    b.  If you lock the baud for one program, it must be locked for
        everything. You can't lock the baud for just this door, but
        not your BBS/mailer.

  3. What follows is some information on possible strange situations
     that may occur on some systems:

    a.  Low speed users can use the door, but high speed users get garbage.

        - If you are the DORINFOx.DEF drop file, then there is a chance
          your BBS is writing the locked port speed to the drop file
          rather than the actual caller baud rate. You should either
          change to the DOOR.SYS drop file, or use the /S parameter to
          pass the actual baud rate to the door.

          Several converter programs are readily available on most
          BBS systems. CallDoor is a good one if you can find it.

    b.  The door hangs up when a user enters the door.

        - Sounds like the door is getting the wrong baud rate somehow.
          Try switching over to the DOOR.SYS drop file method if possible.

        - This can also be cause by using a FOSSIL driver and locking the
          comport at a rate higher than 38400. If this is the case, then
          reduce your locked port speed and try again.

    c.  Text and screens are getting cut off.

        - If you are running with a locked baud, then this could be caused
          by some sort of FLOW CONTROL problem. Make sure your FOSSIL is
          loaded correctly and not locked faster than 38400 baud.

        - If you're using something other than the DOOR.SYS drop file,
          then I always suggest trying to use DOOR.SYS if possible. It is
          the most reliable method and has had the most testing. If that
          is not possible try DORINFOx.DEF as an alternative.

    d.  The door locks up the BBS on every node.

        - This can happen with FOSSIL driver or the internal communications
          routines because it uses the default comport of 1 when NONE or
          COM0: is found in the drop file.

    e.  ANSI is reflected correctly on the local screen but the user is
        getting garbage when using DORINFOx.DEF.

        - Assuming the user has ANSI installed then most likely the problem
          is at your end. First make sure the dropfile is passing the actual
          baud rate INSTEAD of the locked port speed. If it is not passing
          correct baud rate then you may need to use DOOR.SYS instead.

    f.  When a user enters the door or when you run it locally, the screen
        appears to cycle (flipping) over and over until the program shuts
        down with a "Runtime Error 202".

        - This is caused by people running hacked versions of their FOSSIL
          driver. Even though most of these hacks are nothing more than a
          copy with a new version number, once it's tampered with, it's a
          defective copy. Programs to avoid are BNU 2.xx and X00 2.xx. If
          at all possible, get your FOSSIL drivers author direct!

        - If you are running Windows and need a FOSSIL driver, you should
          use ADF v1.50 (filename: ADF_150.ZIP).  It's widely available online
          (http://digsys.se/adf.html is its homepage), but if you do a search
          using your favorite search engine, you'll find it.  It's also
          available on my BBS.  ADF is freeware.

-------------------------------------------------------------------------------

  CREDITS AND THANKS
  ------------------

  The Magic Oracle was developed using Turbo Pascal 7 (RTE200 patched) under
  Windows 2000 Professional with the TDK v2.31 doorkit by Larry Athey, et al.
  The main executable was packed using UPX (http://upx.sourceforge.net).

  Portions of this program contain code written by Michael Preslar and
  are used with permission.  Portions of the documentation written by
  Larry Athey.

  "The Magic Oracle" and "Cheepware" are property of Sean Dennis.  All other
  trademarked/copyrighted names used in this documentation are used for
  reference purposes only and are property of their respective owners.

  Special thanks to:

    -- My wife, Maura, for putting up with me while I whittle away my
       spare time in front of the computers and loving me anyway.

    -- Mark Lewis for the "/V" command line parameter idea.

    -- Steve Wynn for catching the XP auto ANSI detection problem.

    -- All of the many sysops and users over the years that have helped
       me test my programs and hone my programming skills.  There's so
       many that I don't want to mention any names in fear of leaving
       someone out.

-------------------------------------------------------------------------------

  CONTACTING THE AUTHOR
  ---------------------

  I hope you enjoy this door as much as I did developing it.  If you have
  any comments, suggestions, ideas or *gasp* bug reports, please let me
  know directly.  You can contact me via the following:

  Netmail : 1:18/200@Fidonet - 618:618/1@Micronet - 81:10/1@OS2Net
      BBS : telnet://bbs.outpostbbs.net -or- telnet://outpostbbs.darktech.org
    Email : sean@outpostbbs.net -or- hausmaus@darktech.org
      Web : http://outpostbbs.net
       IM : ICQ (19965647) - AIM (eekahausmaus) - YM (blue_vinny)

  If you'd like more information about Cheepware, you can get it via:

        Web : http://outpostbbs.net (click on the Cheepware link)
  Email FREQ: Send an email to bbs@outpostbbs.net with the subject of
              FREQ and the message body of FREQ CHEEP - you will receive
              a listing of available Cheepware files within an hour normally.
        BBS : Just telnet to my BBS and look in my Cheepware file area.

  Thank you for using Cheepware.  Support your local BBS scene!

  -- Sean Dennis
     Cheepware Author

