home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
BURKS 2
/
BURKS_AUG97.ISO
/
BURKS
/
SOFTWARE
/
LIBS
/
PCL4C43.ZIP
/
PCL4CUSR.DOC
(
.txt
)
< prev
next >
Wrap
Text File
|
1995-03-14
|
78KB
|
2,245 lines
Personal Communications Library
For the C Language
(PCL4C)
USERS MANUAL
Version 4.3
March 15, 1995
This software is provided as-is.
There are no warranties, expressed or implied.
Copyright (C) 1995
All rights reserved
MarshallSoft Computing, Inc.
Post Office Box 4543
Huntsville AL 35815
Voice 205-881-4630
FAX 205|880|0925
BBS 205-880-9748
_______
____|__ | (R)
--+ | +-------------------
| ____|__ | Association of
| | |_| Shareware
|__| o | Professionals
--+--+ | +---------------------
|___|___| MEMBER
PCL4C Users Manual Page 1
C O N T E N T S
Chapter Page
1.0 Introduction................................................3
1.1 User Support............................................4
1.2 ASP Ombudsman...........................................4
1.3 A Typical Application...................................5
1.4 Installation............................................6
2.0 Library Organization........................................7
2.1 Configuration...........................................7
2.2 Initialization & Termination............................7
2.3 Modem Control & Status..................................8
2.4 Serial I/O..............................................8
2.5 Error Detection.........................................9
2.6 General Support.........................................9
3.0 Library Overview...........................................10
3.1 Memory Models..........................................10
3.2 Compilers Supported....................................11
3.3 Using the Library......................................12
3.4 Application Notes......................................12
3.4.1 Terminal Programs................................12
3.4.2 Door Programs....................................12
3.4.3 BBS Programs.....................................12
3.5 Compiling & Linking....................................13
4.0 Talking to Your Modem......................................14
4.1 Modem Standards........................................14
4.2 Flow Control...........................................15
4.3 MODEM_IO functions.....................................15
4.4 Modem Initialization...................................16
5.0 Problems...................................................17
6.0 Serial Communications......................................18
6.1 Communications Basics..................................18
6.2 Standard Port Addresses................................19
6.3 Running 3 or 4 Ports Concurrently......................20
6.4 Using Multiport Cards..................................21
6.4.1 The DigiBoard....................................21
6.4.2 The BOCA Board...................................21
6.5 Transmitter Interrupts.................................22
6.6 RS232 Signals..........................................23
6.7 National INS8250, INS16450, and INS16550 UARTs.........24
6.8 Register Summary.......................................25
7.0 Example Programs...........................................27
7.1 MINIMAL................................................27
7.1 SIMPLE.................................................27
7.2 LOGIN..................................................27
7.3 DOOR...................................................27
7.4 SELFTEST...............................................27
8.0 Legal Issues...............................................28
8.1 Registration...........................................28
8.2 License................................................29
8.3 Warranty...............................................29
9.0 Summary....................................................30
9.1 Revision History.......................................30
9.2 Function Summary.......................................32
9.3 Further Reading........................................32
10.0 Other MarshallSoft Computing products for C................33
10.1 The Personal Protocol Library for C...................33
10.2 The LZW Data Compression Library for C................33
10.3 The EMS Expanded Memory Library for C.................33
PCL4C Users Manual Page 2
1.0 Introduction
The Personal Communications Library for the C Language (PCL4C) is an
asynchronous communications library designed for experienced software
developers programming in C. Five compilers are supported: Microsoft C,
Quick C, Borland C, Turbo C, and MIX Power C. An IBM PC/XT/AT or compatible
is required. The PCL features:
o SMALL, COMPACT, MEDIUM, and LARGE memory models.
o 38 communications and support functions.
o Supports the high performance 16550 UART.
o Supports the PC/4 and PC/8 DigiBoard.
o Supports the BOCA BB1004, BB1008, and BB2016 boards.
o Supports hardware (RTS/CTS) flow control.
o Interrupt driven receiver & (optionally) transmitter.
o Supports 300 baud to 115,200 baud.
o Supports COM1 through COM8 (through COM16 with multiport boards)
o Adjustable receive queues from 8 bytes to 32 KB.
o Control-BREAK error exit.
o 18 communications error conditions trapped.
o Allows 4 ports to run concurrently (more with multiport boards).
o Complete modem control & status.
o Written in assembly language for small size & high speed.
o Terminal program featuring ASCII (with XON/XOFF), XMODEM,
YMODEM, & YMODEM-G.
Why should you buy PCL4C ? Several good reasons are:
COMPLETE - PCL4C is complete since it provides absolute control of the
serial ports (including the high performance INS16550).
COMPACT - PCL4C is very compact at less than 8 KB. Your application
doesn't carry a lot of excess code.
FAST - PCL4C is fast since it will run at 38400 baud on even slow 8088
PCs (4.77 MHZ) and at 115200 baud on most everything else.
SUPPORT - If you get stuck, you talk to the programmer that wrote the
code, not a person hired to answer the phone.
BBS - A BBS is available (2400 to 14400 baud, N81) in order to provide
immediate support as necessary.
NEWSLETTER - A one year subscription to the MSC newsletter discusses
communications problems and solutions (published quarterly).
PRICE - You get PCL4C for a very reasonable price!
UPGRADES - Once you buy PCL4C, you can always update to the most recent
version very inexpensively ($20 plus shipping).
PCL4C Users Manual Page 3
1.1 User Support
We want you to be successful in developing your applications using PCL4C! We
depend on our customers to let us know what they need in a communications
library. This means we are committed to providing the best communications
library that we can. If you have any suggestions or comments, please let us
know!
We provide customer support for registered customers by voice, FAX, BBS, and
mail. We provide limited support for unregistered users by voice and BBS
only.
If you are having a problem using PCL4C, call us at 205-881-4630 between
1:30 PM and 9:30 PM (CST) Monday through Friday. You can also call at other
times and leave a message, and call back later for a reply. Registered users
(ONLY) can also FAX us at 205-880-0925 at any time (24 hours).
However, we can only answer questions with respect to using the PCL4C
library. We cannot help you program your application, but we'll be glad to
discuss it with you.
You may also call our User Support BBS (2400 to 14400 baud, no parity, 8
data bits, 1 stop bit) at 205-880-9748 and leave a message (address it to
the SYSOP). We will usually have a reply ready for you within 24 hours.
The BBS is available 24 hours per day. All files are in standard ZIP format.
The BBS will contain the latest shareware version of all MarshallSoft
Computing products as well as related files such as:
BUGS.ZIP - Bug report.
NEWS.ZIP | Latest news regarding our products.
PRODUCTS.ZIP - List of all shareware products.
The MarshallSoft Computing, Inc. newsletter "Comm Talk" is published
quarterly. It discusses various communications problems and solutions using
PCL4C as well as related information. Registered users receive a one year
complimentary subscription when first registering and for each update
purchased.
1.2 ASP Ombudsman
MarshallSoft Computing, Inc. is a member of the Association of Shareware
Professionals (ASP). ASP wants to make sure that the shareware principle
works for you. If you are unable to resolve a shareware-related problem
with an ASP member by contacting the member directly, ASP may be able to
help. The ASP Ombudsman can help you resolve a dispute or problem with an
ASP member, but does not provide technical support for members' products.
Please write to the ASP Ombudsman at 545 Grover Road, Muskegon, MI USA
49442-9427, Fax 616-788-2765, or send a CompuServe message via CompuServe
Mail to ASP Ombudsman 70007,3536.
PCL4C Users Manual Page 4
1.3 A Typical Application
In general, there are two classes of applications that use a communications
library like PCL4C - those that use a modem to connect to the outside world
and those that connect directly to a peripheral device. In either case, a
typical application program using PCL4C might look like the following code
outline:
+---------------------------------------------------+
| #include "pcl4c.h" |
| |
| void main(void) |
| { |
| ... |
| |
| /* initialize serial comm system */ |
| SioRxBuf(Port,AllocSeg(1024),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).
The function AllocSeg() allocates a buffer of specified size on the far heap
and returns the segment SEG such that SEG:0 points to the buffer. The
function AllocSeg() is part of the example code and can be found in the file
ALLOCSEG.C.
Before leaving your application, SioDone is called to restore the prior
state of the serial communications system.
If you are using a modem, you also need to be concerned about initializing
your modem correctly and handling any required flow control. Refer to the
"Talking to Your Modem" chapter for detailed information.
If you are using the versions of the library with transmitter interrupts
enabled (PCL4C_S2.LIB, PCL4C_M2.LIB, PCL4C_C2.LIB, and PCL4C_L2.LIB), then
SioTxBuf() must be called to set up the transmitter buffer just as
SioRxBuf() is called to set up the receive buffer.
PCL4C Users Manual Page 5
1.4 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, and include the correct library in
the project file. 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 (*.PRJ). You may also delete any libraries that you won't need.
(6) Compile SIMPLE.C and link with the appropriate PCL4C library
(PCL4C_S.LIB for all but Power C which must use PCL4C_S.MIX). Makefiles (or
project files) are provided for each of the supported compilers (Borland C &
Turbo C use the same makefiles).
a) Microsoft C: Type MAKE SIMPLE._M_
b) Microsoft Quick C: Type MAKE SIMPLE._Q_
c) Borland C: Type MAKE -fSIMPLE._B_
d) Turbo C: Type MAKE -fSIMPLE._T_
e) MIX Power C: Type pc/e SIMPLE.PRJ
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. SIMPLE can also be tested by connecting your port
to a modem.
PCL4C Users Manual Page 6
2.0 Library Organization
The PCL4C library is organized into six categories of functions. Refer to
the PCL Reference Manual (PCL4C.REF) for details on individual functions.
2.1 Configuration
There are three functions in the configuration category. SioPorts sets the
number of PC and DigiBoard (or BOCA board) ports. SioUART is used to change
the UART base address for a communications port to a non-standard address,
while SioIRQ is used to assign a nonstandard IRQ line to a port. (See the
chapter IBM Communications Ports for more details on standard UART addresses
and IRQ lines).
The configuration functions SioPorts, SioUART and SioIRQ must be called
before calling any other library functions. Be very careful in using these
functions. Remember that your serial hardware must support the UART and IRQ
that you specify. Always test any new configuration immediately.
SioPorts - Sets number of PC and DigiBoard (or BOCA board) ports.
SioUART | Sets the UART base address.
SioIRQ - Assigns an IRQ line to a port.
THE IRQ GOLDEN RULE: You may open (via SioReset) only one port per IRQ
(except for the DigiBoard and BOCA board).
2.2 Initialization & Termination
There are eight functions in the initialization and termination category.
Together, SioParms, SioFIFO, SioRxBuf, SioTxBuf, 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. SioFlow can be
called to enable hardware flow control.
Before exiting from your application, SioDone must be called. Failure to
call SioDone can crash your system later.
SioRxBuf - Sets up receive buffer.
SioTxBuf | Sets up transmitter buffer.
SioFIFO | Sets the interrupt level for the INS16550.
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.
SioFlow - Enables / disables flow control.
PCL4C Users Manual Page 7
2.3 Modem Control & Status
There are nine 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. SioGetDiv reads the baud rate
divisor register so the baud rate can be determined.
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.
SioRead | Reads the contents of the 7 UART registers.
SioGetDiv - Reads the baud rate divisor registers.
2.4 Serial I/O
There are eight 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 "ungets"
the last serial byte read. SioRxFlush clears the receive queue while
SioTxFlush clears the transmit queue. SioLine can be used to test for UART
errors. SioRxQue returns the number of bytes in the receive queue while
SioTxQue returns the number of bytes in the transmit queue.
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 RX queue.
SioTxFlush | Flush (clears) the transmit buffer.
SioTxQue | Returns the number of characters in the TX queue.
SioLine - Reads the line status register.
PCL4C Users Manual Page 8
2.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 the RS232 BREAK signal.
SioError - Displays error in text.
SioLoopBack - Performs a UART loopback test.
2.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.
SioInfo - Returns the library version & memory model.
SioCrtWrite | Use BIOS to write character to the screen.
SioDelay | Delays one or more tics (18.2 tics per second).
SioKeyPress | Use BIOS to detect if keyboard key has been pressed.
SioKeyRead | Use BIOS to reads the keyboard.
SioTimer - Returns the number of system clock tics.
PCL4C Users Manual Page 9
3.0 Library Organization
3.1 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. If you are
compiling with the HUGE memory mode, link with PCL4C_L.LIB.
The equivalent libraries with transmitter interrupts enabled are
PCL4C_S2.LIB, PCL4C_C2.LIB, PCL4C_M2.LIB, & PCL4C_L2.LIB.
PCL4C Users Manual Page 10
3.2 Compilers Supported
At this time, five C compilers are supported by PCL4C.
(1) Microsoft (Optimizing) C Compiler.
(2) Quick C Compiler.
(3) Turbo C Compiler.
(4) Borland C Compiler.
(5) 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 and Turbo C Compilers also support 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 *.PRJ 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. Give us a call if you have any difficulty.
3.3 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), a Gateway
2000 386 (25 MHZ 80386-DX), and a Gateway 2000 486 (66MHZ 80486-DX). PCL4C
has also been tested under MSDOS 2.11, 3.2, 3.3, 4.01, 5.0, 6.0 and 6.2.
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.
If there are any conflicts between PCL4C definitions and those in other
libraries, the PCL4C definitions can be changed in the PCL4C.H file and any
file that uses the definition. There is no change necessary for the library
code itself.
The PCL4C libraries contain no references to any runtime libraries. Only
BIOS and MSDOS functions are called.
PCL4C Users Manual Page 11
3.4 Application Notes
3.4.1 Terminal Programs
The "terminal program" is the most common class of communications program.
It is used to call up a BBS or on-line service such as CompuServe, America
On-Line, etc. Refer to the programs SIMPLE and LOGIN in section 7 for
examples of simple terminal programs.
A more sophisticated terminal program featuring ASCII, XMODEM, YMODEM, and
ZMODEM protocol file transfers can be found in our sister product -- The
Personal Protocol Libray (PPL4C). Source code is included in the shareware
distribution for everything except ZMODEM and the script intepreter.
3.4.2 Door Programs
In order to write a door program which "takes over" a serial port without
resetting the port or changing the baud rate, call SioReset() with NORESET
as the second argument rather than the baud rate. Call SioGetDiv() to get
the baud rate divisor if the baud rate must be determined. Be sure to call
SioDone() before returning to the invoking program. Refer to the DOOR.C
example program.
3.4.3 BBS Programs
If you are designing a BBS program (also known as HOST programs), consider
using 16550 UARTS. You should also choose a multiport card such as the
DigiBoard or BOCA board if you wish to run more than 4 ports simultaneously.
If you are using an error correcting modem, then you should be sure to set
flow control and fix your baud rate at the highest possible transfer rates.
For 14,400 modems, this means 19200 or 38400. You may need a 16550 UART in
order to run at the higher speed.
If you are using an older multi-speed modem (say 1200, 2400, 4800, 9600)
that doesn't use flow control, you should change your baud rate to match the
CONNECT message baud rate.
PCL4C Users Manual Page 12
3.5 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 /DMSC_IO /MX;
Compact MASM PCL4C /DCOMPACT_MODEL /DMSC_IO /MX;
Medium MASM PCL4C /DMEDIUM_MODEL /DMSC_IO /MX;
Large MASM PCL4C /DLARGE_MODEL /DMSC_IO /MX;
To enable transmitter interrupts, add "/DSET_TBE" to each MASM command line
above.
For example, 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. Similiarly for
MAKE_ST.BAT, MAKE_CT.BAT, MAKE_MT.BAT, and MAKE_LT.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 Borland C:
BCC -ms SIMPLE.C 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. Borland
makefiles end with the extension '._B_', Turbo C makefiles with '._T_',
Microsoft C makefiles end with '._M_', Microsoft Quick C makefiles files end
with '._Q_', and Power C project batch files end with '.PRJ'.
The PCL4C libraries may also be used with integrated development
environments. Place all required files along with the library corresponding
to the memory model being used into the project file.
PCL4C Users Manual Page 13
4.0 Talking to Your Modem
A modem is used to extend the distance over which you may communicate.
Without a modem, your RS232 cable is limited to a maximum of approximately
50 feet. But with a modem, you can communicate literally around the world.
Also refer to Section 4.3 for details on MODEM_IO functions. These functions
faciliate communications with modems.
4.1 Modem Standards
Two modems can communicate over a telephone line only if they are both using
the same signaling frequencies and modulation, which are determined by the
the modem standards used. Modem standards can be divided into three sets:
(1) speed, (2) data compression used, and (3) error control.
The Bell standards (103 & 212A) are those of AT&T. The CCITT (The
International Consultative Committee for Telephone and Telegraph) standards
are designated as "V. ".
Speed
Bell 103 - 300 baud
Bell 212A | 1200 baud
V.21 | 300 baud
V.22bis | 1200 & 2400 baud
V.32 | 4800 & 9600 baud
V.32bis | 4800, 7200, 9600, 12000, and 14400 baud
V.34 - through 28800 baud
Data Compression
MNP 5 - Microcom Networking Protocol (proprietary).
V.42bis - International data compression standard.
Error Control
MNP 2,3,4 - Three level error correction (public domain).
V.42 - International error correction standard.
Most of the newer high speed modems use several of the above standards.
However, not all combinations of modem makes communicate easily with each
other, especially at high speeds (9600 and up).
PCL4C Users Manual Page 14
4.2 Flow Control
With modems using data compression, the modem to modem connection will run
at various speeds depending on the quality of the line. The computer to
modem connection will be at a fixed baud rate. Therefore, a protocol (flow
control) is necessary to synchronize the data flow between a modem and the
computer to which it is connected. Refer to your modem manual for
information on flow control protocols supported.
Two flow control protocols are used by most modems which require flow
control. Software flow control is called "XON/XOFF" (other software flow
control character pairs are defined but operate the same as XON/XOFF) and
hardware flow control is called "RTS/CTS". Most modems which require flow
control enable hardware flow control by default.
In XON/XOFF (software) flow control, the computer suspends transmitting data
if it receives a XOFF character (13 hex) from the modem, and continues
transmitting when it receives a XON character (11 hex). Similiarly, the
computer can signal the modem not to send any more data by transmitting a
XOFF to it, and can tell the modem to continue transmission be sending a
XON.
In RTS/CTS (hardware) flow control, the RTS line is used by the computer to
signal the modem , while the CTS line is used by the modem to signal the
computer. The RTS line is set OFF by the computer to tell the modem to
suspend transmission, and set to ON to tell the modem to continue
transmission. The CTS line is set to OFF by the modem to tell the computer
to stop transmitting, and set to ON to tell the computer to continue
transmitting.
Given the choice, always choose hardware flow control over software flow
control so that all data transmission is transparent. If hardware flow
control is not the default (which it almost always is), you should modify
your modem initialization string to turn hardware flow control on.
Both software and hardware flow control is easy to implement using PCL4C.
4.3 MODEM_IO Functions
The file MODEM_IO.C contains several functions that ease communicating with
your modem. Look in the LOGIN.C code for examples of their use. Registered
users can also see examples in the script interpreter SI.C.
ModemSendTo : Sends string (including control chars) to the modem.
ModemWaitFor : Waits for a particular string from the modem, passing
all else through.
ModemQuiet : Waits for continuous quiet of specified duration.
ModemHangup : Hangs up the modem.
ModemCmdState : Goes into the modem's command state.
ModemEcho : Echos all serial incoming bytes to the display.
PCL4C Users Manual Page 15
4.4 Modem Initialization
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 AT command set compatible modems, the following string
(followed by a carriage return) may work:
AT E1 S7=60 S11=60 V1 X1 Q0 S0=0
Refer to your Modem 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
Your modem may require more initialization than presented above. Refer to
your modem manual for details. If you have a communications program such as
ProComm or Telix that is known to initialize your modem correctly, then you
may wish to use the same initialization string.
Refer to the LOGIN program (functions ModemSendTo and ModemWaitFor in the
file MODEM_IO.C) for an example of sending an initialization string to a
Hayes compatible modem.
PCL4C Users Manual Page 16
5.0 Problems
If you cannot get your application to run properly, first compile and run
the terminal emulator program SIMPLE provided on your distribution disk.
If your application does not run but SIMPLE 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 SioInfo('M') returns the model ID under which the library was
assembled.
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 19200 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 SIMPLE.C for an example.
8. Did you send the proper initialization string to your modem ? Did you
set DTR and RTS ? (you should).
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.
10. Your first comm port should be COM1. If you have a second port, it
should be COM2, not COM3 or COM4.
11. Are you passing the proper segment of the receive (or transmit) buffer?
See SIMPLE.C for an example.
PCL4C Users Manual Page 17
6.0 Serial Communications
6.1 Communications Basics
The heart of serial communications is the UART (Universal Asynchronous
Receiver Transmitter). The IBM PC/XT/AT and compatibles use the INS8250,
INS16450, or the INS16550 UART. 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 INS8250/16450/16550 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 it 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 is generated and the "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 section 6.6 "RS232
Signals", and section 6.7 "National INS8250, INS16450 and INS16550 UARTs"
for further information on these topics.
PCL4C Users Manual Page 18
6.2 Standard Port Addresses
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. IRQ Vector
COM1 3F8H 4 12
COM2 2F8H 3 11
COM3 3E8H 4 12
COM4 2E8H 3 11
(Refer to your DigiBoard manual for DigiBoard addresses, or your BOCA board
manual for BOCA port addresses).
PCL4C assumes the above values. If necessary, the UART base address can be
changed by SioUART, and IRQ lines can be re-assigned by SioIRQ. Remember
that each port to be used concurrently must have a unique IRQ line. Refer
to the PCL4C Reference Manual for specific details.
When installing new communications cards, the following guidelines are
recommended:
(1) Be sure to read the documentation for the hardware you are installing.
Pay special attention to UART base addresses and IRQ lines, particularly if
trying to set up a non-standard configuration.
(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. Do NOT skip over
any port.
(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) Select hardware flow control (RTS/CTS) if flow control is required and
hardware flow control is not the default.
(8) Always test your port as soon as it is installed. Try several programs
that use the communications ports.
PCL4C Users Manual Page 19
6.3 Running 3 or 4 Ports Concurrently
PCL4C supports up to 4 serial ports running concurrently (more if you have a
DigiBoard or BOCA board). One free interrupt for each port is required.
Refer to the next section if you have a DigiBoard or BOCA board.
Interrupts IRQ4 and IRQ3 are dedicated to the communications ports in a
standard IBM PC/XT/AT configuration. IRQ4 is shared between COM1 and COM3
while IRQ3 is shared between COM2 and COM4. This means that you can run two
ports simultaneously provided that they don't share an interrupt.
Suppose that you wish to run 3 ports simultaneously. To begin, you must have
3 serial UARTs installed on your computer. Assume, for purposes of this
discussion, that COM1 is installed on your motherboard, and that you have
purchased a new 2 port serial communications board.
You should be able to configure the first serial board port as COM2, which
uses IRQ3. Refer to the manual that came with your serial board.
In order to run the third serial port concurrently with the first two, an
unused interrupt must be found. If your serial card can use only IRQ3 and
IRQ4, then there is no way to run a third line since IRQ4 and IRQ3 are used
for COM1 and COM2.
However, many serial cards can use other IRQs, typically IRQ2 through IRQ5.
Since IRQ5 is normally used for a second printer port, it is a good
candidate for COM3. To use IRQ5 for the third serial port, first set your
serial card to use IRQ5 for COM3 (refer to your serial card manual) and then
add the following line to your applications code before calling SioReset:
SioIRQ(COM3,IRQ5);
Don't forget to disable any device that might use IRQ5, such as a second
printer port or a music card. Unfortunately, there is no easy way to
determine that you have no conflicts until you actually attempt to use the
IRQ. If there are conflicts, your system will probably hang and you will
have to reboot.
To run a fourth serial port, another free IRQ must be found. On some
systems, IRQ7 can be used. To use IRQ7 for the fourth serial port, first set
your serial card to use IRQ7 for COM4 and then add:
SioIRQ(COM4,IRQ7);
To summarize, your serial card must be able to generate the correct IRQ,
which is not already being used. Refer to the entry for the SioIRQ function
in the PCL4C Reference Manual.
PCL4C Users Manual Page 20
6.4 Using Multiport Cards
The PCL4C library supports the dumb Digiboard (PC/4 & PC/8) and the dumb
BOCA board (BB1004, BB1008, and BB2016).
6.4.1 The DigiBoard
PCL4C supports the DigiBoard PC/4 and PC/8. In order to use the DigiBoard,
you must configure PCL4C using the SioPorts(), SioUART(), and SioIRQ()
functions.
Your PC's ports must be partitioned into "standard" PC ports and dumb card
ports. Remember that standard PC ports cannot share IRQs like the DigiBoard
(or BOCA board) can. If you are using IRQ4 and IRQ3 for standard PC ports
COM1 and COM2, then you cannot use either for DigiBoard ports (try IRQ5 or
IRQ7).
Suppose that COM1 through COM2 are standard PC ports (using IRQ4 and IRQ3)
and you have installed a PC/8 DigiBoard that you wish to use for COM3
through COM10 using interrupt line IRQ5. You choose to use the recommended
DigiBoard UART addresses starting at 0x100:
SioPorts(10,COM3,0x140,DIGIBOARD); /* COM3 = 1st DigiBoard port */
Address = 0x100; /* 1st DigiBoard UART address */
for(Port=COM3;Port<=COM10;Port++) /* look at each port */
{SioUART(Port,Address); /* set the UART address */
Address += 8; /* compute next address */
SioIRQ(Port,IRQ5); /* set the DigiBoard IRQ */
}
The DigiBoard uses 0x140 for the status address for odd interrupts and 0x141
for even interrupts.
Digiboard may be contacted at 6400 Flying Cloud Drive, Eden Prairie, MN
55344. Telephone 612-943-9020 or FAX 612-943-5398.
6.4.2 The BOCA Board
PCL4C supports the dumb BOCA board. As with the DigiBoard, you must
configure PCL4C before using the BOCA board.
For example, to configure the BOCA BB2016 to use COM1 to COM16, with base
addresses starting at 0x100 and IRQ5:
SioPorts(16,COM1,0x107,BOCABOARD);/* COM3 = 1st BOCA board port */
Address = 0x100; /* 1st BOCA UART address */
for(Port=COM1;Port<=COM16;Port++) /* look at each port */
{SioUART(Port,Address); /* set the UART address */
Address += 8; /* compute next address */
SioIRQ(Port,IRQ15); /* set the BOCA IRQ */
}
BOCA may be contacted at BOCA Research, Inc., 6413 Congress Avenue, Suite
130, Boca Raton, FL 33487. Phone 407-241-8088, FAX 407-997-0918.
PCL4C Users Manual Page 21
6.5 Transmitter Interrupts
Beginning with version 4.0 of PCL4C, transmitter interrupts are supported by
the library. Separate libraries are provided, one with transmitter
interrupts enabled and one without. When transmitter interrupts are NOT
enabled, the following logic occurs everytime you call SioPutc():
1. Wait for transmit buffer to become empty. The transmit
buffer may not be empty if the previous transmit is not
completed (the UART breaks down the byte & sends 1 bit
at a time).
2. When the transmit buffer is empty, the byte from the
SioPutc() call is loaded into the transmit buffer and
control is returned to the caller.
Note that you can not write to the UART any faster than the UART baud rate.
When transmitter interrupts are enabled, the byte from SioPutc() is put into
a previously prepared (by SioTxQue) transmitter queue. The interrupt service
routine fetches bytes from this queue as soon as the previous byte has been
sent.
While you can now call SioPutc() faster than the baud rate, bytes are still
transmitted at the given baud rate.
The above sounds like transmitter interrupts are the way to go.
Unfortunately, this is often NOT the case. Most applications will perform
better if transmitter interrupts are NOT enabled.
The reason is that transmitter interrupts double the amount of code in the
time critical interrupt service routines. While the library is processing a
transmitter interrupt (which can take a while), incoming bytes can not be
processed. What this means is that a given machine can run at a higher baud
rate without transmitter interrupts. This problem is compounded when running
multiple ports simultaniously.
However, there are a few application areas where transmitter interrupts are
preferable. If your application will be transmitting blocks of data at
fairly slow baud rates you might profit from enabling transmitter interrupts
provided that there is something else for the processor to do (which is NOT
the case in most protocols).
Recall that PCL4C_S2.LIB (small), PCL4C_C2.LIB (compact), PCL4C_M2.LIB
(medium), and PCL4C_L2.LIB (large) are the four memory model libraries with
transmitter interrupts enabled.
PCL4C Users Manual Page 22
6.6 RS-232 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.
DTR should be set high when talking to a modem.
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, and
for hardware flow control in most modems that require flow control.
Clear to Send Pin 5 (DB25), Pin 8 (DB9)
The CTS line is used to "turn the line around" in half duplex modems, and
for hardware flow control in most modems that require flow control.
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 23
6.7 National INS8250, INS16450, and INS16550 UARTs
The Personal Communications Library is based on the standard National
INS8250, INS16450, and INS16550 UARTs. The 8250 was the original UART used
in the IBM PC, whereas the 16450 is a faster version found on most 286 & up
machines. The 16550 contains a 16 byte FIFO to further reduce communications
overhead. These UARTs consists of 8 register ports as follows:
Offset R/W Register
0 R/W Receiver (read) / Transmitter (write)
1 R/W Interrupt Enable (read)
2 R Interrupt Identification
2 W FIFO control (INS16550 only)
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.
For the standard PC ports (not DigiBoard or BOCA ports), the UART registers
are based at 3F8h (COM1), 2F8h (COM2), 3E8h (COM3), and 2E8h (COM4). COM1
and COM3 share interrupt request line IRQ4 while COM2 and COM4 share request
line IRQ3. This means that COM1 and COM3 can't be used concurrently.
Similarly for COM2 and COM4.
If you have a DigiBoard (or BOCA board) installed, you will have 4 or more
additional ports using INS16450 or INS16550 UARTS. The default DigiBoard
and BOCA board ports are located at 100h, 108h, 110h, etc. Refer to your
DigiBoard (or BOCA board) manual.
Four sources of interrupts are possible with the 8250 and 16550: (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 24
6.8 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 (read only) 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 (high) Serialization or break.
1 0 0 1 Received data.
0 1 0 2 Transmitter Buffer Empty.
0 0 0 3 (low) RS232 Input.
In the INS16650, REG 2 (write only) is also the FIFO control register.
Writing bits 6 & 7 will set the FIFO trigger level (number of bytes received
before an interrupt is generated).
Bit 7 Bit 6 Trigger Bit 7 Bit 6 Trigger
0 0 1 byte 1 0 8 bytes
0 1 4 bytes 1 1 14 bytes
REG 3 : Line Control
RS232 line parameters are selected by writing to this register.
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.
Baud Divisor Baud Divisor Baud Divisor
300 0180 4800 0018 38400 0003
1200 0060 9600 000C 57600 0002
2400 0030 19200 0006 115200 0001
PCL4C Users Manual Page 25
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 26
7.0 Example Programs
Four example programs are include with PCL4C. In addition, the Personal
Protocol Library for C (PPL4C) includes the terminal program TERM which
features ASCII, XMODEM, YMODEM, and ZMODEM protocol transfers. Complete
source code is included in the shareware product for all of the protocols
above except ZMODEM. In order to get ZMODEM source, PPL4C must be
registered.
7.1 MINIMAL
MINIMAL is the simpliest possible communications program. It reads from the
serial port & displays on the screen and reads from the keyboard & sends out
over the serial line. COM1 and 9600 baud are hard coded for simplicity.
7.2 SIMPLE
SIMPLE is a simple terminal program. It operates like MINIMAL, except that
you specify both a port and a baud rate. For example.
SIMPLE 1 9600
7.3 LOGIN
LOGIN is programmed to dial our support BBS (205-880-9748) and log on as
GUEST. Start LOGIN like SIMPLE by providing a COM port and a baud rate. For
example,
LOGIN 1 38400
7.4 DOOR
The DOOR program is a simple communications program which can "take over" a
serial port. For example, say you are running PROCOMM, PCPLUS, or any
communications program with a DOS gateway. Select the DOS gateway from
PROCOMM (or whatever) and then type
DOOR 1
at the DOS prompt to take over port COM1.
7.5 SELFTEST
The SELFTEST.C program is designed to test your serial ports provided that
you have two ports which can be connected together with a null modem cable.
SELFTEST can also be used to test your multiport board.
For example, to test PC port COM1 against COM2, type:
SELFTEST PC 1 2
SELFTEST may need to be configured for non-standard PC ports or your
multiport board. Refer to the SELFTEST source code for more information.
PCL4C Users Manual Page 27
8.0 Legal Issues
8.1 Registration
If you wish to register the PCL4C library, please send $65 plus $3 S&H ($6
outside of North America) to:
MarshallSoft Computing, Inc.
Post Office Box 4543
Huntsville AL 35815
Multiple copies are available: $50 for 3 to 9, $35 for 10 to 19, and $25 for
20 or more. A site license is also available for $495 (includes 5 sets of
printed documentation). We pay shipping.
We accept American Express (account number, expiration date, exact name on
your card, and complete AmEx billing address required), checks in US dollars
drawn on a US bank, purchase orders (POs) from recognized US schools and
companies listed in Dun & Bradstreet, and COD (street address and phone
number required) within the USA (plus a $3 COD charge).
You can also order PCL4C from The Public Software Library (PSL) with your
MC, Visa, AmEx, or Discover card by calling 800-242-4PSL (from overseas:
713-524-6394) or by FAX at 713-524-6398 or by CompuServe at [71355,470].
THESE NUMBERS ARE FOR ORDERING ONLY. The product number for PCL4C is 10908.
Please have your credit card billing address ready.
If you wish to update from an older version of PCL4C, send $20 plus $3 S&H
($6 outside of North America). Updates must be ordered directly from
MarshallSoft Computing.
The registered package includes:
o Small,Compact,Medium, & Large libs w/o shareware screens.
o Assembler source code for the library.
o Laser printed Users and Reference Manuals.
o Telephone, FAX, and BBS support for one year.
o Utility program (EXAMPORT) which displays a detailed formatted report
for any serial port.
Print the file INVOICE.DOC if an invoice is needed. The registered user will
receive the latest version of PCL4C shipped by two day priority mail (packet
airmail overseas). A 3.5" diskette is provided unless a 5.25" diskette is
requested.
PCL4C Users Manual Page 28
8.2 License
MarshallSoft Computing, Inc. grants the registered user of PCL4C the right
to use one copy of the PCL4C library (in object form) on a single computer
in the development of any software product (other than libraries such as
PCL4C). The user may not use the library on more than one computer at the
same time. The source code for the library (PCL4C.ASM) is copyrighted by
MarshallSoft Computing and may not be released in whole or in part.
Products developed using PCL4C can include the object form of the library
and may be distributed without any royalty.
8.3 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 29
9.0 Summary
9.1 Revision History
Version 1.0 - 14 January 1991 - original release.
Version 1.1 - 11 March 1991
o Added SioUnGetc() function to library.
Version 1.2 - 1 June 1991
o SioParms() bug - could not call before SioReset.
o SioReset() bug - was not saving & restoring all regs.
Version 1.3 - 1 July 1991
o Added NORESET option to SioReset.
o Added SioDSR, SioCTS, SioDCD, SioLoopBack, and SioRI.
Version 2.0 - 1 Nov 1991
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.
NOTE: MarshallSoft incorporated as "MarshallSoft Computing, Inc."
on December 23rd, 1991.
Version 3.0 - 15 Jan 1992
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).
Version 3.1 - 1 March 1992
o Added SioFIFO (INS16550 support).
o Added SioIRQ function.
o Increased maximum receive buffer size to 32K bytes.
PCL4C Users Manual Page 30
9.1 Revision History (continued)
Version 3.2 - 1 May 1992
o Modified SioReset so that it no longer clears DTR & RTS.
o Modified SioModel & renamed to SioInfo.
o Fixed bug in SioDone when using 2 ports simultaneously.
o Added SioFlow to library.
o Added YMODEM-G protocol to TERM program.
Version 3.3 - 3 August 1992
o Fixed bug in SioUnGet when using 2 ports simultaneously.
o Add SioRead function.
Version 3.4 - 4 Jan 1993
o Library modified to use up to four ports simultaneously.
o SioIRQ was modified to include a third argument.
o EXAMPORT utility distributed to registered users.
Version 3.5 - 15 May 1993
o Supports dumb DigiBoards ( PC/4 and PC/8).
o Two new error traps added ("No such IRQ" & "No such ISR").
o ASCII file transfer protocol added to TERM (with XON/XOFF).
Version 4.0 - 18 Oct 1993
o The library supports transmitter interrupts.
o Corrects bug in Ver 3.5 requiring calling SioIRQ for COM3/4.
o All example code compiles with supported C++ compilers.
o The SioIRQ() function has been simplified.
Version 4.1 - 1 May 1994
o Transmitter FIFO enabled.
o Minor internal modifications.
o Supports dumb BOCA boards (BB1004, BB1008, & BB2016).
o Port definition extented to COM16.
Version 4.2 - 1 Sept 1994
o A flow control bug was fixed.
o SioGetDiv function added.
o SioRxBuf & SioTxBuf function modified.
Version 4.3 - 15 March 1995
o BREAK detection bug fixed,
o Port definitions extended to COM20.
o Support for IRQ8 through IRQ15.
o Line status bits preserved.
(The TERM program moved to PPL4C)
PCL4C Users Manual Page 31
9.2 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.
SioFIFO Sets the interrupt level for the INS16550.
SioFlow Enables / disables hardware flow control.
SioGetc Reads the next character from the serial line.
SioGetDiv Reads the baud rate divisor registers.
SioKeyPress Detects if keyboard has been pressed.
SioKeyRead Reads the keyboard.
SioInfo Returns library version number & memory model.
SioIRQ Assigns an IRQ line to a port.
SioLine Reads the line status register.
SioLoopBack Performs a UART loopback test.
SioModem Reads the modem status register.
SioParms Sets parity, stop bits, and word length.
SioPorts Sets # ports, 1st DigiBoard / BOCA port & status reg.
SioPutc Transmit a character over a serial line.
SioRead Reads any of 7 UART ports.
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.
SioTxBuf Sets up transmit buffer.
SioTxFlush Flushes (clears) the transmit buffer.
SioTxQue Returns the number of characters in the transmit queue.
SioUART Sets the UART base address.
SioUnGetc "Un-gets" (puts back) a specified character.
9.3 Further Reading
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 32
10.0 Other MarshallSoft Computing Products
10.1 The Personal Protocol Library for C/C++
The Personal Protocol Library for C (PPL4C) consists of a C/C++ language
library which implements XMODEM, XMODEM-CRC, XMODEM-1K, XMODEM-G, YMODEM,
YMODEM-G, and ZMODEM file transfer protocols. A script compiler and
interpreter is also included which is capable of such tasks as automatically
logging onto a BBS and downloading a file or retrieving mail. Three example
script programs are included.
The protocol library (PPL4C) requires the Personal Communications Library
for C (PCL4C).
The Personal Protocol Library for C is available for $40 plus $3 S&H ($6 S&H
overseas).
10.2 The LZW Data Compression Library for C
LZW4C is an implementation of the LZW (Lempel-Ziv-Welch) algorithm for
compressing and decompressing data. LZW does particularly well on text
files, achieving better than a 50 % compression ratio for many files.
The LZW algorithm is considered to be one of the best general purpose
algorithms available today. The new high speed modems that employ
on-the-fly data compression (such as MNP 5.0 & the V.42 bis international
standard) use the LZW algorithm, as well as such well known utility programs
such as PKZIP.
The LZW Data Compression Library for C is available for $45 plus $3 S&H ($6
S&H overseas).
10.3 The EMS Expanded Memory Library
The EMS4C library implements version 3.2 of the LIM (Lotus-Intel-Microsoft)
specification for expanded memory. It will run with either version 3.2 or
4.0 of the LIM specification.
The EMM4C library (included with the EMS4C library) is an expanded memory
manager which allows C programmers to allocate and free EMS (expanded)
memory similiar to malloc() and free() in the standard C runtime library.
Both EMM4C and EMS4C require that your system be configured with expanded
(EMS) memory. But, 386 & up systems can use extended memory as expanded
memory.
The EMS Expanded Memory Library for C is available for $35 plus $3 S&H ($6
S&H overseas).
PCL4C Users Manual Page 33