


























                         GAP Communications Online Software




                                       GAPQBDR

                 Door Interface Library For Quick Basic Programmers






          Copyright (C) 1987-1993 by GAP Development Company.


          ALL RIGHTS  RESERVED. No part of this manual shall be reproduced,
          stored in  a retrieval  system,  or  transmitted  by  any  means,
          electronic, mechanical,  photocopying, recording,  or  otherwise,
          without written  permission from  GAP Development  Company. While
          every precaution  has been  taken  in  the  preparation  of  this
          manual, GAP  Development Company  assumes no  responsibility  for
          errors or omissions. Neither is any liability assumed for damages
          resulting from the use of the information contained herein.


          GAPQBDR is  the sole  and exclusive  property of  GAP Development
          Company. It  is licensed  and not  sold  to  the  end  user  with
          restrictions placed upon its use.


          GAPQBDR is copyrighted by GAP Development Company.
          DESQview is a trademark of Quarterdeck.
          PCBoard is a trademark of Clark Development Corporation.
          WildCat! is copyrighted by Mustang Software.
          DigiBoard is a trademark of DigiBoard Incorporated.






                                  TABLE OF CONTENTS






                                                                       Page



          DESCRIPTION                                                     5



          GETTING STARTED                                                 6



          COMPILING AND LINKING                                          12



          SYSOP SETUP AND FUNCTIONS                                      13



          GLOBAL VARIABLES                                               17

               CONSTANTS                                                 17
               ANSI CONSTANTS                                            17
               DOOR.SYS VARIABLES                                        18
                    INTEGERS                                             18
                    LONGS                                                18
                    STRINGS                                              18
               GAPQBDR GLOBALS                                           19
                    INTEGERS                                             19
                    LONGS                                                19
                    STRINGS                                              19


          GLOBAL VARIABLES - ALPHABETICALLY By Type                      20

               CONSTANTS                                                 20
               INTEGERS                                                  20
               LONGS                                                     21
               STRINGS                                                   21




                                       Page 3






          FUNCTIONS AND SUBROUTINES - QUICK REFERENCE                    22



          FUNCTIONS AND SUBROUTINES - REFERENCE                          23



          INDEX                                                          51










































                                       Page 4



          GAPQBDR       (C) Copyright 1988-1993 The GAP Development Company


                                     DESCRIPTION
                                     -----------

          GAPQBDR is a professional development kit for Bulletin Board Door
          programmers. It  can also  be used  to facilitate  the writing of
          stand alone  communications programs.  Written entirely  in Quick
          Basic (with  a little help from some Assembler support routines),
          it is  fast, reliable,  easy to use, and easy to incorporate into
          the serious programmer's source code.

          Features Include :

               o    Interfaces with GAP Communications, PCBoard, WildCat or
                    any BBS capable of writing a DOOR.SYS file.
               o    Complete interrupt driven communications which does not
                    require a DTR patched BRUNxx.EXE run time library.
               o    Supports the  DigiBoard COM/Xi  Intelligent Serial Port
                    Boards.
               o    Supports the FIFO buffers of the 16550 UART.
               o    Speeds to 57,600 bps.
               o    Supports all communications ports.
               o    Does not require watchdog or CTTY.
               o    Uses ANSI colors instead of Basic's color statements so
                    the sysop sees what the caller sees.
               o    Maintains a scoreboard of the top 10 players.
               o    High speed text file display.
               o    Supports ANSI  color  and  ASCII  text  files  with  no
                    programming  effort   other  than   to  make  a  single
                    subroutine call.
               o    Easy to use Random Number Generator.
               o    Informative Status Line display.
               o    Monitors keyboard activity and caller time remaining.
               o    Easy interfacing to BBS system and user files.
               o    Sysop chat with full word wrapping.
               o    Allows the sysop to shell to DOS.
               o    "Remembers"  the  default  drive  and  directory  which
                    prevents file access errors.
               o    Credits caller  with time spent chatting or while sysop
                    is in a DOS shell.
               o    Sysop can  twit caller  without caller ever knowing the
                    sysop is watching.
               o    Caller time can be increased or decreased.
               o    Time calculations  are not  dependent on  the  "seconds
                    since midnight"  and  are  thus  unsusceptible  to  the
                    midnight roll over.
               o    Allows the sysop to "force" a file display.
               o    Automatic detection of multi-user system.
               o    Extremely easy interfacing to door programs.



                                       Page 5



          GAPQBDR       (C) Copyright 1988-1993 The GAP Development Company


                                   GETTING STARTED
                                   ---------------

          GAPQBDR is distributed in archived format. The contents of the
          archive should be as follows:

               QBORDER.FRM    -    Registration Info and Order Form.
               GAPQBDR.TXT    -    This documentation.
               GAPQBDR.QLB    -    Library routines for QB 4.5 environment.
               GAPQBDR.LIB    -    Library routines for QB 4.5.
               GAPQBDR7.LIB   -    Library routines for Basic 7.x.
               GAPQBDR.BI     -    Door Interface include file.
               GAPQBERR.BI    -    Error Handling routines.
               DOOR.ZIP       -    Sample program illustrating many of
                                   the features of GAPQBDR.
               READ.ME        -    Any pertinent information which you
                                   should read.
               LIBLIB         -    Library Response File for QB 4.5.
               LIBLIB7        -    Library Response File for Basic 7.x
               QLBLIB         -    Linker Response File for QB 4.5
               QLBLIB7        -    Linker Response File for Basic 7.x
               MAKE7QLB       -    Batch File to build Basic 7.x QLB file.
               MAKEBAS7.BAT   -    Batch File to build Basic 7.x LIB file.
               MAKESRC.BAT    -    Batch File to build 4.5 LIB & QLB files.


          If you licensed the source code to GAPQBDR, the following files
          are included in an archive called GAPQBSRC:

               ACCESS.BAS     -    Basic source for file access.
               CARRIER.BAS    -    Basic source for no carrier routines.
               DOCHAT.BAS     -    Basic source for sysop chat.
               GAPDOS.BAS     -    Basic source to read/write GAPDOS.DAT.
               GAPQBDR.BAS    -    Basic source for main GAPQBDR functions.
               GAPUSER.BAS    -    Basic source to read/write GAP USERS.
               GETRAND.BAS    -    Basic source for random number routines.
               INITDOOR.BAS   -    Basic source for door initialization.
               LEAVE.BAS      -    Basic source for closing the door.
               PCBSYS.BAS     -    Basic source to read/write PCBOARD.SYS.
               PCBUSER.BAS    -    Basic source to read/write PCB USERS.
               PUTCHAR.BAS    -    Basic source for character output.
               SCOREBRD.BAS   -    Basic source for scoreboard routines.
               SHOWFILE.BAS   -    Basic source for file display.
               STATUS.BAS     -    Basic source for the status line.
               SYSPAGE.BAS    -    Basic source for page sysop routines.
               TIMCRED.BAS    -    Basic source for time credits.
               WAIT.BAS       -    Basic source for time pauses.
               ATSAY.ASM      -    Assembler source for screen positioning.



                                       Page 6



          GAPQBDR       (C) Copyright 1988-1993 The GAP Development Company


               CLS.ASM        -    Assembler source for clear screen.
               CTRLC.ASM      -    Assembler source for CTRL-C handler.
               CURSOR.ASM     -    Assembler code for cursor positioning.
               DOSPRINT.ASM   -    Assembler source for BIOS string output.
               GAPPUTS.ASM    -    Assembler source for string output.
               GETKEYC.ASM    -    Assembler source for keyboard input.
               KEYBRD.ASM     -    Assembler source for keyboard function.
               GAPQBSRC.BI    -    Global declarations for source files.
               LIBLIB         -    Library Response File for QB 4.5.
               LIBLIB7        -    Library Response File for Basic 7.x
               QLBLIB         -    Linker Response File for QB 4.5
               QLBLIB7        -    Linker Response File for Basic 7.x
               MAKE7QLB       -    Batch File to build Basic 7.x QLB file.
               MAKEBAS7.BAT   -    Batch File to build Basic 7.x LIB file.
               MAKESRC.BAT    -    Batch File to build 4.5 LIB & QLB files.
               SRCREAD.ME     -    Any pertinent information which you
                                   should read.

          In addition,  all the  object modules  for  the  private  GAPQBDR
          functions are  provided so that you may create the quick library.
          You will  also need  the file QB.BI which is distributed with the
          Microsoft QB  disks. A DTR patched BRUN45.EXE is not needed since
          GAPQBDR uses its own communications routines.

          Place the  files in  your QB work directory. Make sure that QB.BI
          is accessible  to the compiler. The source files should be placed
          in a directory called SOURCE (off of your QB directory).

          Throughout this  document, the terms function, routine, procedure
          and subroutine  are  used  interchangeably.  However,  pay  close
          attention to the return value and the examples. In QB, a function
          returns a value, where as a sub program does not.

          If you  use an external editor to write your programs, the editor
          must allow  control characters  to be  entered and displayed. The
          ANSI constants  are initialized by literal characters and if your
          editor removes  the ESC  character from  the constants, your ANSI
          displays will be quite messy.

          If you  are using  the QB  environment, you will need to load the
          door module  along with  your source  program. To do so, type the
          following :

               QB door /L GAPQBDR

               (where door is the name of your basic source program)





                                       Page 7



          GAPQBDR       (C) Copyright 1988-1993 The GAP Development Company


          If you  fail to  load the  quick library along with your program,
          you will  receive a  great many  "subprogram not  defined" errors
          when you try to compile or run your program.

          We are a firm supporter of declaring all variables prior to their
          use. Not  only does  it make  your programs  easier to  debug, it
          makes them  easier   to read   and  follow. We recommend that you
          follow our guidelines and declare all of your global variables at
          the beginning of your program, after including GAPQBDR.BI.

          At the  very beginning  of your  program, you  must  include  the
          GAPQBDR.BI file. Without this file, nothing will work. It must be
          the first directive in your source file. To include the file, you
          type the following at the beginning of your source program:

               '$INCLUDE: 'GAPQBDR.BI'

          Do not under any circumstances use the DEF type statements (I.E.,
          DEFINT A-Z).  This is  the lazy  persons method  of  programming.
          Typedef your variables by either declaring them ahead of time, or
          by appending the type after the name (i.e., A$, I%).

          If you  need to use your own On Error routines, you should modify
          the supplied  error handler  rather  than  simply  ignore  it  or
          replace it. If you subsequently change the Error Trap address, it
          is your responsibility to deal with any run time errors.

          After declaring any variables and functions, you must include the
          error handling file. The error handler is included in your source
          module so  that it  can be globally accessible by all routines in
          the GAPQBDR  library. To  include the  file, type  the  following
          immediately AFTER  declaring your global variables and BEFORE any
          executable statements:

               '$INCLUDE: 'GAPQBERR.BI'

          It is  important that  the error handling file be inserted at the
          proper place in your program. The file may not be included before
          your variable  declarations and it MUST be included prior to your
          first executable  statement. Please see the example program for a
          sample of  how to  include this  file. Remember  that a  variable
          assignment is not a variable declaration but an actual executable
          statement.

          You are  now ready  to begin your program. You may now initialize
          your variables and start your program.





                                       Page 8



          GAPQBDR       (C) Copyright 1988-1993 The GAP Development Company


          The first  thing that must be done prior to using any of the door
          functions, is  to initialize  GAPQBDR itself.  This  is  done  by
          making a  call to read.cnf. Read.cnf opens the configuration file
          (the name  of which  you pass as a parameter) and reads the first
          eight lines  of the  file. If  the configuration  file cannot  be
          found, the program will end. The format of the configuration file
          is as follows:

          -----------------------------------------
          C:\GAP
          The Crow's Nest BBS
          4
          03F8
          STANDARD
          D000
          320
          4


          The first  line of  the file  is the  path  to  the  BBS  default
          directory. The second line is the name of the BBS. The third line
          is the Port IRQ and the 4th line is the Port Base Address. If the
          sysop running  your program  has his  BBS configured  to use  Com
          Ports other  than 1  or 2,  he would  then enter the IRQ and Base
          address for  his Com  Port on  lines 3 and 4. GAPQBDR derives the
          Port Number from the DOOR.SYS file.

          Lines five through eight are for the Intelligent DigiBoard multi-
          port Communications  Card. The  DigiBoard  routines  specifically
          support the  COM/Xi series.  All four of these lines are required
          even if  your end  users are  using the  Standard Interface. Line
          five is  the Communications Port Interface. It must be one of the
          following:

                    STANDARD    DIGIBOARD   INT14/EBIOS

          The Standard  interface is the one that will normally be used. If
          an end  user is  using a  DigiBoard then  either the DigiBoard or
          Int14/EBIOS interface  may be  selected. Most sysops will use the
          Int14/EBIOS interface.  All  input/output  to  the  DigiBoard  is
          performed via  Interrupt 14  calls and a Device Driver (available
          from DigiBoard) handles the interface between the program and the
          board. The  DigiBoard interface  uses Direct Programming. GAPQBDR
          talks to the board directly without the need for a Device Driver.
          In order  to use  this interface,  a program  called RESETDIG.EXE
          must be used in the AUTOEXEC.BAT file to reset the DigiBoard once
          when the  computer is first booted. If the end user does not have




                                       Page 9



          GAPQBDR       (C) Copyright 1988-1993 The GAP Development Company


          this program (it is a part of the GAP Communications BBS package)
          then the Int14/EBIOS interface must be used.

          If the  Interface is  other than STANDARD, then lines 6 through 8
          will be  ignored. If  the Interface  is INT14/EBIOS, then lines 6
          and 7 will be ignored.

          Line 6  is the  DigiBoard Memory Window, or the address the board
          uses as  a  communications  area  between  itself  and  the  Host
          Computer. This  line is  used only  if the  Interface is  set  to
          DIGIBOARD. It  can be  set to  0 if  the Interface is STANDARD or
          INT14/EBIOS.

          Line 7  is the DigiBoard I/O Port Address. This line is used only
          if the  Interface is  set to  DIGIBOARD  and  can  be  set  to  0
          otherwise.

          Line 8 is the DigiBoard Channel Number. This line is required for
          the DIGIBOARD  and INT14/EBIOS  Interfaces. It  is normally 1 - 8
          for the  DIGIBOARD Interface  and 4  -  11  for  the  INT14/EBIOS
          Interface. The  Channel Number  is similar  to a  Port Number. It
          tells the  program which of the DigiBoard Communications ports to
          use.


          The configuration  file is  usually given  a name  similar to the
          name of  your door  program, with  a CNF extension. Read.cnf will
          leave this  file open for your use. If you have any configuration
          options of  your own,  you may  place them in this file beginning
          with line  9. Do  not read your configuration options until after
          making a  call to  init.door (which should be the second function
          call in  your program).  Upon return from init.door, you are free
          to read  your configuration  options (if  any). At this time, you
          should close the configuration file. Its file number is #1.

          Normally, your  program is  invoked with a command line parameter
          giving the name of the configuration file to use:

               (I.E., DOOR DOOR.CNF).

          You would  use the COMMAND$ function to extract the configuration
          parameter and  then pass  this parameter  on  to  read.cnf.  This
          allows the  end user  to use a single program (your program) with
          multiple configuration  files. This is especially important under
          multi-user systems where separate configuration files are needed.

          The configuration  file is  opened as  a sequential file so using
          Line Input #1 would be appropriate for reading any data.



                                       Page 10



          GAPQBDR       (C) Copyright 1988-1993 The GAP Development Company



          If there  were no errors, read.cnf will return. You must now make
          a call  to init.door. Init.door uses the information derived from
          line 1  of the  configuration file  to open and read DOOR.SYS. In
          addition, init.door  opens the  communications port (if  a remote
          user is  on), initializes  some global variables, initializes the
          random  number  generator,  and  installs  the  CTRL-C  interrupt
          handler. If there is an error, init.door will not return. Instead
          it will end the program.

          That is  basically all  you have  to do to initialize the GAPQBDR
          module. When  your  program  ends,  you  should  clean  house  if
          necessary and  call leave.  Leave closes  the communications port
          and any  open files,  sends a sign off message to the caller, and
          then exits to DOS.

          Things to remember:

            To get  the ball  rolling,  include  GAPQBDR.BI  as  the  first
            directive in your source program.

            Include GAPQBERR.BI  after declaring  any global  variables and
            prior to your first executable statement.

            To initialize  the door,  call read.cnf  with the  name of your
            programs configuration file. Call init.door.

            Call leave when your program is finished.

            With the  exception of  file #1  which  is  used  to  read  the
            configuration file  and which  YOU should  close, there  are no
            other files  left open.  GAPQBDR uses good programming practice
            by asking  Basic for  a file  number rather  than telling Basic
            which number to use.

            All input  and output  should be  performed through the GAPQBDR
            functions. The  sample program  gives good  examples on  how to
            accomplish this.

            To determine if the BBS is a single or multi user system, check
            the variable  called node. If it is anything other than 0, then
            the BBS is multi-user and you should read/write your data files
            with sharing attributes.


          To test  your program,  you will  need a  DOOR.SYS file  that was
          written for  local exit.  Of course,  you can  always modify  any
          DOOR.SYS file and change the first line so that it reads COM0:. A



                                       Page 11



          GAPQBDR       (C) Copyright 1988-1993 The GAP Development Company


          complete set  of sample  files  are  provided  for  testing  your
          program under  local mode. Experience has shown that although the
          QB environment  editor makes for a cumbersome programmers editor,
          testing programs  inside QB  is  perhaps  the  easiest  and  most
          efficient way  to test. The environment is wonderful for catching
          syntax errors  and even more fantastic at allowing the programmer
          to correct those errors and continue to run the program.

          Do not  use any  of the  Basic input/output or screen positioning
          functions. If  you do,  you will  find that  if  you  attempt  to
          "print" a  string, the string will not appear on the screen where
          you might  think it  should. This  is because Basic maintains its
          own  cursor   location,  and   GAPQBDR  does   NOT  update   this
          information.  All   input/output  should  take  place  using  the
          functions provided  by GAPQBDR.  Not only are they more efficient
          than Basics, they are faster as well!


                                COMPILING AND LINKING
                                ---------------------

          GAPQBDR has already been compiled with the necessary compile time
          switches.

          To compile  your programs,  use whatever switches are required by
          your program  along with the /x (on error) switch which is needed
          for the error handling routine. Use the following commands:

               bc /x doorname;
               link doorname,,NUL.MAP,+gapqbdr

               Where doorname is the name of your program.



















                                       Page 12



          GAPQBDR       (C) Copyright 1988-1993 The GAP Development Company


                              SYSOP SETUP AND FUNCTIONS
                              -------------------------

          These sysop  setup and  function descriptions should be placed in
          the documentation  of your  door program.  You should,  of course
          change the setup information to fit your particular needs.


          Door programs written with the GAPQBDR Door Interface Module will
          run on any BBS System that supports DOOR.SYS.

          To configure the door for a particular BBS setup, a configuration
          file must  be used.  At the  very minimum, this file will contain
          eight lines.  It may  contain more  than eight,  depending upon a
          particular doors configuration requirements. The name of the file
          is usually  the same  as that  of the door program but with a CNF
          extension. The minimum requirements for the file are as follows:

                    C:\GAP
                    The Crow's Nest BBS
                    4
                    03F8
                    STANDARD
                    D000
                    320
                    4


          The first  line of  the file  is the  path  to  the  BBS  default
          directory. The second line is the name of the BBS. The third line
          is the Port IRQ and the 4th line is the Port Base Address. If you
          have your  BBS configured to use Com Ports other than 1 or 2, you
          would enter the IRQ and Base address for your Com Port on lines 3
          and 4. GAPQBDR derives the Port Number from the DOOR.SYS file.

          Lines five through eight are for the Intelligent DigiBoard multi-
          port Communications  Card. The  DigiBoard  routines  specifically
          support the  COM/Xi series.  All four of these lines are required
          even if  you are  using the  Standard Interface. Line five is the
          Communications Port Interface. It must be one of the following:

                    STANDARD    DIGIBOARD   INT14/EBIOS

          The Standard  interface is the one that will normally be used. If
          you  are   using  a   DigiBoard  then  either  the  DigiBoard  or
          Int14/EBIOS interface  may be  selected. Most sysops will use the
          Int14/EBIOS interface.  All  input/output  to  the  DigiBoard  is
          performed via  Interrupt 14  calls and a Device Driver (available



                                       Page 13



          GAPQBDR       (C) Copyright 1988-1993 The GAP Development Company


          from DigiBoard) handles the interface between the program and the
          board. The  DigiBoard interface  uses Direct Programming. GAPQBDR
          talks to the board directly without the need for a Device Driver.
          In order  to use  this interface,  a program  called RESETDIG.EXE
          must be used in the AUTOEXEC.BAT file to reset the DigiBoard once
          when the  computer is  first booted.  If you  do  not  have  this
          program (it is a part of the GAP Communications BBS package) then
          the Int14/EBIOS interface must be used.

          If the  Interface is  other than STANDARD, then lines 6 through 8
          will be  ignored. If  the Interface  is INT14/EBIOS, then lines 6
          and 7 will be ignored.

          Line 6  is the  DigiBoard Memory Window, or the address the board
          uses as  a  communications  area  between  itself  and  the  Host
          Computer. This  line is  used only  if the  Interface is  set  to
          DIGIBOARD. It  can be  set to  0 if  the Interface is STANDARD or
          INT14/EBIOS.

          Line 7  is the DigiBoard I/O Port Address. This line is used only
          if the  Interface is  set to  DIGIBOARD  and  can  be  set  to  0
          otherwise.

          Line 8 is the DigiBoard Channel Number. This line is required for
          the DIGIBOARD  and INT14/EBIOS  Interfaces. It  is normally 1 - 8
          for the  DIGIBOARD Interface  and 4  -  11  for  the  INT14/EBIOS
          Interface. The  Channel Number  is similar  to a  Port Number. It
          tells the  program which of the DigiBoard Communications ports to
          use.


          GAPQBDR will  obtain the  sysop's name from the BBS configuration
          file.

          You must  now create  a batch file to invoke the door. This batch
          file is  placed in  your BBS default directory. Such a batch file
          might look like this:

               @echo off
               cd \gap\doors\tl
               tl tl.cfg
               cd \gap

          As you  can see, the door is invoked by passing the configuration
          file name as a parameter.






                                       Page 14



          GAPQBDR       (C) Copyright 1988-1993 The GAP Development Company


          You will  also need  to modify your doors menu files and the data
          file that  tells the  BBS what  your doors  are and  the security
          level needed to access them. For GAP, these are respectively:

               DOORM
               DOORMG
               DOORS.DAT

          Please refer  to your  BBS documentation  for details on  setting
          these files up.

          If you  are running  multi-nodes, simply  create a  separate door
          configuration file  for each node, and number them. For instance,
          for a  3 node  system, you might have the following configuration
          files:

               TL1.CFG
               TL2.CFG
               TL3.CFG

          The only difference between the three would be the 1st line which
          points to the default directory for the particular node.

          The following sysop functions are available while awaiting
          keyboard input :

                   F5     -  Shell to DOS.
                   F8     -  Twit user and return to BBS.
                  F10     -  Initiate chat with user.
                  CF10    -  Answer user page bell.
                  Home    -  Main user stats.
                  End     -  Displays sysop keys available.
                  PgDn    -  Secondary user stats.
                Up Arrow  -  Increase user's time remaining.
                Dn Arrow  -  Decrease user's time remaining.


          One of  the nicer  features about using the TWIT key, is the user
          is not  told that  "the sysop  wants them  to return to the BBS".
          Instead, a very plain and simple message of "returning you to the
          BBS" is displayed. This way, the user is given no indication that
          the sysop is hovering about.

          When using  the F5  shell to  DOS key,  to  return  to  the  door
          program, simply  type EXIT  at the  DOS command prompt. It is not
          necessary to  change directories  back  to  the  door  directory.
          GAPQBDR is  smart enough  to know  which drive  and directory the




                                       Page 15



          GAPQBDR       (C) Copyright 1988-1993 The GAP Development Company


          door program  is in and  will reset the defaults upon return from
          DOS.

          The Up  and Down Arrow keys increase and decrease the user's time
          respectively by  5 minutes for each press of the key. There is no
          indication of  what is  occurring (except  by the fact the user's
          time remaining  will change), so the sysop should try not to have
          a lead  finger. The  increase or decrease is effective only while
          the user is in the door. Since we are firm believers that the BBS
          system files  belong to  the BBS and should not be altered by any
          door program,  updating the  BBS system file is NOT automatic. If
          you wish that any decrease or increase in the user's time be made
          permanent,  you  may,  after  initializing  the  door,  call  the
          function that  opens the  system file.  Keep track  of  any  time
          credits  during  the  door  programs  operation,  then  call  the
          function that  updates the BBS system file. Examples of how to do
          this are included in the sample program.


































                                       Page 16



          GAPQBDR       (C) Copyright 1988-1993 The GAP Development Company


                                  GLOBAL VARIABLES
                                  ----------------

          All global variables (except for constants) are defined as COMMON
          SHARED. They  are included  in your program by including the file
          GAPQBDR.BI at the top of your source file.


          CONSTANTS
          ---------

          Constants are defined as - CONST name = constant value.

          NO                  Defined as 0
          YES                 Defined as 1

          ANSI CONSTANTS
          --------------

          ANSI constants contain the actual ANSI color sequences.

          BLACK               ANSI codes for Black
          BLUE                ANSI codes for Blue
          BROWN               ANSI codes for Brown
          CYAN                ANSI codes for Cyan
          GREEN               ANSI codes for Green
          MAGENTA             ANSI codes for Magenta
          RED                 ANSI codes for Red
          WHITE               ANSI codes for White

          BBLACK              ANSI codes for Grey
          BBLUE               ANSI codes for bright Blue
          BCYAN               ANSI codes for bright Cyan
          BGREEN              ANSI codes for bright Green
          BMAGENTA            ANSI codes for bright Magenta
          BRED                ANSI codes for bright Red
          BWHITE              ANSI codes for bright White
          YELLOW              ANSI codes for Yellow













                                       Page 17



          GAPQBDR       (C) Copyright 1988-1993 The GAP Development Company


          DOOR.SYS VARIABLES
          ------------------

          DOOR.SYS  variables   are  initialized  while  reading  the  Door
          Interface Module,  DOOR.SYS. These  variables are  available from
          door start  up to  door end.  The DOOR.SYS variables are the door
          programmer's connection to the BBS.


          INTEGERS
          --------

          alarm               Caller Alarm. 0 = off, 1 = on
          bell                Page Bell. 0 = off, 1 = on
          c.olor              Color toggle. 0 = no color, 1 = color ok
          expert              Expert mode. 0 = non-expert, 1 = expert
          l.ocal              0 = remote user, 1 = local
          level               User's security level
          minsleft            Number of minutes user has left at door start
          node                Node number. 0 = single user
          page                User's page length
          parity              Should actually be data bits and is not used
          port                Communications port in use
          printer             Printer Toggle. 0 = off, 1 = on
          s.creen             Screen display. 0 = off, 1 = on

          LONGS
          -----

          baud                DTE rate to open COMM port at
          downbytes           Total bytes downloaded
          downloads           Number of downloads
          maxbytes            Maximum number of bytes allowed to download
          recnum              User's record number in USER file
          timeson             Number of times user has been on
          upbytes             Total bytes uploaded
          uploads             Number of uploads
          userbaud            BPS rate of the remote user

          STRINGS
          -------

          bphone              User's business or data phone number
          city                User's home town
          first               User's first name
          hphone              User's home phone number
          last                User's last name
          lastdate            Last date user was on



                                       Page 18



          GAPQBDR       (C) Copyright 1988-1993 The GAP Development Company


          password            User's password. PASSWORD if sysop is on
          subscrip            Date user's subscription expires
          username            User's full name


          GAPQBDR GLOBALS
          --------------

          These variables are the documented, global variables (initialized
          and used  by GAPQBDR).  They may  be modified  and/or used at the
          programmer's discretion.


          INTEGERS
          ---------

          noup                If set to 1, get.string will not uppercase
          timecredit          Time credits for user (in minutes)
          timeleft            Time user has left (in minutes)

          LONGS
          -----

          starttime           Time the user logged on (in seconds)
          temptime            For calculating keyboard time out
          timenow             Time it is now  (in seconds)

          STRINGS
          -------

          anystring1          Global garbage collector
          bbs.dir             Path to BBS default dir
          birthday            Callers birth date
          board.name          Name of the BBS
          gendir              Path to the gen directory
          maindir             Path to the main directory
          sysname             Sysop's name














                                       Page 19



          GAPQBDR       (C) Copyright 1988-1993 The GAP Development Company


                      GLOBAL VARIABLES - ALPHABETICALLY By Type
                      -----------------------------------------

          CONSTANTS
          ---------

          BBLACK              ANSI codes for Grey
          BBLUE               ANSI codes for bright Blue
          BCYAN               ANSI codes for bright Cyan
          BGREEN              ANSI codes for bright Green
          BLACK               ANSI codes for Black
          BLUE                ANSI codes for Blue
          BMAGENTA            ANSI codes for bright Magenta
          BRED                ANSI codes for bright Red
          BROWN               ANSI codes for Brown
          BWHITE              ANSI codes for bright White
          CYAN                ANSI codes for Cyan
          GREEN               ANSI codes for Green
          MAGENTA             ANSI codes for Magenta
          NO                  Defined as 0
          RED                 ANSI codes for Red
          WHITE               ANSI codes for White
          YELLOW              ANSI codes for Yellow
          YES                 Defined as 1

          INTEGERS
          --------

          alarm               Caller Alarm. 0 = off, 1 = on
          bell                Page Bell. 0 = off, 1 = on
          c.olor              Color toggle. 0 = no color, 1 = color ok
          expert              Expert mode. 0 = non-expert, 1 = expert
          l.ocal              0 = remote user, 1 = local
          level               User's security level
          minsleft            Number of minutes user has left at door start
          node                Node number. 0 = single user
          noup                1 = get.string will not uppercase
          page                User's page length
          parity              Should actually be data bits and is not used
          port                Communications port in use
          printer             Printer Toggle. 0 = off, 1 = on
          s.creen             Screen display. 0 = off, 1 = on
          timecredit          Time credits for user (in minutes)
          timeleft            Time user has left (in minutes)







                                       Page 20



          GAPQBDR       (C) Copyright 1988-1993 The GAP Development Company


          LONGS
          -----

          baud                DTE rate to open COMM port at
          downbytes           Total bytes downloaded
          downloads           Number of downloads
          maxbytes            Maximum number of bytes allowed to download
          recnum              User's record number in USER file
          starttime           Time the user logged on (in seconds)
          temptime            For calculating keyboard time out
          timenow             Time it is now  (in seconds)
          timeson             Number of times user has been on
          upbytes             Total bytes uploaded
          uploads             Number of uploads
          userbaud            BPS rate of the remote user

          STRINGS
          -------

          anystring1          garbage collector
          bbs.dir             Path to BBS default dir
          birthday            Callers birth date
          board.name          Name of the BBS
          bphone              User's business or data phone number
          city                User's home town
          first               User's first name
          gendir              Path to the gen directory
          hphone              User's home phone number
          last                User's last name
          lastdate            Last date user was on
          maindir             Path to the main directory
          password            User's password. PASSWORD if sysop is on
          subscrip            Date user's subscription expires
          sysname             Sysop's name
          username            User's full name
















                                       Page 21



          GAPQBDR       (C) Copyright 1988-1993 The GAP Development Company


                     FUNCTIONS AND SUBROUTINES - QUICK REFERENCE
                     -------------------------------------------

          a.ccess%            Checks for the existence of a file.
          ansi                Displays ANSI escape sequences.
          backspace           Sends one or more backspaces.
          ckeypress%          Checks for a remote or local key press.
          clear.scr           Clears the local and remote screens
          do.chat             To allow sysop to chat with remote user.
          elap.time           Computes elapsed time.
          get.string          Gets a string of characters.
          get.time&           Returns number of seconds since 01/01/70.
          getakey%            Gets one key responses.
          getrand%            Returns a random number.
          init.door           Initializes the Door.
          leave               Shuts down door and returns to the BBS.
          more                Checks for a full screen.
          nl                  Sends a CR/LF to local and remote.
          no.carrier          Prints a message if carrier lost.
          pagesysop           Alerts sysop that the user wants to chat.
          pause               Sends a "Press [Any Key] To Continue" prompt.
          putachar            Sends a single character.
          putkey              Used by chat for word wrapping.
          read.cnf            Reads the door configuration file.
          read.doorsys%       Reads DOOR.SYS.
          read.gapuser%       Reads USERS.DAT.
          read.pcbuser%       Reads PCB USERS file.
          read.score%         Reads and displays the scoreboard.
          right.trim$         Trims spaces from string.
          set.status          Displays status line.
          show.file           Displays text files.
          show.mess           Displays a message.
          time.credit         Gives credits for time used.
          time.left           Computes time remaining.
          update.clock        Updates status line clock.
          waitasec            Pauses for x number of seconds.
          wrap.word           Wraps a word.
          write.gapuser%      Writes USERS.DAT.
          write.pcbuser%      Writes PCB USERS.
          write.score         Creates and maintains the scoreboard.











                                       Page 22



          GAPQBDR       (C) Copyright 1988-1993 The GAP Development Company


                        FUNCTIONS AND SUBROUTINES - REFERENCE
                        -------------------------------------


          Functions always  return a value. The type of the return value is
          denoted by  the type  modifier after  a function name. The return
          value should  be assigned  to a  variable of  the same  type. For
          instance, the  function get.time&  returns a long integer. To re-
          trieve the return value, assign it to an long integer as :

               long.int& = get.time&

          Subroutines do  not return a value. To call a subroutine, use the
          Basic CALL function :

               call get.string





          a.ccess%
          -----------------------------------------------------------------

          Purpose       Checks for the existence of a file.

          Parameters    Full path and name of file

          Return Value  0 = file was found, 1 = file not found

          Description   In order  to avoid  Basic errors  that  occur  when
                        trying to  open a  file that  does not  exist, this
                        function should be used prior to opening any file.

          Example

             r% = access%("GAPQBDR.DOC")
             if r% <> 0 then
               call show.mess("Can't Find GAPQBDR.DOC",NO,YES)
             end if











                                       Page 23



          GAPQBDR       (C) Copyright 1988-1993 The GAP Development Company


          ansi
          -----------------------------------------------------------------

          Purpose       Displays ANSI escape sequences

          Parameters    ANSI color to display

          Return Value  None

          Description   This function  will send  a string  of ANSI  escape
                        sequences to  the remote  user  and  to  the  local
                        console. The  ANSI codes for the various colors are
                        defined as constants in the GAPQBDR.BI file. If the
                        remote or  local user  is in non graphics mode, the
                        function returns immediately.

          Example       call ansi(BWHITE)



          backspace
          -----------------------------------------------------------------

          Purpose       Sends one or more backspaces

          Parameters    Number of backspaces to send

          Return Value  None

          Description   In order  to actually  erase  a  character  on  the
                        screen, you  must send a 3 character sequence which
                        consists  of   backspace,  space,  backspace.  This
                        function will  send as  many of  these 3  character
                        sequences as you specify in the parameter list.

          Example       call backspace(1)

             str$ = "Press Any Key "      ' set up string
             call show.mess(str$,NO,NO)   ' show string
             c% = getkeyc%                ' get a key
             call backspace(len(str$))    ' erase string










                                       Page 24



          GAPQBDR       (C) Copyright 1988-1993 The GAP Development Company


          ckeypress%
          -----------------------------------------------------------------

          Purpose       Checks for a remote or local key press

          Parameters    None

          Return Value  0 = no key is waiting, 1 = a key is waiting

          Description   This function will check the local keyboard as well
                        as the  communications receive  buffer to  see if a
                        key is waiting to be read. It is most often used in
                        loops that need to receive a 1 character keystroke.

          Example       c% = ckeypress%   ' key pressed?

             c% = 0                       ' initialize
             do
                |                         ' do something
                |
                c% = ckeypress%           ' key pressed?
             until c% <> 0                ' key pressed,exit


          clear.scr
          -----------------------------------------------------------------

          Purpose       Clears local and remote screens.

          Parameters    None

          Return Value  None

          Description   This routine  will call  CLS23 to  clear the  local
                        screen. If  the remote caller is in non-color mode,
                        it sends a CHR$(12) to the remote screen, otherwise
                        it sends the ANSI clear screen sequence.

          Example       call clear.scr    ' clear screen












                                       Page 25



          GAPQBDR       (C) Copyright 1988-1993 The GAP Development Company


          do.chat
          -----------------------------------------------------------------

          Purpose       To allow sysop to chat with remote user

          Parameters    None

          Return Value  None

          Description   This function  allows a  one on one chat with a re-
                        mote user.  If the  caller is in graphics mode, the
                        sysop's key  presses will be displayed in green and
                        the remote  user's key presses will be displayed in
                        white. Text  will automatically  wrap at column 76.
                        To exit  chat, press  either the  ESC key or type a
                        CTRL-X. Note  that the  user may  also  send  these
                        characters to  end chat. The user will receive full
                        credit for  the time spent chatting with the sysop.
                        However, this  function will  not  update  the  BBS
                        system file  so it is possible that the user may be
                        logged off  (with an  out  of  time  message)  when
                        he/she returns to the BBS.

          Example       call do.chat

             response$ = " "              ' initialize
             call get.string(response$)   ' get a string
             if response$ = "P" then      ' paging sysop
               call do.chat               ' chat with sysop
             end if





















                                       Page 26



          GAPQBDR       (C) Copyright 1988-1993 The GAP Development Company


          elap.time
          -----------------------------------------------------------------

          Purpose       Computes elapsed  time while  waiting for  keyboard
                        input

          Parameters    None

          Return Value  None

          Description   This function  is used  in loops  that await a key-
                        board response.  Prior to  entering the  loop,  the
                        variable called temptime should be initialized with
                        the  current  time.  Once  inside  the  loop,  this
                        function should  be called  to keep  track  of  the
                        elapsed time.  If there  is  no  keyboard  response
                        within 4 minutes, the user will be logged off.



          Example       call elap.time

             temptime& = get.time&        ' start timer
             do
               gc = getakey%              ' get a key
               if gc <> 0 then            ' key pressed
                 exit do                  ' exit and process
               end if
               call elap.time             ' activity?
             loop                         ' continue





















                                       Page 27



          GAPQBDR       (C) Copyright 1988-1993 The GAP Development Company


          get.string
          -----------------------------------------------------------------

          Purpose       Gets a string of characters

          Parameters    String to fill

          Return Value  None

          Description   This is  the main  input routine.  It  will  get  a
                        string from  either the  remote user  or the  local
                        keyboard. The  string passed  will be  set  to  the
                        characters received. The length of the input string
                        is determined  by the  length of the string passed.
                        Do not pass a fixed length string to this routine.

                        Before calling,  you  must  initialize  the  passed
                        string with  spaces. The  number of  spaces in  the
                        string determines  the number of characters allowed
                        to be  input. If  a  user  attempts  to  type  more
                        characters than  allowed, the  cursor will not move
                        pass the  end of  the string.  Input ends  when the
                        Enter key is pressed.

                        To initialize  the string,  use  the  Basic  space$
                        function (IE,  input$ =  space$(10)  -  initializes
                        input$ to 10 spaces).

                        WARNING : It is extremely important that the passed
                        string be initialized. Failure to set the string to
                        spaces, will cause unpredictable results!

                        This function  does not  return a  new string  con-
                        taining the  keyboard input.  Instead, it  modifies
                        the string  you pass  to it  in the parameter list.
                        The string will be stripped of any trailing spaces.

                        get.string automatically  uppercases the string. If
                        you wish  to disable this feature, set the variable
                        noup to 1.

                        get.string will  automatically check  for  keyboard
                        activity so it is not necessary for you to do so.

          Example

             instr$ = space$(10)          ' initialize
             call get.string(instr$)      ' get string



                                       Page 28



          GAPQBDR       (C) Copyright 1988-1993 The GAP Development Company


          get.time&
          -----------------------------------------------------------------

          Purpose       Gets the number of seconds elapsed since 01/01/70

          Parameters    None

          Return Value  Number of seconds since 01/01/70

          Description   This routine  is equivalent  to the  C time() func-
                        tion. It  is used  throughout the GAPQBDR module to
                        compute various  times. This  function is  not sus-
                        ceptible to  the  midnight  roll  over  problem  so
                        prevalent in Basic communications programs.

                        Note that  the Return  Value is  of type  LONG. You
                        must cast  the Return  Value to  a LONG  INTEGER or
                        loss of significant digits will result.

          Example

             dim ltime as long            ' declare as long

             ltime = get.time&            ' get the time

             ' if you don't like declaring variables, you can
             ' do it the old fashioned way

             longtime& = get.time&        ' get the time






















                                       Page 29



          GAPQBDR       (C) Copyright 1988-1993 The GAP Development Company


          getakey%
          -----------------------------------------------------------------

          Purpose       Gets one key responses

          Parameters    None

          Return Value  ASCII code for the key pressed or 0

          Description   This is the main keyboard input routine (internal).
                        It is  called by get.string as well as any keyboard
                        polling loops. It checks the receive buffer as well
                        as the  local keyboard  for a  key press. If one is
                        not found  it returns 0. The character input is not
                        echoed. Since  99% of all keyboard input comes from
                        this  routine,   it  checks   for   carrier,   time
                        remaining, keyboard  time-out, as  well as  special
                        sysop function  keys. The  "timeleft"  variable  is
                        updated via  this routine. This is the variable you
                        would normally use in a prompt such as,

                                   [20 mins left] Main Command :

          Example       c% = getakey



























                                       Page 30



          GAPQBDR       (C) Copyright 1988-1993 The GAP Development Company


          getrand%
          -----------------------------------------------------------------

          Purpose       Gets a random number

          Parameters    Low number, high number

          Return Value  A random number

          Description   This routine  is provided because it is much easier
                        to use and understand than Basic's random function.
                        Provide  as  parameters  two  integers.  The  first
                        parameter is the lowest number you will accept as a
                        random number,  and the  second  parameter  is  the
                        highest random number you will accept. The function
                        will return  a random  integer  between  the  range
                        specified (low  and high  are included in the range
                        of numbers). It is not necessary to seed the random
                        number generator  as this is done automatically for
                        you during program initialization.

          Example

             ' get a random number between 1 and 10

             rndnum% = getrand% (1,10)

























                                       Page 31



          GAPQBDR       (C) Copyright 1988-1993 The GAP Development Company


          init.door
          -----------------------------------------------------------------

          Purpose       Initializes the GAPQBDR functions

          Parameters    None

          Return Value  None

          Description   This  routine  must  be  called  immediately  after
                        calling read.cnf.  It initializes  the door,  opens
                        and reads  system files, initializes the comm port,
                        initializes global  variables and in general, makes
                        sure that  all of  the files required for operation
                        are present.  There is no Return Value. If an error
                        occurs while  trying to  initialize,  the  function
                        will display an error message and end the program.

          Example

             call read.cnf("DOOR.CFG")    ' read config file
             call init.door               ' init the door


          leave
          -----------------------------------------------------------------

          Purpose       Exits the program

          Parameters    None

          Return Value  None

          Description   When the  program terminates,  it  must  call  this
                        function to  end. This is the ONLY proper exit from
                        the door.

          Example       call leave













                                       Page 32



          GAPQBDR       (C) Copyright 1988-1993 The GAP Development Company


          more
          -----------------------------------------------------------------

          Purpose       Checks for a full screen and issues a More Prompt

          Parameters    None

          Return Value  None

          Description   This is  an internal  routine that is called by the
                        character output functions.

          Example



          nl
          -----------------------------------------------------------------

          Purpose       To send  a Carriage  Return and  Line Feed to local
                        and remote

          Parameters    Number of New Line's to send

          Return Value  None

          Description   To send  a blank  line, call  this routine with the
                        number of blank lines you wish to send.

          Example       call nl(2)        ' send two blank lines





















                                       Page 33



          GAPQBDR       (C) Copyright 1988-1993 The GAP Development Company


          no.carrier
          -----------------------------------------------------------------

          Purpose       Prints a message and calls leave()

          Parameters    None

          Return Value  None

          Description   Internal routine  that is  called when  there is  a
                        loss of  carrier. Displays  a message  to the local
                        screen  and  then  calls  leave  to  terminate  the
                        program.

                        If you  have a  routine that checks for carrier and
                        you wish  to  display  the  standard  "No  Carrier"
                        message and log the user off, call this function.

          Example       call no.carrier



          pagesysop
          -----------------------------------------------------------------

          Purpose       Alerts sysop that user wants to chat

          Parameters    None

          Return Value  None

          Description   Allows the  programer to  provide the  user with  a
                        Page Sysop  command. The  page lasts for 30 seconds
                        and can be aborted by typing CTRL K. If the sysop's
                        page bell  is on,  the sysop's  speaker  will  also
                        sound. To  answer the  page, the sysop should press
                        CTRL F10.

          Example

             response$ = " "              ' initialize var
             call get.string(response$)   ' wait for a key
             if response$ = "P" then      ' wants to chat
               call pagesysop             ' tell sysop
             end if






                                       Page 34



          GAPQBDR       (C) Copyright 1988-1993 The GAP Development Company


          pause
          -----------------------------------------------------------------

          Purpose       Sends a "Press [Any Key] To Continue" prompt

          Parameters    None

          Return Value  None

          Description   This function  sends a pause prompt and waits for a
                        key press.

          Example

             call nl(1)                   ' send blank line
             call pause                   ' wait for a key


          putachar
          -----------------------------------------------------------------

          Purpose       Send a single character to local and remote

          Parameters    ASCII character to send

          Return Value  None

          Description   This routine  is called  a "semi-unfiltered"  char-
                        acter output  routine because  it allows  for  most
                        ASCII characters to be output.

          Example

             c% = ASC("A")                ' send an 'A'
             call putachar(c%)            ' to local and remote screen

             c% = getakey%                ' get a keypress
             if (c% <> 0 then             ' if we got a key
               call putachar(c%)          ' display the
             end if                       ' character











                                       Page 35



          GAPQBDR       (C) Copyright 1988-1993 The GAP Development Company


          putkey
          -----------------------------------------------------------------

          Purpose       Used  by  chat  routines  to  keep  track  of  word
                        wrapping

          Parameters    Character to send

          Return Value  None

          Description   This is  the  main  output  routine  for  the  chat
                        functions. It  keeps track  of the  current column,
                        and decides  when it  is time  to wrap  a word.  It
                        should not  be called  by the programmer's routines
                        since putachar is faster and more efficient.

          Example


































                                       Page 36



          GAPQBDR       (C) Copyright 1988-1993 The GAP Development Company


          read.cnf
          -----------------------------------------------------------------

          Purpose       To read the door configuration file

          Parameters    Full path and file name to the configuration file.

          Return Value  None

          Description   Opens the  configuration file for the current door.
                        Normally the  passed parameter  is the  name of the
                        door with  a .CNF extension (it is assumed that the
                        file is in the same directory as the door program).
                        If an error occurs, the program ends immediately.

                        The first  line of  the file is the path to the BBS
                        default directory.  The second  line is the name of
                        the BBS. The third line is the Port IRQ and the 4th
                        line is the Port Base Address. If the sysop running
                        your program  has his  BBS configured  to  use  Com
                        Ports other  than 1  or 2,  he would then enter the
                        IRQ and  Base address  for his  Com Port on lines 3
                        and 4.  GAPQBDR derives  the Port  Number from  the
                        DOOR.SYS file.

                        Lines five  through eight  are for  the Intelligent
                        DigiBoard  multi-port   Communications  Card.   The
                        DigiBoard routines  specifically support the COM/Xi
                        series. All  four of  these lines are required even
                        if your end users are using the Standard Interface.
                        Line five  is the Communications Port Interface. It
                        must be one of the following:

                                   STANDARD  DIGIBOARD INT14/EBIOS

                        The  Standard   interface  is  the  one  that  will
                        normally be  used.  If  an  end  user  is  using  a
                        DigiBoard then  either the DigiBoard or Int14/EBIOS
                        interface may be selected. Most sysops will use the
                        Int14/EBIOS  interface.  All  input/output  to  the
                        DigiBoard is performed via Interrupt 14 calls and a
                        Device Driver  (available from  DigiBoard)  handles
                        the interface  between the  program and  the board.
                        The DigiBoard  interface uses  Direct  Programming.
                        GAPQBDR talks  to the  board directly  without  the
                        need for  a Device  Driver. In  order to  use  this
                        interface, a  program called  RESETDIG.EXE must  be
                        used  in   the  AUTOEXEC.BAT   file  to  reset  the



                                       Page 37



          GAPQBDR       (C) Copyright 1988-1993 The GAP Development Company


                        DigiBoard once  when the  computer is first booted.
                        If the end user does not have this program (it is a
                        part of  the GAP  Communications BBS  package) then
                        the Int14/EBIOS interface must be used.

                        If the Interface is other than STANDARD, then lines
                        6 through  8 will  be ignored.  If the Interface is
                        INT14/EBIOS, then lines 6 and 7 will be ignored.

                        Line 6  is the  DigiBoard  Memory  Window,  or  the
                        address the  board uses  as a  communications  area
                        between itself  and the Host Computer. This line is
                        used only  if the Interface is set to DIGIBOARD. It
                        can be  set to  0 if  the Interface  is STANDARD or
                        INT14/EBIOS.

                        Line 7 is the DigiBoard I/O Port Address. This line
                        is used  only if  the Interface is set to DIGIBOARD
                        and can be set to 0 otherwise.

                        Line 8  is the  DigiBoard Channel Number. This line
                        is  required  for  the  DIGIBOARD  and  INT14/EBIOS
                        Interfaces. It  is normally 1 - 8 for the DIGIBOARD
                        Interface and 4 - 11 for the INT14/EBIOS Interface.
                        The Channel  Number is similar to a Port Number. It
                        tells  the   program   which   of   the   DigiBoard
                        Communications ports to use.

                        It is  the responsibility  of the  door  author  to
                        describe the format of these eight lines to the end
                        user. It  is also  the responsibility  of the  door
                        author to insure that the end user have these eight
                        lines in  the door configuration file. If your door
                        program requires no configuration parameters of its
                        own, you  can simply distribute a sample "door".cnf
                        file with these eight lines already in it.

                        GAPQBDR will  NOT close  this file  (file #1) after
                        reading the  first eight  lines. It leaves the file
                        open for  the programmer's  use. If  your door does
                        require certain configuration parameters, have your
                        users place  the parameters  in the  file  starting
                        with line  9. If  you use a set up program, be sure
                        that your  set up  program writes  the first  eight
                        lines as specified.

                        After you  have called  read.cnf and  init.door, if
                        you  have   any  configuration   options   in   the



                                       Page 38



          GAPQBDR       (C) Copyright 1988-1993 The GAP Development Company


                        "door".cnf file,  you should  line input  those op-
                        tions. Then  close file  #1. Even  if you  have  no
                        options to read, close the file.

                        WARNING :  You MUST  call this routine before using
                        any of  the GAPQBDR  functions. After  calling this
                        routine, you MUST call init.door.

          Example

             call read.cnf("TOURIST.CNF")
             call init.door


          read.doorsys%
          -----------------------------------------------------------------

          Purpose       Reads the DOOR.SYS universal door interface file

          Parameters    None

          Return Value  0 = no error, 1 = error

          Description   Internal routine  called by  init.door.  Reads  the
                        DOOR.SYS file  and initializes any global variables
                        that depend on the information in that file.

          Example       c% = read.doorsys%



          read.gapuser%
          -----------------------------------------------------------------

          Purpose       Reads the GAP Communications USERS.DAT file

          Parameters    None

          Return Value  0 = no error, 1 = error

          Description   Reads the  user record  of the  current user in the
                        GAP  USERS.DAT   file.  The  record  variables  are
                        contained in a variable called user.

          Example       c% = read.gapuser%






                                       Page 39



          GAPQBDR       (C) Copyright 1988-1993 The GAP Development Company


          read.pcbuser%
          -----------------------------------------------------------------

          Purpose       Reads the PCB USERS file.

          Parameters    None

          Return Value  0 = no error, 1 = error

          Description   This function  will read  the PCB  Users record for
                        the user currently in the door.

          Example       c% = read.pcbuser%



          read.score%
          -----------------------------------------------------------------

          Purpose       Reads and displays the top 10 player file.

          Parameters    Filename to read, message to display.

          Return Value  0 = ok, 1 = file not found

          Description   This  function   reads  the   scoreboard  file  and
                        displays it  to  the  caller.  Pass  as  the  first
                        parameter, the  name of  the scoreboard  file.  The
                        second parameter  is a  string to  display prior to
                        showing the actual scores.

          Example

             c% = read.score% ("SCORE.DAT","Top 10 Players")
             if c% = 1 then
               call show_mess("No winners yet!",NO,YES)
             end if














                                       Page 40



          GAPQBDR       (C) Copyright 1988-1993 The GAP Development Company


          right.trim$
          -----------------------------------------------------------------

          Purpose       Trims  spaces  from  the  end  of  NULL  terminated
                        strings

          Parameters    String containing the spaces.

          Return Value  String without the spaces.

          Description   This function  will remove  the NULL  and trim  any
                        spaces from the right end of any 'C' string.

          Example       username$ = right.trim$(user.fname)



          set.status
          -----------------------------------------------------------------

          Purpose       To display and update the sysop status line

          Parameters    0 =  set the  status line,  1 =  update the  status
                        line, 4 = show other user stats

          Return Value  None

          Description   This routine is used internally. There should be no
                        reason to call it unless you have modified a user's
                        stats and  you need  to update  those stats  on the
                        status line. In this case, you should use option 0.

          Example       call set.status(0)


















                                       Page 41



          GAPQBDR       (C) Copyright 1988-1993 The GAP Development Company


          show.file
          -----------------------------------------------------------------

          Purpose       To display a text file

          Parameters    The full path and file name to the file to be shown

          Return Value  None

          Description   Many door  programs have  welcome, news, exit, help
                        and other  files to  show to  the user  at  various
                        points in  the program.  This is  the function that
                        allows you to do that. This function tries to be as
                        intelligent as  it possibly  can in determining the
                        sysop's wishes. To display a file to the user, call
                        the function  with the  full drive\path\filename of
                        the file to display.

                        If you  have color  and non-color versions of files
                        pass the  name of  the non-color  version  as  this
                        function will  automatically append  a "G"  to  the
                        filename if  the user  is in  color mode.  In fact,
                        this function will ALWAYS try to find a file with a
                        "G" appended to the end of the name (if the user is
                        in color  mode) before it looks for the actual file
                        by the  name you  specified. If you pass "WELCOMEG"
                        to this  function and the user is in color mode, it
                        will first  try to  find a  file with  the name  of
                        "WELCOMEGG".

                        As with  GAP Communications,  your text  files  can
                        have  certain   control  characters  as  the  first
                        character in  the file. A "{" signals that the more
                        prompt  should   never  display.  In  other  words,
                        GAPQBDR will  not keep track of the number of lines
                        displayed and  will never issue a more prompt. This
                        is useful  for very  long ANSI files. A "@" signals
                        that the  pause prompt should be displayed when the
                        screen is  full instead  of a  more prompt. This is
                        very handy  when you  want the user to see the file
                        in its  entirety. The  user will  not be allowed to
                        break out of the file read.

                        WARNING :  The "{"  or "@"  MUST appear as the VERY
                        first character  in the  file. If  you use  an ANSI
                        editor, be aware that the first few characters in a
                        file will  usually be  an ANSI  color sequence. You




                                       Page 42



          GAPQBDR       (C) Copyright 1988-1993 The GAP Development Company


                        normally have  to edit  the file with a text editor
                        to insert the control character.

                        Because QB  4.x is  EXTREMELY slow when it comes to
                        function calls,  all input  and output  is done "in
                        line". Despite QB's high overhead, this function is
                        pretty fast.

                        GAPQBDR does  not have  the ability  to protect the
                        status line. Because of this, it is possible for an
                        ANSI file that contains clear screen codes to erase
                        the status  line. At  the end  of the function, the
                        status line  will be  re-drawn just  in case. Since
                        most ANSI  files contain  the clear screen codes at
                        the beginning  of the  file, show.file  will remove
                        any such codes during the first read of the file.

                        Pressing CTRL  K or  CTRL X  will  abort  any  file
                        display if the file does not begin with a "@".

                        REMEMBER :  If you  have both  color and  non-color
                        versions of  the same  files, pass  the name of the
                        non-color version. Also, the actual disk files must
                        be named  in such  a way  that they  have  no  file
                        extension and the color version ends with a "G".

          Example       call show.file("WELCOME")

             call show.file("C:\GAP\GEN\WELCOME")






















                                       Page 43



          GAPQBDR       (C) Copyright 1988-1993 The GAP Development Company


          show.mess
          -----------------------------------------------------------------

          Purpose       Displays a message

          Parameters    Message, ring the bell, issue a New Line

          Return Value  None

          Description   Finally!   After all  of this, just how do you dis-
                        play a message to the user?  Well, here it is. This
                        is the  string output  function for  GAPQBDR. Under
                        most circumstances,  this is  the one function that
                        you would call to display output to the user. There
                        should  be   no  reason  to  ever  call  putkey  or
                        putachar, as they are basically internal routines.

                        There should  be no  reason to  EVER use  the Basic
                        print statement  unless you  need to display a mes-
                        sage to  the local  screen that you do not want the
                        remote user  to see.  In other  words,  ALL  string
                        output should  be done  through this  function.  If
                        there is a reason to display information locally it
                        would be  much easier  and more  efficient to  keep
                        track of  the l.ocal  variable, set  it to  1, call
                        show.mess with  the strings  to be  displayed, then
                        restore the  l.ocal variable to what it was before,
                        instead of  using the  print function  which cannot
                        display ANSI  sequences (forcing  you to  translate
                        ANSI codes to color statements).

                        The three parameters are :

                          1 - the string to display

                          2 - YES or NO if you want to sound the remote
                              user's bell.

                          3 - YES or NO if you want to issue a CR/LF after
                              displaying the string.











                                       Page 44



          GAPQBDR       (C) Copyright 1988-1993 The GAP Development Company


          Example

             ' the first show.mess displays the string and leaves the
             ' cursor on the same line. The second show.mess displays
             ' the string, rings the remote user's bell, and drops the
             ' cursor to the next line.

             call nl(1)
             call show.mess("Are you ready? (Y/N) : ",NO,NO)

             a$ = space$(3)
             call get.string(a$)

             if left$(a$,1) = "Y" then
               ' begin whatever it is you want to begin
             else
               call nl(1)
               call show.mess("Too Bad!",YES,YES)
             end if
































                                       Page 45



          GAPQBDR       (C) Copyright 1988-1993 The GAP Development Company


          time.credit
          -----------------------------------------------------------------

          Purpose       Keeps track  of time and credits the user with time
                        elapsed

          Parameters    1 = start timer, 0 = end timer

          Return Value  None

          Description   This is  basically an  internal routine  called  by
                        chat and sysop shell to DOS so that the user is not
                        penalized  for  time  used.  It  updates  a  global
                        variable called  timecredit. Timecredit  is used in
                        the calculations  that determine  the  user's  time
                        remaining.

                        If you  wish to  use this  feature in your own rou-
                        tines,  prior   to  entering   your  routine,  call
                        time.credit with  a 1  and it will start the timer.
                        When your  routine is  finished,  call  time.credit
                        with a  0 and  the timer  will stop.  The  variable
                        timecredit will be updated with the elapsed time.

          Example

             call time.credit(1)          ' start the timer
             call do.chat                 ' chat with user
             call time.credit(0)          ' stop the timer

             ' Note that this is simply an example. do.chat
             ' calls time.credit on its own. In the above
             ' example, if the sysop chat with the user took
             ' 10  minutes, the user will be credited with
             ' that 10 minutes as will be reflected in the
             ' timecredit variable.















                                       Page 46



          GAPQBDR       (C) Copyright 1988-1993 The GAP Development Company


          time.left
          -----------------------------------------------------------------

          Purpose       To compute the user's time remaining

          Parameters    None

          Return Value  None

          Description   This is the routine that is called by the input and
                        output  routines   to  compute   the  user's   time
                        remaining. It  is not  necessary for the programmer
                        to call this routine directly.

                        A global  variable called  timeleft will be updated
                        with each  call.  This  variable  may  be  used  in
                        prompts that display the user's remaining time.

                        As long as all input/output is performed thru calls
                        to the  GAPQBDR library, the timeleft variable will
                        always be current.

          Example       call time.left



          update.clock
          -----------------------------------------------------------------

          Purpose       Updates the status line clock

          Parameters    None

          Return Value  None

          Description   Internal routine to update the status line clock.

          Example













                                       Page 47



          GAPQBDR       (C) Copyright 1988-1993 The GAP Development Company


          waitasec
          -----------------------------------------------------------------

          Purpose       Pauses for the number of seconds specified.

          Parameters    Number of seconds to pause

          Return Value  None

          Description   This function  allows you  to pause  all processing
                        for the  specified number  of seconds.  It  is  in-
                        sensitive to  processor speed  and is immune to the
                        midnight rollover problem.

           Example      call waitasec(10) ' pause for 10 sec



          wrap.word
          -----------------------------------------------------------------

          Purpose       To wrap a word during sysop chats

          Parameters    None

          Return Value  None

          Description   Internal function called by putkey to wrap words.

          Example





















                                       Page 48



          GAPQBDR       (C) Copyright 1988-1993 The GAP Development Company


          write.gapuser%
          -----------------------------------------------------------------

          Purpose       Updates the user record in GAP's USERS.DAT file

          Parameters    None

          Return Value  0 = no error, 1 = error

          Description   This function allows you to update any variables in
                        the GAP USERS.DAT file for the current user.

                        WARNING :  The GAP  USERS.DAT file contains C char-
                        acter arrays. These are equivalent to Basic's fixed
                        length  strings  with  the  exception  that  the  C
                        strings have a NULL character (chr$(0)) in the last
                        position. If  you modify  any of these fixed length
                        strings, you  MUST make  sure that  the  string  is
                        fully  padded  with    spaces  and  that  the  NULL
                        character is  placed in  the last  string position.
                        When assigning  a value  to a  fixed length string,
                        Basic  will  automatically  pad  the  fixed  length
                        string with  spaces. All  the programmer need to is
                        insure that  the NULL is inserted at the end of the
                        string.

                        WARNING : The indexes for the user file consists of
                        the  user's  last  name,  first  name,  level,  and
                        handle.  Do  not  under  any  circumstances  modify
                        either of  these four  fields. Doing  so will cause
                        corruption of the Index file.

          Example

             ' Increase # of Files User has downloaded

             c% = read.gapuser%           ' 1st read record
             user.downloads = user.downloads + 2
             c% = write.gapuser%          ' update the record












                                       Page 49



          GAPQBDR       (C) Copyright 1988-1993 The GAP Development Company


          write.pcbuser%
          -----------------------------------------------------------------

          Purpose       Updates the PCB USERS file

          Parameters    None

          Return Value  0 = no error, 1 = error

          Description   This function  allows the  programmer to update the
                        PCB USERS  File. Note  that you  will need  to  use
                        MKSMBF on  the field  lastmsg, and  MKDMBF  on  the
                        fields downbytes and upbytes, if you modified these
                        fields since reading the file.

          Example       c% = write.pcbuser%  ' write the file



          write.score
          -----------------------------------------------------------------

          Purpose       Creates and maintains the scoreboard file.

          Parameters    Filename to write, score to write.

          Return Value  None

          Description   This function  will create and maintain a data file
                        of the  top 10  scores. You pass as parameters, the
                        name of the file to use as the scoreboard file, and
                        the score  to write.  The score  is a long integer.
                        The name  and date  are already  known. If the file
                        does not exist, it will be created.

          Example

             DIM score AS LONG

             score = 45600
             write.score("SCORE.DAT",score)










                                       Page 50



                                        INDEX
                                        -----

          @    42
          {    42
          A.ccess%  23
          ANSI 5, 7, 17, 20, 24, 42, 44
          Backspace 24
          Base address   9, 13, 37
          Bell 44
          Chat 5, 26, 34, 36, 46, 48
          Ckeypress%     25
          Clear.scr 25
          COMMAND$  10
          Communications
            base address 9, 13, 37
            configuration file     9, 13, 37
            IRQ     9, 13, 37
          Communications port 11
          Configuration file  10, 11
          Do.chat   26
          DOOR.SYS  9, 11, 13, 18, 22, 37
          Elap.time 27
          Error     8, 11, 23, 32, 37
          Files
            Aborting     43
            Color   42
            Configuration     11, 37
            DOOR.SYS     9, 13, 37, 39
            Errors  23
            Include 8, 11
            Opening 23
            PCB USERS    40
            Showing 42
            System  26, 32
            USERS.DAT    39, 49
          Functions 23
          Get.string     19, 26, 28, 30, 34, 45
          Get.time& 29
          Getakey%  30
          Getrand%  31
          Global Variables
            Constants
              ANSI
                BBLACK   17
                BBLUE    17
                BCYAN    17
                BGREEN   17
                BLACK    17
                BLUE     17
                BMAGENTA 17



                                       Page 51



                                        INDEX
                                        -----

                BRED     17
                BROWN    17
                BWHITE   17
                CYAN     17
                GREEN    17
                MAGENTA  17
                RED 17
                WHITE    17
                YELLOW   17
              General
                NO  17
                YES 17
            Integers
              DOOR.SYS
                alarm    18
                bell     18
                c.olor   18
                expert   18
                l.ocal   18
                level    18
                minsleft 18
                node     18
                page     18
                parity   18
                port     18
                printer  18
                s.creen  18
              General
                noup     19
                timecredit    19
                timeleft 19
            Longs
              DOOR.SYS
                baud     18
                downbytes     18
                downloads     18
                maxbytes 18
                recnum   18
                timeson  18
                upbytes  18
                uploads  18
                userbaud 18
              General
                starttime     19
                temptime 19
                timenow  19
            Strings
              DOOR.SYS



                                       Page 52



                                        INDEX
                                        -----

                bphone   18
                city     18
                first    18
                hphone   18
                last     18
                lastdate 18
                password 19
                subscrip 19
                username 19
              General
                anystring1    19
                bbs.dir  19
                board.name    19
                gendir   19
                maindir  19
                sysname  19
          Init.door 10, 11, 32, 39
          IRQ  9, 13, 37
          Leave     11, 32
          MKDMBF    50
          MKSMBF    50
          More 33
          New Line  33, 44
          Nl   33
          No.carrier     34
          Node 11
          Noup 28
          Pagesysop 34
          Pause     35, 48
          PCB USERS 22
          Putachar  35, 44
          Putkey    36, 44
          Read.cnf  9, 10, 11, 37
          Read.doorsys%  39
          Read.gapuser%  39
          Read.pcbuser%  40
          Read.score%    40
          Right.trim$    41
          Set.status     41
          Show.file 42
          Show.mess 24, 44
          Spaces
            Trimming     41
            USERS.DAT    49
          Status Line    5, 41, 43, 47
          String output  44
          Subroutines    23
          Time.credit    46



                                       Page 53



                                        INDEX
                                        -----

          Time.left 47
          Timecredit     46
          Timeleft  30, 47
          Trimming Spaces     41
          Update.clock   47
          USERS.DAT 22
          Waitasec  48
          Wrap.word 48
          Write.gapuser% 49
          Write.pcbuser% 50
          Write.score    50








































                                       Page 54