Category : BASIC Source Code
Archive   : QBCOM.ZIP
Filename : QUICKCOM.DOC

QUICKCOMM Version 1.0
June 9, 1989
Copyright 1989 by David Cleary











































DISCLAIMER:

This software is marketed as shareware and as such, is
only guaranteed to take up disk space. The author is not
responsible for any loss resulting in using this product. By
choosing to use this product, you assume all risks involved.

DISTRIBUTION:

I encourage distribution of this software in its
unmodified form as long as no fee is charge except a nominal
disk charge not to exceed $10. I require that if you
distribute this package, that it be distributed in a self
extracting ZIP format. I have done this because there is no
longer any standards left in the file archiving world. I
don't like getting some software and then find that I have to
get yet another unarcing utillity to use it. I have chosen
ZIP because it works well and I think PKWARE origanated the
self extracting type.


REGISTRATION:

I ask that everyone who tries this software, likes it,
and plans on using it, to please register it. Registration is
FREE and will allow you to receive free telephone support. By
registering, you will also be notified about major updates
and new product announcements. Please take the time to fill
out the registration form at the end of this documentation.


LICENSE:

Quickcomm's four part licensing agreement:

1. You are free to use this package for your own personal
use as you see fit. Read on about distributing programs.

2. If you use this package for a shareware or freeware
product, all I ask for is a full registered version of
the software and all rights I would receive as a
registered user. I have done this to help promote
shareware by providing these tools at no monetary cost
to shareware authors.

3. If you use this package for a commercial product, a fee
of $50 is required. This will entitle you to use this
product royalty free for all versions of a particular
product. A fee of $50 is required for each particular
product you use this package for.















4. If you plan on using this package for software
distributed in house of a corporation, a fee of $50 is
required. This will allow your company all rights to use
this product in any and all software distributed in
house. Send a check or money order payable to David
Cleary to the address on the registration form.



CONTACTING THE AUTHOR:

I can be contacted a number of ways. The fastest way is
by sending in your free registration and receiving free
telephone support. The next fastest way is by sending me a
FIDO Netmail message to 1:141/730. I am also active in the
QUIK_BAS and ECPROG FIDO echoes. I can be contacted on
COMPUSERVE by sending mail to 76510,1725 or on PRODIGY by
sending mail to HSRW18A although I am not very active on
these services. You can also send a letter to me at the
address on the registration form.



ABOUT QUICKCOMM:

I wrote QuickComm because of the problems I was having
with the com routines in QuickBASIC. I would get device
errors whenever there was line noise or just for no reason at
all. I also need to support baud rates higher than 9.6K. I
was able to work around these faults but after I wrote this,
my programs became much more reliable and easier to use.

QuickComm is an interrupt driven communications library
for Microsoft QuickBASIC versions 4.0b and 4.5. It was
written and compiled with Microsoft C 5.1 with all calls to
routines in the C library rewritten in assembly. There is a
layer of QB code to ease the user interface. While this is
not the most efficient way of doing things, I felt it was
necessary to make this product easy to use. There may be an
advanced version in the future that doesn't contain this
interface.

QuickComm may support QuickBASIC version 3.0 in the
future if there is demand for it. I know that version 3.0
does not do direct screen writes and also supports an
alternate math library, making programs execute faster.
Quickcom supports only Com1 and Com2 at this time. Support
for more com ports will be included in the future as I learn
more about the hardware involved. QuickComm will support a
baud rate up to 112K although the actual baud you achieve
will be limited to your hardware.














Versions of QuickComm for Microsoft C/QuickC and
Microsoft ForTran 4.1 may be available in the future if there
is demand for it. There is no support planned for QuickPascal
at this time because it is not compatible with other
Microsoft languages and I don't have it. With the advent of
QuickAssembler, I hope to optimize even further the assembly
language generated by C 5.1 but this will take some time as I
improve my programming in assembly. I also plan to release a
toolbox for QuickComm that will be BASIC source for alot of
communication functions. Registered users will be the first
to know about the release.

I have included source to two BASIC programs. The first
is called TREMINAL. It is the program that is distributed
with QuickBASIC. This program is what taught me how to use
the serial port. The other program is called TERMQKCM. It is
adapted to use the QuickComm library. I also suggest reading
"Programming in BASIC. Selected Topics." for those of you who
bought QB 4.0 and got the manuals. It explains thier TERMINAL
program pretty well.

I know this documentation sucks. I am sorry but when it
started taking longer than the programming took, I had to
rush it. When I release the next version of QuickComm, I
promise that the documentation will be better. This is what
happens when you wait till the end to do the documentation.


A NOTE ABOUT CHAINING AND SHELLING:

If you do door type programs and have to CHAIN or SHELL,
here is a simple rule of thumb to follow. If the program you
transfer control to does not need to access the com port, use
SHELL. The interupt routine will stay in memory and handle
all input while in the other program. If you need to transfer
control to a program that has to use the com port, use call
QComChain first and then use CHAIN or RUN. QComchain will
remove the interrupt routine but keep DTR hi so your modem
won't disconnect. Then if you are in another QB program, call
QComInit to put the interrupt routine back in memory. If you
don't call QComChain or QComClose before your program
terminates or transfer control permenantly to another
program, YOUR MACHINE WILL LOCK UP. It will jump to a place
in memory that no longer has a valid routine and it will
crash.

When you use QuickCom in the enviroment, you should save
your program before you run it. While I think I got it to
work pretty well in the enviroment, I am not guarenteeing
anything. If you loose cde because your machine locks up and
you didn't save your program, you have been warned.















QComBuffOut

Function

QuickBASIC Equiv: PRINT #1,

Use: Ercd% = QComBuffOut("This is a string I want to print")

Returns: 0 Worked properly.
-2 Com Port not initialized.
-4 Time out on Com Port handshake lines.
-5 Transmit buffer not empty.
#Bytes Returns number of bytes it put into the
transmit buffer. The only way for this to
happen is by sending more than 2048 bytes at
a time.

I had problems with this routine if I sent things while
the buffer was still transmitting. It would stall and I don't
know why. To solve this, the transmit buffer must be empty.
This is so I can start the interrupts up in a reliable way. I
hope to have this routine improved by the next release.
This routine is very useful for file transfers. The size
of the buffer is 2048 bytes. Once it gets done dumping the
data into the buffer, you regain control while it is sending
the data. This will allow you to get the next block of data
from disk or other things you might have to do without
slowing down the transfer. This does not add a carriage
return/linefeed at the end. If you need that, you must add it
yourself.


EXAMPLE:

OPEN "SENDTHIS.FIL" FOR BINARY AS #1 LEN=1024 'OPEN FILE
'YOU WANT
'TO SEND

DO UNTIL EOF(1)
GET #1,,A$ 'GET 1K BLOCK
DO:LOOP UNTIL(QComXLoc = 0) 'WAIT FOR XMIT TO
'EMPTY
IF (QComBuffOut(A$)) 'BUFFERED PRINT
PRINT "ERROR TRANSMITTING FILE"
END
END IF
LOOP



















QComChain

Subroutine

QuickBASIC Equiv: None

Use: Call QComChain or just QComChain


This routine is used to transfer control to another
program permanently without dropping DTR. This is used when
you use the QB commands CHAIN or RUN. It returns control over
to the BIOS for all com input and output. You should make
sure you don't have anything in the transmit or receive
buffers when you call this or you will lose it. I hope it
solves the problem people have with door programs and QB. I
have not had to do anything like this myself so I am not sure
exactly what people are trying to do. If this doesn't solve
that problem, let me know and I will try to solve it.
If you use the QB command SHELL to transfer control to
another program, the interrupt routine still resides in
memory and will function except the program you shelled to
will not have any access to it. You should only use SHELL if
you need to run a program that doesn't need to use the com
port. Use CHAIN or RUN for all other purposes.


EXAMPLE:

QComChain 'CLOSE COM PORT LEAVING DTR HI
CHAIN "NEXTPROG.EXE" 'PROGRAM TO TAKE CONTROL



































QComClose

Subroutine

QuickBASIC Equiv: CLOSE #

Use: Call QComClose or just QComClose


This routine is exactly the same as the QComChain
routine except that it drops DTR. You must make sure you
close the com port when your program terminates or you will
have problems with you machine locking up. It will expect an
area in memory to goto when there is input to the com port
and will overwrite what's ever in memory there.


EXAMPLE:

QComClose 'CLOSE PORT AND RESET INT VECTOR
END













































QComDTR

Function

QuickBASIC Equiv: None

Use: ErCd% = QComDTR(Toggle) Toggle = 0 DTR Dropped
Toggle = Not(0) DTR Raised

Returns: 0 Worked Properly
-2 Com Port not initialized


This routine lets you control the DTR line. Sending it a
0 raises it and anything else drops it.


EXAMPLE:

IF (QComDTR(-1)) THEN PRINT "Com port not initialized"














































QComEOF

Function

QuickBASIC Equiv: A = EOF(1)

Use: A = QComEOF

Returns: 0 Data in receive buffer
-1 Receive buffer empty


This routine emulates QuickBASIC's EOF function. It
returns a 0 if there is data in the buffer or a -1 if it is
empty.


EXAMPLE:

IF NOT(QComEOF) 'CHECK FOR CHARACTERS IN RECEIVE BUFFER
ModemIn$ = QComInput$(ErrorCode) 'GET CHARACTERS
PRINT ModemIn$; 'PRINT CHARACTERS
END IF











































QComFlush

Subroutine

QuickBASIC Equiv: None

Use: CALL QComFlush


This routine flushes the transmit and receive buffers.
IMPORTANT... If you have a receive buffer overflow, you must
make a call to this routine. Otherwise your program will be
in limbo.


EXAMPLE:

CALL QComFlush
















































QComInit

Function

QuickBASIC Equiv: OPEN "COM1:"

Use: ErCd% = QComInit(Parameters$)

Returns: 0 Worked properly
-1 Syntax error in Parameter$


This is the heart of the package. This installs the
interrupt routine and sets up all the parameters. Parameters$
has the following syntax:

Port,Baud,Parity,Databits,Stopbits,Handshaking

Port: COM1:
COM2:

Baud: 110 4800
150 9600
300 19200
600 38400
1200 57600
2400 115200

Parity: N
E
O

Databits: 5
6
7
8

Stopbits: 1
2

Handshake: CTS
NONE

You select the parameters you want and separate them by
commas and put them into a string. You can call this routine
as many times as you want in order to change a parameter. You
must include all of them. QuickComm supports COM1 or COM2.
You can not switch com ports unless you call QComClose to
close the port first. Quickcom supports baud rates from 110
to 115200. It supports CTS handshaking. If the receive buffer
gets near full, RTS is dropped until the buffer is emptied.
Of course the other computer must stop sending when RTS is














dropped or you could still overrun the buffer.


EXAMPLE:

If you wanted to open COM1 at 2400 baud with 8 databits, 1
stopbit, no parity and CTS handshaking it would be:

ErCd% = QComInit("COM1:,2400,N,8,1,CTS")

Remember to put a comma between the COM1 and 2400.























































QComInput$

Function

QuickBASIC Equiv: INPUT$()

Use: ModemIn$ = QComInput$(ErCd%)

Returns: String from recieve buffer.

Errorcodes: 0 Worked properly
-2 Com port not initialized
-3 Receive buffer overflow
-5 No characters in buffer


This routine gets a string from the receive buffer.
IMPORTANT... If you get a receive buffer overflow error, you
must execute a QComFlush to have your program continue to
function properly.


EXAMPLE:

ModemIn$ = QComInput$(ErCd%)
IF ErCd% = -3 THEN CALL QComFlush








































QComOut

Function

QuickBASIC Equiv: PRINT #

Use: ErCd% = QComOut("This is what I want to send.")

Returns: 0 Worked properly.
-2 Com Port not initialized.
-4 Time out.

This routine outputs a string to the com port with out
buffering. It will output characters and when it is
completed, will return control back to your program. This is
what you should use unless you are sending a large amount of
data. This routine does not add carraige returns or
linefeeds so you have to add them to your string yourself if
you want them.


EXAMPLE:

KeyInput$=INKEY$
IF KeyInput$<>"" THEN
ErCd% = QComOut(KeyInput$)
IF ErCd% THEN PRINT"ERROR TRYING TO OUTPUT TO COM PORT
END IF






































QComRLoc

Function

QuickBASIC Equiv: A% = LOC(1)

Use: Bytes% = QComRLoc

Returns: 0 Receive buffer empty.
>0 Number of bytes in receive buffer.


This function returns the number of characters in the
receive buffer. It ruturns 0 if the buffer is empty.


EXAMPLE:

See Use.















































QComRTS

Function

QuickBASIC Equiv: None

Use: ErCd% = QComRTS(Toggle%) Toggle = 0 RTS Dropped
Toggle = Not(0) RTS Raised

Returns: 0 Worked Properly .
-2 Com Port not initialized.


This routine is similar to QComDTR except it works on
the RTS line. You drop this line if you want the other guy to
stop sending you stuff. If you select CTS handshaking when
you call QComInit, DTR is automatically dropped when the
buffer gets near full and is raised when it gets near empty.


EXAMPLE:

IF (QComDTR(-1)) THEN PRINT "Com port not initialized."











































QComXLoc

Function

QuickBASIC Equiv: None

Use: Bytes% = QComXLoc

Returns: 0 Transmit buffer empty.
>0 Number of bytes in transmit buffer.


This routine is similar to QComRLoc except it checks the
transmit buffer. It will always return 0 unless you use
QComBuffOut.


EXAMPLE:

See Use.














































Please mail this registration if you plan on using this
program.

Mail to:

DAVID CLEARY
LAKEVIEW TERRACE EXT.
SANDY HOOK, CT 06482




NAME:___________________________________________________


ADDRESS:________________________________________________


CITY,STATE ZIP:_________________________________________



ANY COMMENTS,SUGGESTIONS,BUGS:__________________________


________________________________________________________


________________________________________________________


________________________________________________________


________________________________________________________


________________________________________________________


________________________________________________________