QuickBASIC FOSSIL Comms Routines
by Tom Collins
Version 1.0
10-19-90

Intro
-----

With the introduction of the FOSSIL (Fido-Opus-SEADog standard interface
layer), the BBS community has ushered in a way to write fast
computer-independent communications routines for any computer that
supports a FOSSIL implementation. FOSSILs provide a high-level
interface to the computer's RS-232 port via a series of assembly
language calls.

Unfortunately, FOSSIL implementations are a rarity among QuickBASIC
programmers, as many either don't understand or don't want to get
involved in writing assembly-language routines.

With the release of the X00 FOSSIL driver, version 1.20c, Ray Gwinn
included what's called a HLLAPI interface into releases of X00. This
provides the QuickBASIC programmer with a good way to invoke FOSSIL
functions without using QB's CALL INTERRUPT routines. Unfortunately,
the QuickBASIC programmer still had to write generic FOSSIL routines
using Gwinn's HLLAPI modules. QBFCOMMS relives the programmer of this
hassle by providing simple, QB-callable routines for FOSSIL interface.

Included
--------

Included in this archive is:

QBFCOMMS.DOC - What you're reading now.

QBFCOMMS.BAS - Source code for the QuickBASIC FOSSIL interface
routines.

QBFCOMMS.BI - Header file containing declarations for all of the
QBFCOMMS functions, as well as some miscellaneous
CONSTs.

QBFCOMMS.OBJ -
QBFCOMMS.LIB - LINKable compiled versions of the above.

QBFCDEMO.EXE -
QBFCDEMO.BAS - Demo illustrating how to call QBFCOMMS functions.

DEMO.BAT - Batch file to run QBFCDEMO.EXE.

INQB.BAT - Batch file illustrating how to invoke QB.EXE for the
QBFCDEMO.BAS and QBFCOMMS.BAS files.

QBFCDEMO.MAK - Used by QB.EXE when running INQB.BAT.

Not Included
------------

To make this package work, you'll need QBX00.OBJ from a recent X00
release, as well as QuickBASIC v4.5. (v4.0 may work... dunno)

Warranty
--------

Yea, right.

Shareware?
----------

QBFCOMMS isn't shareware. It's free for all to use and learn from. If,
however, you use QBFCOMMS in a program of yours, please give credit to
me for QBFCOMMS.

Usage
-----

1. Get a recent X00 release (the version used for testing these
routines was v1.23j). Included in the X00 archive (somewhere!) is
QBX00.OBJ. Extract this file, the FOSSIL.DOC file and the FOSSIL.CHT
file.

2. If you plan to write and test applications using QB.EXE, the
QuickBASIC integrated environment, you'll need to create a .QLB and a
.LIB version of QBX00.OBJ. If you're just going to use BC.EXE, the
command-line compiler, skip this step.

To create QBX00.QLB from QBX00.OBJ, try:
LINK /Q QBX00,,,BQLB45.LIB

To create QBX00.LIB from QBX00.OBJ, do this:
LIB QBX00 +QBX00;

(LINK.EXE, LIB.EXE and BQLB45.LIB should be on your original QuickBASIC
diskettes)

3. Invoke a FOSSIL driver on your system. The driver can be X00,
loaded as a TSR or a device driver, BNU or any other FOSSIL driver. For
testing, it's best to use X00 until everything works.

4. Run DEMO.BAT. This will illustrate most of the functions provided
in QBFCOMMS. You should verify that the demo can transfer information
between two computers. The computers should be connected via modem over
a phone line or with a cable and a NULL modem adapter. On the computer
that's not running the demo, invoke Procomm or another terminal program.
Until the demo can transfer information between computers, there's no
point in writing applications using QBFCOMMS.

5. When you're satisfied that the demo can transfer information
properly, look at the demo source code, the QBFCOMMS source code, and
Gwinn's FOSSIL.DOC and FOSSIL.CHT to determine what functions you'll
need in your application. Remember QBFCOMMS provides a simple,
QB-callable set of functions for interfacing to the FOSSIL, so don't
dwell on the assembly-language interface details in FOSSIL.DOC. Just
make a note of the functionality of the FOSSIL.

6. Write and test your own applications using QBFCOMMS.

Compiling and Linking
---------------------

If you're using BC.EXE for your QB work, you can link QBFCOMMS into your
routine (assumed to be called MYPROG.BAS) like this:

BC myprog.bas /o;
LINK myprog.obj+qbfcomms.obj+qbx00.obj;

If you're using QB.EXE to develop your programs, do this:

a) Create QBX00.QLB and QBX00.LIB, as outlined above.

b) Create a MYPROG.MAK file containing:

MYPROG.BAS (line 1)
QBFCOMMS.BAS (line 2)

and invoke QB.EXE like this:

QB myprog /lqbx00.qlb

With this setup, when you're done with MYPROG.BAS, just tell QB to
make a standalone EXE to create MYPROG.EXE.

Functions Supplied
------------------

FossilAnsiPrint% (A$)

Prints A$ on the screen using ANSI processing.

FossilBIOSPrint% (A$)

Prints A$ on the screen using the PC's BIOS functions.

FossilBreak% (Port%, Ctrl%)

Sends a BREAK signal to the modem. If Ctrl% is a 1, it starts
sending the BREAK. If it is 0, the function stops sending the BREAK.

FossilCtrlKCtrlC% (Port%, Ctrl%)

Enables or disables extended ^K and ^C FOSSIL checking. See the
values in QBFCOMMS.BI for possible Ctrl% values.

Returns:
1 - ^C or ^K has been received
0 - ^C or ^K hasn't been received

FossilDTR% (Port%, Ctrl%)

Sets or resets the DTR line of a port. Ctrl% equal to 1 sets DTR,
Ctrl% equal to 0 resets it.

FossilDeactivate% (Port%)

Deinitializes the FOSSIL for a given port.

FossilFlowControl% (Port%, Ctrl%)

Sets up the flow control (XON/XOFF, etc) to be used on a port. See
QBFCOMMS.BI for possible Ctrl% values.

FossilFlush% (Port%)

Forces pending output to be sent to the port.

FossilGetb% (Port%, Buffer$, Length%)

Gets a buffer of data from a port.

Returns:
The number of characters actually received.

Warning:
See the QBFCDEMO program for how to use this function. Incorrect
use will cause string space corrupts and other nasties to occur.

FossilGetch$ (Port%)

Gets and returns a character from a port, or a null string if no data
is available.

FossilInfo% (Port%, Rev%, Ver%, ID$, ISZ%, IFR%, OSZ%, OFR%, SW%, SH%, Baud&)

Gets a bunch of information about the FOSSIL:

Rev% - FOSSIL revision this driver follows
Ver% - FOSSIL version this driver follows
ID$ - ID string ("BNU Fossil Driver")
ISZ% - Input buffer size
OSZ% - Output buffer size
IFR% - Input buffer bytes free
OFR% - Output buffer bytes free
SW% - Screen width
SH% - Screen height
Baud& - FOSSIL current baud rate (300,1200...)

FossilInit% (Port%)

Initializes a port for communications.

Returns:
0 - Success
1 - Couldn't initialize the port

FossilInkey% ()

Reads a key from the local keyboard and returns the scan code for the
key received. If no key was available, -1 is returned.

FossilInkeyWait% ()

Just like FossilInkey(), 'cept this function will wait forever for a
keystroke before returning.

FossilLocate% (Row%, Column%)

Moves the cursor to a given screen row and column. The coordinates
place (0,0) at the upper left corner of the screen.

FossilPeek$ (Port%)

Looks into the FOSSIL input buffer to see if a byte is available. If
it is, that byte is returned (but not removed from the buffer). If
nothing is available, the function returns "". Use FossilGetch() to
remove the data from the input buffer.

FossilPurgeInputBuf% (Port%)

Purges all pending input from the FOSSIL input buffer.

FossilPurgeOutputBuf% (Port%)

Purges all pending data from the FOSSIL output buffer.

FossilPutb% (Port%, Buffer$)

Writes a string of data to a port and returns with the number of
characters actually written. If this number is less than the length
of the string, the input buffer filled up as a result of the
FossilPutb() call.

FossilPutch% (Port%, Char$)

Writes a character to the output buffer.

Returns:
1 - Success
0 - No room in output buffer for character

FossilPutchWait% (Port%, Char$)

Just like FossilPutch() except this function will wait forever until
it can send the requested character.

Returns:
The port status (see FossilStatus())

FossilReadCursor% (Row%, Column%)

Gets the current screen cursor position.

FossilReboot% (Ctrl%)

Reboots the computer. If Ctrl% is 1, a warm boot is invoked. If
Ctrl% is 0, a cold boot is performed.

FossilSetBaud% (Port%, BaudRate&)

Sets the baud rate for a port. The baud rate should be 300, 600,
1200, 2400, 4800, 9600, 19200 or 38400.

Returns:
The port status (see FossilStatus())

FossilStatus% (Port%)

Gets the status of a port. Various values are OR'd together, as
defined in the QBFCOMMS.BI file. See the QBFCDEMO.BAS file for an
example.

FossilWatchdog% (Port%, Ctrl%)

Turns on (Ctrl% = 1) or off (Ctrl% = 0) the FOSSIL watchdog
function. Watchdogs automatically reboot your computer if the
carrier drops.

For more information on how the functions work, take a look at
FOSSIL.DOC. To see examples of using the functions, see QBFCDEMO.BAS.
That's why it's included.


Good Luck!

-- Tom Collins