                         Documentation for Beat The House
                         Written by Robert V. Chambers
                               Copyright (c) 1997


WHAT IS BEAT THE HOUSE?
Beat  The House is basically the card game Black Jack, or 21, implemented as a
BBS  door. This version allows the player to get advice based on probabilities
about whether to stand, hit, split, or double down while playing. The game has
no  maintenance and automatically generates scores  bulletins and a door usage
statistics bulletin.

Two  versions  of the program are  included:  a 16-bit version (bhouse.exe) as
well  as  a 32 bit version (bhouse32.exe).  The  32 bit version will run under
either  Windows95 or Windows NT, but it will  not run under any of the Windows
3.x versions. It may be used with an MS-DOS based BBS running under Windows 95
or Windows NT.

Both  versions of the program were written  in C using Brian Pirie's OpenDoors
Programming  Toolkit. Thanks, Brian, for an  excellent product and for the use
of some of your text in this document!

SYSTEM REQUIREMENTS:
486 or better processor (Pentium recommended)
Requires ANSI graphics on the user's end

WHAT ARE SOME OF THE FEATURES?
*  Instant advice on when to hit, stand, split, or double.
*  Optional activity log.
*  Automatic statistics and scores bulletins.
*  Has a sysop chat mode.
*  Fossil aware.
*  No maintenance required.
*  Supports   standard   drop  files   such   as  DOOR.SYS  (PCBoard/GAP),
   DORINFOx.DEF, EXITINFO.BBS, CHAIN.TXT, etc.
*  Supports simultaneous play on multiple nodes.
*  Sysop configurable path/filename for scores bulletin.
*  Configurable time-in-door limit.
*  Optional autoplay mode.

LIMITATIONS ON UNREGISTERED VERSION:
The  unregistered  version  limits  a player to  10  hands  per  day. You must
register  the  program  to  eliminate this  restriction.  See  the  section on
registration below.

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

INSTALLING THE 16-BIT VERSION:
This is simple, but you must follow these instructions. I am assuming that you
are already familiar with the steps required to install a door on your BBS. If
not,  I  would  suggest  that you read  your  manual  first. This doc will not
attempt to guide you through that.

Step 1)
Place all files in the BH16_10 archive into a single directory of your choice.

Step 2)
Create  a  batch  file that your BBS will  use  to  start the door.
The batch file must always run the game from within the game directory.

I use PCBoard, and my file looks something like this:

 @echo off
 cd\pcb\bhouse
 bhouse.exe c:\pcb\node1\door.sys /L
 IF "%INPCB"=="Y" EXIT
 %PCBDRIVE%
 %PCBDIR%
 board

You  may call the file whatever you  like, subject to restrictions that may be
enforced  by  your  BBS software. Mine is  simply  called BHOUSE, with no .BAT
extension. Again, consult your manual.

A  little  explanation of the startup batch  file is in order here. The second
line  simply changes to the directory where all of your Beat The House program
files  are found. (Remember you put them there  in Step 1.) The second line is
the  name  of the door program, BHOUSE.EXE,  followed  by the complete path to
your  drop file and the (optional) log  file switch. Notice that the drop file
name  is  specified.  If you are using  PCBoard,  you may also use the PCBoard
environment variables for the path to the drop file. Like this:

                     bhouse.exe %PCBDRIVE%%PCBDIR%\door.sys

The  final lines contain BBS reload instructions that are specific to your BBS
software.  Your startup file will undoubtedly  look different, but you get the
general idea.

Step 3)
Setup your BBS software and  configure any door menus, etc. that give
the user access.

Step 4)
Edit  the sample configuration file, SAMPLE.CFG,  to suit your tastes and save
it  as  BHOUSE.CFG.  It  is *CRITICAL*  that  the  configuration file be named
BHOUSE.CFG.  Instructions for each line are contained in the sample file. Note
that  you  must  supply valid paths for  both  scores  bulletins and the stats
bulletin.  Otherwise  you will get an error  message when the door starts, and
default bulletin files will be created in the game directory. Instructions are
included in SAMPLE.CFG.

Step 5)
Edit  DOOR.CFG to setup maximum door  time and keyboard inactivity timeout.

------------------------------------------------------------------------------
INSTALLING THE 32-BIT VERSION UNDER WINDOWS 95:

First  of  all  the 32-bit version will not  run  under Windows 3.x due to the
multitasking and multithreaded design.

Also please NOTE: The program data files generated by the two versions are NOT
interchangeable.  That  means  that if you  start  with  one version and later
decide  to switch to the other you must  reset the game. The easiest way to do
this  is with the RESET.BAT file which is explained later in the "HOW TO RESET
THE GAME" section.

Step 1)
Unzip the 32-bit archive, BH32_10, into the game directory of your choice.

Step 2)
Copy ODOORS61.DLL to your Windows system directory.

Step 3)
If  your BBS is MS-DOS based add  a line of the form "COM<n>AutoAssign=<x>" to
the  [386Enh] section of your SYSTEM.INI  file. Here, <n> specifies the serial
port  number that the BBS's modem is connected  to, and <x> will usually be 0.
For  example, if your modem is connected to COM1, you would add a line such as
"COM1AutoAssign=0" (sans quotes). You will then have to re-start your computer
for  this change to take effect. If you do not do this, the Windows-based door
program will not be able to access the modem.

The  explanation for this is as follows: The default value for this setting in
Windows  95  is -1, which prevents  any Windows-based program from accessing a
serial  port  which has previously been  used  by a non-Windows-based program,
until  the window that program was running in is closed. By setting this value
to  0, you are allowing the Windows-based  door program to immediately use the
modem,  even while the MS-DOS session is  still active. A value of <x> greater
than  0  will allow Windows-based programs to  access the serial port, only if
the  DOS-based  program  has  not accessed the  serial  port  for at least <x>
seconds. For example, the default setting in Windows 3.1 was COM1AutoAssign=2,
which  allowed  Windows-based  programs to access  the  serial  port if no DOS
program had used it for at least 2 seconds.

Step 4)
Create  a batch file that your BBS will  use to start the door. The batch file
must always run the game from within the game directory.

Since I run PCBoard (a Dos-based BBS) my batch file looks like this:

 cd\pcb\bhouse32
 start /w /m bhouse32.exe -DROPFILE %PCBDRIVE%%PCBDIR%\door.sys
 dtron /port 1 /bps 38400
 <statements to restart BBS>

The command line that runs the Windows program should be of the form:

             start /w /m bhouse32.exe -DROPFILE <path to drop file>

This  will cause the program to start in minimized mode, and cause the calling
session  to wait until the Windows program  exits before continuing. If you do
not  wish the program to be started in  minimized mode, remove the /m from the
command  line.  If  you attempt to start  the  program by calling it directly,
rather  than  using the "start /w"  command, the BBS software will immediately
start  again, cause it to attempt to run simultaneously with the door program.
Note  that  for  some reason the /m  command  appears  to have no effect under
Windows  NT. The door will run fine,  but will not automatically minimize upon
startup.

                        ================================
                                  Special Note
                        ================================
If  your BBS can pass a serial port handle to the door on the command line you
might try setting up like this:

   start /w /m bhouse32.exe - handle xxxxxxxxx -dropfile <path to drop file>

where xxxxxxxxx is the serial port handle, in decimal format. In this case you
should not need DTRON.EXE.
                        ================================

After  running the start command, if you  are running Windows 95, you must use
DTRON.EXE  or  a similar utility to re-enable  DTR detection by the modem. You
will not need to do this under Windows NT. See the next section for details on
why this is necessary. Normally, this command line will be of the form:

                              dtron /port x /bps y

Where  x is the serial port number (0 for COM1, 1 for COM2, etc.) and y is the
locked  bps rate. For example, if your serial  port is locked at 38400 bps and
is connected to COM2, you would use:

                            dtron /port 1 /bps 38400

For full information on the DTRON utility, simply type the command line:

                                  dtron /help

I  found  that I had to add a  short  delay after putting the modem online and
before  loading the BBS so I had  to customize the command line for DTRON.EXE.
The "~" at the end adds a one second delay.

            dtron /port 1 /bps 38400 /cmd "~+++ OK AT&D2| OK ATO|~"

Step 5)
Setup  your BBS software and configure any door menus, etc. that give the user
access.

Step 6)
Edit  the sample configuration file, SAMPLE.CFG,  to suit your tastes and save
it  as  BHOUSE.CFG.  It  is *CRITICAL*  that  the  configuration file be named
BHOUSE.CFG.  Instructions for each line are contained in the sample file. Note
that  you  must  supply valid paths for  both  scores  bulletins and the stats
bulletin.  Otherwise  you will get an error  message when the door starts, and
default bulletin files will be created in the game directory. Instructions are
included in SAMPLE.CFG.

Step 7)
Edit  DOOR.CFG to setup maximum door  time and keyboard inactivity timeout. If
you're using the DTRON.EXE utility you may also have to modify the DTR disable
string. Try the default first.

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

INSTALLING THE 32-BIT VERSION UNDER WINDOWS NT:

Installing  under  Windows NT should be exactly  the  same as under Windows 95
with  the exception of using DTRON.EXE  to re-enable DTR recognition. You will
not need to add this statement to your batch file.

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

WHAT IS DTRON AND WHY IS IT NECESSARY?
When  a  Windows  program  exits and closes  the  serial  port (by calling the
CloseHandle()  function),  Windows 95 lowers the  DTR line on the serial port.
Most  modems  are  configured to respond to  this  by hanging up on the remote
user.  It seems that this "feature"  (or fundamental design flaw, depending on
how  you  want to look at it) is unique  to Windows 95, and has no effect when
running  under Windows NT. However, the majority of people will undoubtedly be
using the 32-bit version Windows 95.

There are currently two solutions to this problem.

First  of  all  the door can use an  already  open serial port handle, if that
information  is supplied to it. On BBS  systems where this form of hot sharing
of the serial port is supported, the serial port can remain open at all times,
and so the CloseHandle() problem is avoided.

This  means that the only situation  where the CloseHandle() problem still has
to be dealt with is when the program is running on a Windows 95 system and the
program  has to open the serial port itself (and so must close the serial port
before  exiting).  This  would be the case  for  most MS-DOS based BBS systems
running  under  Windows  95, unless some  intermediate  layer  is provided. By
default,  in this situation the program will disable DTR response by the modem
just  before  it closes the serial port,  by  sending the AT&D0 command to the
modem. The exact sequence of commands used to do this is specified in DOOR.CFG
and  may  be  changed if necessary. Since  many  programs assume that they can
hangup  the modem by lowering the DTR  signal, a small utility will usually be
run  after  the  door,  which  first raises  the  DTR  signal  again, and then
re-enables  DTR  response  by the modem. Such  a  utility  is included in this
package, named DTRON.EXE.

So,  to  summarize, DTR disabling and  subsequent  reenabling by DTRON is only
required  for  the 32-bit version running under  Windows  95 when the modem is
configured  to hangup if the DTR signal  is lowered, and the BBS software does
not have the ability to pass a live serial port handle to the door program.

Setting COM<n>AutoAssign in SYSTEM.INI is only required for the 32-bit version
when  it  is being called from an  MS-DOS session that has previously accessed
the serial port.

Once again, note that the 32-bit version requires Windows 95 or Windows NT. It
will not run under Windows 3.x, even with Win32s. This is because it makes use
of  the  Windows 95/NT multitasking and  multithreading  services that are not
available under Win32s.

RUNNING LOCAL:
You can run the game in local mode if a drop file is in the program directory.
DORINFO1.DEF is included in the archive for this purpose. Just place it in the
door program file directory and execute the program by running BHOUSE.EXE (16)
or BHOUSE32.EXE (32), whichever you happen to be working with.

You  should be able to leave this file  in your game directory with no problem
since  you  have defined the path to the  real drop file in your startup batch
file.  You  should  only  run  the game in  local  mode  to  test  it prior to
installation.  Because the program automatically  generates bulletins as it is
played  you should reset the game after  running in local mode to avoid having
the  default  name in the sample drop  file included in the scores bulletin. A
batch file, RESET.BAT is provided for this purpose.

CUSTOMIZATION:
-  TITLE AND WINNER SCREENS
If  you want a new title screen you can  do it. Create a new screen using your
favorite   ANSI  editor,  and  call  it  TITLE.ANS  (for  16-bit  version)  or
TITLE32.ANS  (for  32-bit  version). Leave enough  room  at the bottom for the
additional  registration  text.  It's  *CRITICAL*  that  you  name these files
correctly.  You  may do the same with  WINNER.ANS,  the file that is displayed
when  a player reaches the winning amount. Both 16 and 32-bit versions use the
same file name.

- INACTIVITY TIMEOUT AND MAXIMUM DOOR TIME
You  may specify the maximum time allowed in the door and the keyboard timeout
limit  by  editing DOOR.CFG. Instructions are in  this file and should be self
explanatory. Be sure you allow enough time for your users to sit and think!

- LOGGING ACTIVITY
The program will optionally provide activity logging of entry and exit times.
To enable this feature simply edit your configuration file and change line 7
from "NO" to "YES" (without the quotes).

The log file can become lengthy if the door is used regularly. A suggestion is
to  enable  logging when the door is  initially  installed to monitor its use.
After  a  period  of  time you may wish  to  disable  logging or trim the file
occasionally  (there are programs that will do  this in an event).

THE STATISTICS BULLETIN:
This  version will create a basic door statistics bulletin which will tell you
how  many times the door has been entered, average time in the door, etc. This
was  added  primarily to help the sysop  gauge usage, but it is available from
within  the door, just like the scores bulletins. The bulletin that is created
will  include  the  date  that  statistics  collection  started,  so  you  can
occasionally  delete  STATS.DAT  if you want  to  periodically start over. The
bulletin  is  generated each time a player  exits so there's no need to delete
the  bulletin  file  if  you  delete  STATS.DAT.  Statistics are automatically
restarted  if the game is reset using  the included RESET.BAT file, though you
can simply remove the line in the batch file if you don't want to do this.

MAINTENANCE:
There  is  no maintenance! The game maintains  itself when the first player of
the  day enters the game. The game will immediately reset player data if there
is  a winner and create a winner's banner that is displayed each time the game
is entered. Door statistics are not reset when the game is won.

MULTINODE USE:
The  game  is  set  up  to  run  on  multiple  nodes  simultaneously.  It will
automatically take care of the situation that exists when a player on one node
wins  the game while there are other players on other nodes. You should follow
your  bulletin  board  software instructions for setting  up  a door to run on
multiple nodes. It is critical that each node execute the game from within the
game file directory.

HOW TO RESET THE GAME:
A  batch file is included (RESET.BAT) that  will delete all files necessary to
reset  the  game.  It must be run from  the  game  file directory. It will not
delete  the scores or stats bulletins since  these are recreated each time the
game is played.

TROUBLE  SHOOTING:
In  the  event you have trouble maybe some  of  these tips will help you. This
list  is  not  very  long yet, but  will  be  added  to as information becomes
available.

1)  The  door will not open from the BBS  at  all. It looks like it tries, but
immediately  shuts down and returns to the BBS. It will, however, run in local
mode (from Dos).

-  This is almost certainly a sign that the startup file is not specifying the
correct  path  and/or file name of the  drop file. It's also possible that you
have  not  set the board up correctly and  the expected drop file is not being
created.  The  startup batch file must include  the full path and file name of
the  drop  file as an argument to  the executable. See the sample startup file
above.  The  reason  it will run in local  mode  is that the sample drop file,
DORINFO1.DEF,  is  in the same directory as the  game files so the game has no
trouble finding it.

2)  You  are using DOOR.SYS and the  door  keeps logging you out when entering
locally.

- If you are not using the long GAP version (51 lines) of DOOR.SYS then either
go  to  the long version or try  DORINFO1.DEF. The DORINFO style drop file has
been successfully tested on Maximus.

3)  The graphics don't behave exactly right (on the user's end) with the board
running under Windows 95.

-  If  you  experience problems with this  try  running the window either full
screen  or  in  the  foreground. This seems  to  solve  the problem if you are
running the X00 fossil driver, but is not a good solution if running more than
one  node.  Try switching to the BNU  fossil driver. This driver seems to work
better  with  Win95.

THE LEGAL STUFF:
Users  of  Beat The House must accept  this  disclaimer of warranty: "Beat The
House  is  supplied as is. The  author  disclaims all warranties, expressed or
implied,  including, without limitation, the warranties of merchantability and
of  fitness  for  any purpose. The  author  assumes  no liability for damages,
direct or consequential, which may result from the use of Beat The House."

I  make no guarantee that this software  will perform properly on your system.
Though  every  effort  has been made to  make  the program suitable for a wide
range   of  systems,  you  should   thoroughly  evaluate  the  product  before
registering.  Once a registration key is provided there will be no refund.

By  registering  you do NOT own this  software.  You have simply licensed it's
use.  You may use it on as many BBS  nodes as you wish, as long as these nodes
comprise  a single bulletin board system. You  may create as many instances of
the program as you wish, as long as they all reside on a single bulletin board
system.

You  are encouraged to pass a copy of Beat The House along to your friends for
evaluation.  Please  encourage them to register  their  copy if they find that
they  can use it. You may NOT pass along your registration code, however. This
should go without saying, and will be dealt with appropriately if discovered.


REGISTRATION :
This  is  not  freeware; it is shareware.  If  you  are not familiar with this
concept it means that you are allowed to try the software free of charge for a
period  of time not to exceed 30 days. At the end of this time you must either
register it or remove it from your system.

I  feel  that  the  time  invested in  writing  and  testing  the  program was
significant  enough  to justify a registration fee.  The cost is $15 U.S., and
payment  may be made via check drawn on  a United States bank. No credit cards
are accepted. I will take your cash, but you send it at your own risk.

To  register  fill  out REGISTER.FRM (included)  and  send it, along with your
check  or money order, to the address on  the form. I will respond to you with
your  registration either through U.S. Postal  Service or Internet E-Mail. The
choice is yours; just be sure to specify which you prefer on the form.

When  you  receive your registration code  manually edit BHOUSE.CFG and change
the  first two lines to your registered  name and code number. Be careful that
the registered name is entered EXACTLY as it has been specified as it is space
and  case  sensitive.  Also please note that  your  registered name MUST be at
least 4 characters in length.

The  unregistered  version  will  only support  10  hands  per player per day.
Registration  will remove this limitation and allow the sysop to configure the
game  for  any  number of hands. Registration  will  also  entitle you to free
lifetime upgrades.

There  will  be no automatic notification of  upgrades. You can always get the
latest version of the program from my website at:

                        http://www.premier.net/~chambers


TECHNICAL SUPPORT:
Technical support will be provided to both registered and non-registered users
to  the best of my ability. However, please be sure you have read this file in
its  entirety  first. I will not attempt  to  support the product unless it is
running  on  a  BBS. This is what the  product  was designed for as opposed to
standalone use like a typical PC game.  However, I WILL do my best to help you
run it locally for evaluation purposes.

You may reach me via the following:

Internet EMail -       chambers@premier.net

Thanks  for  your interest in Beat The House!  I hope you and your users enjoy
the game.
