Programmer 7500

home *** CD-ROM | disk | FTP | other *** search

/ Programmer 7500 / MAX_PROGRAMMERS.iso / PASCAL / JPDOOR32.ZIP / JPDOOR.DOC < prev next >

Wrap

Text File | 1992-02-26 | 35.8 KB | 915 lines

┌──────────────────────────────────────────────┐ │ MOTOR CITY SOFTWARE │ │ ┌──────────────────────────────────────┐ │ │ │ JPDoor - Version 3.1 SE │ │ │ │ ┌──────────┐ │ │ │ │ │\ │ │ │ │ │ │ \ │ │ │ │ │ │ \ P │ │ │ │ │ │ \ A │ │ │ │ │ │ │ S │ │ │ │ │ │ │ C │ │ │ │ │ 5.5 │ │ A │ 6.0 │ │ │ │ │ o│ L │ │ │ │ │ │ │ │ │ │ │ │ \ │──────┘ │ │ │ │ \ │ │ │ │ └──────────────\ │─────────────────────┘ │ │ The Ultimate \│ Door Writing Unit. │ └────────────────────┴─────────────────────────┘ JPDoor - Version 3.1 SE Copyright 1990,1991,1992 by Motor City Software. All Rights Reserved 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 ....................... 6 Trapping Extended Keys .................... 9 Getting the User Information .............. 12 Initializing the Fossil Driver ............ 13 Initializing ANSI Color Sequences ......... 14 The Status Bar ............................ 14 Fossil Output Buffering ................... 15 JPDoor Reference Section .................. See File JPDOOR.REF [2] JPDoor 3.1.Doc ╒═════════════════════════════════════════════════════════════════════════════╕ │░░░░░░ MOTOR CITY SOFTWARE ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░│ ╘═════════════════════════════════════════════════════════════════════════════╛ Motor City Software is a Shareware Programming Partnership composed of four different Programmers, which each bring their own special talents to this unique partnership: Rod Hancock John Parlin Jeff Wilson Peter Kling Oshawa Ontario Hopkins MN Bowmanville Ont Albany NY CANADA USA CANADA USA [3] JPDoor 3.1.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 $30.00 and is not a lot to ask considering the time and effort required for a toolkit of this nature. JPDOOR is Copyright 1990,1991,1992 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.11 and QuickBBS 2.62 thru 2.75 compatible door programs using Turbo Pascal* 5.5 and Turbo Pascal* 6.0. Use of this product constitutes acceptance of these terms. ╒═════════════════════════════════════════════════════════════════════════════╕ │░░░░░░ 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 included in this archive as SUPPORT.LST [4] JPDoor 3.1.Doc ╒═════════════════════════════════════════════════════════════════════════════╕ │░░░░░░ ACKNOWLEDGEMENTS ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░│ ╘═════════════════════════════════════════════════════════════════════════════╛ The release of JPDoor has been a cooperative effort. Our sincere gratitude goes out to those who helped with the development of one of the most popular Door Writing Toolkits available. 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 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. - Andrew Milner & Continental Software for unlimited support and a great BBS package without which some of the new features of JPDoor would not be possible. - 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.1.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, JPDoor31 ; code segment: -------------------------------------------------------------------------- | PROGRAM MyDoorProgram ; | | USES DOS, CRT, JPDoor31 ; | | ..... | | ... | | {your program continues} | -------------------------------------------------------------------------- JPDoor needs to find MAPPED.TPU to perform some of its functions. MAPPED.TPU is included in the JPDoor 3.1 distribution archive. You are not required to include it in your USES statement, however, it must reside in your Turbo Pascal UNIT directory. Trapping HALT codes (exits): ---------------------------- 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.1.Doc Trapping HALT codes (continued): -------------------------------- ----------------------------------------------------------------------------- | 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 | | 8 : WRITELN('RAXIT Semaphore forced Exit'); | | 9 : Writeln('Door.Sys file not found'); | END ; | | END ; | --------------------------------------------------------------------------- [7] JPDoor 3.1.Doc Trapping Halt Codes (continued): -------------------------------- 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: --------------------------------------------------------------------------- | {$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.1.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.1.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.1.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. [11] JPDoor 3.1.Doc Getting the 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. 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.11 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.11 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.11 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.1.Doc Getting the User Information: (Continued) ----------------------------------------- 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. Initializing the FOSSIL Driver: ------------------------------- 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.1.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. -------------------------------------------------------------------------- | {$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 | -------------------------------------------------------------------------- The Status Bar -------------- JPDoor also provides a 2 line Status Bar at the bottom of the screen. This is optional and may be turned on and off by you with the StatusLineOn Boolean variable. You may also change the default display of the status bars simply by putting your own info into the variables StatLineA[X] and StatLineB[X] where X is a number from 1 to 9. These coincide with funtion keys 1 - 9 and F-10 will turn OFF the status Bar. These variables are of type String[79]; The following codes are supported in the statusline string: ~C Current Time ~R Time Remaining ~S Security Level ~A [ANSI] or [MONO] ~B Baud Rate We have now included all the initialization functions that are required by JPDoor. Your program code can continue at this point! [14] JPDoor 3.1.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.1.Doc