QB/FOSSIL v2.0

A Quickbasic Interface to FOSSIL Type COMM Drivers

(c) 1992 Scott MacLean

QB/FOSSIL Interface v1.1 (c) 1992 Scott MacLean Page 1
======================================================================

Introduction
------------

I have been very active in development of telecommunications
software for the past few years. I also remain a staunch supporter of
Microsoft Quickbasic. Logic suggests that I write my communications
software in Quickbasic. However, the communications routines inside
Quickbasic leave a lot to be desired. It has some severe limitations:

- Access to COM1 and COM2 only
- Maximum baud rate of 9600
- Drops DTR when COM port closed

For this reason, several "third party" library publishers have
been producing Quickbasic libraries with built in COMM routines, to
replace those inside Quickbasic. However, most of these also have
limitations, lacking either buffers, flow control, ability to run more
than one COM port simultaneously, or other crucial parts. So we have
been stuck with the built-in Quickbasic routines.

One day, I was setting up a Fido node using D'Bridge, which uses
something called a FOSSIL driver to handle it's communications. The
driver I was using was Raymond Gwinn's X00.SYS. I looked into the
documentation for this driver, and lights went on inside my head. This
driver did everything I wished Quickbasic did! I decided that I simply
MUST write a routine so that I would be able to use X00.SYS (or any
FOSSIL driver, for that matter) from Quickbasic.

What is a FOSSIL driver? In quick layman's terms, a FOSSIL driver
is an interface between software and hardware. If you write a BBS, and
want it to run on a variety of machines, even though those machines
have different COM port configurations, you will have to write
separate communication routines for each one. However, if you write
your BBS to talk with the FOSSIL driver instead, the FOSSIL driver
does all the hardware-level processing appropriate to the machine it
is being run on, and your BBS never knows the difference. FIDO, OPUS
and SEADOG, to name a few, use the FOSSIL driver standard. Therefore,
if you write a communications program that interfaces with a FOSSIL
driver, you are expanding your potential user base instantly!

I would highly recommend you download X00.SYS (look for a file
starting with "X00") and read the documentation on it before attempt-
ing to use QB/FOSSIL. While you will be able to get by without it, by
doing so you will learn much more than I can easily tell you here.

Not all the features contained in the FOSSIL driver are imple-
mented in QB/FOSSIL. I left out things like reading the keyboard
buffer and printing to the screen, simply because those things can
easily be done from within Quickbasic anyway. I left in lots of other
goodies, however. Prepare to be amazed!

QB/FOSSIL Interface v1.1 (c) 1992 Scott MacLean Page 2
======================================================================

Features of QB/FOSSIL
---------------------

- Ability to set Baud Rate, Parity, Word Length, and Stop Bits on the
fly, even after the COM port has already been initialized

- Ability to READ Baud Rate, Parity, Word Length, and Stop Bits from
a port - handy for writing DOORs that can't reset the baud rate

- Can send BREAK signals

- Can watch for and expedite CTRL-C or CTRL-K, for BBS uses

- Built-in carrier monitoring - can be monitored manually, or set to
reboot PC if carrier drops

- Data can still be sent to the COM port even if there is no carrier
detect

- Variable size buffers up to 32K (set in the FOSSIL driver at star-
tup)

- Automatic block movement of text in and out of buffers from and to
string variables, up to 32K at a time. No character-by-character
reading: This feature can allow you to create a super-fast stream-
ing protocol, in Quickbasic!

- User control over the DTR signal

- XON/XOFF and CTS/RTS handshaking built in (both can be disabled)

- Ability to flush both the input and output buffers

- Functions to report number of characters in each buffer, and number
of bytes free remaining in each buffer

- Ability to test for input buffer overrun

- Ability to either cold start or warm start upon command (reboot)

- Ability to support up to eight COM ports simultaneously (X00.SYS
and some other drivers allow you to define many COM ports to use a
single IRQ line - put 8 COM ports in your PC with no expensive
"Multiport" hardware!)

- Convenient, fully-functional Quick Library (.QLB) and Library
(.LIB) files included, all you need to test and compile programs
with. Source code provided upon registration, allows you to cus-
tomize QB/FOSSIL to your needs

QB/FOSSIL Interface v1.1 (c) 1992 Scott MacLean Page 3
======================================================================

Registration
------------

By now, you can probably see why I am so excited about this
project. It has taken me some time to put together the support code
and write the documentation. If you use QB/FOSSIL, please register it.
QB/FOSSIL is fully functional in the unregistered version, with all
the files you need to run interpreted Quickbasic 4.5 programs, and
compile them. You are free to use QB/FOSSIL in any programs you write.
However, if you use QB/FOSSIL in a program which you are going to
SELL, MARKET, DISTRIBUTE or otherwise GIVE AWAY, I must request that
you register QB/FOSSIL first. Registered users will receive a disk
containing the source code to QB/FOSSIL. This fully-documented source
code can be modified, stripped down, used in your own programs, or
whatever else you want to do with it. Registered users are also al-
lowed to distribute their programs which make use of QB/FOSSIL. To
register your copy of QB/FOSSIL, send $25 US FUNDS to the address
shown below:

Scott MacLean - QB/FOSSIL
6 Marilyn Crescent
Georgetown, ON
L7G 1K4
Canada

PLEASE include your return address. Source code will be sent on a
3.5" 720K diskette as soon as your registration funds are received. As
an added bonus, I will include on the disk the latest assortment of
programs which I have for release at the time I receive your registra-
tion. (Sorry, 5.25" diskettes just cost too much to mail, due to all
the extra protection required) If you could care less about the source
code, and don't want the disk, please indicate so. In this case, you
can send $20 US instead of the regular $25 US. And of course, comment
is invited. If you have a comment or suggestion, by all means, send it
along!

Basic 7
-------

Due to the different way Microsoft Basic 7 PDS stores far
strings, this version of QB/FOSSIL will not work with it. This is cur-
rently being worked on, and is expected to be finished in the near fu-
ture.

A Quick Note
------------

Before I get hundreds of letters from people screaming about how
QB/FOSSIL doesn't work, I want to mention this. QB/FOSSIL is NOT a
communications driver. It is an INTERFACE to a communications driver.
QB/FOSSIL WILL NOT WORK UNLESS A FOSSIL DRIVER IS LOADED INTO MEMORY
FIRST! Go back to the beginning of the manual where it recommends you
download X00.SYS. Did you do it yet? If not, do it now. If you don't,
you won't get any farther than this, because nothing will work.

QB/FOSSIL Interface v1.1 (c) 1992 Scott MacLean Page 4
======================================================================

Implementation
--------------

Getting QB/FOSSIL up and running is ridiculously easy. Let's
write a small terminal program to show how simple it really is. To
begin, start Quickbasic with the following command line:

QB /LFOSSIL45

This loads up Quickbasic, and also loads in the QB/FOSSIL quick
library. (.QLB) Enter the following program:

REM $INCLUDE: 'FOSSIL45.BI'
Init 0
SetBaud 0, 1200, 8, "N", 1
FlowCtl 0, 1
DO
PRINT Receive (0, 0);
Transmit 0, INKEY$
LOOP

That's it. You have just written a terminal program. Let's ex-
amine it. The first line MUST appear at the top of each module you
write which will be calling QB/FOSSIL routines. It is a BASIC INCLUDE
file which contains all the declarations necessary for the interface.
Next we see the Init command. This tells the FOSSIL driver to initial-
ize port 0. Port 0 will be the first port we defined when we started
our FOSSIL driver. Next we set the port parameters. We tell it that
for port 0, we want 1200 baud, 8 bit word, no parity, and 1 stop bit.
We could just as easily say we wanted 38400 baud. Or, we could omit
this line altogether, and QB/FOSSIL would use whatever settings the
COM port was last used at. Next, we tell the driver that we want
CTS/RTS flow control on port 0.

Now we go into an endless loop. The first line inside the loop
tells QB/FOSSIL to PRINT whatever is received from port 0. The next
line transmits whatever we type. Notice that we are not closing the
port (DInit) after we are done, because this program will never exit
the endless loop.

In our program, we are not doing any sort of error detection.
After each command, the common variable "FossErr" contains the result
of the command just executed. If FossErr = 0, the command was executed
successfully. If FossErr contains a value other than 0, an error has
occurred. The values of FossErr differ for each command, but they are
similar for the most part: for instance, a value of -2 almost always
indicates that an invalid port number was specified. In the case of an
error, a second common variable "PortErr" will hold the port number
the error occurred on.

What follows is a small description of each QB/FOSSIL command,
and an example. Following that is a list of each command, with allow-
able parameters, and possible results.

QB/FOSSIL Interface v1.1 (c) 1992 Scott MacLean Page 5
======================================================================

Break PortNum%, Length!

This command sends a BREAK signal to the modem for a specified
amount of time. The length of the BREAK is specified in seconds. The
example causes a BREAK signal on port 1 for 1.5 seconds.

Break 1, 1.5

SEE ALSO: DTR
----------------------------------------------------------------------
Carrier% (PortNum%)

Carrier returns the status of the carrier detect line from the
modem. If a 0 is returned, the carrier detect line is high, indicating
a connection is made.

Result% = Carrier (0)

SEE ALSO: WatchDog
----------------------------------------------------------------------
CtrlCK% (PortNum%)

CtrlCK is a unique function which comes in handy in BBS and host
applications. A call to the CtrlCK routine will determine whether or
not a CTRL-C or CTRL-K has been received, without having to read from
the input buffer. A 0 returned indicates neither has been received
since the last call to CtrlCK. Every call to CtrlCK resets this flag
to 0, regardless of it's prior value.

Result% = CtrlCK (0)
----------------------------------------------------------------------
DInit PortNum%

DInit deallocates the settings which were assigned when the port
was initialized. It should be done to each and every port which was
Init'ed before your program terminates. The DTR line is NOT dropped
when this function is executed, like it is in the regular Quickbasic
routines.

Dinit 0

SEE ALSO: Init, DTR
----------------------------------------------------------------------
DTR PortNum%, State%

DTR is used to control the state of the Data Terminal Ready line
to the modem. This is frequently used to cause the modem to "hang up"
when a connection is finished. Our example raises the DTR line.

DTR 0, 1

SEE ALSO: Break
----------------------------------------------------------------------

QB/FOSSIL Interface v1.1 (c) 1992 Scott MacLean Page 6
======================================================================

FlowCtl PortNum%, FType%

Flow control is commonly used on high speed modems, but is also
used frequently on dumb terminals as well. It allows the computers at
each end to tell each other to "stop sending data" when it needs a few
moments to process data. Enabling flow control on QB/FOSSIL will cause
the fossil driver to do it's own flow control automatically, depending
on the amount of data in the buffers. Two types of flow control are
available, XON/XOFF and CTS/RTS. High speed modems with fixed DTE
rates commonly use CTS/RTS, while dumb terminals often use XON/XOFF.
Our example turns on XON/XOFF flow control.

FlowCtl 0, 2
----------------------------------------------------------------------
FlushIn PortNum%

FlushIn causes the entire contents of the input buffer to be
dumped, and the input buffer is reset. Any data which was in the input
buffer is lost.

FlushIn 0

SEE ALSO: FlushOut
----------------------------------------------------------------------
FlushOut PortNum%

FlushOut causes the entire contents of the output buffer to be
dumped, and the output buffer is reset. Any data which was in the out-
put buffer is lost.

FlushOut 0

SEE ALSO: FlushIn
----------------------------------------------------------------------
FVersion$


FVersion returns the current version of QB/FOSSIL, as a string.
This text is automatically printed every time Init is called.

Result$ = FVersion
----------------------------------------------------------------------
InBufF& (PortNum%)

InBufF returns the number of bytes of free space remaining in the
input buffer. When this number falls to 0, either flow control will be
initiated, or the input buffer will overrun, depending on whether or
not flow control is enabled.

Result& = InBufF (0)

SEE ALSO: OutBufF, InBufW, OutBufW, OverRun, Receive
----------------------------------------------------------------------

QB/FOSSIL Interface v1.1 (c) 1992 Scott MacLean Page 7
======================================================================

InBufW& (PortNum%)

InBufW returns the number of characters waiting to be read from
the input buffer. It can be used to determine whether or not the
Receive routine should be called to retrieve the text.

Result& = InBufW (0)

SEE ALSO: InBufF, OutBufF, OutBufW, OverRun, Receive
----------------------------------------------------------------------
Init% PortNum%

Init causes the FOSSIL driver to allocate the resources required
to access the specified COM port. Init ABSOLUTELY MUST be called
before any other activity is done on a port.

Init 0

SEE ALSO: DInit
----------------------------------------------------------------------
OutBufF& (PortNum%)

OutBufF returns the number of bytes of free space remaining in
the output buffer. When this number falls to 0, the next time a Trans-
mit is called, it will "wait" until enough space is cleared in the
output buffer to insert the new text. If something has crashed, and
flow control is being used, this could hang things up indefinitely.

Result& = OutBufF (0)

SEE ALSO: InBufF, InBufW, OutBufW, OverRun, Transmit
----------------------------------------------------------------------
OutBufW& (PortNum%)

OutBufW returns the number of characters waiting to be sent from
the output buffer. When a large amount of text is transmitted, this
value will rapidly fall to 0 as the data is moved out of the output
buffer. When this value is 0, no data is waiting to be sent, and no
data is being sent.

Result& = OutBufW (0)

SEE ALSO: InBufF, OutBufF, InBufW, OverRun, Transmit
----------------------------------------------------------------------

QB/FOSSIL Interface v1.1 (c) 1992 Scott MacLean Page 8
======================================================================

OverRun% (PortNum%)

When flow control is not being used, and data is streaming into
the input buffer, it must be read out from the input buffer rapidly.
If this does not happen, the input buffer will become full, and data
will be lost, as the FOSSIL driver has no place to put it. This is
called a data overrun. If this function ever returns a non-zero
result, then data overrun has occurred, and the data in the input
buffer can now be considered corrupt. In this case, a FlushIn function
should be called to clear out the input buffer.

Result% = OverRun (0)

SEE ALSO: InBufF, InBufW, FlushIn, Receive
----------------------------------------------------------------------
ReadBaud$ (PortNum%)

ReadBaud returns the current settings found in the specified COM
port. It returns it as an eight character string. The first five
characters are the baud rate, the sixth is the word length, the
seventh is the parity, and the eighth is the stop bits. An example of
19200 baud, 8 bit word, no parity and one stop bit would be returned
as "192008N1". Baud rates are filled with leading zeroes, so 300 baud
appears as "00300".

Result$ = ReadBaud (0)

SEE ALSO: SetBaud
----------------------------------------------------------------------
ReBoot RType%

ReBoot allows you to give the PC the old "three finger salute".
Two types of reboots are supported, warm (reboot only) and cold
(memory check, diagnostic check, reboot). Our example does a warm
reboot.

ReBoot 1

SEE ALSO: WatchDog
----------------------------------------------------------------------

QB/FOSSIL Interface v1.1 (c) 1992 Scott MacLean Page 9
======================================================================

Receive$ (PortNum%, Chars%)

Receive is one of the two most important functions of QB/FOSSIL.
It is the function used to move data from the input buffer into a
string variable. You can have QB/FOSSIL move the entire buffer (up to
32767 characters) at once, or you can specify as many characters as
you wish. This is done with the Chars parameter. Using a value of 0
will cause QB/FOSSIL to return the contents of the entire input buf-
fer. Using any other value (up to 32767) will return exactly that many
characters. If less than the specified amount of characters exists in
the input buffer, Receive will return those characters only. (ie. just
because you told it you want 20 characters, doesn't necessarily mean
you're going to GET 20 characters. However, you won't get MORE than 20
characters.) The data is removed from the input buffer when this func-
tion is executed.

Result$ = Receive (0, 255)

SEE ALSO: Transmit, InBufW, InBufF, FlushIn
----------------------------------------------------------------------
SetBaud PortNum%, BaudRate&, WordLen%, Parity$, StopBits%

This command allows you to set all the parameters of a COM port
in one stroke. Make sure that all the parameters passed are valid, or
SetBaud will return an error value. SetBaud should be called im-
mediately after Init, unless you intend on using values that already
exist in the COM port.

SetBaud 0, 19200, 7, "E", 1

SEE ALSO: Init, ReadBaud
----------------------------------------------------------------------
Transmit PortNum%, Text$

Transmit moves the text from a string variable into the output
buffer. If there is not enough space in the output buffer for the en-
tire text to fit, Transmit will wait until there is, and then insert
the text. Transmit can handle up to 32767 characters at a time.

Transmit 0, x$

SEE ALSO: TransmitC, Receive
----------------------------------------------------------------------
TransmitC PortNum%, Text$

TransmitC is functionally identical to Transmit, except that it
adds a carriage return (ASCII 13) and line feed (ASCII 10) after the
block of text. This is useful when you wish to send a line of text,
but don't want to manually tack on the CR/LF combination.

TransmitC 0, x$

SEE ALSO: Transmit, Receive
----------------------------------------------------------------------

QB/FOSSIL Interface v1.1 (c) 1992 Scott MacLean Page 10
======================================================================

WaitTx PortNum%

WaitTx will cause QB/FOSSIL to enter an endless loop until the
entire output buffer is empty. This is useful for BBS's, where you
don't want the BBS terminating the connection when someone logs off
until all the data has been sent. It is wise to write a two or three
second delay AFTER each WaitTx call, because some high speed modems
also incorporate their own buffers, and these can take time to clear
out as well.

WaitTx 0

SEE ALSO: Transmit
----------------------------------------------------------------------
WatchDog PortNum%, Status%

WatchDog allows you to write programs which cannot crash. It is
useful for systems which MUST remain connected at all times. When
WatchDog is enabled by setting Status% to 1, it will watch the
specified COM port. If the carrier detect is lost on that COM port,
WatchDog will reboot the computer immediately. Caution! If WatchDog is
enabled on a COM port which does not have a carrier detect signal on
it, the computer will reboot instantly! Enable WatchDog on a port ONLY
after a connection has been established! Our example enables WatchDog
on port 0.

WatchDog 0, 1

SEE ALSO: ReBoot

QB/FOSSIL Interface v1.1 (c) 1992 Scott MacLean Page 11
======================================================================

Break: Sends a break signal to specified COM port


Break portnum%, length!

portnum% 0 through 7, for COM1 through COM8, as defined when the
fossil driver was initialized

length! length of break in seconds (single precision variable)

Returns FossErr = 0: Success
FossErr = -2: Invalid port specified
----------------------------------------------------------------------
Carrier: Reports status of Carrier Detect

result% = Carrier (portnum%)

portnum% 0 through 7, for COM1 through COM8, as defined when the
fossil driver was initialized

Returns 0: Carrier detect
-1: No carrier detect
-2: Invalid port number
----------------------------------------------------------------------
CtrlCK: Detects CTRL-C or CTRL-K on incoming data stream, without
having to read or flush input buffer. Each read resets it
for the next one.

result% = CtrlCK (portnum%)

portnum% 0 through 7, for COM1 through COM8, as defined when the
fossil driver was initialized

Returns 0: None detected since last call
-1: CTRL-C or CTRL-K detected since last call
-2: Invalid port specified
----------------------------------------------------------------------
DInit: De-initializes specified COM port after use - DTR is not
dropped

DInit portnum%

portnum% 0 through 7, for COM1 through COM8, as defined when the
fossil driver was initialized

Returns FossErr = 0: Success
FossErr = -2: Invalid port specified
----------------------------------------------------------------------

QB/FOSSIL Interface v1.1 (c) 1992 Scott MacLean Page 12
======================================================================

DTR: Raises or lowers DTR line to modem

DTR portnum%, state%

portnum% 0 through 7, for COM1 through COM8, as defined when the
fossil driver was initialized

state% 1: Raise DTR (normal operation)
0: Lower DTR (usually causes modem to disconnect)

Returns FossErr = 0: Success
FossErr = -2: Invalid port specified
FossErr = -3: Invalid DTR state specified
----------------------------------------------------------------------
FlowCtl: Turns flow control on and off, and sets type of flow control

FlowCtl portnum%, FType%

portnum% 0 through 7, for COM1 through COM8, as defined when the
fossil driver was initialized

FType% 0: Turn off flow control
1: CTS/RTS flow control
2: XON/XOFF flow control

Returns FossErr = 0: Success
FossErr = -1: Invalid type of flow control specified
FossErr = -2: Invalid port specified
----------------------------------------------------------------------
FlushIn: Discards and resets input buffer, releases flow control if
enabled

FlushIn portnum%

portnum% 0 through 7, for COM1 through COM8, as defined when the
fossil driver was initialized

Returns FossErr = 0: Success
FossErr = -2: Invalid port specified
----------------------------------------------------------------------
FlushOut: Discards and resets output buffer, releases flow control if
enabled

FlushOut portnum%

portnum% 0 through 7, for COM1 through COM8, as defined when the
fossil driver was initialized

Returns FossErr = 0: Success
FossErr = -2: Invalid port specified
----------------------------------------------------------------------

QB/FOSSIL Interface v1.1 (c) 1992 Scott MacLean Page 13
======================================================================

FVersion: Returns the version of the FOSSIL interface

result$ = FVersion

Returns Current revision of the Quickbasic FOSSIL interface
----------------------------------------------------------------------
InBufF: Returns number of bytes free in the input buffer

result& = InBufF (portnum%)

portnum% 0 through 7, for COM1 through COM8, as defined when the
fossil driver was initialized

Returns 0, or positive integer: number of characters free
-2: Invalid port specified
----------------------------------------------------------------------
InBufW: Returns number of characters waiting in the input buffer

result& = InBufW (portnum%)

portnum% 0 through 7, for COM1 through COM8, as defined when the
fossil driver was initialized

Returns 0, or positive integer: number of characters waiting
-2: Invalid port specified
----------------------------------------------------------------------
Init: Initializes specified COM port for use - DTR is raised

Init portnum%

portnum% 0 through 7, for COM1 through COM8, as defined when the
fossil driver was initialized

Returns FossErr = 0: Success
FossErr = -1: Port could not be opened, or not defined
FossErr = -2: Invalid port specified
----------------------------------------------------------------------
OutBufF: Returns number of bytes free in the output buffer

result& = OutBufF (portnum%)

portnum% 0 through 7, for COM1 through COM8, as defined when the
fossil driver was initialized

Returns 0, or positive integer: number of characters free
-2: Invalid port specified
----------------------------------------------------------------------

QB/FOSSIL Interface v1.1 (c) 1992 Scott MacLean Page 14
======================================================================

OutBufW: Returns number of characters waiting in the output buffer

result& = OutBufW (portnum%)

portnum% 0 through 7, for COM1 through COM8, as defined when the
fossil driver was initialized

Returns 0, or positive integer: number of characters waiting
-2: Invalid port specified
----------------------------------------------------------------------
OverRun: Checks for input buffer overrun (should never happen when
flow control is enabled)

result% = OverRun (portnum%)

portnum% 0 through 7, for COM1 through COM8, as defined when the
fossil driver was initialized

Returns 0: Input buffer intact
-1: Input buffer overrun - data is unreliable
-2: Invalid port specified
----------------------------------------------------------------------
ReadBaud: Returns the current baud rate, word length, parity and stop
bits from the specified port

result$ = ReadBaud (portnum%)

portnum% 0 through 7, for COM1 through COM8, as defined when the
fossil driver was initialized

Returns "bbbbbwps", where: b = baud rate
w = word length
p = parity
s = stop bits
ie: "024008N1"

spaces: Invalid port specified
also, FossErr = -2

Note: If a 5 bit word length is being used with 2 stop bits,
it will return "5N2", "5O2" or "5E2" (depending on the
parity). This indicates that it is using 1.5 stop bits,
not 2.
----------------------------------------------------------------------
Reboot: Reboots PC (closes all Quickbasic files first)

Reboot RType%

RType% 0: Cold boot
1: Warm boot

Returns (nothing, hopefully!)
----------------------------------------------------------------------

QB/FOSSIL Interface v1.1 (c) 1992 Scott MacLean Page 15
======================================================================

Receive: Retrieves up to 32767 characters from the input buffer

result$ = Receive (portnum%, chars%)

portnum% 0 through 7, for COM1 through COM8, as defined when the
fossil driver was initialized

chars% Number of characters to be retrieved, or 0 to retrieve
the entire buffer (up to 32767 characters). If more
characters are requested than exist in the buffer, only
those characters which exist are returned

Returns text: Contents of input buffer
null: Empty buffer or invalid port number
if FossErr = -2, indicates invalid port number
----------------------------------------------------------------------
SetBaud: Sets baud rate, word length, parity and stop bits for
specified port.

SetBaud portnum%, baudrate&, wordlen%, parity$, stopbits%

portnum% 0 through 7, for COM1 through COM8, as defined when the
fossil driver was initialized

baudrate& valid baud rates: 300, 600, 1200, 2400, 4800, 9600,
19200, 38400 (long integer variable type)

wordlen% 5, 6, 7 or 8

parity$ valid arguments: "N", "O", "E" (for None, Odd or Even)

stopbits% 1 or 2

Note: if 2 stop bits are specified for a 5 bit word length,
it defaults to 1.5 stop bits.

Returns FossErr = 0: Success
FossErr = -2: Invalid port specified
FossErr = -3: Invalid baud rate specified
FossErr = -4: Invalid word length specified
FossErr = -5: Invalid parity specified
FossErr = -6: Invalid stop bits specified
----------------------------------------------------------------------
Transmit: Transmits string to specified port, does not add CR/LF

Transmit portnum%, text$

portnum% 0 through 7, for COM1 through COM8, as defined when the
fossil driver was initialized

text$ any string variable, literal or constant

Returns FossErr = 0: Success
FossErr = -1: String was not transmitted
FossErr = -2: Invalid port specified
----------------------------------------------------------------------

QB/FOSSIL Interface v1.1 (c) 1992 Scott MacLean Page 16
======================================================================

TransmitC: Transmits string to specified port, adds CR/LF afterwards

TransmitC portnum%, text$

portnum% 0 through 7, for COM1 through COM8, as defined when the
fossil driver was initialized

text$ any string variable, literal or constant

Returns FossErr = 0: Success
FossErr = -1: String was not transmitted
FossErr = -2: Invalid port specified
----------------------------------------------------------------------
WaitTx: Waits for the output buffer to empty

WaitTx portnum%

portnum% 0 through 7, for COM1 through COM8, as defined when the
fossil driver was initialized

Returns FossErr = 0: Success
FossErr = -2: Invalid port specified

Note: If flow control is active, and the driver is waiting to
send data, it is possible for this function to never
return control to the caller
----------------------------------------------------------------------
WatchDog: Reboots PC if carrier is lost (Quickbasic files are NOT
closed)

WatchDog portnum%, status%

portnum% 0 through 7, for COM1 through COM8, as defined when the
fossil driver was initialized

status% 0: Disable WatchDog
1: Enable Watchdog

Returns FossErr = 0: Success
FossErr = -2: Invalid port specified

Note: Enabling this function on a port which does not cur-
rently have a positive carrier detect will cause an in-
stant reboot!

QB/FOSSIL Interface v1.1 (c) 1992 Scott MacLean Page 17
======================================================================

Help!
-----

Q: You keep talking about buffers! How do I change the size of my
buffers from within QB/FOSSIL?

A: You can't. The size of the buffers is determined when you install
your FOSSIL driver. Read the documentation that came with the FOS-
SIL driver.

Q: How come you keep talking about port 0? My computer has only COM1
and COM2. It doesn't have a COM0.

A: COM1 and Port 1 are two different things. When you start the FOSSIL
driver, you define up to eight "virtual" ports, Port 0 through Port
7. Each one of these ports "points" to a COM port. For instance,
Port 0 could represent COM3, Port 1 could represent COM1, and Port
2 could represent another COM port at some strange address. This is
all in the idea of getting away from direct hardware manipulation.
Read the documentation that came with the FOSSIL driver.

Q: What's a library? How do I get it to work with my program?

A: A library is a collection of routines which can be "added" onto
Quickbasic, but where you can't actually see the code. There are
two types of libraries, Quick Libraries (those ending in .QLB) and
regular libraries (those ending in .LIB). Quick Libraries are used
when you are running a program interpreted (in the environment) and
.LIB libraries are used when a program is being compiled. To load
the .QLB into Quickbasic, start Quickbasic with the following line:

QB /LFOSSIL45

When you compile from within the Quickbasic environment, it will
compile the .LIB library in automatically. For more information,
read the section on compiling and linking in your Quickbasic
manual.

Q: I have QBasic, that came with DOS 5. How do I get QB/FOSSIL to
work?

A: You don't. QB/FOSSIL is designed to work with Quickbasic 4.5. Go
out and spend the $90 on Quickbasic, it's well worth the money.

Q: I wrote a program with QB/FOSSIL, but it only gives me errors when
I try to run and compile it.

A: Check to ensure that you put the following line at the top of every
module which is calling QB/FOSSIL functions:

REM $INCLUDE: 'FOSSIL45.BI'

QB/FOSSIL Interface v1.1 (c) 1992 Scott MacLean Page 18
======================================================================

Release History
---------------

Date Ver Notes
--------- ---- -----
23-Jun-92 2.0 Rewrite of main routines and documentation. All func-
tions that were doing commands without returning data
were changed to subroutines to facilitate writing
readable code. Bug discovered in old version of X00.SYS
was corrected in X00.SYS version 1.3, and compensation
in the QB/FOSSIL code was removed. Use version 1.3 or
greater of X00.SYS when using version 2.0 QB/FOSSIL.

07-Mar-92 1.2 Some people reported having problems with the way the
segment pointers were being loaded, as FOSSIL was
changing the BASIC defined segment on them. This method
was removed, and a soft code method was inserted in-
stead. You can now safely execute a DEF SEG statement,
call a FOSSIL routine, and your SEG will remain as it
was before you called the routine. Routine to display
copyright changed to display through DOS instead of
through Quickbasic.

18-Feb-92 1.1 Bug was discovered in the InBufF, InBufW, OutBufF and
OutBufW routines, all of which were reporting one byte
offset incorrectly. (ie. All "Waiting" functions would
always report one byte waiting, even when buffers were
empty)

31-Jan-92 1.0 Initial Release: Beta test completed