Dec 232017
 
A BBS Door Writing Kit for Turbo Pascal programmers.
File PDOOR30.ZIP from The Programmer’s Corner in
Category Pascal Source Code
A BBS Door Writing Kit for Turbo Pascal programmers.
File Name File Size Zip Size Zip Type
CONTENTS.LST 724 414 deflated
JPDOOR.DOC 36117 8057 deflated
JPDOOR.REF 97356 22064 deflated
JPDOOR.REG 1591 416 deflated
JPD_TP55.ZIP 44867 44013 deflated
JPD_TP60.ZIP 45049 44203 deflated
MULTI.DOC 16583 5199 deflated
OFFER.TXT 1157 618 deflated
PID.APP 1915 736 deflated
SUPPORT.TXT 4653 1495 deflated
SYSOPKEY.PAS 1630 690 deflated
TRAPEXIT.PAS 4696 1629 deflated

Download File PDOOR30.ZIP Here

Contents of the JPDOOR.DOC file
















MOTOR CITY SOFTWARE

JPDoor - Version 3.0 SE
Copyrighted 1991

\
\
\ P
\ A
S
C
5.5 A 6.0
o L

\
\
\
The Ultimate \ Door Writing Unit.




JPDoor - Version 3.0 SE
Copyright 1991 by Motor City Software.
All Rights Reserved
























M O T O R C I T Y S O F T W A R E
-----------------------------------------


PRESENTS:


J P D O O R D O C U M E N T A T I O N



TABLE OF CONTENTS




Motor City Software ............................. 3

Licensing Information .......................... 4

Support Systems ................................. 4

Acknowledgements ............................... 5

Getting Started With JPDoor

The Uses Statement ........................ 6

Trapping Halt Codes ....................... 7

Trapping Extended Keys .................... 9

Getting the User Information .............. 12

Initializing the Fossil Driver ............ 13

Initializing ANSI Color Sequences ......... 14

Fossil Output Buffering ................... 15



JPDoor Reference Section .................. included











[2] JPDoor 3.0.Doc









MOTOR CITY SOFTWARE





Motor City Software is a Shareware Programming Partnership composed
of three different Programmers, each bringing their own special talents
to this unique partnership:




Rod Hancock
Motor City Software Online
(416)579-6318
1:229/418 (HST-DS)
Oshawa Ontario
CANADA



John Parlin
City Terminal BBS
(612)938-4301
1:282/12 (HST-DS)
Hopkins Minnesotta
USA




Jeff Wilson
Compro Systems
(416)623-5148
1:229/414 (HST)
Bowmanville Ont.
CANADA










[3] JPDoor 3.0.Doc





LICENSING INFORMATION



This program is not Freeware. This is SHAREWARE which means it is user-
supported software. If you use this program for more than 30 days, you are
required to register or remove it from your system. The registration fee is
a mere $25.00 and is not a lot to ask.

JPDOOR is Copyrighted 1991 by Motor City Software and all rights are
reserved. You may copy this program and documentation for backup purposes.
You also may copy and share UNMODIFIED copies of the program package, pro-
viding that the copyright notice is reproduced and included on all copies.

You may not sell the product for a fee and/or distribute the product
along with other products without expressed written permission from Motor
City Software, nor may you modify or remove the Copyright Notice from the
program or the documentation.

You may not distribute programs which you have created using JPDoor
without first registering JPDoor with the author. You may not accept com-
pensation for programs created using JPDoor without registering JPDoor with
the authors.

This unit was written to aid programmers in writing RemoteAccess 0.01
thru 1.xx and QuickBBS 2.62 thru 2.75 compatible door programs using Turbo
Pascal* 5.5 and Turbo Pascal* 6.0.




SUPPORT SYSTEMS



If you have any comments, suggestions or bug reports please address them to
Rod Hancock at FidoNet 1:229/418. For additional support or the latest files
a list of the Motor City Software Support Systems is listed below.

System Name Location Sysop Name Phone Number Fido Node
----------------------------------------------------------------------------
Motor City BBS Oshawa, Ontario Rod Hancock 416-579-6318 1:229/418
Compro Systems Bowmanville, Ont. Jeff Wilson 416-623-5148 1:229/414
City Terminal BBS Hopkins, MN John Parlin 612-938-4301 1:282/12
The Chancellors Den Faversham Kent,UK Dennis Bennet 44-795-538359 2:254/92
The Computer Group Albany, NY Peter Kling 518-437-1267 1:267/169

If you're reporting a bug, please give as much detail as possible about the
problem you are experiencing so that it can be duplicated and fixed.





[4] JPDoor 3.0.Doc







ACKNOWLEDGEMENTS



The release of JPDoor has been a cooperative effort. Our sincere
gratitude goes out to those who helped put this release together. The
contributors towards past versions were:

- Cary Howell, QuickAccess BBS (1:379/207), The Manhatten Project

Cary really added a lot to the code providing us with the status bar,
text file control codes, screen handling, and other enhancements to
existing blocks of code.

- Scott Davis, Phoenix Starfighter BBS (1:3616/20)

Scott provided his assistance whenever I asked for it and volunteered
even more. Thanks to Scott, we now have the ability to trap extended
keys from the local console or the remote. Scott contributed in many
areas and has helped to keep JPDoor compatible with QuickBBS 2.64
systems. Scott also enhanced the unit by combining ShowAnsiFile and
ShowTextFile to make one procedure called ShowFile.

- Mark Cook, Wizardry BBS (1:104/630)

Mark provided us with the initial idea of far calls in JPDoor so that
we could trap unexpected exits. Some of Mark's TRAPEXIT.PAS code is
still included in this release.

- Robert Van Hoeven and Tom Ordelman of European Cybernetics

Robert optimized the code and cleaned up some of my not-so-pretty
stuff for release 2.4c. Tom coordinated the effort. Thanks to these
two, We can read the code that John wrote. John tells us that He
will never write his code in a non-formated pattern again.

- Peter Kling of The Computer Group Ltd (1:267/169.0).

Peter provided some enhancements to make the error handling
procedures more readable for the user and the sysop. The
error handling code had been imported directly from Packer.

- A special thanks to all the beta testers for all the suggestions
and help in ironing out the bugs.

And a big thanks to all the users out there who have shown an interest
in this product. Your support is what generates new releases. Program
updates will continue to be made as long as there is user support in the
form of product registrations.

(* Turbo Pascal is trademarked by Borland International, Inc.)

[5] JPDoor 3.0.Doc





GETTING STARTED WITH JPDOOR




The USES statement:
-------------------


To use JPDoor with your door program, you'll need to put it into your
USES statement:

USES DOS, CRT, JPDoor30 ;

code segment:

--------------------------------------------------------------------------
| PROGRAM MyDoorProgram ; |
| USES DOS, CRT, JPDoor30 ; |
| ..... |
| ... |
| {your program continues} |
--------------------------------------------------------------------------


JPDoor needs to find MAPPED.TPU to perform some of its functions.
MAPPED.TPU is included in the JPDoor 3.0 distribution archive. You
are not required to include it in your USES statement, however, it
must reside in your Turbo Pascal UNIT directory.


The include file TRAPEXIT.PAS contains a far call procedure called
TRAPEXIT. The TRAPEXIT procedure, in turn, calls a TERMINATE procedure
and passes the halt code to it. You could conceivably do all your
clean-up, etc. right inside of the TRAPEXIT procedure and not call
another procedure such as TERMINATE but for the sake of demonstration,
let us say that the far call procedure TRAPEXIT does call the procedure
TERMINATE.


First of all, let's get setup to trap HALT codes. Here's what you'll
need to do:


1) Incorporate the following TERMINATE procedure. The TRAPEXIT
procedure will call this procedure, passing the HALT code to
it. If the HALT is a runtime error, TRAPEXIT will report that
instead of calling TERMINATE.






[6] JPDoor 3.0.Doc




Trapping HALT codes (exits):
----------------------------


-----------------------------------------------------------------------------
| PROCEDURE Terminate(HaltCode : BYTE) ; |
| BEGIN |
| CASE HaltCode OF |
| 0 : WRITELN('Normal termination') ; {normal terminate - no action} |
| 1 : BEGIN |
| WRITELN('Carrier lost') ; |
| EndGame ; {call EndGame proc. and write user info} |
| END ; |
| 2 : BEGIN |
| WRITELN('Time limit exceeded') ; |
| { do what you would want done if the caller's time |
| limit was exceeded } |
| END ; |
| 3 : BEGIN |
| WRITELN('User inactivity timeout') ; |
| { do what you would want done if user was inactive } |
| END ; |
| 4 : BEGIN |
| WRITELN('Dorinfo1.Def file not found') ; |
| { not good - do what you would want done in this situation} |
| END ; |
| 5 : BEGIN |
| WRITELN('Exitinfo.Bbs file not found') ; |
| { not good - do what you would want done in this situation} |
| END ; |
| 6 : BEGIN |
| WRITELN('Directory read/change error') ; |
| { this is a nasty. You should close files and HALT(0) } |
| END ; |
| 7 : BEGIN |
| WRITELN('CTS - Clear To Send Error/Time Out'); |
| { most likely carrier has been dropped, close files } |
| { and then Halt(0) } |
| END |
| END ; |
| END ; |
---------------------------------------------------------------------------


Place your TERMINATE procedure anywhere within your program. The
only stipulation is that you must place it BEFORE the line that
includes the file TRAPEXIT.PAS.


2) Next, be sure to include the TrapExit.Pas file:





[7] JPDoor 3.0.Doc





Trapping Halt Codes (continued):
--------------------------------




---------------------------------------------------------------------------
| {$I TRAPEXIT} |
---------------------------------------------------------------------------



3) Now, in the Main Body of your program code, you will need to add
the following line:


---------------------------------------------------------------------------
| BEGIN { Main - Example } |
| ASSIGN(OutPut,'') ; |
| REWRITE(OutPut) ; |
| DoorExit := TrapExit ; |
| ...... |
| ... |
| your program continues |
---------------------------------------------------------------------------


The statements ASSIGN(OutPut,'') and REWRITE(OutPut) will allow
ANSI escape codes to be properly displayed on the local console.
The statement DoorExit := TrapExit will setup halt code trapping.


Now HALT code trapping is in effect. When a HALT code is encountered,
the TRAPEXIT procedure will be called. TRAPEXIT will determine if a
Runtime Error has occurred or if a HALT code was used. If a HALT code
was used, TRAPEXIT will call your program's TERMINATE procedure, passing
the HALT code to it.


If you do not assign a procedure to DoorExit as shown, HALT codes will
not be trapped.











[8] JPDoor 3.0.Doc




Trapping Extended Keys:
-----------------------


JPDoor allows you to define up to 20 extended keys for Sysop/Local use
as well as 20 keys for End-User/Remote use. This would allow the Sysop
to setup procedures that can be called at the press of an ALT key or
Function key. This would also be good for a door program that required
the end-user to press, for example, an up or down arrow key.


Extended codes are codes that return a null (character #0) first, and
then a second, extended code second. For example, ALT-C is a two-code key.
It's a null (ASCII #0) code followed by an ASCII #46.


Other codes are, for example, control codes such as CONTROL-R which
is an ASCII #18. This type of control code is not an extended code yet
you might want to trap for it and have a procedure called.


So how do we setup to trap these keys? For the sake of this example,
let's say that our goal is to trap for an ALT-C. Let's say that we want
to call an online chat procedure called CHAT when ALT-C is pressed.


The first thing we need to do is to tell JPDoor the key codes we want
to trap and the procedure name to call. Since this is a Sysop/Local
key/function we'll use SysopKey and SysopProc. Let's define it as follows:



---------------------------------------------------------------------------
| SysopKey[1] := #0 + #46 ; |
| SysopProc[1] := ALT_C ; |
---------------------------------------------------------------------------



We can define up to 20 keys and procedures here but we'll just work with
this one. Next, we'll need to set the unit variable 'SysopKeysOn' to TRUE:



---------------------------------------------------------------------------
| SysopKeysOn := TRUE ; |
---------------------------------------------------------------------------








[9] JPDoor 3.0.Doc






Trapping Extended Keys (continued):
-----------------------------------

Next, we need to take a look at our SYSOPKEY.PAS far call include file.
Here's what it might look like:


--------------------------------------------------------------------------
| {$F+} |
| PROCEDURE ALT_C ; |
| BEGIN |
| SysopKeysOn := FALSE ; {turn off key trapping for the duration } |
| CHAT ; {call your CHAT procedure in your code } |
| SysopKeysOn := TRUE ; {turn key trapping back on } |
| END ; |
| {$F-} |
--------------------------------------------------------------------------


Pretty straight forward, isn't it? The far call procedure ALT_C turns
off key trapping (you don't want to be able to chat within CHAT do you?).
It then calls your procedure called CHAT. Lastly, it turns key trapping
back on again. Your program will then continue where it was before ALT-C
was pressed.



So how's our main program code segment looking so far? Let's take a look:

--------------------------------------------------------------------------
| {$I TRAPEXIT} |
| {$I SYSOPKEY} |
| |
| BEGIN { Main - Example } |
| ASSIGN(OutPut,'') ; |
| REWRITE(OutPut) ; |
| DoorExit := TrapExit ; |
| SysopKey[1] := #0 + #46 ; |
| SysopProc[1] := ALT_C ; |
| SysopKeysOn := TRUE ; |
| ...... |
| ... |
| your program continues |
| |
--------------------------------------------------------------------------








[10] JPDoor 3.0.Doc

Trapping Extended Keys(continued):
----------------------------------

Now if you wanted to enable a user to enter extended codes or control
codes, you use the same theory as with Sysop/Local keys only we work with
the variables UserKey[1..20], UserProc[1..20], and UserKeysOn (BOOLEAN).

For example, let's say that we want our door program to allow the user
to press CONTROL-R to redraw the screen. Let's say that you already have
a procedure called REDRAW in your program. Let's create a file called
USERKEY.PAS. Here's what it might look like:

--------------------------------------------------------------------------
| {$F+} |
| PROCEDURE CONTROL_R ; |
| BEGIN |
| UserKeysOn := FALSE ; |
| REDRAW ; |
| UserKeysOn := TRUE ; |
| END ; |
| {$F-} |
--------------------------------------------------------------------------

Now here's how your main program code might look:

--------------------------------------------------------------------------
| {$I TRAPEXIT} |
| {$I SYSOPKEY} |
| {$I USERKEY} |
| |
| BEGIN { Main - Example } |
| ASSIGN(OutPut,'') ; |
| REWRITE(OutPut) ; |
| DoorExit := TrapExit ; |
| SysopKey[1] := #0 + #46 ; |
| SysopProc[1] := ALT_C ; |
| SysopKeysOn := TRUE ; |
| UserKey[1] := #18 ; |
| UserProc[1] := CONTROL_R ; |
| UserKeysOn := TRUE ; |
| ..... |
| ... |
| your program continues |
--------------------------------------------------------------------------

It works the way the SysopKey/SysopProc does. You can define up to 20
SysopKey, UserKey, SysopProc, and UserProc's. There's no need to initialize
them. Toggling SysopKeysOn and UserKeysOn TRUE/FALSE is all you need to
turn them on or off.

GETTING USER INFORMATION
------------------------

Now we're at a point where we can get the online user's information.
Previous versions of JPDoor required the presence of both a DORINFOx.DEF
and an EXITINFO.BBS file created which are created by RemoteAccess and
QuickBBS. Because many doors are used on a wide variety of BBS types,
and many of them are not capable of producing an Exitinfo.bbs, this is
now optional. If your door does not need to update any user information,
simply include the following in your program BEFORE calling GetDorinfo.

[11] JPDoor 3.0.Doc



GETTING USER INFORMATION CONT.
------------------------------

CkExitInfo := False;

Finally, JPDoor will now read a GAP style DOOR.SYS file as well as the
DOOR.SYS created by RemoteAccess. If you wish to use this file, rather
than DORINFOx.DEF then include the following BEFORE calling GetDorinfo.

DoorSys := True;

The GetDorinfo routine will automatically detect the correct structures
for any of these drop files:

QBBS 2.64 - 2.75 EXITINFO.BBS
RemoteAccess V0.03 - 1.xx EXITINFO.BBS
RemoteAccess V1.xx DOOR.SYS (DoorWay Style)
GAP DOOR.SYS (Also created with PCBoard)

To get information about the user currently online, we must pass two
parameters to GetDorInfo.
They are:
1: the current node
2: the path to DORINFOx.DEF and EXITINFO.BBS or DOOR.SYS

JPDoor is designed to support RemoteAccess 1.xx data structures.
However, if the program you create is run on a QuickBBS system,
or earlier releases of RemoteAccess, the EXITINFO.BBS file will be
converted automatically to RemoteAccess 1.01 format upon program startup.
It will also be automatically converted back to its original format when
your program ends. No intervention or conversion is required by your
program!

So now let's add the GetDorInfo procedure to your program code:

--------------------------------------------------------------------------
| {$I TRAPEXIT} |
| {$I SYSOPKEY} |
| {$I USERKEY} |
| |
| BEGIN { Main - Example } |
| ASSIGN(OutPut,'') ; |
| REWRITE(OutPut) ; |
| DoorExit := TrapExit ; |
| SysopKey[1] := #0 + #46 ; |
| SysopProc[1] := ALT_C ; |
| SysopKeysOn := TRUE ; |
| UserKey[1] := #18 ; |
| UserProc[1] := CONTROL_R ; |
| UserKeysOn := TRUE ; |
| GetDorInfo(Node,'') ; |
| ...... |
| .... |
| your program continues |
--------------------------------------------------------------------------

[12] JPDoor 3.0.Doc


Initializing the FOSSIL Driver:
-------------------------------

This example uses the current directory as the directory to read
DORINFOx.DEF and EXITINFO.BBS from. Once done, we have all the user

and FOSSIL port information needed by JPDoor.

This is really straight forward. You should always use a FOSSIL driver
when executing a door program. Whether or not you're local, you still
need one installed for proper I/O. We're at a good spot in your main
program segment to check/initialize the FOSSIL driver. Let's add the
following lines of code:

--------------------------------------------------------------------------
| |
| IF NOT SetFossil THEN BEGIN |
| WRITELN(#7,'WARNING! Fossil not detected!') ; |
| HALT(0) ; |
| END ELSE WRITELN('Fossil detected') ; |
--------------------------------------------------------------------------

Of course you can use any halt code greater than ten instead of zero.
What this block of code does is checks the value of the BOOLEAN function
'SetFossil'. When referrenced, SetFossil calls an internal procedure
which initializes the FOSSIL driver and returns a TRUE or FALSE depending
on its success.

Let's add this to your program code:

--------------------------------------------------------------------------
| {$I TRAPEXIT} |
| {$I SYSOPKEY} |
| {$I USERKEY} |
| |
| BEGIN { Main - Example } |
| ASSIGN(OutPut,'') ; |
| REWRITE(OutPut) ; |
| DoorExit := TrapExit ; |
| SysopKey[1] := #0 + #46 ; |
| SysopProc[1] := ALT_C ; |
| SysopKeysOn := TRUE ; |
| UserKey[1] := #18 ; |
| UserProc[1] := CONTROL_R ; |
| UserKeysOn := TRUE ; |
| GetDorInfo(Node,'') ; |
| IF NOT SetFossil THEN BEGIN |
| WRITELN(#7,'WARNING! Fossil not detected!') ; |
| HALT(0) ; |
| END ELSE WRITELN('Fossil detected') ; |
| ...... |
| ... |
| your program continues |
--------------------------------------------------------------------------




[13] JPDoor 3.0.Doc





Initializing ANSI Color Sequences:
----------------------------------


Next we need to initialize ANSI colors. Whether or not a user of your
program has ANSI turned on, you should still include this segment in your
program code. If the user does not have ANSI turned on, the procedure
'SetColor' will exit without performing any tasks.



--------------------------------------------------------------------------
| x |
| {$I TRAPEXIT} |
| {$I SYSOPKEY} |
| {$I USERKEY} |
| |
| BEGIN { Main - Example } |
| ASSIGN(OutPut,'') ; |
| REWRITE(OutPut) ; |
| DoorExit := TrapExit ; |
| SysopKey[1] := #0 + #46 ; |
| SysopProc[1] := ALT_C ; |
| SysopKeysOn := TRUE ; |
| UserKey[1] := #18 ; |
| UserProc[1] := CONTROL_R ; |
| UserKeysOn := TRUE ; |
| GetDorInfo(Node,'') ; |
| IF NOT SetFossil THEN BEGIN |
| WRITELN(#7,'WARNING! Fossil not detected!') ; |
| HALT(0) ; |
| END ELSE WRITELN('Fossil detected') ; |
| SetColor(0,7,0) ; |
| ...... |
| ... |
| your program continues |
--------------------------------------------------------------------------



We have now included all the initialization functions that are required
by JPDoor. Your program code can continue at this point!












[14] JPDoor 3.0.Doc





FOSSIL Output Buffering:
------------------------

JPDoor supports hotkeys. In order for JPDoor to act quickly when a
hot-key is pressed, output buffering does not normally take place. In
other words, JPDoor will send out one character at a time to the FOSSIL
output buffer and wait until that character has been sent from the buffer
before sending another one.

With programs written using JPDoor that do not utilize hot-keys, output
may be buffered which may increase the program's speed on the host computer.
If output buffering is used during a program which utilizes hot-keys,
hot-keys will still function but there may be a delay before display is
interrupted after a valid hot-key is pressed.

To turn on JPDoor's use of output buffering, you must set the DOS
environment variable OUTBUFF to ON. You can do this in a batch file
which calls the door program for which you want output buffering.

Let's say we want to execute a door program that was compiled using
JPDoor. In this example, the program is called DOORPROG.EXE. Here's a
little batch file segment that calls DOORPROG.EXE:

Menu Type 7 Optional Data Field Contents:


\COMMAND.COM /C \RA\MYDOOR.BAT

MYDOOR.BAT:

SET OUTBUFF=ON
DOORPROG.EXE
SET OUTBUFF=OFF


This batch file segment turns on JPDoor's output buffering, calls
the door program DOORPROG.EXE, and then turns JPDoor's output buffering
off again before returning operation to the BBS.













[15] JPDoor 3.0.Doc



 December 23, 2017  Add comments

Leave a Reply