The World of Computer Software

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

/ The World of Computer Software / World_Of_Computer_Software-02-386-Vol-2of3.iso / b / bbskt20e.zip / BBSKIT.DOC < prev next >

Wrap

Text File | 1992-05-06 | 74KB | 1,875 lines

BBSkit version 2.00 Communications toolkit for Turbo Pascal by Steve Madsen Copyright BBSkit, associated utilities, source code, and documentation are copyright (c) 1991, 1992 by Steven Madsen. All rights reserved. Other brand and product names are trademarks or registered trademarks of their respective holders. Shareware Policy This software is provided to you subject to the terms and conditions of this agreement. In the event that you cannot accept these terms and conditions, you must destroy all copies of the software you have made. BBSkit is being distributed under the shareware (try before you buy) system to insure that users have a fair chance to see if this product will suit their needs before having to spend money on it. I feel that this is a good way to distribute new software of use to programmers. If you use this product and find it a good thing to keep around, you are expected to register the package with the author. Registration is currently $40 in United States funds. You may pay by check or money order (payable to "Steven Madsen") by sending a printed copy of ORDER.FRM to: Steven Madsen 1888 Edith Marie Drive Beavercreek, OH 45431-3377 Please remember to specify 5.25" or 3.5" disk media. Registration entitles you to free technical support, a printed manual, source code, example code, and low cost upgrades. Chapter 1: Introduction to BBSkit About this manual Welcome to BBSkit! As the author of this package, I feel that you have purchased the most powerful unit available to Turbo Pascal programmers who wish to manipulate their serial port hardware in any way they wish. BBSkit makes it realistic to start drafting plans for a BBS or terminal program to suit your particular needs. Many hours of work have gone into making BBSkit a well-written, well-documented and well-supported shareware package. This manual is designed with getting you off the ground and programming with BBSkit as quickly as possible. Note: this shareware version of the manual is actually just a scaled-down version of the real manual. The real manual will include all of the chapters and appendices listed in this introduction. Chapter 1 provides a brief overview of the BBSkit package and the style conventions that will be used in this manual. Chapter 2 provides a basic introduction to telecommunications and describes the need for software in today's world of telecommunications. Chapter 3 gives a brief introduction to object oriented programming as it is used by a BBSkit programmer. Objects make it possible for your programs to do a lot in very little code, and makes it easier to maintain such programs. Chapter 4 presents some ideas on the development of a BBS application with BBSkit. Design of a BBS application is covered in-depth in this chapter to give you a good idea about what is needed in a solid BBS package. Chapter 5 presents some ideas on the development of a terminal application. Terminal programs are used worldwide to connect to a variety of systems, not just BBSes. This chapter focuses on some of these design ideas. Chapter 6 presents the BBS Session Protocol, which will radically change your views of how a user-to-host session is serviced. BSP functions allow you to bring graphically oriented interfaces to your remote users when they are also running BSP- aware terminal packages. Chapter 7 provides an alphabetical listing of all of the methods provided in the BBSkit Turbo Pascal unit. Chapter 8 provides an alphabetical listing of all of the methods provided in the objects contained in the Protocol unit. Chapter 9 provides an alphabetical listing of the procedures and functions supplied in the BBSkit unit. These are the heart of communicating with your serial port. Appendix A gives an very in-depth presentation of programming interrupt driven serial communications under Turbo Pascal. This appendix is provided to help make the source code a little more understandable. Appendix B covers the EmuMaker utility, which is used for maintaining emulation templates used during a session with a multitude of host computers, from ANSI capable BBSes to VT-100 mainframes. Appendix C is a glossary covering terms used in the telecommunications field. If you don't know what a word or acronym means, try looking in here. Appendix D discusses how to go about contacting Technical Support if you have problems with BBSkit. Appendix E is a simple table of ASCII values. The following tools were used to create BBSkit and the documentation: o Turbo Pascal v6.0 from Borland International o Turbo Assembler v2.0 from Borland International o Microsoft Word for Windows v2.0 Style conventions This manual will make use of some style conventions throughout the text which you should be aware of. Some of this text is merely for information, while other text may mean serious trouble for certain situations. Indented text shows something that will appear on your screen, example program text, or text your should type into your computer. The purpose of BBSkit Ever since I became involved with telecommunications in the mid 1980's, I have been very interested in writing applications that work with the serial port. Particularly, I like writing bulletin board systems. The only problem was that I found no communications packages that met my standards, which included being usable under Turbo Pascal 6.0. Thus, BBSkit was born. My main idea in creating BBSkit was to provide the most seamless environment for a BBS author to create his or her application. BBS applications require certain things that terminal programs do not, such as being able to route input and output, having support to handle all kinds of terminals, from slow terminals requring nulls to keep up with transmission to new ones that have advanced terminal emulation as standard equipment. Users have grown along with the technology. They want power, speed and beauty in the systems that they frequent. But the most important thing was creating a toolkit that would meet my needs, and also meet those of people like me that were having the same difficulty finding toolkits that would do the job for them. Think of BBSkit as a shell program. Everything you need to use your modem or communicate through your serial port is already there. You can route input and output, send and receive files, emulate over 10 different terminals. Now you can concentrate on writing your application, not on communicating with your serial port. What's new in version 2.0? Version 2.0 is a tremendous enhancement to the original package. Version 1.0 was robust when compared to many of the other shareware or freeware packages I still find on systems today, but 2.0 will easily surpass that. With 2.0 I have added more complete VT-100 style terminal emulation directly into the package. This means no more ANSI.SYS! All of the file transfer protocols have been recoded and are now much easier to understand since the source follows the same style as the main units. Ymodem and Ymodem-G have also been added to our list of protocols. To keep things more close to home, I have rewritten my serial support in 100% assembly language. You no longer need a FOSSIL driver to communicate with your system, and that reduces the amount of memory taken up by device drivers and leaves more for your app. Of course, as a registered user, you have all of the source code to BBSkit available on your registration disks. Perhaps the most important announcement comes in the form of the BBS Session Protocol. Lately everyone has been going crazy over the incredible changes user interfaces are going through. Mouse support is becoming standard, graphics are being found everywhere. And Windows is responsible. Well... wouldn't it be great to have this kind of support over a normal telephone line? BSP gives it to you! Mouse support and graphics, in a form of terminal emulation that can be used in conjunction with any of the provided templates. Now you can add mouse and graphics support to your app, and the remote end will take advantage of it if it can. Otherwise, the user will experience no change from a normal session. Where's Zmodem? Some of you who saw or used the first version of BBSkit may be wondering where Zmodem is in the new package. The reason is actually quite simple, although it is a very disappointing one. During the development of BBSkit 2.00 I looked long and hard for the latest Zmodem specifications, to be assured that my users would receive the latest Zmodem implementation, coded according to Omen Technology's most current Zmodem documentation. I became very disappointed when I could not find any recent specifications on local BBSes, or anywhere in the world through Internet ftp access. This led me to actually call Omen's BBS a few times, searching diligently for these specifications. I could not find any later than 1987, and these were done in the typical Omen fashion, which pretty much kept me from doing a good implementation of their protocol. To top things off, when I read through Omen's BBS, I found something called the Zmodem Developer's Kit (which convienently comes with C source code!). Apparently Omen has taken Zmodem out of the public domain with their introduction of MobyTurbo. So, sorry, but Zmodem is not going to be included in this (or probably any future) release of BBSkit. If you don't like this (I don't), please complain directly to Omen Technology, because I cannot do anything about it from where I stand. As the author of whatever software you write using BBSkit, I would suggest that you do your utmost to promote Ymodem-batch. This protocol is fast, safe (CRC-16 error checking) and probably more efficient than Zmodem. The reason for this is that Zmodem is one of those "do everything" protocols, so it tries to make file transfers safe across all platforms. This includes packet switching networks which gobble up certain characters. Zmodem protects these characters by prefixing them. The problem is that it turns one offending character into two non-offending characters, which slows down the overall speed of the transfer. Ymodem doesn't even try to do this, so it sends all characters as they are, which can speed up transfers. Plus, you still get batching capability. The only thing you lose is transfer recovery, but this could be fixed with a proprietary protocol for all BBSkit applications. If there is any interest in such a thing, please let me know. I would make all specifications public domain and implementations of the protocol royalty free, without the complexity of Zmodem. Chapter 7: BBSkit Method Listing This chapter will do its best to provide complete information on every method available in the TBBS object. In general, they will all follow this format: Dummy1 Declaration: PROCEDURE Dummy(Variable : Integer);2 Dummy does something useful.3 See Also: Something.4 1: Name of the method. 2: Formal definition in Pascal format. 3: Brief description. 4: Other methods which may be of interest to this one. Init Declaration: CONSTRUCTOR Init; Init sets up the TBBS object for use. It resets several internal variables, clears out some memory allocated to arrays, and fixes up the virtual method table. Init must be called in every application that uses TBBS, or your system will lock up. Code contained in Init should be "do once" code. That is, code in Init should not be called more than once, only when Init itself is called. Don't call Init multiple times to get something done. This method can be overridden without a virtual clause because it is a constructor. Descendant objects should still call TBBS.Init within their Init constructors. See Also: Done, Run. Done Declaration: DESTRUCTOR Done; VIRTUAL; Done is the general destructor method for the TBBS object. If the communications port is still open, it will close it as well as deallocate internal variables. Done, like Init, should be called in every application that makes use of TBBS. Code in Done should only be shutdown code, and should be executed only once each time the application is run. Descendant objects should call TBBS.Done in their Done destructors. See Also: Init, Run. Run Declaration: PROCEDURE Run; VIRTUAL; Run is an empty method designed to be used by all descendant TBBS objects. All time spent between Init and Done should be spent somewhere in Run. Descendant objects do not need to call TBBS.Run, as it doesn't do anything. See Also: Init, Done. AddIntChar Declaration: PROCEDURE AddIntChar(Code : Char); AddIntChar will add the character Code to the internal list of characters which can interrupt a TypeFile call. When TBBS.Init is called, the internal list, which is maintained by a simple set of char, is empty. This means that no characters can interrupt the output. This is not always desireable in situations such as outputting menu, or reading messages. The user may wish to get a jump on things and just get to the next part of his session. Depending on the value of the boolean variable CaseSensitive, AddIntChar('A') and AddIntChar('a') may or may not do the same thing. The only output that can be stopped by one of these keys is a file being dumped to the console/modem with TypeFile. Other methods, such as ComWriteLn, are not affected in any way. See Also: ClearIntChars, SetCaseSensitivity, TypeFile. AddVirtualKey Declaration: PROCEDURE AddVirtualKey(Code : Char); AddVirtualKey is used to maintain the list of keys that the local console can handle to do special things while a user is online with your system. All keys that are handled through the HandleVirtualKey method must first be defined by a call to AddVirtualKey. Legal keys are those found in the back of your Turbo manuals. These keys are also known as extended keys. Examples are the arrows, F1 through F10, and any Alt- key combination. Typically, these kinds of keys should be used to change what is happening in the user's session. On a BBS, you could have the up and down arrows adjust his time limit without his knowledge. Alt-C, for example, could enter into your chat routine. Alt-L could instantly logoff an offending user. The possibilities are limited only by the number of keys you can define and the functions you code for them. These keys are always active during any kind of input that BBSkit is told to accept. The code to figure out what to do with a virtual key is contained in ComReadKey, which the base method for accepting input of any kind. Note that if you call one of Turbo's input procedures, such as ReadLn, BBSkit has no way of intercepting virtual keys. See Also: ClearVirtualKeys, HandleVirtualKey. CarrierLost Declaration: FUNCTION CarrierLost : Boolean CarrierLost easily checks to see if the comport has lost carrier since the last time you checked. This is much different than checking to see if the line has a carrier, because CarrierLost will not bomb if there was no carrier to begin with. It only returns a true value if a carrier was not found when it previously existed. This is done by checking one of the UART registers, which maintains a "delta" data carrier detect bit. If this bit is true while the data carrier detect bit is false, we've lost carrier because the state has changed from true to the current false. Therefore, someone hung up on us. Checking these bits is done in the internal assembler routine. When such a situation occurs, it sets a bit in the ErrorFlg variable, which is then checked and reported by CarrierLost. See Also: Carrier (procedural). ClearIntChars Declaration: PROCEDURE ClearIntChars; ClearIntChars wipes the internal list of of interruptable characters. This is the equivalent of executing IntChars := []. After this call, a call to TypeFile cannot be interrupted by any characters coming in from the console or comport. See Also: AddIntChar, TypeFile. ClearVirtualKeys Declaration: PROCEDURE ClearVirtualKeys; Clears the internal set of virtual keys. This simply causes no extended keys to be handled, and are passed straight through ComReadKey. Their values will be returned exactly like Turbo returns them in ReadKey (#0 followed by their code). See Also: AddVirtualKey. ClosePort Declaration: PROCEDURE ClosePort(LowerDTR : Boolean); VIRTUAL; Closes down the comport if it has already been opened by calling the shutdown procedure DeInitPort. If LowerDTR is true, the DTR line will be lowered before shutting the port down. DTR is usually kept high if the connection should be kept active after the application has been terminated. Most new modems will interpret a low DTR line as a command to make sure the modem is on-hook, and will hang up the phone line. See Also: OpenPort. Cls Declaration: PROCEDURE Cls; VIRTUAL; Cls clears the screen on the local end and the remote end. This method may not always be successful when clearing the screen on the remote end if the remote terminal does not understand a formfeed (#12) character as a clear screen code. Most terminals, including the TTY template supplied with BBSkit, do understand this code. ComReadKey Declaration: FUNCTION ComReadKey : Char; VIRTUAL; ComReadKey will wait for a keypress to come in over one of the allowed input devices. These are defined by the SetInput method. ComReadKey will handle virtual keys that have been defined with AddVirtualKey as well as inactivity timeouts if they have been enabled. See Also: AddVirtualKey, ComReadKeyE, SetInput, SetTimer. ComReadKeyE Declaration: FUNCTION ComReadKeyE : Char; VIRTUAL; This method performs the same function as ComReadKey, but when a key is finally received it is outputted using ComWrite. The two methods do not differ except in this respect. ComReadKeyE still checks inactivity and virtual keys. See Also: ComReadKey. ComReadLn Declaration: PROCEDURE ComReadLn(var Inp : String; Max : Byte); VIRTUAL; ComReadLn is the BBSkit version of ReadLn. ComReadLn is enhanced in many ways over the standard ReadLn provided in Pascal. Perhaps the most obvious is the second parameter, Max. This byte value determines the maximum number of characters to accept on the input line. When the maximum is reached, further characters will be discarded until one of the previously accepted ones is deleted using the backspace key. The following characters have special meaning when used somewhere on the input line: #8, Control-H: Backspace (erases previous character) #9, Tab: Advance to next tabstop (modulo 8) #12, Enter: Terminates current input line #24, Control-X: Erase line and start over Only backspace, enter, and control-X are permitted when the maximum input length has been reached. Other control characters in the range [#0..#31] not defined here are ignored and discarded. All other characters in the range [#32..#255] are accepted without question and placed in the input line, provided there is room for them. ComReadLn is subject to the same input restrictions that ComReadKey has. See Also: ComReadKey, ComReadLnWrap. ComReadLnWrap Declaration: PROCEDURE ComReadLnWrap(var Inp : String; Max : Byte; var Wrap : String); VIRTUAL; ComReadLnWrap is a modified version of ComReadLn intended specifically for line based editors. ComReadLn will not permit any input past the Max value passed in the parameter list. ComReadLnWrap improves on this idea when used in a line editor format by saving the last incomplete word in the additional variable Wrap. When called over and over, this method is used to perform word wrapping at the margin, which is defined by the Max variable. The following example shows how word wrap is done. The user can type all he/she wants, without having to press [Enter] at the end of each line, until a blank line is entered. Var Inp, Wrap : String; begin Wrap := ''; Repeat ComReadLnWrap(Inp, 79, Wrap); Until (Inp = ''); end; There are two things that need to be quickly pointed out. First, note that Wrap is initialized to a null string ("") before the first time ComReadLnWrap is called. What actually happens inside ComReadLnWrap is that whatever is contained in Wrap at the beginning of the call is actually placed into Inp as the first few characters. When the margin is reached (in this case, 79), ComReadLnWrap searches back for a character allowed to break a line, such as a space, and places everything to the right (but not including the break character) into Wrap for the next call to ComReadLnWrap. It may occur to you that you could use this method for prompting the user with default values for various things, such as a default subject in a message. This would work great, but the only problem is that if the user typed too far, the last bit of his typing would be lost due to ComReadLnWrap trying to wrap this text. This may or may not be reasonable for your application. The possibility is there, however. See Also: ComReadLn. ComWrite Declaration: PROCEDURE ComWrite(Strn : String); VIRTUAL; Outputs a string of text exactly like Write to the output device(s). The output devices are controlled with the SetOutput method. See Also: ComWriteLn, SetOutput. ComWriteLn Declaration: PROCEDURE ComWriteLn(Strn : String); VIRTUAL; Outputs a string of text exactly like WriteLn. ComWriteLn is also subject to the same output restrictions that ComWrite has. ComWriteLn is actually just a call to ComWrite: ComWrite(Strn + #13#10); If this causes problems on your system or for your users (such as a blank line always between two normal lines), then override this method to only tack on a carriage return character (#13) instead of the carriage return/line feed combination (#13#10). See Also: ComWrite. Dial Declaration: PROCEDURE Dial(Number : String); VIRTUAL; Attempts to dial Number by sending a Hayes-style ATD command to your serial port. A modem is expected to be on the other end to receive and execute the command. Please note that it does not specify tone or pulse dialing. If you need to do this, place a T or P before the number for tone or pulse, respectively. If your modem is not Hayes-compatible, please override this method to give specific support to your modem. See Also: SendAT. FilterWrite Declaration: PROCEDURE FilterWrite(Strn : String); VIRTUAL; Writes Strn to the console screen only, after first passing it through the emulation filter defined by the record Emu. Emu contains the legal codes for several emulation functions. When a string matching one of these functions is passed through FilterWrite (and it must match exactly), then the function is executed instead of the characters simply being written to the screen. Please note that the emulation supported by BBSkit is rudimentary. BBSkit is primarily concerned with giving a base for writing communications applications. There are some terminals, such as the VT-100/102/220/320 that have many commands that are not supported by BBSkit. Most of these deal with setting modes not supported by BBSkit. If your application needs to support these codes, you are responsible for them. Also, there can be more than one code contained in the string sent to FilterWrite. As long as the codes are legal, they will be interpreted. FilterWriteLn Declaration: PROCEDURE FilterWriteLn(Strn : String); VIRTUAL; Performs the same function as FilterWrite, but also appends a CR/LF to the end of the string. See Also: FilterWrite. GetAnswerMode Declaration: FUNCTION GetAnswerMode : TAnswerMode; Returns the answer mode that was previously set using the SetAnswerMode method. The default value is originate mode. The answer mode only affects the way that the modem is told to answer the phone when a call to PickupPhone is made. See Also: PickupPhone, SetAnswerMode. GetInput Declaration: PROCEDURE GetInput(var Con, Rem : Boolean); Returns boolean variables defining whether or not input is accepted from the two devices. If Con is true, input is allowed from the console. If Rem is true, input is allowed from the comport. See Also: SetInput. GetOutput Declaration: PROCEDURE GetOutput(var Con, Rem : Boolean); Returns boolean variables defining whether or not output is directed to the two devices. If Con is true, all output routed through ComWrite or ComWriteLn is also put to the console screen. If Rem is true, all output will go to the comport. See Also: SetOutput. HandleVirtualKey Declaration: FUNCTION HandleVirtualKey(Code : Char) : Boolean; VIRTUAL; HandleVirtualKey is designed to allow you to define virtual keys for use during any session and to handle them using code of your own choosing. HandleVirtualKey will be called whenever any extended key is found at the local console which matches one of the virtual keys BBSkit knows about. The default HandleVirtualKey method is empty because no virtual keys are defined in the TBBS object. It is up the programmer to override this method and provide support for virtual keys that the application defines. The return value of HandleVirtualKey is important. It determines whether the current input session should be terminated or not. For example, if you are just changing the time left for a user's session, you want to return False from this method. If are actually interacting with the user or part of your BBS, you will want to return True. In general, if there is any chance that the user's screen has changed in any way during the handling of your key, return True. Otherwise return False and the user won't know anything happened. Hangup Declaration: FUNCTION Hangup : Boolean; VIRTUAL; Attempts to hangup the modem. It first attempts to hangup using an on-to-off transition of DTR. Most new modems are capable of recognizing this DTR transition by issuing the command ATX3 to the modem. If this fails to hang the modem up, Hangup will send the attention sequence (+++) to the modem, followed by the hangup command (ATH0). If this still fails, your modem will probably require some special tweaking. Hangup can be overridden to provide support for tempermental modems. The return value is not Carrier. Hangup returns the false (failed) value if there is still a carrier after trying to hang the modem up. It returns true if there is no carrier present and the line is clear. Hangup also resets the inactivity error bit in ErrorFlg. See Also: Dial. Incoming Declaration: FUNCTION Incoming : Boolean; Returns true if any keys are present at the allowed input devices. If console input is accepted, it checks Keypressed in the CRT unit. If modem input is accepted, it checks ReceiveBufferEmpty. If either of these are true, Incoming is true. See Also: Keypressed (CRT), ReceiveBufferEmpty (procedural). IntegerVal Declaration: FUNCTION IntegerVal(Strn : String; Index : Byte) : Integer; Converts the two bytes starting at Strn[Index] into a full integer value. These two bytes are actually the high and low bytes in character form, high byte first. This method is primarily used by BSP but can be used by other applications for whatever purpose you wish. See Also: SendInteger. LoadEmulation Declaration: FUNCTION LoadEmulation(Fname : String) : Boolean; Loads the emulation template defined by Fname. Fname can be any filename, but should be a valid emulation file if you don't want strange things happening. LoadEmulation returns true if the file was loaded without errors, false if the file could not be found. See Also: LoadEmulationLib. LoadEmulationLib Declaration: FUNCTION LoadEmulationLib(ID, Fname : String) : Boolean; Loads the emulation template stored as ID in the file Fname. If Fname is not found or the ID isn't in the file, a false value is returned. If the emulation template is loaded without errors, true is returned. See Also: LoadEmulation. OpenPort Declaration: FUNCTION OpenPort(Comport : Byte) : Boolean; Opens the specified comport by calling InitPort at setting up some default values. By default, the port is opened at 2400 bits per second, 8 data bits, 1 stop bit, no parity. Input and output buffers are set to 2048 bytes each. No flow control is enabled. See Also: ClosePort. PickupPhone Declaration: PROCEDURE PickupPhone; VIRTUAL; Attempts to pick the phone up by issuing the appropriate command to the modem. You can set originate or answer mode by calling SetAnswerMode. PickupPhone supports Hayes-compatible modems (those with the AT command set) only. If you have a non-standard modem, please override PickupPhone to provide support to your modem. If the answer mode is set to answer, the answer carrier tone will be sent across the phone line. Otherwise, the modem will attempt to connect with the remote modem by issuing the dial command with no number. See Also: SetAnswerMode. SetBSP Declaration: PROCEDURE SetBSP(Level : Byte); Sets the allowed level of BSP according to the Level mask. Level is constructed according to these rules: bit 0: 0=no support for BSP; 1=buffering support bit 1: 0=no mouse; 1=mouse available bit 2: 0=no graphics; 1=graphics (EGA+) available Buffering includes the most basic functions of BSP including simple file transfers and spooling disk files directly to the screen for very fast text display. Graphics are only supported if a high resolution mode (640x350 EGA) or better is found. The only exception is the 256 color 320x200 mode found in VGA cards, which is also supported due to the higher number of colors available and the fact that the high resolution 640x480 mode is also available. BSP is only available in the registered version of BBSkit. See Also: BSP_xxxx methods. SetCaptureFile Declaration: PROCEDURE SetCaptureFile(Path : ComStr); Sets the default file pathname for any capture to disk commands. If disk capturing is set, all characters displayed by the ComWrite and ComWriteLn methods will be sent to the disk file for a permanent record. This method does not actually turn disk capturing on. SetCaptureStatus either opens or closes the file defined by this method. The default file is CAPTURE.TXT, and is placed in the current directory. See Also: SetCaptureStatus. SetCaptureStatus Declaration: PROCEDURE SetCaptureStatus(Status : Boolean); Either turns on disk capturing, turns it off, or does nothing. If disk capturing is not on, and Status is true, disk capturing is turned on and all further characters sent to ComWrite or ComWriteLn will be appended to the end of the capture file. If disk capturing is on and Status is false, the file will be closed and disk capturing will stop. If disk capturing is on and Status is true, or if disk capturing is off and Status is false, nothing happens. See Also: SetCaptureFile. SetCaseSensitivity Declaration: PROCEDURE SetCaseSensitivity(Status : Boolean); Sets case sensitivity for two methods in TBBS. The first is AddIntChar. When case sensitivity is true, 'A' and 'a' are equal, so only 'A' is stored in the set of interruptable characters. WaitFor also makes use of the state of case sensitivity. When true, all characters will first be converted to uppercase before being compared to the string being sought after. See Also: AddIntChar, WaitFor. SetEcho Declaration: PROCEDURE SetEcho(Ch : Char); Sets the echo character used for all input also directed to the screen or modem. Usually, every character typed is also echoed back to show the user what he/she is typing. Sometimes, such as during password entry, this is undesirable because others may be watching. A call to SetEcho will cause every character normally sent back the user to be Ch. For example, SetEcho('*'); will cause every character typed to be seen as an asterisk. A call to SetEcho with a null (#0) as the parameter will turn echoing off and cause each character to be echoed back normally. SetInput Declaration: PROCEDURE SetInput(Con, Rem : Boolean); Tells BBSkit where to accept input from during a call to ComReadKey, ComReadKeyE, ComReadLn, or ComReadLnWrap. If Con is true, console input will be accepted. If Rem is true, input from the remote user will be accepted. Be careful with this procedure. If you turn off console input but still allow remote input, the user will be able to type things and you won't be able to do anything. In effect, this can lock your local keyboard. Virtual keys will work regardless of this setting. See Also: GetInput. SetInputCap Declaration: PROCEDURE SetInputCap(Style : TCapStyle); SetInputCap allows you to change the way input is modified when using ComReadLn or ComReadLnWrap. NoCaps makes no modification to input text. UpperCase turns all lowercase letters into uppercase. LowerCase turns all uppercase letters into lowercase. Proper turns all letters after puncuation into uppercase, while all other letters remain in lowercase. The default value is NoCaps. SetLF Declaration: PROCEDURE SetLF(Status : Boolean); Some terminals, such as the IBM and compatible, like to have a carriage return followed immediately by a line feed. For such terminals, SetLF allows you to tell BBSkit to insert a line feed each time it runs across a carriage return in a ComWrite or ComWriteLn call. In this sense, it turns each CR into a CR/LF combination. Other terminals do not require the line feed to advance to the next line. For these terminals, turn off automatic addition of the line feed with SetLF. SetNulls Declaration: PROCEDURE SetNulls(Num : Byte); Some older terminals require null padding at the end of each line to give the display hardware time to catch up. For these terminals, you can specify that each CR be followed by a certain amount of null (#0) characters. These characters are non-printing characters which are never used by terminal emulation, so they make ideal time-wasting characters. Newer terminals do not need nulls, so this can usually be left to the default, which is no nulls after CR. SetOutput Declaration: PROCEDURE SetOutput(Con, Rem : Boolean); Sets up output redirection for ComWrite and ComWriteLn calls. If Con is set to true, text sent to ComWrite and ComWriteLn will appear on the local console. If Rem is true, text will be sent out the comport. Again, be careful here. You can inadvertently send text out the comport and not out the screen. This can cause problems if you are using your own system and can't see things you should be seeing. See Also: GetOutput. SetPaging Declaration: PROCEDURE SetPaging(Status : Boolean); This method allows you to turn paging on or off for the session. When paging is on, it causes each line output to increment a "line out" counter. When this counter reaches a predetermined limit, a full screen has been displayed and the user is prompted for more output with a simple "More..." style prompt. After a key is pressed, the counter is reset and output will continue. This paging is active during all output to ComWrite and ComWriteLn, and is not restricted to something such as TypeFile. See Also: SetPagingLines, SetPagingMsg. SetPagingLines Declaration: PROCEDURE SetPagingLines(Num : Byte); Sets a limit on the number of lines that can be output before the "More..." prompt is displayed. Whenever a CR is found during a ComWrite or ComWriteLn, the line counter is incremented. This counter is not incremented if a line is more than 80 characters long and happens to wrap to the next line. For this reason, make sure that your text wraps with hard returns so that paging (if active) will work correctly. See Also: SetPaging, SetPagingMsg. SetPagingMsg Declaration: PROCEDURE SetPagingMsg(Msg : String); This method allows you to define what the message that is displayed to the user at the end of a screen page will be. Default value is "More...". This string should not contain any characters that could cause a line break, such as CR or LF. After a user presses a key, the message is erased. This can only be done if the cursor is still on the same line as the message. See Also: SetPaging, SetPagingLines. SetPrinter Declaration: PROCEDURE SetPrinter(Status : Boolean); This method controls whether or not text sent to ComWrite and ComWriteLn will be sent to the printer. When Status is true, the printer will print every character sent to ComWrite and ComWriteLn. When false, printing stops. The printer used is the one provided in the Printer unit. If your printer works with Turbo Pascal programs of your own design, it will work with BBSkit. If your printer doesn't work, it won't work here either. SetTimer Declaration: PROCEDURE SetTimer(Status : Boolean); Built into BBSkit is a simple timer routine which keeps track of inactivity while waiting for a key using ComReadKey or ComReadKeyE. If the limit of this timer is reached, a message is displayed and the user has a short time to press a key or be logged off. This timer can be enabled or disabled with a call to this method. When Status is true, the timer is enabled. When Status is false, the timer is disabled and the terminal can be idle for an indefinite period of time. Inactivity timeouts are usually used to keep one user from hogging your board while he/she isn't doing anything with it. See Also: SetTimerDelay, SetTimerMsg. SetTimerDelay Declaration: PROCEDURE SetTimerDelay(Dly : Word); Sets the period of inactivity allowed before the timeout message is displayed. The Dly parameter is expressed in seconds, so a value of 180 is equal to three minute of inactivity before a logout occurs. This value should be long enough to give a user a chance to get something done quickly without keeping your board idle for an extended period of time. See Also: SetTimer, SetTimerMsg. SetTimerMsg Declaration: PROCEDURE SetTimerMsg(Msg : String); When an inactivity timeout occurs, a message is displayed to the user telling him/her than they have a very short period of time to press a key or they will be logged out. This message should be very obvious and could contain a few beep characters (#7) to get the user's attention. The default message is "Hello?" followed by a beep. See Also: SetTimer, SetTimerDelay. SetVirtualKeys Declaration: PROCEDURE SetVirtualKeys(Status : Boolean); SetVirtualKeys allows you to temporarily turn off or on the handling of the virtual keys. By default, virtual keys are not allowed and are not handled by HandleVirtualKey. Calling SetVirtualKeys when Status is true will enable the virtual keys, while calling it when Status is false will disable them. This does not clear the list of virtual keys, but rather just stops checking for them. The same virtual keys can again be interpreted after virtual keys have been re-enabled using SetVirtualKeys(True). See Also: AddVirtualKey, ClearVirtualKeys. TerminalMode Declaration: FUNCTION TerminalMode(Duplex : TDuplex; ShowControls : Boolean) : Char; TerminalMode provides a rudimentary terminal mode for BBSkit applications. TerminalMode allows you to send and receive characters from the modem without the additional features found in real terminal programs. Duplex defines whether or not characters you type will be echoed back to the screen. Duplex can be one of these enumerated values: Full: characters are not echoed. Half: characters are echoed. Chat: characters are echoed, and CR is turned into CR/LF. ShowControls allows you to have control characters show up in a different way from the rest of the text. If a control character is received while ShowControls is true, it will be displayed as the character in reverse video. That is, control-A is displayed as an uppercase 'A' in reverse video. The return value from TerminalMode is the last half of an extended key. TerminalMode exists whenever any extended key, such as F1, is pressed. The first half that Turbo Pascal receives (the #0), is thrown away, and the second is returned through the function. In this way, you could implement a more powerful TerminalMode simply by having certain extended keys do things that TerminalMode doesn't already do, like file transfers. TimeOut Declaration: FUNCTION TimeOut : Boolean; TimeOut will return true if an inactivity timeout has occurred during the last wait for a key. It is best to use TimeOut after important prompts. If a user times out during one prompt, a flag is set which will cause him to timeout of every prompt after that, so it should be easy to have this "pop" back to the main level, log the user out, and reset your BBS. The flag is not automatically reset except during a call to Hangup, so if you don't make a call to Hangup, you will have to reset the flag yourself with the command ErrorFlg := ErrorFlg AND (NOT ErrInactivity); TypeFile Declaration: PROCEDURE TypeFile(Fname : String); TypeFile displays the file defined by Fname to the outputs defined by SetOutput by passing each line through ComWriteLn. TypeFile can be interrupted by one of the characters in the interrupt list, which is constructed using AddIntChar. If an interrupt character is received, it will not be removed from the buffer, and can act as an immediate keypress for such things as menus. Using TypeFile in this way makes it very easy to construct menus with "hot-keys." If case sensitivity is currently set, all lowercase letters are converted to uppercase before being tested against the interrupt list. See Also: AddIntChar, ClearIntChars. VersionID Declaration: FUNCTION VersionID : String; Returns a string containing the BBSkit identification, version number, and release date. It would be nice if you could use this function somewhere in your code to let the world know you used BBSkit to develop your application. This is not required, but it would be nice! WaitFor Declaration: FUNCTION WaitFor(Strn : String; Timeout : Word) : Boolean; WaitFor will wait for a specified number of seconds for Strn to be seen at the comport. Characters received while waiting for this string are discarded, as is the string itself when (and if) it is found. A true value is returned only if the string was seen. A false value is returned when too many seconds have elapsed without seeing the string. If Timeout is set to zero, then WaitFor will wait indefinitely for Strn to be seen at the comport. There is no timeout value. If case sensitivity is set, then all characters received will be converted to uppercase before being tested against Strn. Strn is also converted to uppercase. Thus, "ok" and "OK" are the same thing. See Also: SetCaseSensitivity. Chapter 8: Protocol Unit Listing ReceiveXmodem Declaration: FUNCTION ReceiveXmodem(Mode : Byte; Fname : PathStr) : TError; ReceiveXmodem prepares to receive a single file into Fname using the Xmodem protocol. The other end must be ready to send using Xmodem or nothing is going to get transferred. Mode is a single byte bit mask constructed from the following constants. If you construct a bit mask using more than one of Checksum, CRC, or OneK, you will most likely get unpredictable results. Checksum = $01 CRC = $02 OneK = $06 Turbo = $80 Checksum uses 128 byte packets with an 8-bit checksum for error checking. CRC uses 128 byte packets with a 16-bit cyclical redundancy check. OneK uses 1024 byte packets and the same 16-bit CRC. Turbo speeds up receiving of files at the cost of no error checking. Instead of actually computing the checksum or CRC, it will automatically acknowledge the packet and proceed to the next. In this way, it can be used with any Xmodem sender, even if they do not support a "Turbo" mode. This mode is also best if used on error-correcting modems, as the protocol no longer does any error checking of its own. Fname specifies where the received file will be put and its name. Unless you want an error generated, make sure this file doesn't already exist. ReceiveXmodem returns a value reporting the status of the transfer. If no errors or problems were detected, NoError is returned, signifying that the transfer was successful. One of the following corresponds to the appropriate error condition: TimeOut (timed out while waiting for the receiver), TooManyErrors, Aborted (by the user or local operator), DiskError (error reading/writing to disk), NoCarrier (there was nothing to send a file to), FileExists (file already exists so we can't receive it again). See Also: SendXmodem. SendXmodem Declaration: FUNCTION SendXmodem(Mode : Byte; Fname : PathStr) : TError; SendXmodem sends a single file using the Xmodem protocol. The other end must be ready to receive using Xmodem or nothing will get transferred. Mode is a byte bit mask constructed from one of the following constants. If you use more than one, you will most likely get unpredictable results. Checksum = $01 CRC = $02 OneK = $06 Checksum uses simple checksum error checking with 128 byte packets. CRC upgrades the error checking to use 16-bit cyclical redundancy checks, which catch more errors. CRC still uses 128 byte packets. OneK improves throughput by increasing the packet size to 1K, or 1024 bytes. CRC error checking is also utilized to make the protocol more foolproof. Please note that Xmodem-1K is sometimes misrepresented as Ymodem. Ymodem is a batching protocol, even though both use the exact same method of transfers. Xmodem-1K is not a batching protocol and will not work with Ymodem. Fname is simply the path to the file you wish to send. SendXmodem returns a value reporting the status of the transfer. If no errors or problems were detected, NoError is returned, signifying that the transfer was successful. One of the following corresponds to the appropriate error condition: TimeOut (timed out while waiting for the receiver), TooManyErrors, Aborted (by the user or local operator), DiskError (error reading/writing to disk), NoCarrier (there was nothing to send a file to). See Also: ReceiveXmodem. Chapter 9: Procedure/Function Listing BpsRate Declaration: FUNCTION BpsRate : Longint; Returns the bits per second rate of the currently opened comport. This function should not be called if a port has not already been initialized through InitPort. The results you get would most likely be garbage. See Also: SetBpsRate. Carrier Declaration: FUNCTION Carrier : Boolean; Returns the carrier status of the current comport. If there is a carrier present on the line, true is returned. Otherwise it will return a false value. See Also: TBBS.CarrierLost. ClearPort Declaration: PROCEDURE ClearPort; Clears some of the registers of the UART on the current comport. The line status register, the modem status register, and the receive buffer register are all read. This will clear any pending event from each register, effectively clearing them. ClearReceiveBuffer Declaration: PROCEDURE ClearReceiveBuffer; Destroys all characters currently in the receive buffer. After this call, no characters will be available in the buffer until they are received at the comport. See Also: ClearSendBuffer, FlushSendBuffer. ClearSendBuffer Declaration: PROCEDURE ClearSendBuffer; Destroys all characters waiting in the send buffer. Any characters which were waiting to be sent are cleared out. The send buffer will then be ready to send out any new characters placed in the buffer with Send, SendString, or SendW. See Also: ClearReceiveBuffer, FlushSendBuffer. ClearToSend Declaration: FUNCTION ClearToSend : Boolean; Returns a boolean based on the CTS bit in the modem status register. This bit is primarily used by hardware handshaking. If the bit is high (true), the other end is capable of receiving data. If the bit is low (false), then the other end does not want to receive any data at that time. See Also: SetFlowControl, SetRTS. DataTerminalReady Declaration: FUNCTION DataTerminalReady : Boolean; Returns the state of the data terminal ready (DTR) line in the modem status register. If the DTR line is low, no characters can be read from or sent to the modem. A low DTR line also causes most new modems to hang up the line if you are connected with another computer. See Also: SetDTR. DeInitPort Declaration: PROCEDURE DeInitPort; Shuts the current comport down by clearing the interrupt flags, resetting the interrupt vector, and deallocating memory used by the comport. This procedure should be called after you are done using a comport or when your application is about to terminate. See Also: InitPort. DetectPort Declaration: FUNCTION DetectPort(AtPort : Byte) : Boolean; Returns a true or false value depending on whether or not it could find a National based UART at the specified comport. It runs a simple test to check to see if the specified comport is run by a National compatible UART. If this test succeeds, it returns true. Otherwise it will return false. See Also: DetectUART. DetectUART Declaration: FUNCTION DetectUART : String; Tries to determine which National-based UART is located on the specified comport. The comport must already have been initialized through a call to InitPort to make sure that a National-based UART is actually at the comport. This function will return a string describing the UART found. 8250B = National 8250B (PC, XT) 16450 = National 16450 (80286) 16550 = National 16550 (early PS/2s, no FIFOs) 16550A = National 16550A (working FIFOs) See Also: DetectPort. FlushSendBuffer Declaration: PROCEDURE FlushSendBuffer; FlushSendBuffer will wait for the send buffer to completely empty itself. Note that this is different than ClearSendBuffer because it actually allows the buffer to be sent. The end result (send buffer is empty) is the same for both procedures. See Also: ClearSendBuffer. GetFlowControl Declaration: PROCEDURE GetFlowControl(var XonXoff, RTSCTS : Boolean); Returns the status of flow control as previously set using SetFlowControl. These two booleans do not report the state of flow control being active or not, but rather report the ability to use each type of flow control. It is advised to keep XonXoff (software) flow control on during any host-type application. This will give the user a way to stop transmission if he/she wishes to. See Also: SetFlowControl, SetFlowLimits. InitPort Declaration: FUNCTION InitPort(AtPort : Byte; BufferSize : Word) : Boolean; InitPort will set up the specified comport for activity. It will first check to make sure that the comport is a valid National-based UART, and that there is enough memory to allocate for the send and receive buffers. If any of these two conditions prove to be false, InitPort will abort and return a false value. If all goes well, on the other hand, InitPort will return true after first setting up the port. All defaults values are set in this function, as well as the interrupt handler being activated. This function must be called before any other port- intensive procedure or function. See Also: DeInitPort. LineRinging Declaration: FUNCTION LineRinging : Boolean; Checks the current comport to see if the phone line is ringing. If it is, this function will return true. If it is silent, the function will return false. The phone company sends a special voltage level down the phone line when the line is ringing. The UART is capable of detecting this signal and reporting it. ModemError Declaration: FUNCTION ModemError : Byte; The internal assembler routines keep track of various error conditions and set bits in ErrorFlg when they occur. ModemError is capable of reporting these errors and then clearing the internal ErrorFlg variable. The byte value returned by ModemError in made up of a bit mask constructed from the following constants. The error condition exists if the bit mask is true when ANDed with the value returned by ModemError. errInputOverflow = $01 errOutputOverflow = $02 errInactivity = $04 errOverrun = $08 errParity = $10 errFraming = $20 errCarrierLost = $40 errBreakSignal = $80 A few of these constants need to be further explained here. Overflow errors occur when the incoming characters or outgoing characters are placed in the buffer when there is no room for them. Inactivity errors occur in two situations. Both require that the BBS mode be set using SetBBSMode. First, when SendW is trying to send a character and flow control is active. If flow control stays active too long, a timeout is considered to have occurred, and this error condition will be set. The second situation is when TBBS.ComReadKey is being used and the user does nothing for an extended period of time. This will also cause an inactivity timeout. errOverrun, errParity and errFraming are all errors reported by the UART. errCarrierLost is set when DCD goes from high to low. errBreakSignal is set when a break signal is detected at the UART. See Also: TBBS.CarrierLost, TBBS.Timeout. Parity Declaration: FUNCTION Parity : TParity; Returns the current parity as set at the UART. This function will return one of the types defined in the enumerated type TParity: TParity = (NoParity, OddParity, EvenParity, MarkParity, SpaceParity);TParity type See Also: SetParity. PeekNextChar Declaration: FUNCTION PeekNextChar : Char; EXTERNAL; This external assembler routine quickly checks the next character in the receive buffer and returns it. It does not remove the character from the buffer, but simply checks to see what it is. You should make sure that there is actually a character to be checked before calling this routine. Otherwise it will return garbage. See Also: Receive, ReceiveW. Receive Declaration: FUNCTION Receive : Char; EXTERNAL; This routine acts much like PeekNextChar, except that it also removes the character from the buffer. In doing so, it checks flow control to see if any of it needs to be deactivated. This routine does not wait for a character to appear in the buffer, so you should make sure there is one there before calling Receive. See Also: PeekNextChar, ReceiveW. ReceiveBufferEmpty Declaration: FUNCTION ReceiveBufferEmpty : Boolean; Reports the status of the receive buffer. If the buffer is completely empty, it will return true. Otherwise it will return a false value. See Also: ReceiveBufferFull. ReceiveBufferFull Declaration: FUNCTION ReceiveBufferFull : Boolean; Reports the status of the receive buffer. If the buffer is completely full, it will return true. Otherwise it will return a false value. See Also: ReceiveBufferEmpty. ReceiveW Declaration: FUNCTION ReceiveW : Char; EXTERNAL; This function acts exactly like Receive, except that if there are no characters waiting in the buffer, it will wait indefinitely for one to appear. It is guaranteed to always return a valid character. It never grabs things from the buffer unless there is something to grab. See Also: PeekNextChar, Receive. Send Declaration: PROCEDURE Send(Ch : Char); EXTERNAL; Sends a single character out the comport. This procedure does not check to see if there is room left in the send buffer. If there isn't, the appropriate error bit will be set in ErrorFlg. See Also: SendString, SendW. SendBufferEmpty Declaration: FUNCTION SendBufferEmpty : Boolean; Reports the status of the send buffer. If it is completely empty, it will return true. Otherwise it will return false. See Also: SendBufferFull. SendBufferFull Declaration: FUNCTION SendBufferFull : Boolean; Reports the status of the send buffer. If the buffer is completely full, it will return true. Otherwise it will return false. See Also: SendBufferEmpty. SendString Declaration: PROCEDURE SendString(Strn : String); Sends a complete string out the comport by repeatedly calling SendW. This is a quick way to send an entire string out the port without using the TBBS object. See Also: Send, SendW. SendW Declaration: PROCEDURE SendW(Ch : Char); EXTERNAL; Sends a single character out the comport. SendW will check the send buffer to make sure there is room before sending the character. If there isn't room, it will wait until there is. See Also: Send, SendString. SetBBSMode Declaration: PROCEDURE SetBBSMode(Status : Boolean); Sets BBS mode either on or off. BBS mode allows the assembler routines to keep track of a couple more things than it can when BBS mode is not set. The first is inactivity when trying to send a character using SendW. The second is the ability to clear the receive buffer from the remote terminal either by receiving a special character, or optionally allowing the break signal to clear it. See Also: SetBreakClearBuffer, SetClearBufferChar. SetBpsRate Declaration: PROCEDURE SetBpsRate(Bps : Longint); Sets the bits per second (bps) rate of the current comport. This value can range anywhere from 50 to 115,200. Typically, this value is one of 300, 1200, 2400, 9600, 19200, 38400, 57600, or 115200. See Also: BpsRate. SetBreakClearBuffer Declaration: PROCEDURE SetBreakClearBuffer(Status : Boolean); If BBS mode is set, this command can cause the receive of a break signal to clear the receive buffer. There may be times when characters have built up in the receive buffer and the remote user would want to cancel them before they are processed. This command would then allow the break signal to clear the characters from the buffer before your application could handle them. See Also: SetBBSMode, SetClearBufferChar. SetClearBufferChar Declaration: PROCEDURE SetClearBufferChar(Ch : Char); This procedure acts much like SetBreakClearBuffer. When BBS mode is set, you may also want certain control characters, for example control-^, to clear the receive buffer. Once the character is set, it would then clear the buffer each time it was received, without being placed in the buffer itself. For this reason, don't use characters that are typable, and don't use characters that need to be received by any terminal emulation in use. See Also: SetBBSMode, SetBreakClearBuffer. SetDTR Declaration: PROCEDURE SetDTR(Status : Boolean); SetDTR allows you to control the status of the data terminal ready (DTR) line of your serial port. DTR must be high at all times to send and receive data. Most new modems are capable of hanging up the modem when DTR goes low, so this can also be used to hang some modems up. See Also: DataTerminalReady. SetFIFO Declaration: PROCEDURE SetFIFO(Status : Boolean); SetFIFO allows you to control the FIFO buffers on the 16550A UART. (On older UARTs that do not support FIFOs, this command is ignored.) The FIFOs are additional buffers on the UART that allow multiple characters to be received before an overrun error would be generated. They can drastically improve throughput on high speed modems. See Also: DetectUART. SetFlowControl Declaration: PROCEDURE SetFlowControl(XonXoff, RTSCTS : Boolean); Flow control allows each end to control when transmission should stop to give the application time to catch up with incoming characters. The two styles supported by BBSkit are Xon/Xoff (software) and RTS/CTS (hardware) flow control. Xon/Xoff works by sending characters to the other end to turn flow control on and off. ^S always stops transmission, while ^Q restarts it. The good thing about this method is that the user has the ability to stop transmission when reading a message, for example. The bad thing is that these two characters can interfere with some terminal emulations. RTS/CTS works by maintaining bits in the UART of each end. RTS, which stands for Ready To Send, is set when the UART is able to receive more data. CTS, which stands for Clear To Send, is set when the remote UART is able to receive more data. In this way, each UART can manipulate bits and keep the other end from sending when a buffer is getting full. This style does not intefere with any terminal emulation, but it also does not allow the user to manually turn flow control on or off. See Also: GetFlowControl, SetFlowLimits, SetRTS. SetFlowLimits Declaration: PROCEDURE SetFlowLimits(Xon, Xoff : Word); This procedure allows you to define when flow control should be activated. If the number of characters in the receive buffer meets or excess the value of Xon, flow control will be activated until the level drops below Xoff, at which point flow control will be turned off. Usually, this value can be left to the defaults set by InitPort. Flow control will be turned on when there are 16 or less characters left in the buffer, and turned off once there are at least 32 characters left. See Also: GetFlowControl, SetFlowControl. SetInactiveLimit Declaration: PROCEDURE SetInactiveLimit(Sec : Word); This procedure sets the number of seconds that the user can have flow control on while SendW is trying to send a character. If this limit is reached, an inactivity error will be generated and SendW will abort. See Also: TBBS.SetTimer, TBBS.SetTimerDelay, TBBS.SetTimerMsg. SetParity Declaration: PROCEDURE SetParity(Mode : TParity); Sets the parity for the UART. Most 8-bit connections use no parity, but some mainframes still use even parity. No parity, even parity, odd parity, mark parity and space parity are all supported. These are the only modes support by the UART. See Also: Parity. SetRTS Declaration: PROCEDURE SetRTS(Status : Boolean); Sets the Ready To Send bit in the UART. This bit is usually maintained by the assembler routines using hardware flow control, but can be manipulated by your Pascal code. It is recommended that you leave this alone when hardware flow control is in use. See Also: SetFlowControl. SetSoftHandshake Declaration: PROCEDURE SetSoftHandshake(Xon, Xoff : Char); There is the ability here to set up different characters than ^S and ^Q for software flow control. Be careful with this, though. Your end will know what it is using, but the other end will not. This ability is meant for applications that will only be used for private purposes, because the rest of the world won't understand non-standard characters. See Also: SetFlowControl. SetStopBits Declaration: PROCEDURE SetStopBits(Bits : TStopBits); Sets the number of stop bits required at the end of each character received or sent by the UART. In a standard 8-bit or 7-bit connection, one stop bit is used. The possibility exists for two stop bits as well. To set 1 or 2 stop bits, just call SetStopBits(1) or SetStopBits(2). The 1.5 stop bits option is not supported mainly because I have never seen it used. See Also: StopBits. SetWordLength Declaration: PROCEDURE SetWordLength(WordLen : TWordLength); UARTs are capable of supporting word lengths from 5 bits up to 8 bit. Most standard connections use 8 bits, although some connections to mainframe computers use 7 bit connections. BBSkit supports word lengths from 5 to 8. See Also: WordLength. StopBits Declaration: FUNCTION StopBits : TStopBits; Returns the number of stop bits currently being used by the UART. This number will be in the range 1..2. The number of stop bits used can be set through the SetStopBits procedure. See Also: SetStopBits. WaitForRingTrailer Declaration: PROCEDURE WaitForRingTrailer; While the UART has the ability to detect a ringing line, it also has the ability to detect when the ring has stopped. WaitForRingTrailer will simply wait until a ring has stopped and then exit. This is different than checking to see if the line is ringing and getting a false result. See Also: LineRinging. WordLength Declaration: FUNCTION WordLength : TWordLength; Returns the current word length as set in the UART's registers. This value will be in the range 5..8. See Also: SetWordLength. Appendix D: Contacting Technical Support Technical support is available to all registered users free of charge from the time that registration is received. By "free of charge" I mean that I will provide as much help as I can in any way that I can, so long as it does not cost me lots of money. Support is available over the phone (no collect calls will be accepted), through United States Mail, through CompuServe, through the Internet, or through BITNET. As a college student, my address away at school changes with each year. Since this something that can be a bother to users, I am taking it upon myself to inform registered users of my change of address at the beginning of each school year. The address for that school year and the telephone number will be provided in a mailing sent to all users through U.S. Mail. Additional information may be included with this mailing about technical support. Current addresses are as follows: U.S. Mail (at home): Steve Madsen BBSkit Technical Support 1888 Edith Marie Drive Beavercreek, OH 45431-3377 CompuServe: INTERNET>sjmadsen@miavx1.acs.muohio.edu Internet: sjmadsen@miavx1.acs.muohio.edu BITNET: sjmadsen@miavx1 As an added convenience, I will accept calls for technical support. As a private developer, there are no hours for technical support. Instead, I would like to simply ask my users to call at a reasonable hour. "Reasonable" is anywhere from 8am to 11pm, but remember that I have a "normal" job, too. The best time to reach me would probably be from 6pm to 11pm. If for some reason I am not home, please leave a message. To make sure that I receive this message, let whoever answers know that it is about BBSkit. That way, I'll see it as soon as I get in. I will return calls for tech support provided that the calls don't start costing too much. However, the most reliable method for reaching me for technical support would be through some means electronic. When calling technical support, please have the following information available in the event that it is needed to help diagnose your problem: o Version of BBSkit being run (use VersionID) o Version of Turbo Pascal o Version of DOS o Computer make & model o Modem make & model I will do my best to help you with any problems you may be having getting BBSkit to work with your hardware. However, I cannot debug your code for you. Technical support is primarily a means to getting BBSkit to work with your particular hardware configuration. In general, upgrades to new versions of BBSkit will be $20 in U.S. funds. This will include the new printed manual, new disks, and postage. If there isn't a new manual, the cost will be considerably less, of course. When an upgrade is ready for release, registered users will receive postcards informing them of the upgrade and giving a short list of new features or bug fixes.