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
allowed and are 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>[email protected]
Internet: [email protected]
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.