Doordriver version 3.00
By Scott Baker
With help from Derrick Parkhurst

IMPORTANT- Changes from previous version
----------------------------------------
You MUST call "InitDoorDriver('filename.ext')" in your program BEFORE any
doordriver features are activated. This is VERY important.
Doordriver is now distributed in two versions. DOORDRIV.TPU is the standard
version while DOORDRSM.TPU is the small version. The smaller one simply
excludes come of the less used features.

Introduction
------------
DoorDriver is a set of procedures for turbo pascal version 5.5 that allows
the easy creation of Door programs for various bbs types including
Rbbs-Pc, Pc-Board, WWIV, Phoenix, and many more types. The routines are
distributed in a .TPU file. They include fossil and BIOS based serial
I/O, High-level string input routines, and complete ANSI support.

Overview of routines
--------------------
The procedures included in the DoorDriver package can be categorized into
two main groups - Input and Output. The output routines consist of SWRITE()
and SWRITELN() which do the equivilant of the Turbo Pascal routines
WRITE() and WRITELN(). The input routines consist of SREAD(var s: string),
SREAD_NUM(var i: integer), SREAD_NUM_WORD(var w: word),
SREAD_NUM_BYTE(var b: byte), SREAD_NUM_LONGINT(l: longint), and
PROMPT(var s: string; length: integer; hilight: boolean). Also included
are routines for time-limit management, information filtering, advanced
menu systems, and much much more.

BBS-Software independence
-------------------------
DoorDriver will allow you to develop your software independent of whatever
bbs software the sysop is using. DoorDriver correctly loads the users info
from RBBS-PC, PCBOARD version 12, PHOENIX, QBBS, and WWIV with more
type coming soon (PCB v. 14 and WILDCAT). The users time-left is automatically
calculated and maintained by DoorDriver.


Configuration
-------------
New with doordriver version 3.0 is the use of a control file for
configuration. All configuration parameters are stored inside the control
file which may be edited with any ASCII editor.
The control file is loaded with a call to "InitDoorDriver()". This must
be done before any of doordrivers procedures, functions, or variables are
used.
A sample control file (DOORDRIV.CTL) is included. Your program can pick any
name it wants for the control file (i.e. NEWS.CTL, GALWAR.CTL, etc). Just
rename DOORDRIV.CTL to that filename and distribute it with your users so they
have a sample to work off of.
The record structure for the configurable editor (CFGEDITR.TPU) has been
modified. See edittest.pas for the new format.

Reference - Procedures
----------------------

INITDOORDRIVER(filen: string);
This procedure MUST BE CALLED before any of doordrivers features are
used in your program. The filename specifies the name of the control file
that your door will use to load it's parameters off of. (the /C option is
no longer used). InitDoorDriver parses the control file, loads the
bbs information, etc.

DISPLAYFILE(Filen: String);

This Procedure is usefull in that it will transfer an Ascii or Ansi
file, and will put "(C)ontinue,(S)top,(N)onstop" to stop an Ascii file
from scrolling of the page and thus allowing the user to read this file
at his or her own speed.


DISPLAY_MACRO(s: string);

This procedure is used to display a macro-string. The macro string is
usually contained in the variable MACRO_STRING.


PROMPT(var s: string; length: integer; hilight: boolean);

The prompt procedure is a high-level string input routine. It allows you
to specify the maximum length of the input string and if HILIGHT is set to
true, it will hilight the input in reverse background. The colors for the
prompt routine are defined in the configuration menu.


RECORD_MACRO(var s: string);

This procedure allows the user to record a macro string, up to 255
characters that will be invoked whenever the CTRL-N key is pressed. The
macro is stored in the string variable S. To activate the macro
capability, you must place the macro into the string variable
"MACRO_STRING".


SCLRSCR;

This procedure clears the remote side's and the local side's screen.


SET_FOREGROUND(i: integer);

The set_foreground procedure sets the current foreground color to the
one specified by the integer variable, i. The color is set both on the
local side and the remote side if the remote user has ANSI toggled on. The
acceptable range for the color is 0-15.


SET_BACKGROUND(i: integer);

The set_background procedure sets the current background color to the
one specified by the integer variable, i. The color is set both on the
local side and the remote terminal if the remote user has toggled his
ANSI on. The acceptable range for the color is 0-7.


SGOTO_XY(x,y: integer);

Sgoto_xy allows you to position the cursor on the local and remote
screen. The valid range for X is 1 to 80 and the valid range for Y
is 1 to 24.


SREAD_CHAR(var c: char);

This procedure waits for a character to be pressed and then returns that
character in the character variable. No echoing is performed (i.e. the user
will not see the key he pressed). If you wish echoing, you must again write
the character with SWRITE below. This routine is useful for writing your
own lowlevel readln routines or performing "hot-key" operations. It is
a direct replacement for CH:=READKEY.

SREAD(var s: string);

The sread procedure accomplishes the equivilant of the Turbo Pascal
procedure READLN. A string is read from the user and wher the CR character
is obtained, the procedure exits with the string stored in the string
variable, s.


SREAD_NUM(var i: integer);

The sread_num procedure is almost identical to the sread procedure except
it will read an integer variable instead of a string. Only the characters
0-9 are allowed to be entered by the user. The value returned will be in the
range of -32768 to +32768.


SREAD_NUM_BYTE(var b: byte);

The sread_num_byte procedure is almost identical to the sread procedure
except it will read an byte variable instead of a string. Only the
characters 0-9 are allowed to be entered by the user. The value returned
will be in the range of 0 to 255.


SREAD_NUM_WORD(var w: word);

The sread_num_word procedure is almost identical to the sread procedure
except it will read an word variable instead of a string. Only the
characters 0-9 are allowed to be entered by the user. The value returned
will be in the range of 0 to 65535.


SREAD_NUM_LONGINT(var l: longint);

The sread_num_longint procedure is almost identical to the sread procedure
except it will read an longint variable instead of a string. Only the
characters 0-9 are allowed to be entered by the user. The value returned
will be in the range of -2147483648 to +2147483647.


SWRITE(s: string);

The swrite procedure is the equivilant of the Turbo Pascal WRITE
procedure. Swrite will simultaniously write to both the local screen
and the remote terminal. No CR/LF sequence is added to the end of the
string.


SWRITELN(s: string);

The swriteln procedure is the equivilant of the Turbo Pascal WRITELN
procedure. Swrite will simultaniously write to both the local screen
and the remote terminal. A CR/LF sequence is appended to the end of
the string.


Reference - Functions
---------------------

SKEYPRESSED: Boolean;

This allows the program to pause until the user presses a key. When
used in a loop like this it stops everything until user input occurs.

Repeat Until skeypress;


TIME_LEFT: Byte;

The time_left function returns the amount of time left in minutes. The
time is computed internally by echodor and we need not be concerned about
it here.

Reference - Variables
---------------------

ANSION: boolean;

When the door gets loaded the bbs door info file specify's if the
current user has ansi on or not. It is then transfered into this variable.


BAUD_RATE: integer;

This variable holds the users current baud rate.

BBS_SOFTWARE: byte;

The following numbers indicate software names:

1 : Mach-10 BBS
2 : Rbbs-Pc
3 : Qbbs
4 : Pcboard-12
5 : WWIV
6 : Opus
7 : Rbbs 16.x
8 : Phoenix
9 : WildCat
10: Pcboard-14


BBS_TIME_LEFT: integer;

The users time left is transfered into this variable from the bbs.


BOARD_NAME: String[70];

Board_Name hold the current BBS's name that is set on the configuration
menu.


COM_PORT: byte;

Contains the current com port that the bbs is using.


CURRENT_FORGROUND: byte;

This variable stores the current foreground.


CURRENT_BACKGROUND: byte;

This variable stores the current background.


GRAPHICS: integer;

Graphics specifys a text mode:

1 : Ascii - General Text
2 : Ascii's Extended Graphics and General Text
3 : Ansi Color and Graphics
4 : Ansi Color and Graphics and Ansi Music (See Section on ANSI.TPU)


HELP_AR: Array[1..14] of string[80];

This array is displayed when the Sysop presses the Alt-H key. When
defining your own Alt-Key commands you will want to add in what each
Alt-Key does and here is where you do it.

---(See: Configurable Alt Key Section)---


IN_BUFFER: integer;

This allows you to change the input buffer. The larger the input buffer
the more memory it will consume. The default buffer size if 1024 bytes.


OUT_BUFFER: integer;

This allows you to change the output buffer. The larger the output
buffer the more memory it will consume. The default buffer size if
1024 bytes.


LOCAL: boolean;

This boolean is alway true if in local mode and false if in remote mode.


MINTIME: byte;

By allowing the sysops to set this up in your door you can set a minimum
time on the door.


MORECHK: boolean;

This boolean allows you to toggle the more prompts on or off. this is
especially useful when writing non-scrolling doors.


NODE_NUM: byte;

Returns the current Node that the door is running under. 0 represents
a single node system.


NOTIME: String;

When the users time limit has been reached this string will be
displayed then the user will be returned to the bbs. This string has a
default of "(***TIME LIMIT EXCEEDED***)".


PROC_PTR_AR: Array[1..26] of Pointer; (REMOVED IN SMALL VERSION)

This array stores all the Author definable Alt-Key Pointer addresses.

---(See: Configurable Alt Key Section)---


PROC_PTR_OnOff_AR: Array[1..26] of Pointer; (REMOVED IN SMALL VERSION)

This array tells weither or not all the Author definable Alt-Keys
are in use or not.

---(See: Configurable Alt Key Section)---


SAVE_SCREEN_CHAT: boolean; (REMOVED IN SMALL VERSION)

Save_Screen_Chat enables you save the current screen when the ALT-C
key is pressed and then enter into chat on a clear screen. then after
exiting chat it will redraw the screen in the condition that it was in
before chat. As you can see this might be useful for non-scrolling doors.


STACKED: string;

The Procedure sread and sreadln can have stacked commands which is when
a user type something in like this:

"m;101;m;102;m;103;m;104"

Notice the ";"'s throughout the example. well this is a stacked command.
the ";"'s indicate a seperate operation. This allows the user to type in
multiple operations to preform on one line and not have to go through each
and every prompt of the door. This can be very useful when used in combi-
nation with the Record_Macro command.


STATFORE: byte;

The status line foreground.


STATBACK: byte;

The status line background.


STATLINE: boolean;

A status line pops while any door is in operation if this boolean is
set true. The status line contains the user name and the program name an
the users time left.


SYSOP_FIRST_NAME: string[30];

Returns the first name of the sysop. The name is entered into door-driver
through the configuration menu.


SYSOP_LAST_NAME: string[30];

Returns the last name of the sysop. The name is entered into door-driver
through the configuration menu.


USER_FIRST_NAME: string[30];

Returns the first name of the current user of the door program. The
user's name is determined from whatever door information is passed from
the bbs software.


USER_LAST_NAME: string[30];

Returns the last name of the current user of the door program. The
user's name is determined from whatever door information is passed from
the bbs software.


USER_ACCESS_LEVEL: word;

Returns the access level of the user. The user's access level is
determined from whatever door information is passed from the bbs software.


FILTER: boolean; (REMOVED IN SMALL VERSION)

Toggles the sysop-filter. This option may be used as a toggle within
your program. The intent of the feature is to insure paranoid users that
the sysop is not viewing their game and using it to his own benefit. The
filter will scramble any numeric data that is displayed on the local
side. The option can be allowed by the sysop by setting the option in the
configuration menu. If the option in the configuration menu is set to true
the sysop can toggle the filter on and off with ALT-F, but an "!" will echo
remotely and the user will know you have toggled on or off. Authors may
install this option into there game by setting up an option in thier door
to toggle the filter TRUE or FALSE, otherwise the user cannot turn the
filter on or off.


PROGNAME: String[60];

This option must be set by the programmer, preferably in the beginning
of the door. It sets the name that will be displayed centered on line
25 of the screen. It is simply used for cosmetic purposes.


MACRO_STRING: string;

The contents of this variable are treated as a macro. Whenever the
user types a CTRL-N, the string will be output. The string may be
easily recorded with the RECORD_MACRO procedure and displayed with
the DISPLAY_MACRO procedure.


Referance - Types
-----------------

WINDOWAR = Array[1..23] of string[79]; (REMOVED IN SMALL VERSION)

WindowAr is used by the ReWindow unit to hold the windows text.


MEMORYAR = Array[0..3999] of byte; (REMOVED IN SMALL VERSION)

MemoryAr is used by the GetScreen and ReInitScreen routines.


Referance - Constants
---------------------

VERSION = 'Version 3.00; 6-21-90' (LARGE VERSION)
= 'Version 3.00S; 6-21-90' (SMALL VERSION)


Reference - Procedure Substitutions
-----------------------------------
This section is provided to help you in figuring out which doordriver
routines you should call to replace turbo's standard I/O routines.

char:=READKEY
replace with SREAD_CHAR(char)

WRITELN(string_variable)
replace with SWRITELN(string_variable)

WRITE(string_variable)
replace with SWRITE(string_variable)

WRITE/WRITELN(Char,integer,word,longint,real,etc)
you must use the appropriate SWRITE or SWRITELN command, but you
must first convert the data you are writing into a string variable.
(i.e. assuming "TEMPSTR" is a temporary string and "DATA" is youre
non-string data)

WORD/INTEGER/REAL/LONGINT CHAR

STR(data,tempstr); tempstr:=data;
SWRITE(tempstr); (or SWRITELN) SWRITE(tempstr); (or swriteln)

CLRSCR
replace with SCLRSCR

GOTOXY(x,y)
replace with SGOTO_XY(x,y)

READLN(string_variable)
replace with SREAD(string_variable)

READLN(integer_variable)
replace with SREAD_NUM(integer_variable)

READLN(word_variable)
replace with SREAD_WORD(word_variable)

READLN(longint_variable)
replace with SREAD_LONGINT(word_variable)



REFERENCE - Author Configurable Alt Key Section (REMOVED IN SMALL VERSION)
-----------------------------------------------

Contained in doordriver are routines that can be configured to accept
any authors routines. This allows authors to write up there own, Game
oriented, user editor that can be poped up by almost any alt-key.

The actual process is easy, all you need to do is write up a procedure
that you would like the sysop to be able to call up with an ALT-Key. This
procedure MUST BE A FAR PROCEDURE!! To make a normal procedure a Far
procedure you must put a "{$F+}" (without the quotes) before your
procedure and an "{$F-}" (again without the quotes) after your procedure.
After you have completed that and the procedure compiles you must modify
1 variable, PROC_PTR_AR.

PROC_PTR_AR is set in the following manor:

PROC_PTR_AR[1]:[email protected];

This tells DoorDriver that the ALT-A key is enabled. The Array for both
variables is set up in the manor that 1 is equal to ALT-A and 26 is equal
to ALT-Z.

After you have set your procedure up and running you may want to tell
the sysop that the procedure exists through the Help display which is
popped up localy by pressing ALT-H. Well, Only 7 lines of the help
display have so far been taken up, so that leaves you 14 more. These 14
more lines can be defined by setting HELP_AR. HELP_AR is an array of 14
strings. They will be displayed when ALT-H is hit.

Some of the letters are not definable because DoorDriver uses them,
such as:

ALT-H : HELP MENU
ALT-I : SYSTEM INFO
ALT-F : FILTER TOGGLE
ALT-C : CHAT MODE
ALT-D : DROP TO DOS

Remeber that when defining new procedure for Alt-Keys you MUST MAKE
THEM FAR (as explained above) and you must define where the procedures
are at the absolute beginning of your source code(as explained above).

Refer to example program "EDITTEST.PAS" which uses the template editor
to edit users when the ALT-E key is pressed. This Program will sit and
until you press any alt-keys or to quit press return. The template editor
is explained further allong in the document.


REFERENCE - ANSI MENU ROUTINES
------------------------------

There is an additional TPU file included with the doordriver package that
includes a user-friendly ANSI-MENU handler. The TPU can be called up with
the statement "USES ANSIMENU". The menu system is accessed by the
single function:

CHAR:=GetAnsiMenu(menu_definition_template)

The menu-definition-template type is declared within the unit. It is
identical to the structure below:


menutype = record
header: string[80];
footer: string[80];
headercolor, footercolor, optioncolor, desccolor, arrowcolor: byte;
bracketcolor: byte;
numoptions: byte;
options: array[1..20] of string[1];
desc: array[1..20] of string[80];
end;

The structure is usually defined by your program as a constant. The
ANSIMENU procedure interprets this strucure and uses it to generate
a centered menu. The menu options may be selected by using the numeric
keypad (the 8 for up and the 2 for down) or by simply typing the
the letter of the option.
A sample door, NEWS.PAS, is included to demonstrate the use of the
ansimenu unit.

REFERENCE - REMOTE WINDOW ROUTINES (REMOVED IN SMALL VERSION)
----------------------------------

These procedures are contained in the TPU file "DoorDriv.tpu":
--------------------------------------------------------------

Procedure GetScreen(Tx,Ty,Bx,By:integer; Var topar : MemoryAr)

This Procedure allows you to save the current screen,or part
of the screen, by defining:

Tx - X Coordinate of the top left hand corner of the window
Ty - Y Coordinate of the top left hand corner of the window
Bx - X Coordinate of the bottom right hand corner of the window
By - Y Coordinate of the bottom right hand corner of the window
Topar - MemoryAr is an Array[0..3999] of Byte which holds the
screens contents.


Procedure ReinitScreen(Tx,Ty,Bx,By:integer; Var topar : MemoryAr)

This Procedure allows you to recall the screen saved by the
procedure GetScreen using the previously saved MemoryAr.

Tx - X Coordinate of the top left hand corner of the window
Ty - Y Coordinate of the top left hand corner of the window
Bx - X Coordinate of the bottom right hand corner of the window
By - Y Coordinate of the bottom right hand corner of the window
Topar - MemoryAr is an Array[0..3999] of Byte which holds the
screens contents.

Both of these procedures use a Type called MemoryAr. MemoryAr
is defined in "DoorDriv.Tpu" as an array[0.3999] of Byte.

These procedures are contained in the TPU file "ReWindow.tpu":
--------------------------------------------------------------

Procedure RWindow(TopX,TopY,BottomX,BottomY,
BorderFg,BorderBg,
TxtFg,TxtBg : Integer;
Txtstring : Windowar)


This procedure draws a remote window which is defined by
by the author to fit his or her specific needs.

Topx - X Coordinate of the top left hand corner of the window
Topy - Y Coordinate of the top left hand corner of the window
Bottomx - X Coordinate of the bottom right hand corner of the window
Bottomy - Y Coordinate of the bottom right hand corner of the window
BorderFg - The Windows border foreground
BorderBg - The Windows border background
TxtFg - The Windows Text foreground
TxtBg - The Windows Text background
TxtString - The array that specifys what gets written in the window
WindowAr = Array[1..23] of string[78];



Update History:

2.50 - First Public release

2.55 - DoorDriver screen removed and replaced by a 2-line
message.
- Small problem with SET_FOREGROUND has been fixed.
- the NEWS.DIR file which was left out in previous versions
has now been included.

2.60 - Modifications to the ANSIMENU TPU
1) The TPU is now called "ANSIMENU" instead of
"ANSIMENUSYSTEM". If your program was using the
ansimenu routines, then the "uses" statement
must be changed from "uses ansimenusystem" to
"uses ansimenu".
2) The function name "ANSIMENU" has been repleaced
by "GETANSIMENU". All occurences of the function
call :=Ansimenu() must be
changed to :=GetAnsiMenu().
- DoorDriver title screen/info shrunk even more at
users' request.

3.00 - Doordriver majorly modified to switch to use of control
file rather than the /C configuration.
- INITDOORDRIVER(filename) must be called before any of
doordrivers routines are used.
- SREAD_CHAR was omitted by accident in previous versions of
the documentation.
- Many new configuration options present in the control file
including EGA/VGA support.
- Two versions of DoorDriver are now included. DOORDRIV is the
normal version with all features included while DOORDRSM
is the SMALL version which leaves out the REWINDOW,
ALT-KEY, and SYSOP FILTER support. If your program begins
to run low on memory, you may wish to consider using
DOORDRSM instead of DOORDRIV.
- Doordirv.INT has been included in the package and includes
the actual interface section of doordriver.
- CFGEDITR.TPU has been altered. (See edittest.pas for the new
template record structure)


Credits
-------
SCOTT BAKER (myself)
Author of DOORDRIVER, NEWS, and ANSIMENU

DERRICK PARKHURST
Repairs to the still malfunctioning ANSI.TPU unit
Various work on configurable editor routines
Remote windowing and Windowed chat support
Sysop filter

CARL EVANS (of Vervans War Board)
Addition of PC-BOARD 14 support


Copyright and Registration
--------------------------

The DOORDRIVER routines are copyrighted by Scott Baker and
Derrick Parkhurst. This copyright includes all material contained in this
package - TPU modules, PAS files, sample door, Documentation, etc.
You are permitted to USE these routines in your own doors if you
wish under the following conditions:

1) Any material which you use from this package must not be
modified in any way.

2) No material in this package may be used for commercial
purposes without explicit written permission of the authors.

3) You MUST include credit to the authors of these routines
in your program.

I encourage you to register this package with the authors if you
find it useful to your programming. Registration/donations can be mailed
to the following address:

Scott M. Baker
6433 Tierra Catalina #48
Tucson, Az 85718

If you wish to contact the authors of this software for any reason,
they may be reached by the address above, or you may log on to our software
support bbs:

"The Not-Yet-Named bbs"

Sysop: Scott Baker
Baud: 2400, 1200, 300
NODE #1: (602) 577-3650
NODE #2: (602) 577-3419
RBBSNET: 8:902/10
FIDONET: 1:300/9