Programmer 7500

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

/ Programmer 7500 / MAX_PROGRAMMERS.iso / PASCAL / TRIDV1.ZIP / TRIDOOR.DOC < prev next >

Wrap

Text File | 1990-12-19 | 35.9 KB | 941 lines

T R I U M P H S O F T W A R E Presents ░██████████ ░██ ░███████ ░█ ░██ ░█ ░██ ░██ ░██ ░█░██ ░██ ░██ ░██ ░███ ░███ ░█░██ ░██ ░█ ░█ ░█ ░██ ░██ ░█ ░█ ░█ ░█ ░█ ░█ ░████ ░██ ░███ ░███████ ░███ ░███ ░██ An On-Line Door Support Unit For use with the QuickBBS System and Turbo Pascal 5.5 TriDoor Written by Christopher M. Russo TriComm Communications Support Written by Jeremy H. DuBois TriDoor, TriComm (c)1990 Triumph Software, All Rights Reserved. QuickBBS is a Registered Trademark of the QuickBBS Group. Turbo Pascal is a Registered Trademark of Borland, Inc. Triumph Software is not aphiliated in any way with either The QuickBBS Group or Borland, Inc. Triumph Software - TriDoor Documentation pg. i DISCLAIMER Triumph Software and the employees/programmers in conjuctions with and/or aphiliated with Triumph Software can not be held responsible for the condition of any software recieved through any non-postal/ non-parcel means. Nor can said persons be held responsible for any damage caused to media or hardware as a result of the use of any of our products. Triumph Software and it's employees and associates would like it to be known, however, that all of their products are thoroughly tested before leaving our offices. It is only in the deepest faith in our own product that any such software is released to the public. Triumph Software - TriDoor Documentation pg. ii LIMITED LICENSING AGREEMENT Triumph Software grants the user of the unregistered TriDoor unit and it's documentation a limited usage license of 30 (thirty) days. During this period of time, the user may program/test/work with and incorporate the TriDoor unit into his/her code as long as no money is obtained in any way through the use of the TriDoor unit. This license does NOT allow for distribution, in any way, of code incorporating the TriDoor unit in any form. A private copy of this sofware may be obtained by filling out the registration form included with this software and sending it and $45.00 check or money order to Triumph Software. This private copy will allow the user to use the TriDoor unit as an incorporated portion of any of his/her programs/software that are to be used by him/her only. This license is also extended to the users of a Bulletin Board System that will use, but will not obtain a copy of, the user's (registered owner of TriDoor unit) programs/software. This license does NOT allow the registered owner of the TriDoor unit to distribute programs/software for money or compensation of any sort. A limited distribution license is extended to private copy owners in that they may distribute software incorporating the TriDoor unit as long as no money or compensation in any way is recieved in payment for said software and that Triumph Software is given full and acceptable credit for the door and communications support. A sample of acceptable credit is included in this package. A commercial copy of this sofware may be obtained by filling out the registration form included with this package and sending it and $100.00 check or money order to Triumph Software. This commercial copy will allow the user to sell and/or distribute code incorporating the TriDoor unit as they please as long as Triumph Software is given acceptable credit for the door and communications support. No registered copy is to be distributed in any other form other than as a compiled and included portion of another program. The unregistered version of TriDoor may be distributed freely as long as ALL files that were included in the original package are kept, unchanged in any way, during the distribution. In the act of using TriDoor, you are hereby agreeing to and will be held responsible for all of the above listed terms and clauses. NOTE : When you register you will recieve the LATEST running version of TriDoor and it' s documentation. You will also receive news, in the mail, of any new software or upgrades and will be entitled to one free upgrade (shipping cost not included) of any version of the software that was written at up to six months after the original registration date. Triumph Software - TriDoor Documentation pg. iii SOME NOTES ON DOCUMENTATIONS Yes, we all hate reading documentation, even people like me who just spent four hours taking the time to write this particular documentation file up. However, with that knowlege, I have done my best to make this file as verbose as possible without losing any of the important facts and/or information. That is, of course, with the exception of the disclaimer and licenseing agreement, which have to be long and annoying or our lawyers will be twice as long and annoying, right? So, buck up, print this thing out and read it. Take heart- it's less than twenty pages- so far, anyway. We'll see what happens a couple versions down the road. Triumph Software - TriDoor Documentation pg. iv TABLE OF CONTENTS Why Use Tridoor?. . . . . . . . . . . . . . . . . . . . . . . . .001 History of TriDoor. . . . . . . . . . . . . . . . . . . . . . . .002 Who to Contact. . . . . . . . . . . . . . . . . . . . . . . . . .003 Tested Limits of TriDoor. . . . . . . . . . . . . . . . . . . . .004 Features of TriDoor . . . . . . . . . . . . . . . . . . . . . . .005 Command Summary . . . . . . . . . . . . . . . . . . . . . . . . .006 Reserved Words. . . . . . . . . . . . . . . . . . . . . . . . . .010 Accessable Variables. . . . . . . . . . . . . . . . . . . . . . .011 Things to Come ("The Workbench"). . . . . . . . . . . . . . . . .012 Programming Hint(s) . . . . . . . . . . . . . . . . . . . . . . .013 Other Products by Triumph Software. . . . . . . . . . . . . . . .014 A Comment on Quality. . . . . . . . . . . . . . . . . . . . . . .015 Triumph Software - TriDoor Documentation pg. 001 WHY USE TRIDOOR? The TriDoor communications package provides the programmer with a list of many commands and features that I have found extremely useful, if not invaluable while writing various on-line doors for both my BBS and others. No longer is the value of any door program you write hinging upon your abilities to write the communications drivers and commands to support them! Now, with communications equivelents of standard Pascal commands, such as print() which almost mirrors Turbo Pascal's write() and writeln(), you can sit at your terminal and write any program for a BBS in the same amount of time and with the same amount of effort it would take to write one for local usage! The possibilities are endless- I personally have written on-line games, archive viewing utilities, text/ansi file viewers, "top-ten" user-list creators and I am sure I few more that escape me at the moment. How many times have you said to yourself, "Wow, this is a great system I have here, if only I could add..." Oh, sure, you can go out and download many programs to do some of the things you need to do, but MANY of those you could do yourself. (And you do not have to pay all those shareware fees, either.) I can very definately say that if you are a person who registers their shareware (like I'm SURE you do) that TriDoor will pay for itself in a very short period of time. And what about all the things that you cannot do yourself? What do you do then? Hire a programmer? I frequently find myself saying "If you can't do it with TriDoor, YOU CAN'T DO IT!" It is the easiest way to create a door. If you do not know Pascal, it is worth learning, just to have this amount of control over your BBS. This is the only software package available of this kind that I have ever seen. It's easy, quick, and powerful and you are holding that power in your midst. Dare to make the doors and on-line games that you have always wanted! Triumph Software - TriDoor Documentation pg. 002 HISTORY OF TRIDOOR TriDoor and it's communications support is the end result of almost three years of effort by both Jeremy H. DuBois and myself. (Christopher M. Russo) We started one rainy day when Jeremy had informed me that he had managed to write some basic communications supporting Pascal routines. As Jeremy already had a bulletin board system running at that time, I suggested that we write an on-line game for it. And that is when it all began. We went from writing a semi-complete and not-too-awful on-line game to writing DoorBase, our first version of an on-line door supporting unit. Then I wrote a game on my own- Monopolistic Competition, followed shortly thereafter by Monopolistic Competition II which was running off of a newer, but still bedragged version of DoorBase. Then one day while trying to write a terminal program, we realized that the communcations routines that Jeremy had made were simply not fast enough to handle all the tasking necessary, and at anything above 2400 baud, were a miserable failure. Thus, Jeremy set out once again to create newer, faster routines. I had quite a lot of trouble dealing with the newer routines for reasons which, I admit, are beyond my knowlege. After time and perseverence, however, I mastered the new routines and re-wrote the newest version of DoorBase, now called TriDoor in the interest of our newly-founded company. And thus, I present to you said software and complete documentation for the easy usage and incorporation of communication and door support in your Pascal programs for QuickBBS and clones. I strongly believe that using TriDoor is the easiest, most user-friendly way of writing doors and on-line games available today. Finally, before we commence, I would like to take a moment to thank Jeremy for all his help and patience with my quirky little habits and programming nit-picks. I have never given another teacher more of a hard time than I gave him. Rediculous as this may sound, he is an inspiration to me, and I thank him for all he's taught me and all he will, undoubtably, teach me in the future. Triumph Software - TriDoor Documentation pg. 003 WHO TO CONTACT Did your machine swear in protest at our software? Are you missing files that should be included in this release? Do you have any questions you would like to ask us? Do you have any comments or suggestions? Do you get frustrated with document files? Well, then- you may get in contact with us at any of the following places/numbers : Christopher M. Russo Voice : (508)264-4376 Jeremy H. DuBois Voice : (508)263-7004 Triumph BBS Data : (508)263-4247 * If you call our BBS (best way to get in touch with either of us) our handles/positions are as follows : Christopher M. Russo, a.k.a. "Seymoore" (SysOp) Jeremy H. DuBois, a.k.a. "Particle Man" (Co-SysOp) Remember that those voice phones are our HOME phones as we do not yet have a business line- please refrain from hassling the other people that live there- NONE of us will answer "Hello, Triumph Software." We will tell you when we get the business line. Also note that it is MUCH easier to get in contact with me, Chris Russo during the school year then it is to get in touch with Jeremy. We are also looking out for potential support boards and beta-testing systems, so if you have a system and are interested, make sure you inform us of your desire and eligibility. Triumph Software - TriDoor Documentation pg. 004 TESTED LIMITS OF TRIDOOR TriDoor has been run and tested, successfully, on a variety of systems ranging from a 15MHz IBM XT with a 2400 baud modem to a 25MHz 386 with a 9600 baud HST modem. As far as we know, if your system is fast enough to handle your modem, this unit will function without a hitch. There are a few limitations, however, that we are aware of at this point in time, and we are working on remedies for said limits. The constraints are as follows : * The only communications ports supported are COM1 and COM2. * The Turbo Pascal commands of blockread and blockwrite will do awful, unfreindly things. DO NOT USE THEM until we have made a correction to allow for this problem. Those are all of them as far as we are aware. If you come up with any new ones, please contact us immediately and we will either tell you what you are doing incorrectly or remedy the problem in a later version. Triumph Software - TriDoor Documentation pg. 005 FEATURES OF TRIDOOR TriDoor has many advanced, easy to use features and I intend to add many more over the course of time. Any additional features will be tacked on to the actual program commands explanations with their appropriate version numbers. This document was originally written for the release of Version 1.10 of the software. * Automatic set-up and support of communications ports. * Automatic reading and processing of the file DORINFO1.DEF. * Easy to use commands such as PRINT and GETINPUT which will print to the local screen, and the comport if a carrier is detected. * Built-in chat mode with word-wrap and highlighted user- entered text on the local screen. * Boolean variable QUIT which is set to true if ALT-H is hit from the local keyboard- allows for programmer-defined or non-existant "hang-up" procedures. * Easy "caps-lock", and "password-entry" (see "***" instead of "hey") modes. * Length restriction allowance on input fields. * Built-in string capitalization and easy integer/longint to string conversion. * Built-in direct screen write functions. * Automatic status bar displaying time, name and baud rate. * Automatic handling of user's time. * Built-in routines for clearing user's and local screen. * Built-in boolean response "Are you sure?" function. V1.26 * Built-in User-Pager. V1.26 * Automatic & Disablable "Last Printed" Memory. V1.26 * Help Status Bar on Local Screen. V1.28 * Auto-sensing of color/monochrome mode. V1.30 * Turbo Pascal 5.5 AND 6.0 support. V1.38 * ANSI Support. V1.40 * User time changeability. V1.40 * Auto-hangup (quit:=true) at time<1 (can be disabled). V1.40 * System messages in status bar. Triumph Software - TriDoor Documentation pg. 006 COMMAND SUMMARY <01> function offline : boolean; This function simply returns the value TRUE if a carrier in the assumed communications port is not detected, and false if a carrier is detected. <02> function strg( i : integer ) : string; This function will turn any integer into a string and return the value to the caller. <03> function bstrg( li : longint ) : string; The bstrg() function is identical to the strg function with the exception that it will accept longints. <04> function ucase( s : string ) : string; This function will take any string s, capitalize it and return it to the calling function. <05> procedure gotopos( x, y : integer ); The procedure gotopos() is the direct screen write equivelent of the Pascal command gotoxy(). It is necessary to use this command with the following two commands. <06> procedure dwrite( outchr : char; attr : integer ); The dwrite() function will do a direct screen write of the character outchr with the attribute (color) attr at the position x,y of the previous function gotopos(). <07> procedure dstr( outstr : string; attr : integer ); This procedure is identical to dwrite() with the exception that it allows a string to be written as opposed to just one character. <08> function comwait : boolean; This will tell you if there is a character waiting in the input buffer of the communications port waiting to be read. <09> function readstats : boolean; The readstats() function will read and process the file DORINFO1.DEF. In unregistered versions, this command is forced. Triumph Software - TriDoor Documentation pg. 007 <10> procedure recordtimeon; This function records the time that the user enters the program. This is necessary if time management is to take place. In unregistered versions, this command is forced. <11> function timeleft : integer; This function will calculate and return the time the user has left for a given session. <12> procedure clearcom; The clearcom() procedure will send an IBM clear screen control code over the modem as well as to the local screen. <13> function getkey : char; This function will wait for a key to be pressed either locally, or over the communications port if a carrier is present. <14> procedure chat; The chat() procedure is called when ALT-C is pressed locally. It can be called at will, however, to allow for user-paging of the SysOp if so desired and programmed. <15> function getinput( wrdsize : byte ) : string; The getinput() function is similar to getkey() except that this function allows for a string to be entered. The following variables also apply : caps := TRUE/FALSE -- will convert all typed to uppercase if true. code := TRUE/FALSE -- will show all characters typed as *'s if true. wrdsize := n=(1-255) -- will limit length of user input to n. Note that in unregistered versions, these are automatically set to the following values every time you finish a getinput() call. code := FALSE / caps := FALSE Triumph Software - TriDoor Documentation pg. 008 <16> procedure print( s : string ); The print() procedure will print a string to the local screen, as well as to the communications port if a carrier is detected. To create a carriage return, simply plug in a || anywhere in the string to be printed. For example... print('My name is george.||Who are you?||||BLAH! '); would print... My name is george. Who are you? BLAH! ( <-- cursor would remain here! ) NOTE : When plugging variables, substitue +'s where you would normally place ,'s in a write()/writeln(). For example... print('My name is '+mynamevar+'.||'); Also note that as of V1.26 there is a boolean variable called QUEUEOFF. If this variable is set to false, the print() command will always remember the last thing printed. (Comes in handy when exiting chat-modes and so-forth.) The variable that the last thing printed is stored in is QUEUEONE. (a string) <17> function aysure( s : string ) : boolean; This function will print the string s followed by a "? (Y/[N]) " and then wait for a response, returning a boolean TRUE or FALSE meaning YES or NO respectively. <18> procedure sysmessage( s : string ); This procedure will print a string of up to 65 characters in the status bar for the SysOp or local user to see. Triumph Software - TriDoor Documentation pg. 009 <19> procedure comprint( s : string ); The comprint() procedure is identical to print, except that it prints SOLELY to the communications port. <20> procedure angotoxy( x, y : integer ); This is the ANSI equivelant of the Pascal procedure gotoxy(). If ANSI is disabled, this function will NOT work. <21> procedure anleft( ls : integer ); This is an ANSI procedure that will move left the number of spaces specified in the variable ls. <22> procedure anright( rs : integer ); This is identical to anleft() except that it goes right instead of left. <23> procedure anclear; The anclear() procedure is the ANSI equivelant of clearing the screen. Like all ANSI functions and procedures, this does not function if ANSI is disabled. <24> procedure ancolor( bl, br, fg, bg : integer ); This function will set the ANSI color. Use the following specifications to set it : bl = blinking? 0 = no 5 = yes br = bright? 0 = no 1 = yes fg = forground color bg = background color 37 : white 47 : white 36 : cyan 46 : cyan 35 : purple 45 : purple 34 : blue 44 : blue 33 : yellow 43 : yellow 32 : green 42 : green 31 : red 41 : red 30 : black 40 : black Triumph Software - TriDoor Documentation pg. 010 RESERVED WORDS The following list of words are reserved (used by TriDoor) and not to be re-defined by any program incorporating TriDoor as a conflict will arise that will result in non-functionability, to some degree, of the final resultant program/software. tridr55? userstatrec sysstatrec user sys scrnpos wrdsize local logontime code quit caps waitk tdver tddate CR BS offline strg bstrg ucase dwrite gotopos dstr statusbar readstats recordtimeon timeleft clearcom getkey chat checkkey getinput print aysure setup buffptr buffrec noise comintvect queueoff timeoff comchar key queueone buffertop head tail oldint exitsave IER IIR LCR MCR LSR MSR RLS RDA TRE MSI PIC EOI picmask enable1 enable2 disable1 disable2 bioseg keyhead keytail EVEN ODD NONE COM1 COM2 COM3 COM4 IRQ2 IRQ3 IRQ4 setupcom setparams carrier shutdowncom setupbuffer charready readcom writecom comstr clearbuffer finishcom screnmode getmode autohang ansi sysmessage comwait anleft anright angotoxy ancolor anclear This list will be updated as necessary, noting appropriate version numbers with their corresponding added words. Due to the nature of Turbo Pascal, all words are considered reserved both in capitals and in lowercase letters. Triumph Software - TriDoor Documentation pg. 011 ACCESSABLE VARIABLES Here is a list of accessable variables and their descriptions. You may work with these as you like at any time during program operation. I would, however, avoid changing them as much as possible. type userstatrec = record firstname, User First Name lastname, User Last Name citystate : string[40]; User City, State comport, User Comport baud, User Baud refnum, [ not yet implemented ] security : integer; User Security time : word; User Time Left end; sysstatrec = record name, System Name sysopfirst, SysOp First Name sysoplast : string[40]; SysOp Last Name end; var user : userstatrec; Record to access userstatrec sys : sysstatrec; Record to access sysstatrec code, See *'s at getinput() caps, Force caps at getinput() queueoff, Turn off print() queue timeoff, Disable Time Left readout ansi, Turn ANSI graphics on autohang : boolean; Turn on quit:=true at time<1 queueone : string; Store for print() command So, for example, if you wanted to know the user's baud rate, you would look at user.baud- NOT userstatrec.baud. Triumph Software - TriDoor Documentation pg. 012 THINGS TO COME ("THE WORKBENCH") The following is a list of some of the things that are most likely going to be added in future versions of this software. Or they are things that we are, at the very least, seriously considering. This is a far from complete list, but it gives you an idea of what I am up to. If you have any further ideas or suggestions, please contact us and tell us what you think. * Built-in ANSI capabilities. * Config file for directory paths/chat color settings/etc * Highlighted chat text over modem as well as locally V1.28 * Auto-sensing of color V1.30 * Turbo Pascal 6.0 support (pending the arrival of 6.0) * Support for other BBSes such as PCBoard and Fido V1.26 * Incorporation of communications routines directly into TriDoor unit * COM3 and COM4 support V1.26 * Help menu un status-bar for local screen * Ability to force-capitalize first letter of every word in getinput() function * Ability to access all communications commands in main communications unit V1.26 * Ability for SysOp to Page User Triumph Software - TriDoor Documentation pg. 013 PROGRAMMING HINT(S) Here are a few ideas to get you going. TriDoor is written very flexibly to allow for you to do essentially as you like with the commands and to even make new commands out of the original ones and some work of your own. However, due to the flexibility involved, some things may seem confusing, or just not occur to you right away. Over time, as I think of these things, I will place them in this area. * Do you want the SysOp to see something that the user will not? Simply use a writeln() instead of print(). It's always good to make it obvious to the SysOp that the user is not seeing that text, though! A standard way of doing this is by using a small ANSI block before the text and high-lighting it. * If you are going to use the status-bar, make sure that you recordtimeon() (preferably before statusbar()) or you may get a very ugly number in the "Time Left :" area. * If you make a door that supports ANSI make sure to ask the users if they can use ANSI first- keep a log file with their settings to save them from answering everytime they use the door/on-line game. * Try not to exclude non-ANSI users from your door. It's a sign of a lazy/unthinking programmer. Better than 35% of BBS users DO NOT have ANSI capabilities- don not limit yourself and your program! * Always remember that a quick, efficient, well-written program that does not do much is better than a slow, sloppy, poorly- organized one that does more. * Remember that many bulletin board systems run better if they stay in memory while dropping to dos to run a door, and many systems do not have more than 640k-1 meg of RAM. If your program requires more, try to break it up into pieces to run more efficiently. If you have an update program that needs to be run but once per day, make it a seperate one. Triumph Software - TriDoor Documentation pg. 014 OTHER PRODUCTS BY TRIUMPH SOFTWARE The following products are also available from Triumph Software. For more information on these products or specific consulting services, please contact us. TriComm . . . . . . . . . . . . . . . . . . . .Registered : $30 TriComm is the original communications unit compiled for Turbo Pascal 5.5 and used in the creation of TriDoor. It currently supports COM1 and COM2 and runs at all baud rates. (Has been tested up to over 9600 baud) TriUser . . . . . . . . . . . . . . . . . . . .Registered : $25 TriUser is an on-line QuickBBS user editor written using the TriDoor on-Line door support unit. It also takes advantage of TriDoor's ANSI support features. Monopolistic Competition II . . . . . . . . .Coming This Spring Monopolistic Competition II is the latest craze in on-line Space Trader games. It combines all the thrill of making money, with the additional spice of semi- intelligent Interstellar Police, free-roaming traders and a sarcastic and greedy god named Victor. Triumph Software - TriDoor Documentation pg. 015 A COMMENT ON QUALITY To finalize, I would like to take a moment to voice my thoughts on quality in programs and programming. I have spent over eight years working on and with bulletin board systems, an equal amount of time programming both at an amateur and a professional level, and three years or more programming for bulletin board systems. In that time I have seen many doors and many bulletin board systems, and I have noticed so many sloppy doors and on-line games that if I had a computer for every one I have ever seen, I would be able to put them together and form a top-of-the-line VAX with tint-control, a built-in microwave and a television. I can't tell you how many times I have run a program and then been asked, infuriatingly, "Cannot find BRUNxx.EXE. New Path?" or found that a program would literally crash inside of two minutes of operation on any machine that I could try it on. And all the programs that I saw grinding away at the disk-drive as they either accessed a massive load of disorganized data or simply were running in the slowest possible languages and needed three days to load 360k of marginally organized data. Then there were the programs that simply crashed without a peep, or crashed and threw some sickening statement like "KILLROY DEATH NOTICE #093284AF84UAREDEAD" at you as you sat in bewilderment. Well, I would gladly trade in my suped-up VAX for an opportunity to scream very loudly at every single one of those programmers and then throw a programming etiquette book at them. I am the pickiest person on earth when it comes to programming, so you can be assured that any product that you ever get from Triumph Software has been brutally cirticized and abused to make sure it is doing everything it should be doing, doing it well, and then some. If I missed something, I will be ever amazed, but I assure you that I literally don't sleep until the problem is fixed. (Helloooo, coffee!) I hope you enjoy this and all of our programs and find them easy to use and well-written. If you have suggestions or complaints, please contact us/me as we/I are/am always happy to hear them and try to incorporate them. Happy Programming! -Christopher M. Russo