Doordriver version 4.00 By Scott Baker 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. SETFORECHECK: boolean; (default=FALSE) This variable when set to TRUE will cause DDTERM to filter out repetetive SET_FOREGROUND() calls. If for example, you set the foreground to gray, then set it to gray again later while the foreground is still gray, the second call would be ignored. This can spare the user from the slowdown effects of meaningless, repetetive SET_FOREGROUND calls. 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]:=@; 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]; REFERENCE - DDTERM TERMINAL SUPPORT ----------------------------------- Doordriver has built-in support for my DDTERM terminal package. When DDTerm successfully communicates with doordriver, the result can be a massively speeded up session. DDTerm provides the following benefits: - Data can be placed in "packets". These packets only need to be sent once - once they are on the remote side, DoorDriver can call them up to be displayed by sending a simple 6-byte sequence. - ANSI color changes are sent in three byte sequences instead of the lengthly 4-6 byte sequences they usually require. - Many more features (context sensitive help, elapsed time updates, etc) that I don't have time to discuss. Here are the procedures for DDTERM activation and packet control: PROCEDURE DDTERMON; This activates DDTERM capabilities. What you should do is allow the user to select an option from one of your menus to activate DDTERM support if he/she is using DDTERM. (Recognition of the DDTERM terminal program is not automatic) PROCEDURE PACKETSTART(N: WORD); This indicates the start of a DDTERM packet. Once this statement is issued, all output will be redirected to the packet instead of the com-port. The "N" is a unique identifier number for the packet - you must number each packet you use seperately. PROCUEDRE PACKETSEND; This procedure will send the data since the last PACKETSTART. Before sending the data, DOORDRIVER will "ask" DDTERM if the packet is already present. If so, DDTERM will simply display the packet rather than having doordriver transmit the whole packet. PROCUEDRE DDTERMOFF; This shuts down DDTERM support. EXAMPLE: begin; DDTERMON; packetstart(1); swriteln('All of this text is inside a DDTERM packet.'); swriteln('It only needs to be sent ONCE to the remote, then it can'); swriteln('be called up without re-transmission of the data.'); packetsend; end; That little batch of code would place those three swriteln() lines into the DDTERM packet. The first time the code was encountered, the actual bytes of the packet would be sent. The second time, DoorDriver would request DDTERM to display the packet. PACKETSTART and PACKETSEND can be placed in a program with or without DDTERM support active - if DDTERM has not been activated, the procedures will simply be ignored and not effect normal program operation. 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) 4.00 - The DDANSI unit went through a major overhaul - it should now be faster and more error free. - DDTERM support included - see the above section for information. - Both TP5.5 and TP6.0 routines included. 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