home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Shareware 1 2 the Maxx
/
sw_1.zip
/
sw_1
/
PROGRAM
/
PCL4C30.ZIP
/
PCL4C.USR
< prev
next >
Wrap
Text File
|
1992-01-27
|
56KB
|
1,651 lines
Personal Communications Library
For the C Language
( PCL4C )
USERS MANUAL
Version 3.0
Jan 15, 1992
This software is provided as-is.
There are no warranties, expressed or implied.
Copyright (C) 1992
All rights reserved
MarshallSoft Computing, Inc.
Post Office Box 4543
Huntsville AL 35815
Phone (205) 881-4630
PCL4C Users Manual Page 1
Table of Contents
Chapter Page
Introduction.........................................3
Registration.........................................4
Library Overview.....................................5
Initialization & Termination......................5
Configuration.....................................5
Modem Control & Status............................6
Serial I/O........................................6
Error Detection...................................7
General Support...................................7
Library Memory Models................................8
Compilers Supported..................................9
Installation........................................10
Using the Library...................................11
Compiling & Linking.................................12
Talking to your Modem...............................13
Problems............................................14
Function Summary....................................15
Serial Communications...............................16
IBM Communications Ports............................17
RS232 Signals.......................................18
National INS8250 UART...............................19
Register Summary....................................20
Example Code........................................22
SIMPLE...........................................22
INTERCOM.........................................22
MODEM............................................22
NORESET..........................................22
TERM.............................................23
XFER.............................................23
LOOPBACK.........................................23
BBS..............................................23
Revision History....................................24
License.............................................25
Warranty............................................25
PCL4C Users Manual Page 2
Introduction
The Personal Communications Library for the C Language ( PCL4C )
is an asynchronous communications library designed for experienced
software developers programming in C. Four compilers are
supported: Microsoft Optimizing C, Microsoft Quick C, Borland
Turbo C, and MIX Power C. An IBM PC/XT/AT or compatible is
required. The PCL features:
o SMALL, COMPACT, MEDIUM & LARGE memory models.
o 29 communications and support functions.
o Interrupt driven receiver.
o Supports 300 baud to 115,200 baud.
o Supports COM1, COM2, COM3, and COM4.
o Adjustable receive queues from 8 bytes to 16 KB.
o Control-BREAK error exit.
o 17 communications error conditions trapped.
o Allows 2 ports to run concurrently.
o Complete modem control & status.
o Written in assembly language for small size & high speed.
A typical application program using PCL4C might look like the
following code outline:
+-------------------------------------------------------+
| #include "pcl4c.h" |
| |
| char Buffer[1024]; |
| main() |
| {/* initialize serial comm system */ |
| SioRxBuf(Port,Buffer,Size1024); |
| SioParms(Port,NoParity,OneStopBit,WordLength8); |
| SioReset(Port,Baud2400); |
| |
| ...application code... |
| |
| /* terminate serial comm system */ |
| SioDone(Port); |
| } |
+-------------------------------------------------------+
In the above example, SioRxBuf is called to set up the a 1024 byte
receive buffer; SioParms is called to set up the parity, stop bit
count, and word length; SioReset is called to set the baud rate to
2400 and reset the UART ( Univeral Asynchronous Receiver /
Transmitter ).
Before leaving your application, SioDone is called to restore the
prior state of the serial communications system.
PCL4C Users Manual Page 3
Registration
The shareware version of PCL4C.LIB is provided so that you may
personally determine the usefulness of the product for yourself.
If you can use the Personal Communications Library for C, please
register your use with us. Send $45 plus $3 S&H ( $6 outside of
the USA, Canada, and Mexico ) to:
MarshallSoft Computing, Inc.
Post Office Box 4543
Huntsville AL 35815
Please pay by check in US dollars drawn on a US bank. Payment must
accompany purchase orders. Print the file PCL4C.INV if an invoice
is needed. The registered package is mailed first class US Mail
and includes:
o Small, Compact, Medium & Large memory model libraries without
the shareware screens.
o Assembler source code for the library.
o Printed Users Manual.
o Printed Reference Manual.
o Telephone support for one year.
o All updates ( with printed manuals ) are $15 plus $3 S&H
( $6 outside of USA, Canada, & Mexico ).
PCL4C.ASM is the source code for the library. The source code is
copyrighted by MarshallSoft Computing, Inc. The user is granted a
license to use the PCL4C object code in his own application only.
PCL4C.ASM is not shareware and may not be sold or given away to
anyone.
The registered user will receive the latest version of PCL4C by
return mail. A 5.25" diskette is provided unless a 3.5" diskette
is requested.
PCL4C Users Manual Page 4
Library Overview
The PCL4C library is organized into six categories of functions.
Refer to the PCL Reference Manual ( PCL4C.REF ) for details on
individual functions.
1. Initialization & Termination
There are five functions in the initialization and termination
category. Together, SioParms, SioRxBuf, and SioReset initialize
your serial communications system. Your application must call
SioParms and SioRxBuf before calling SioReset, and SioReset must
be called before any serial I/O processing can be done.
After initialization, SioParms and SioBaud can be called again to
change the communications parameters without resetting the serial
port.
Before exiting from your application, SioDone must be called.
Failure to call SioDone can crash your system later.
SioRxBuf -- Sets up receive buffer.
SioParms -- Sets parity, stop bits, and word length.
SioReset -- Initialize a serial port for processing.
SioDone -- Terminates further serial processing.
SioBaud -- Sets the baud rate of the selected port.
2. Configuration
SioUART is the only function in the configuration category. It is
used to change the UART base address for a communications port at
a non-standard address Note however, that IRQ4 is still used for
ports COM1 and COM3, while IRQ3 is still used for ports COM2 and
COM4. ( See the chapter IBM Communications Ports for more details
on standard UART addresses and IRQ lines ).
SioUART can also be used to set the UART base address to zero for
non-existant ports. For example, if you don't have COM4 installed
in your computer ( SioLoopBack will return an error ), use SioUART
to zero the UART address for COM4:
SioUart(COM4,0)
Then, any subsequent attempt to reset COM4 will result in a "UART
undefined" message - reminding you that you don't have COM4.
SioUART -- Sets the UART base address.
PCL4C Users Manual Page 5
3. Modem Control & Status
There are seven functions in the modem control and status
category which provide your application with complete control over
the status and control bits of your modem.
There are two modem control bits, "Data Terminal Ready" ( DTR )
and "Request To Send" ( RTS ). These bits can be read, set, or
cleared by SioDTR and SioRTS.
There are four modem status bits, "Data Set Ready" ( DSR ), "Clear
To Send" ( CTS ), "Ring Indicator" ( RI ), and "Data Carrier
Detect" ( DCD ). SioModem can read any of the modem status bits.
SioDSR, SioCTS, SioRI, and SioDCD can only read their respective
modem status bit.
Refer to the chapter entitled "RS232 Signals" for a discussion of
each of the control and status bits.
SioDTR -- Set, clear, or read the Data Terminal Ready (DTR) bit.
SioRTS -- Sets, clears, or reads the Request to Send (RTS) line.
SioModem -- Reads the modem status register.
SioDSR -- Reads the Data Set Ready (DSR) modem status bit.
SioCTS -- Reads the Clear to Send (CTS) modem status bit
SioDCD -- Reads the Data Carrier Detect (DCD) modem status bit.
SioRI -- Reads the Ring Indicator (RI) modem status bit.
4. Serial I/O
There are six library functions in the serial I/O category.
Together, these functions give the programmer complete control
over serial I/O. Higher level functions such as protocols and
smart modem communications can be completely implemented in terms
of these functions. Refer to the example code.
SioGetc and SioPutc perform all the actual serial I/O. SioUnGetc
and SioRxFlush modify the receive queue. SioLine can be used to
test for UART errors.
SioGetc -- Reads the next character from the serial line.
SioPutc -- Transmit a character over a serial line.
SioUnGetc -- "Un-gets" (puts back) a specified character.
SioRxFlush -- Flush ( clears) the receive buffer.
SioRxQue -- Returns the number of characters in the receive queue.
SioLine -- Reads the line status register.
PCL4C Users Manual Page 6
5. Error Detection
There are four functions in the error detection category. They are
concerned with detecting or reporting communications errors. Use
of these functions can make your application significantly more
robust.
SioBrkKey can be used as an "emergency" exit from your
application. SioBrkSig can read or modify the UART break bit. This
is useful for signalling the remote system that a fatal condition
has occurred. SioLoopBack can be used to test the integrity of
your UART. SioError displays a error message corresponding to an
error code returned from a PCL4C function ( every PCL4C function
returns a code ).
SioBrkKey -- Returns non-zero if the Control-BREAK key was pressed
SioBrkSig -- Asserts, cancels, or detects BREAK signal.
SioError -- Displays error in text.
SioLoopBack -- Performs a UART loopback test.
6. General Support
There are six functions in the general support category. Strictly
speaking, they are not communications functions but are provided
in the PCL4C library because they are not always available (
especially in some older compiler run-time libraries ). At any
rate, they take up a very small amount of additional memory.
Registered users can also remove these functions from the library
if needed.
SioCrtWrite -- Write character to the screen.
SioDelay -- Delays one or more tics.
SioKeyPress -- Detects if keyboard has been pressed.
SioKeyRead -- Reads the keyboard.
SioTimer -- Returns the number of system clock tics.
PCL4C Users Manual Page 7
Library Memory Models
Because of the segmented architecture of the INTEL CPU, there are
four memory organizations possible for computer programs. These
are named the SMALL, COMPACT, MEDIUM, and LARGE memory models,
which correspond to the four combinations of "near" and "far"
addresses for code and data.
Each executable is composed of one or more segments, where each
segment can occupy from one byte to 64 KB of memory. A "near"
address is a 16 bit offset in a segment, whereas a "far" address
consists of both a 16 bit segment value and a 16 bit offset.
In the small memory model, code and data each occupy one segment.
Thus, near addresses are allocated for both code and data.
In the compact memory model, code occupies one segment while data
may occupy multiple segments. Near addresses are allocated for
code but far addresses are allocated for data.
In the medium memory model, data occupies one segment while code
may occupy multiple segments. Near addresses are allocated for
data but far addresses are allocated for code.
In the large memory model, data and code each occupy multiple
segments. Far addesses are allocated for both code and data.
Thus, both code and data can use as many segments as required.
Refer to your compiler manual for a discussion of the memory
models supported by your compiler.
PCL4C is organized as four separate libraries ( PCL4C_S.LIB,
PCL4C_C.LIB, PCL4C_M.LIB and PCL4C_L.LIB ) corresponding to the
four standard memory models. For the MIX Power C compiler, the
small, medium, and large models are provided ( PCL4C_S.MIX,
PCL4C_M.MIX and PCL4C_L.MIX ). MIX doesn't support the compact
memory model.
MODEL CODE DATA Library
Small Near Near PCL4C_S.LIB & PCL4C_S.MIX
Compact Near Far PCL4C_C.LIB
Medium Far Near PCL4C_M.LIB & PCL4C_M.MIX
Large Far Far PCL4C_L.LIB & PCL4C_L.MIX
However, one can always use the large memory model library
PCL4C_L.LIB with any memory model application code by explicitly
declaring the PCL4C procedures to be FAR ( by prefixing "far"
before the name of each function in the PCL4C.H file ) and
declaring your receive buffer to be FAR. This was the method used
in early versions of PCL4C.
PCL4C Users Manual Page 8
Compilers Supported
At this time, four compilers are supported by PCL4C.
(1) Microsoft Optimizing C Compiler
(2) Microsoft Quick C Compiler
(3) Borland Turbo C Compiler
(4) MIX Power C Compiler
The Microsoft Optimizing C Compiler supports all memory models.
Just be careful to link with the PCL4C library that corresponds to
the memory model used. Recall that the small memory model is the
default. Examine the ( small model ) makefiles *._M_ for the
Microsoft compiler.
The Microsoft Quick C Compiler supports all memory models, but be
careful to link with the PCL4C library that corresponds with the
memory model used. Recall that the small memory model is the
default for the command line compiler ( QCL ) while the medium
memory model is the default for the interactive compiler
environment. Examine the ( small model ) makefiles *._Q_ for the
Microsoft Quick C compiler.
The Borland Turbo C Compiler also supports all memory models. Be
sure to link with the correct PCL4C library corresponding to the
memory model used. Examine the ( small model ) makefiles *._T_
for the Turbo C compiler.
The MIX Power C Compiler supports the small, medium, and large
memory models. However, older versions of Power C only support the
small model. Examine the ( small model ) project batch files
X_*.BAT for the Power C Compiler.
Other compilers may also work with one or more of the PCL4C
libraries but have not been tested. Since registered users have
the source code to the library, it should not be difficult to
modify PCL4C for use with any MSDOS C compiler.
PCL4C Users Manual Page 9
Installation
(1) Before installation of PCL4C , your C compiler should already
be installed on your system and tested. If you are not familiar
with makefiles, refer to your compiler manual. If you are using
the interactive environment for Quick C or Turbo C, be sure to
compile with the memory model corresponding to the PCL4C library
used. Examine the file "FILES.LST" for a list of all the
distribution files.
(2) Make a backup copy of your distribution disk. Put your
original distribution disk in a safe place.
(3) Create a work directory on your work disk ( normally your
harddisk ). For example, to create a work directory named PCL4C,
we first log onto the work disk and then type:
MKDIR PCL4C
(4) Copy all the files from your backup copy of the distribution
disk to your work directory. For example, to copy from the A:
drive to your work directory, we type:
CD PCL4C
COPY A:*.*
(5) [OPTIONAL] Delete the makefiles that you won't need. For
example, if you use the Microsoft C compiler, then you want to
keep all makefiles ending *._M_ but can delete those for Turbo C (
*._T_ ), Quick C ( *._Q_ ), and MIX Power C ( X_*.BAT ). You may
also delete any libraries that you won't need.
(6) Compile SIMPLE.C and link with the appropriate PCL4C library (
PCL4C_SM.LIB for all but Power C which must use PCL4C_S.MIX ).
Makefiles ( or project files ) are provided for each of the
supported compilers.
a) Microsoft C: Type MAKE SIMPLE._M_
b) Microsoft Quick C: Type MAKE SIMPLE._Q_
c) Borland Turbo C: Type MAKE -FSIMPLE._T_
d) MIX Power C: Type X_SIMPLE
SIMPLE.C should compile without any problems as all example code
has been tested with each of the supported compilers.
(7) The recommended way to test SIMPLE is to run it on two
computers connected by a null modem cable. Whatever is typed on
one computer should be displayed on the other.
(8) Compile and run each of the remaining example programs.
PCL4C Users Manual Page 10
Using the Library
The PCL4C has been tested on a TANDY 1000 ( 4.77 MHZ 8088 IBM PC
clone ), a TANDY 3000 ( 80286 IBM AT clone ), a TANDY 1400LT ( IBM
XT clone ), and a Gateway 2000 Cache ( 25 MHZ 80386-DX ). PCL4C
has been tested under MSDOS 2.11, 3.2, 3.3, 4.01, and 5.0.
Please examine the PCL4C.H file. Note that COM1 is defined as port
zero, not port one. The user must assume the responsibilty for
passing the correct information when calling PCL4C functions.
Note that function prototypes are provided in PCL4C. But since
some earlier C compilers don't support function prototypes,
PCL4C.H can be modified for no prototypes by changing the line
#define PROTOTYPES 1
to
#define PROTOTYPES 0
For an example of PCL4C use, examine the terminal emulator program
SIMPLE.C. The user should compile and link SIMPLE.C as a test of
the library.
If you have two computers, then you can connect them together with
a null modem cable and run SIMPLE or TERM on both machines.
Whatever is typed on one machine should appear on the other, and
vice versa.
If you have a modem, use TERM to call up any bulletin board system
( BBS ). Be sure to set the Hayes constant
#define HAYES 1
in the source code so that TERM sends an initialization string to
your modem.
There are many free BBSs around the country. Look in any issue of
"Computer Shopper" ( available in bookstores, computer shops, and
many grocery stores ) for a list of current systems.
PCL4C Users Manual Page 11
Compiling and Linking
Registered users may wish to assemble PCL4C.ASM. Use the /MX
switch in order to disable automatic conversion from lower case to
upper case. If the /MX switch is not used, then all PCL4C
function references in C code must be in upper case. To assemble
using the Microsoft assembler:
Model Command
Small MASM PCL4C /DSMALL_MODEL /MX;
Compact MASM PCL4C /DCOMPACT_MODEL /MX;
Medium MASM PCL4C /DMEDIUM_MODEL /MX;
Large MASM PCL4C /DLARGE_MODEL /MX;
To make the (small) model PCL4C.OBJ into a library file:
DEL PCL4C_S.LIB
LIB PCL4C_S.LIB+PCL4C,PCL4C.MAP;
If you are using the MIX Power C Compiler, create the MIX object
file ( you will need version 1.3 of MIX which has the /_ switch ):
MIX /_ PCL4C_S
Similarly with the other memory model libaries. See the batch
files MAKE_S.BAT, MAKE_C.BAT, MAKE_M.BAT, and MAKE_L.BAT.
To compile and link (small model) using Microsoft C:
cl /AS simple.c /link pcl4c_s.lib
To compile and link (small model) using Microsoft Quick C:
qcl /AS simple.c /link pcl4c_s.lib
To compile and link (small model) using Turbo C:
tcc -ms simple.c pcl4c_s.lib
To compile and link (small model) using Power C:
pc /ms simple.c
pcl simple pcl4c_s.mix
Makefiles or project files are provided for all example code.
Turbo C makefiles end with the extension '._T_', Microsoft C
makefiles end with '._M_', Microsoft Quick C makefiles files end
with '._Q_', and Power C project batch files start with 'X_' and
end with '.BAT'.
PCL4C Users Manual Page 12
Talking To Your Modem
If your application uses a Modem ( as opposed to using a null
modem cable ), then you should always send an initialization
string to your modem if it is a programmable modem such as those
made by Hayes. Communication programs such as PROCOMM and TELIX
always send such a string automatically as soon as they start up.
The particular initialization string depends on the make of your
modem. For Hayes and Hayes compatible modems, the following
string ( followed by a carriage return ) should work:
AT E1 S7=60 S11=60 V1 X1 Q0 S0=0
Refer to your Hayes User's Guide for a full discussion of these
commands. A brief description is as follows:
AT Modem attention command.
E1 Modem will echo what you send to it.
S7=60 Wait 60 seconds for carrier and/or dial tone.
S11=60 Use 60 milliseconds for tone dialing duration & spacing.
V1 Display result code as words ( not numbers ).
X1 Use the extended result message ( CONNECT XXXX ) set.
Q0 Modem returns result codes.
S0=0 Do not answer RING.
If your application will answer incoming calls, then set the S0
register to the ring on which to automatically answer.
If you send the above codes by using SioPutc ( as opposed to
typing them from the keyboard ), then follow these guidelines:
(1) Send an initial carriage return before the initialization
string.
(2) Pause at least two tics ( 18 tics to the second ) after each
character sent as your modem needs the time to perform its own
internal processing. Pause a little longer if your modem is not
accepting your initialization string.
(3) Pause one and a half seconds after sending any initialization
command such as ATZ or AT&F since your modem must do quite a bit
of processing.
If you experience any problems in initializing your Hayes modem,
you should first reset it to factory settings by sending:
AT&F
Refer to the TERM program ( functions SendTo and WaitFor in the
file MODEM_IO.C ) for an example of sending an initialization
string to a Hayes compatible modem.
PCL4C Users Manual Page 13
Problems
If you cannot get your application to run properly, first compile
and run the terminal emulator program TERM provided on your
distribution disk. If you are using a null modem cable or a
non-programmable modem, be sure to set the HAYES constant to 0 in
the source code ( #define HAYES 0 ). If you are using a Hayes
compatible modem, set the HAYES constant to 1. If you are using a
programmable modem which is not Hayes compatible, then you must
modify the initialization string for your particular modem.
If your application does not run but TERM runs correctly, then you
have most likely made a programming mistake in your application.
MarshallSoft Computing cannot debug your application, especially
over the telephone! However, consider each of the following when
searching for an error in your application.
1. Have you included the file PCL4C.H in your application ?
2. Did you link with the correct PCL4C library ? This is the
most probable cause if your application 'hangs' as soon as it
starts and you must reboot. The function SioModel() returns
the model ID under which the library was assembled.
SioModel() return 0 for small, 1 for compact, 2 for small,
and 3 for large.
3. Is your receive buffer large enough ? If you are using 1K data
blocks in YMODEM, then your receive buffer should be at least
1K ( 2K if baud rates above 38400 are to be used ).
4. Have you selected too high a baud rate ( if you are using a
slow PC ) ? If only one COM port is being run, you should be
able to run at 38400 baud on 8088 machines and 115200 on most
286 and all 386 and 486 machines.
5. Are you attempting to run another application in the
background ? Try running without any other programs running
in the background ( unload all TSR programs ).
6. If you are running two COM ports simultaneously, are you using
separate receive buffers ? ( you should ).
7. Did SioReset return a zero value ? If not, then you must call
SioReset again. See TERM.C for an example.
8. Did you send the proper initialization string to your modem ?
9. Do you have more than one COM1 port, etc. For example, if you
have a COM1 port on your motherboard, you cannot add another
COM1 port or modem board that uses COM1 without first
disabling the COM1 on the motherboard.
If TERM does not run, then either there is a physical connection
problem or your computer isn't as compatible as you thought !
Registered users can call (205) 881 - 4630 from 5 PM to 8 PM CST
Monday through Friday for help.
PCL4C Users Manual Page 14
Function Summary
Refer to the PCL4C Reference Manual ( PCL4C.REF ) for detailed
information on the communications and support functions. A one
line summary of each function follows:
SioBaud Sets the baud rate of the selected port.
SioBrkKey Returns non-zero if the Control-BREAK key was pressed.
SioBrkSig Asserts, cancels, or detects BREAK signal.
SioCrtWrite Write character to the screen.
SioCTS Reads the Clear to Send (CTS) modem status bit.
SioDCD Reads the Data Carrier Detect (DCD) modem status bit.
SioDelay Delays one or more tics ( 18 tics per second ).
SioDone Terminates further serial processing.
SioDSR Reads the Data Set Ready (DSR) modem status bit.
SioDTR Set, clear, or read the Data Terminal Ready (DTR) bit.
SioError Displays error in text.
SioGetc Reads the next character from the serial line.
SioKeyPress Detects if keyboard has been pressed.
SioKeyRead Reads the keyboard.
SioLine Reads the line status register.
SioLoopBack Performs a UART loopback test.
SioModel Returns a code corresponding to the memory model used.
SioModem Reads the modem status register.
SioParms Sets parity, stop bits, and word length.
SioPutc Transmit a character over a serial line.
SioReset Initialize a serial port for processing.
SioRI Reads the Ring Indicator (RI) modem status bit.
SioRTS Sets, clears, or reads the Request to Send (RTS) line.
SioRxBuf Sets up receive buffer.
SioRxFlush Flushes ( clears ) the receive buffer.
SioRxQue Returns the number of characters in the receive queue.
SioTimer Returns the number of system clock tics.
SioUART Sets the UART base address.
SioUnGetc "Un-gets" ( puts back ) a specified character.
PCL4C Users Manual Page 15
Serial Communications
The heart of serial communications is the UART ( Universal
Asynchronous Receiver Transmitter ). The IBM PC/XT/AT and
compatibles use the INS8250 UART or an UART that is compatible
with the INS8250. The purpose of the UART is:
(1) To convert bytes from the CPU ( Central Processing Unit ),
into a serial format by adding the necessary start, stop, and
parity bits to each byte before transmission, and to then transmit
each bit at the correct baud rate.
(2) To convert the incoming stream ( at a specified baud rate ) of
serial bits into bytes by removing the start, stop, and parity
bits before being made available to the CPU.
The UART is part of the serial interface circuitry which allows
the CPU to send and receive signals over the RS232 lines. This can
be diagrammed as follows:
Serial Interface
+-------------------+
+-----+ Data Bus | +------+ | RS232 Signals
| CPU |============| | UART | |<------------------>
+-----+ | +------+ |
+-------------------+
The INS 8250 UART is capable of operating in one of two modes,
"polled" and "interrupt driven". The serial communications
functions in the BIOS uses the polled method. In this approach,
the CPU is typically in a loop asking the UART over and over again
if it has a byte ready. If its does, the polling code returns the
byte. But, if the next byte comes in before the polling code is
executing again, then that byte is lost.
In the interrupt driven approach ( used by PCL4C for incoming data
), when a byte is received by the UART, an "Interrupt Service
Routine" ( ISR ) is executed immediately, suspending temporarily
whatever else is executing. The ISR then moves the byte to a
buffer so that your application program can later read it. Refer
to the sections entitled "RS232 Signals" and "National INS8250
UART" for further information on these topics.
The best way to learn about serial communications is to read a
good book on the subject. Several good texts are available. Two
that I like are:
(1) C Programmers's Guide to Serial Communications by Joe Campbell
(SAMS)
(2) Mastering Serial Communications by Peter Gofton (SYBEX).
PCL4C Users Manual Page 16
IBM Communications Ports
There are a few things to know about how serial communications
ports are used by IBM PC/XT/AT and compatible computers. The
standard IBM PC/XT/AT configuration values are as follows:
Port Reg Base IRQ Line Vector
COM1 3F8H 4 12
COM2 2F8H 3 11
COM3 3E8H 4 12
COM4 2E8H 3 11
PCL4C assumes the above values. If necessary, the UART base
address can be changed by SioUART. However, the IRQ and Service
vector values can not be changed ( unless you modify the source
code ).
When installing new communications cards, the following guidelines
are recommended:
(1) Be sure to read the documentaion for the hardware you are
installing. Pay special attention to UART base addresses and IRQ
lines.
(2) If you have a choice in base addresses and IRQ lines, always
choose standard values as defined above.
(3) The first port should be COM1, the second COM2, etc.
(4) Use SioUART to zero all unused ports ( for example, call
SioUART(COM4,0) if there is no COM4 port installed ).
(5) Be carefull not to configure two ports for the same address.
This is easier to do than you may believe.
(6) Choose an external modem over an internal one. It is much
easier to debug problems with an external modem than an internal
one.
(7) Always test your port as soon as it is installed.
PCL4C Users Manual Page 17
RS232 Signals
RS-232 is the name of the serial data interface standard used to
connect computers to modems. Most IBM compatible computers are
built with at least one serial port and use either DB9 ( 9 pin )
or DB25 ( 25 pin ) connectors.
A summary of these pins and their function follows. For more
detailed information, refer to one of the many books dealing with
RS-232 interfacing.
Signal Ground Pin 7 (DB25), Pin 5 (DB9)
The SG line is used as the common signal ground, and must always
be connected.
Transmit Data Pin 2 (DB25), Pin 3 (DB9)
The TX line is used to carry data from the computer to the modem.
Receive Data Pin 3 (DB25), Pin 2 (DB9)
The RX line is used to carry data from the modem to the computer.
Data Terminal Ready Pin 20 (DB25), Pin 4 (DB9)
The DTR line is used by the computer to signal the modem that it
is ready.
Data Set Ready Pin 6 (DB25), Pin 6 (DB9)
The DSR line is used by the modem to signal the computer that it
is ready.
Request to Send Pin 4 (DB25), Pin 7 (DB9)
The RTS line is used to "turn the line around" in half duplex
modems, but is not necessary in full duplex modems.
Clear to Send Pin 5 (DB25), Pin 8 (DB9)
The CTS line, like the RTS line, is not necessary in full duplex
modems.
Data Carrier Detect Pin 8 (DB25), Pin 1 (DB9)
The DCD line is used by the modem to signal the computer that a
data carrier signal is present.
Ring Indicator Pin 22 (DB25), Pin 9 (DB9)
The RI line is asserted when a 'ring' occurs.
PCL4C Users Manual Page 18
National INS8250 UART
The Personal Communications Library is based on the standard
National INS8250 UART and compatible UARTs. The 8250 consists of
8 register ports as follows:
Offset R/W Register
0 R/W Receiver ( read ) / Transmitter ( write )
1 R/W Interrupt Enable
2 R Interrupt Identification
3 R/W Data Format ( Line Control )
4 R/W RS-232 ( Modem ) Control
5 R/W Line Status
6 R/W RS-232 ( Modem ) Status
7 R/W Not used.
The UART registers are based at 3F8 (COM1), 2F8 (COM2), 3E8
(COM3), and 2E8 (COM4). COM1 and COM3 share interrupt vector 12
and interrupt request line IRQ4 while COM2 and COM4 share
interrupt vector 11 and interrupt request line IRQ3. This means
that COM1 and COM3 cannot both be used at the same time.
Similarly, COM2 and COM4 cannot both be used at the same time.
Port Reg Base IRQ Line Vector
COM1 3F8H 4 12
COM2 2F8H 3 11
COM3 3E8H 4 12
COM4 2E8H 3 11
Four sources of interrupts are possible with the 8250: (1)
receiver error or BREAK, (2) receiver data ready, (3) ready to
transmit, and (4) RS232 input. These four sources of interrupts
are summarized as follows:
Source of Interrupt Action Required to Clear
Receiver error or BREAK. Read Line Status register.
Receiver data. Read data from data register.
Transmitter Buffer Empty. Write to data register or read IID reg.
RS232 input. Read Modem Status register.
However, PCL4C only enables the receiving data interrupt. This
means that interrupts can only be caused by incoming data.
If you are not familiar with the INS8250, several good books are
available. Refer to the Serial Communications chapter for
recommendations. Although a knowledge of the 8250 is not
necessary to use PCL4C, a general knowledge of the theory of
asynchronous serial communications is recommended.
PCL4C Users Manual Page 19
Register Summary
REG 0 : Data Register
Reading from the data register fetches the next input byte, once
it is ready. Writing to the data register transmits the byte
written to it over the serial line.
REG 1 : Interrupt Enable
The Interrupt Enable register enables each of four types of
interrupts when the appropriate bit is set to a one.
bit 3 : Enable interrupt on RS232 input.
bit 2 : Enable interrupt on receiver error or break.
bit 1 : Enable interrupt on transmitter buffer empty ( TBE ).
bit 0 : Enable interrupt on received data ( RxRDY ).
REG 2 : Interrupt Identification (IID)
Reading the Interrupt Identification register once an interrupt
has occurred identifies the interrupt as follows:
Bit 2 Bit 1 Bit 0 Priority Interrupt
===== ===== ===== ======== =========
0 0 1 none none
1 1 0 0 Serialization or break.
1 0 0 1 Received data.
0 1 0 2 Transmitter Buffer Empty.
0 0 0 3 RS232 Input.
where 0 = highest priority.
REG 3 : Line Control
RS232 line parameters are selected by writing to this register as
follows:
bit 7 : DLAB = 0
bit 6 : BREAK on(1), off(0).
bits 5-3: Parity None(000),ODD(001),EVEN(011),MARK(101),SPACE(111)
bit 2 : One stop bit(0), two stop bits(1).
bits 1-0: Data bits = 5 (00), 6(01), 7(10), 8(11).
When the Divisor Latch Access Bit ( DLAB ) is 1, registers 0 and 1
become the LS and MS bytes of the Baud Rate Divisor registers.
Divisor Baud Rate Divisor Baud Rate
300 0180 9600 000C
600 00C0 19200 0006
1200 0060 38400 0003
2400 0030 57600 0002
4800 0018 115200 0001
PCL4C Users Manual Page 20
REG 4 : Modem Control
RTS, DTR, loopback testing, and General Purpose Outputs #1 and #2
are controlled by the Modem Control register as follows:
bit 4 : Enable local loopback.
bit 3 : Enable GP02. Necessary for 8250 interrupts.
bit 2 : Enable GP01.
bit 1 : Set / clear RTS.
bit 0 : Set / clear DTR.
REG 5 : Line Status
Reading the Line Status register provides status information as
follows ( 1 for TRUE, 0 for FALSE ) :
bit 6 : Transmitter Empty.
bit 5 : Transmitter Buffer Empty ( TBE ).
bit 4 : BREAK detect.
bit 3 : Framing error.
bit 2 : Parity error.
bit 1 : Overrun error.
bit 0 : Data Ready.
REG 6 : Modem Status
Reading the Modem Status register provides the following status
information ( 1 for TRUE, 0 for FALSE ) :
bit 7 : DCD status.
bit 6 : RI status.
bit 5 : DSR status.
bit 4 : CTS status.
bit 3 : Delta DCD status.
bit 2 : Delta RI status.
bit 1 : Delta DSR status.
bit 0 : Delta CTS status.
The delta bits ( bits 0 through 3 ) are set whenever one of the
status bits ( bits 4 through 7 ) changes ( from 0 to 1 or from 1
to 0 ) since the last time that the Modem Status register was
read. Reading the Modem Status register clear the delta bits.
REG 7 : Scratch Register
There is no function associated with register 7. It does not
exist in early versions of the 8250.
PCL4C Users Manual Page 21
Example Code
The following programs are provided as examples of the use of the
PCL4C library. They are not part of the PCL4C library, and may be
used in any way the user wishes. Makefiles ( small model ) are
provided for all example code.
SIMPLE
SIMPLE is an extremely simple terminal emulator program. It is
provided as the smallest and easiest to understand example of
serial communications programming using PCL4C.
To start SIMPLE, just type SIMPLE. The baud rate is set at 2400
and can be easily changed in the source code. Similiarly the port
is set to COM1 and is easily changed in the source code. Note that
SIMPLE does not send an initialization string to your modem.
INTERCOM
INTERCOM is just slightly more complex than SIMPLE. Hook up two
computers via modem or a null modem cable. INTERCOM divides the
screen horizontally into two areas. Whatever is typed on one
machine is displayed locally in the top half of the screen and
sent over to the other computer. Whatever is received is
displayed in the lower half of the screen.
To start INTERCOM, type INTERCOM followed by the port ( 1 to 4 ).
MODEM
MODEM displays the modem status lines (DSR, CTS, DCD, and RI) and
the modem control lines (DTR and RTS). Additionally, it allows the
user to set or clear the modem control lines. MODEM is useful when
testing RS232 cable connections.
To start MODEM, type MODEM followed by the port ( 1 to 4 ). For
example "MODEM 1".
NORESET
NORESET is designed to "take over" a port from a serial
communications program which has a DOS gateway. This is useful for
implementing external protocols or similiar uses.
For example, if you start PROCOMM ( a popular shareware
communications program ) and select the DOS gateway after
establishing communications, you will see the DOS prompt. At this
point type "NORESET 1" to take over COM1 ( or whatever port
PROCOMM is using ) without dropping the carrier. NORESET will run
using the same baud rate and parameters as PROCOMM. When you are
finished, type ESC to leave NORESET and type EXIT to return to
PROCOMM.
PCL4C Users Manual Page 22
TERM
TERM is a more capable terminal emulator than SIMPLE. It
functions as a dumb terminal emulator but can exchange files using
XMODEM ( Standard XMODEM, XMODEM-CRC, and XMODEM-1K ) and YMODEM (
batch capability ) communications protocols. TERM will also send
an initialization string to your Hayes compatible modem.
To start TERM, type TERM followed by the port ( 1 to 4 ) and the
baud rate ( 300, 600, 1200, 2400, 4800, 9600, 19200, 38400, 57600,
or 115200). For example, "TERM 4 2400".
XFER
XFER is designed to transfer files between PCs connected via
their serial ports using a null modem cable. It uses a protocol
similiar to YMODEM and accepts wildcards in the filename.
Start XFER on the computer which is to receive files by typing
"XFER port baud" as with TERM. Then start XFER on the computer
which is to send the files by typing "XFER port baud filespec"
where filespec is the file specification to transfer. Type ESC to
cancel at any time.
For example, to send all the C files over COM4 at 115200 baud,
type "XFER 4 115200 *.C" after starting XFER on the destination
computer ( which must have the same baud rate ).
LOOPBACK
LOOPBACK performs a loopback test of the selected port UART. This
is useful for testing a serial port UART that is suspected of
being bad. However, defective UARTS are very unusual.
Start LOOPBACK by typing LOOPBACK followed by the port ( 1 to 4 ).
For example "LOOPBACK 4".
BBS
BBS is a simple single caller bulletin board system featuring file
uploading and downloading via XMODEM and YMODEM. If you have a
Hayes compatible modem, BBS will initialize your modem and wait
for an incoming call.
BBS demonstrates the communications principles used in
constructing a single caller bulletin board system as well as
XMODEM and YMODEM protocols.
To use BBS, type BBS followed by the port ( 1 to 4 ) and the baud
rate. For example, "BBS 1 2400".
PCL4C Users Manual Page 23
Revision History
Version 1.0 -- 14 January 1991 -- original release.
Version 1.1 -- 11 March 1991
o Added SioUnGetc() function to library.
o Added ASCII file transfer to TERM.
o Minor documentation changes.
Version 1.2 -- 1 June 1991
o Name changed to Personal Communications Library.
o SioParms() bug -- could not call before SioReset.
o SioReset() bug -- was not saving & restoring all regs.
o Added SIMPLE.C and XFER.C example code.
Version 1.3 -- 1 July 1991
o Added NORESET option to SioReset.
o Added SioDSR, SioCTS, SioDCD, and SioRI.
o Added SioLoopBack function to library.
o Added NORESET.C example program.
o Added LOOPBACK.C example program.
Version 2.0 -- 1 Nov 1991
o All example code released in shareware package.
o Reorganized as four memory model libraries.
o Added SioModel function to library.
o Added support for Quick C and Power C.
Version 2.1 -- 1 Dec 1991
o Fixed bug due to Microsoft Assembler (MASM 5.0,5.1) error.
o Added BBS & INTERCOM example code.
o Greatly expanded documentation.
( MarshallSoft incorporated on December 23, 1991 )
Version 3.0 -- 15 Jan 1991
o Added SioUART function.
o Added "UART undefined" error code.
o Added "Bad or missing UART" error code.
o Added "Port already enabled" error code.
o Added "Cannot enable both COM1 & COM3 ..." error code.
o Fixed several minor bugs ( using new automated testing ).
PCL4C Users Manual Page 24
License
MarshallSoft Computing, Inc. grants the registered user of PCL4C
the right to use the PCL4C library ( in object form ) in the
development of any software product without any royalties.
However, the source code for the library may not be released in
whole or in part.
Warranty
MARSHALLSOFT COMPUTING, INC. DISCLAIMS ALL WARRANTIES RELATING TO
THIS SOFTWARE, WHETHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT
LIMITED TO ANY IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
FOR A PARTICULAR PURPOSE, AND ALL SUCH WARRANTIES ARE EXPRESSLY
AND SPECIFICALLY DISCLAIMED. NEITHER MARSHALLSOFT COMPUTING, INC.
NOR ANYONE ELSE WHO HAS BEEN INVOLVED IN THE CREATION, PRODUCTION,
OR DELIVERY OF THIS SOFTWARE SHALL BE LIABLE FOR ANY INDIRECT,
CONSEQUENTIAL, OR INCIDENTAL DAMAGES ARISING OUT OF THE USE OR
INABILITY TO USE SUCH SOFTWARE EVEN IF MARSHALLSOFT COMPUTING,
INC. HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES OR
CLAIMS. IN NO EVENT SHALL MARSHALLSOFT COMPUTING, INC.'S LIABILITY
FOR ANY SUCH DAMAGES EVER EXCEED THE PRICE PAID FOR THE LICENSE TO
USE THE SOFTWARE, REGARDLESS OF THE FORM OF THE CLAIM. THE PERSON
USING THE SOFTWARE BEARS ALL RISK AS TO THE QUALITY AND
PERFORMANCE OF THE SOFTWARE.
Some states do not allow the exclusion of the limit of liability
for consequential or incidental damages, so the above limitation
may not apply to you.
This agreement shall be governed by the laws of the State of
Alabama and shall inure to the benefit of Marshallsoft Computing,
Inc. and any successors, administrators, heirs and assigns. Any
action or proceeding brought by either party against the other
arising out of or related to this agreement shall be brought only
in a STATE or FEDERAL COURT of competent jurisdiction located in
Madison County, Alabama. The parties hereby consent to in personam
jurisdiction of said courts.
PCL4C Users Manual Page 25
