Category : Pascal Source Code
Archive   : LTCOMM50.ZIP
Filename : LCTP.PRN

 
Output of file : LCTP.PRN contained in archive : LTCOMM50.ZIP














Chapter 1
Chapter 1

OVERVIEW
OVERVIEW


1.1 FEATURES
1.1 FEATURES


The LiteComm-TP Toolbox(Tm) is a set of powerful routines designed to
provide easy access to the full capabilities of the PC's asynchronous
communications ports. The LiteComm-TP ToolBox supports fully
interrupt-driven and buffered communications support on COM1 through
COM4 simultaneously. Now you can quickly incorporate sophisticated
communications support in your applications without having in-depth
knowledge of how the hardware functions.

LiteComm-TP is implemented as a set of 4 units for the basic product,
with additional units providing the protocol-engine capability. The
protocol engines are a part of the registered version of the package.

The LiteComm ToolBox was originally developed in the C language for
use in CAD/CAM applications that required the ability to have PC
compatible systems communicating with a variety of devices.
LiteComm-TP extends the same capabilities to the PASCAL programmer.


1.2 THE SHAREWARE CONCEPT
1.2 THE SHAREWARE CONCEPT


Shareware is a "try before you buy" means of software distribution. If
you find a shareware product useful, pay the registration fee, and let
the authors know that you support their efforts.

Information Technology 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
P.O. Box 5786, Bellevue, WA 98006 or send a Compuserve message via
easyplex to ASP Ombudsman 70007,3536.



LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL




























































Page 2
Copyright (c) 1987, 88, 89 Information Technology, Ltd.


LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL









Chapter 2
Chapter 2

LICENSE, WARRANTY AND REGISTRATION
LICENSE, WARRANTY AND REGISTRATION


2.1 LICENSE
2.1 LICENSE


The LiteComm-TP ToolBox, is distributed as a shareware product. We
urge you to register your copy today. See the registration form at the
end of this manual.

Information Technology, Ltd, grants to registered users a
nonexclusive, perpetual license to the LiteComm-TP ToolBox, subject to
these terms and conditions:

1. You must treat your copy of the LiteComm-TP Toolbox as you
would a book. You may install the LiteComm-TP ToolBox on more
than one machine, but you may use only one copy at a time. If
you desire, site licenses are available at a reduced cost. You
may make as many copies of the LiteComm-TP ToolBox as you
require for the sole purpose of backup.

2. You may incorporate portions of the LiteComm-TP ToolBox into
products that you develop without the payment of additional
royalties or license fees. You must include the statement
'Portions Copyright 1987, 1988, Information Technology, Ltd' in
your product's documentation.

3. You may copy and redistribute the shareware portion of the
LiteComm-TP ToolBox, commonly known as LCOMMTP.ARC, but you may
not modify in any way, the contents of the shareware package.

4. Information Technology grants to ASP-approved vendors only the
right to charge a duplication fee, not to exceed $8.00 for
providing a copy of the shareware version of the product. No
other individual or vendor is permitted to charge a fee for
providing such a copy without the express, written consent of
Information Technology, Ltd,

5. You may not redistribute, in any form, the source code for the
LiteComm-TP ToolBox. Further, you may not translate the source
code for the LiteComm-TP ToolBox into any other language
without the express, written consent of Information Technology,
Ltd.






Page 3
Copyright (c) 1987, 88, 89 Information Technology, Ltd.


LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL



6. Information Technology reserves the right to change both the
LiteComm-TP ToolBox or its documentation without prior notice,
with no obligation to you, the licensee.

7. You agree that any disputes arising from this license will be
subject to the laws of the state of Rhode Island.

8. You agree to hold the developer and distributors of the
LiteComm-TP ToolBox harmless for any damages, either direct or
consequential, that might arise from the use of this product.

9. You acknowledge that the LiteComm-TP ToolBox, libraries, source
code, and documentation are the copyrighted property of
Information Technology, Ltd.

10. By your use of the LiteComm-TP ToolBox, you acknowledge that
you have read, and understand the terms and conditions of this
license.


2.2 WARRANTY
2.2 WARRANTY


The LiteComm-TP ToolBox is distributed as-is and without warranty,
including, but not limited to, the implied warranties of
merchantability and fitness for a particular purpose.

Information Technology, Ltd does warrant the distribution media for a
period of 30 days. During that period, Information Technology, Ltd
will replace the distribution media or provide a refund at its option.


2.3 REGISTERING YOUR COPY
2.3 REGISTERING YOUR COPY


Registration of your copy of the LiteComm-TP ToolBox provides you with
several benefits:

1. Puts you on our mailing list for low-cost updates,
enhancements, and alert bulletins when they occur.

2. Gives you access to telephone support. Sorry, but we cannot
provide support by telephone to unregistered user's of the
ToolBox. Unregistered users can leave EMAIL on Compuserve to
70166,1152 and on GEnie to I.TECH. We will respond to EMAIL on
an as-available basis.

3. Helps to further the shareware concept.

You can order directly from us or from the Public (Software) Library
1-800-2424-PSL (for orders only. For information call 1-713-665-7017)
or by writing PSL; P.O.Box 35705; Houston, TX 77235-5705. MC/Visa
Accepted.




Page 4
Copyright (c) 1987, 88, 89 Information Technology, Ltd.


LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL



If you want to order directly from us, print the file REG.FRM and
follow the instructions there.


2.4 NOTE
2.4 NOTE


LiteComm-TP is a package undergoing continuing development.
Registered users of the product receive, in addition to the fully-
functional base package, units that provide protocol engines
supporting XModem, XModem-1K, and YModem protocols.

We plan to follow these with similar engines for CompuServe B, Telink,
and other protocols. These engines, as they are released, will only be
made available to registered ToolBox users. The shareware version, as
enhanced but without the protocol engines, will continue to be
offered.








































Page 5
Copyright (c) 1987, 88, 89 Information Technology, Ltd.


LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL




























































Page 6
Copyright (c) 1987, 88, 89 Information Technology, Ltd.


LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL









Chapter 3
Chapter 3

Serial Port Fundamentals
Serial Port Fundamentals


3.1 The 8250 UART family
3.1 The 8250 UART family


This portion of the manual provides you with some details about the
working of the 8250 (and related) UART'S, the basic component of
your system's serial port. Some close compatibles use enhanced
versions of this chip, such as the Intel 16450. LiteComm is known
to work successfully with such devices. If you have questions
about the kind of serial port you are using, refer to the
manufacturer's documentation. If your serial port does not use an
8250 or similar chip, LiteComm will not function.


3.2 Purpose of the port
3.2 Purpose of the port


The purpose of the serial port is to convert information from the
form in which it is used within your system, to a form that can be
easily used outside your system. Modern computers, by design, are
parallel in nature. By this we mean that information travels
through the computer's circuitry as whole units or as multiples of
whole units. In the IBM PC and related systems, information travels
as bytes (8 bits at a time), as words (16 bits at a time), or, on
80386 based systems, as double words (32 bits at a time).

Within the computer, such arrangements are convenient and fast. But
when the computer must transfer information to an external device,
the problem of data path width is introduced. To provide a true,
parallel path between the computer and external devices, there
would have to be, at a minimum, enough data lines or circuits
between the two to satisfy the data path. For most modern computer
systems, this would mean a minimum of 8 data lines, not counting
any additional control information that might also be required.
For certain newer systems, the requirement might be for as many as
32 data lines. In effect, it might be necessary to have several
different versions of a device, dependent upon the data path width
of the computer to which it is connected.

The purpose of a serial port is to convert the information from its
internal, parallel form, to a more common, external form and back
again. By using such an approach, we simplify the interconnection
of devices, reducing information to its lowest common denominator,
the bit. And it allows us to transfer information 1 bit at a time,



Page 7
Copyright (c) 1987, 88, 89 Information Technology, Ltd.


LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL



using a single data path, between devices. The real beauty of this
approach is that, by 'agreeing' on how this external form appears,
each device can hide the details of how it works, and still
accomplish the required task.


3.3 Internal Details
3.3 Internal Details


In this section we discuss the fundamental working of serial ports
as they are implemented of the IBM PC and close compatible systems.
It is not essential that you understand this material thoroughly to
be successful with LiteComm. However, it may help to answer some of
the more important questions that may arise as you proceed with
your development.

3.3.1 The Interrupt Connection
3.3.1 The Interrupt Connection

The PC is an interrupt driven system. This is a sophisticated way
of saying that the PC can 'pay attention' to a number of internal
devices without the necessity of having to check on them
periodically.

When we describe interrupts to clients, we use the school room as a
metaphor. Think of a teacher lecturing to a group of students
during a class. The teacher knows that, on occasion, one or more
students may not understand the material that is being presented.
So the teacher has the choice of either asking each student
periodically if they understand or permitting the students to raise
a hand to ask a question. As you can imagine, stopping the class
to 'poll' each student will waste valuable time, particularly if no
one wants to ask a question. Not only is it wasteful of time, but
the last student polled may have forgotten the question he or she
wanted to ask by the time the teacher gets to him. If the teacher
permits students to 'interrupt' his lecture by raising a hand, much
less time is wasted, but the teacher has to be careful to identify
each raised hand by name and answer the question quickly and
accurately, lest some student forget his question or looses
interest altogether.

The internal working of most modern computers is identical to the
teacher that permits hand raising. The computer focuses on the
task at hand, stopping only to identify and pay attention to
devices when they signal that they require this attention. So much
for the hardware end of things. The PC has this same capability.
But at least some of the work that has to be done requires software
in a general purpose computer, otherwise the computer wouldn't be
general purpose.

The serial port on the PC is no less capable of asking for
attention from the computer, at least from the standpoint of
hardware. But, for whatever the reason, MS-DOS and PC-DOS do not
provide the needed software to exploit the full capabilities of the
serial port. OS/2 does provide such support, we are told, but, at



Page 8
Copyright (c) 1987, 88, 89 Information Technology, Ltd.


LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL



least for the foreseeable future, its an MS-DOS world. On PC's and
true compatibles, the only support for the serial port that is
provided is through the system's ROM BIOS. And that support is
only for the polled mode of operation.

The method by which 80x86 family systems, of which the PC is a
part, is elegant in its simplicity. When a device needs the
attention of the system, its asserts a control signal and
identifies itself with a number ranging from 0 to 255. On the basic
PC, the numbers used actually range from 8 through 15 decimal. The
identification is translated to a memory location by multiplying
the identification by 4, and the system simulates a special form of
a call to the routine whose address is stored at that location.
Since it is impossible to predict when a device will require
attention, the full address of the routine is stored, both segment
and offset, hence the 4.

Once the routine, called the Interrupt Service Routine or ISR is
invoked, it has a duty to save the state of the system when the
interrupt occurred, take care of the interrupt as quickly as
possible, and return control to the interrupted process. But it
must also be aware that, while it is doing its work, other, more
important devices may require attention, too.

One such device that is likely to require attention is the system
clock which ticks roughly 18 times per second. In part, the PC
makes provision for this by prioritizing the interrupt scheme. The
ISR must allow for this by re- enabling the interrupt control
system as rapidly as it is practical to do so. The PC's interrupt
structure, if left undisturbed, will prevent interrupts of the same
or lower priority from occurring. To help your organize your
thoughts, the standard identification for the first two serial
ports on the system are 12 (0C) and 11 (0B) for ports 1 and 2
respectively.

As you can see, dealing with the PC's interrupt structure is not
for the faint of heart. It requires a significant amount of
knowledge, and close attention to detail. With LiteComm, these
details have already been taken care of for you. You are free to
focus on your application, treating the serial port in much the
same way that you would any DOS file.

3.3.2 The Programmable Port Registers
3.3.2 The Programmable Port Registers

The 8250 port, and its close relatives, are fully programmable.
You are fortunate that LiteComm has already taken care of the
intricacies of this programming. But some additional information
about each of the registers used in the serial port may be of use
when you are attempting to communicate with an external device. For
the sake of this discussion, we use the basic register numbers,
although the register number that is employed in programming is
actually the register number referenced below used as an offset to
a base port number. In the case of COM1 (port 1), this base is
3F8(hexadecimal).



Page 9
Copyright (c) 1987, 88, 89 Information Technology, Ltd.


LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL



3.3.2.1 register 0 - transmit/receive
3.3.2.1 register 0 - transmit/receive

In normal operation, individual characters are read from register 0
when the become available, and are written to register 0 when the
transmitter portion of the 8250 is ready to accept a character.

3.3.2.2 register 0 - baud rate selection
3.3.2.2 register 0 - baud rate selection

During initialization, register 0 is used as part of the mechanism
that sets baud rate. During this process, register 0 and its
companion register 1 are used to specify the baud rate divisor (not
the actual baud rate). The baud rate divisor is a value which, when
divided into a given, preset constant, yields the desired baud
rate. To use registers 0 and 1 to set the baud rate, access to
this mode must be first enabled by writing a value of 80H to
register 3, the line control register. Once access is enabled, the
least significant byte (LSB) of the divisor is written to register
0; the most significant byte is written to register 1. Access to
the normal modes of registers 0 and 1 are re- enabled by writing
any value less than 80H to the line control register. Of course,
only certain values less than 80H would be meaningful (see the line
control register description below).

3.3.2.3 register 1 - interrupt enable
3.3.2.3 register 1 - interrupt enable

Values written to register 1 control which conditions will cause
the 8250 to interrupt the system. There are four possible
conditions that can cause interrupts:

1. A character has been received (RDI)

2. The transmitter is ready to send a character (TDI)

3. An error or BREAK signal has been detected (ERI)

4. A modem status signal has changed (MSI)

The designations, in parentheses, are for our purposes only. They
are not 'standard' designations. To enable a particular type of
interrupt, you must set the corresponding bit in a byte to a 1,
then write the byte to register 1. To reset (ignore) the
condition, set the corresponding bit to 0. The diagram that
follows shows the bit positions the correspond to the various
conditions described above.

+------+------+------+------+------+------+------+------+
| | | | | | | | |
| N/A | N/A | N/A | N/A |Modem |Error/| Xmit | Recv |
| | | | |Status|Break |Ready | Char |
+------+------+------+------+------+------+------+------+
7 6 5 4 3 2 1 0
Figure 3.1: Register 1 Bit Definitions
Figure 3.1





Page 10
Copyright (c) 1987, 88, 89 Information Technology, Ltd.


LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL



3.3.2.4 register 1 - baud rate selection
3.3.2.4 register 1 - baud rate selection

See the description under register 0, baud rate selection.

3.3.2.5 register 2 - interrupt identification
3.3.2.5 register 2 - interrupt identification

Register 2, in normal operation, acts as a companion to register 1.
Register 1 determines the conditions that can cause an interrupt.
Register 2 is used to determine which condition actually caused the
interrupt, when more than one condition has been enabled. Only
least significant 3 bits of the register are actually employed.
See the diagram of register 2 below.

+------+------+------+------+------+------+------+------+
| | | | | | | | |
| N/A | N/A | N/A | N/A | N/A | see |below | Int |
| | | | | | | | pend |
+------+------+------+------+------+------+------+------+
7 6 5 4 3 2 1 0
Figure 3.2: Register 2 Bit Definitions
Figure 3.2

Since it is possible, even likely, that more than one condition may
occur at the same time, bit 0 is used to determine whether all
conditions that currently exist have been handled. When bit 0 has
a value of 0 (yes zero), there are conditions waiting to be
handled. When bit 0 has a value of 1, all outstanding conditions
have been handled. Bits 2 and 1 taken together identify the actual
cause of the interrupt.

Again, because of the multiple conditions which may occur, the 8250
presents the conditions in a prioritized order. When bits 2 and 1
have a value of 3 (the most important), an ERI condition has been
identified. The actual error is determined by reading the line
status register(register 5). Reading this register also clears the
condition.

When a value of 2 is present, an RDI condition has occurred, and a
character should be read. from port 0. If the character is not read
quickly enough, a data overrun error may occur, indicating that a
character was lost.

When bits 2 and 1 have a value of 1, a TDI condition has occurred
and a character may be written to register 0.

A value of zero in bits 2 and 1(least important) indicates that one
or more of the modem status lines (so called) have changed. The
condition is cleared by reading the contents of the modem status
register, register 6.

3.3.2.6 register 3 - line control
3.3.2.6 register 3 - line control

The line control register provides the means for setting those
values that affect the way in which the serial port appears to the
outside world. It is through this register that character length,



Page 11
Copyright (c) 1987, 88, 89 Information Technology, Ltd.


LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL



parity, and other significant values are established. Indirectly,
register 3 also plays a role in setting the speed (baud rate) of
the port. (See the description of registers 0 and 1 above.)

+------+------+------+------+------+------+------+------+
| Baud | | | | | | | |
| Div | Send |Force |Parity|Enable| Stop | Character |
|Enable|Break |Parity| Type |Parity| Bits | Length |
+------+------+------+------+------+------+------+------+
7 6 5 4 3 2 1 0
Figure 3.3: Register 3 Bit Definitions
Figure 3.3

3.3.2.7 register 4 - modem control
3.3.2.7 register 4 - modem control

The modem control register permits control of the two modem-
related signals that the serial port generates as an output. The
signals are RTS and DTR.

These two signals are called 'handshaking' signals, since they, in
part, help a connected device determine the state of the
connection. You should be aware that although these signals were
originally designated to be used in a specific fashion,
manufacturers of specific devices have used them to meet their own
needs. Your success or failure in dealing with any specific device
may depend, in part, on your understanding of how the device's
manufacturer uses these signals. LiteComm provides you the means
for manipulating these signals in a variety of ways.

You will notice in the register 4 diagram, below that some
additional positions are identified.

+------+------+------+------+------+------+------+------+
| | | | | | | | |
| N/A | N/A | N/A |Enable| OUT2 | N/A |Enable|Enable|
| | | |Loopbk|(reqd)| | RTS | DTR |
+------+------+------+------+------+------+------+------+
7 6 5 4 3 2 1 0
Figure 3.4: Register 4 Bit Definitions
Figure 3.4

LiteComm controls all of these additional positions for your
benefit. Only one deserves mention, the position labeled OUT2. It
is necessary for this position to have a value of 1 for the serial
port to function as an interrupting device. Since LiteComm relies
on interrupts to perform it's job, it insures that this position is
always set correctly.

3.3.2.8 register 5 - line status
3.3.2.8 register 5 - line status

The line status register is read normally when an ERI condition
occurs. Each bit of the character returned when the port is read
has significance, as shown in the accompanying diagram. Using the
appropriate functions in LiteComm, you can interrogate the value in
this register, and test for the various conditions using the
LiteComm- provided definitions. Note that, due to the special



Page 12
Copyright (c) 1987, 88, 89 Information Technology, Ltd.


LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL



nature of the BREAK signal, LiteComm treats this one condition as a
separate entity.

+------+------+------+------+------+------+------+------+
| |Shift | Hold | | | | | |
| Time |Reg | Reg | Recd |Frame |Parity| Data | Char |
| Out |Empty |Empty |Break |Error |Error |OvrRun| Recd |
+------+------+------+------+------+------+------+------+
7 6 5 4 3 2 1 0
Figure 3.5: Register 5 Bit Definitions
Figure 3.5

3.3.2.9 register 6 - modem status
3.3.2.9 register 6 - modem status

Just as the serial port can generate certain 'handshaking' signals,
it can also read, and report on the status of similar signals that
are generated by an external device. In their original form, these
signals had special significance when a terminal was connected to a
modem. We refer you to our comments, above, about present day use
of the handshaking signals.

One special note is appropriate here. The modem status register
actually provides two types of information. The most significant 4
bits (see the diagram) show the current state of the 4 covered
signals. The least significant 4 bits indicate which, if any, of
the signals have changed state (from zero to one, or vice-versa),
since the last time the register was interrogated. LiteComm
updates its internal tables with this value in real-time, and
reports the results when asked to do so. You can test the signals
individually or in combination using the LiteComm-provided
definitions.

+------+------+------+------+------+------+------+------+
| DCD | RI | DSR | CTS | | | | |
| carr | ring |data |clr to|DELTA |DELTA |DELTA |DELTA |
|detect|indic |set rd| send | DCD | RI | DSR | CTS |
+------+------+------+------+------+------+------+------+
7 6 5 4 3 2 1 0


3.4 The LiteComm Connection
3.4 The LiteComm Connection


Figure 3.6: Register 6 Bit Definitions
Figure 3.6

In the design of LiteComm, we have purposely 'hidden' many of the
underlying details we presented above. In many cases, you will have
little use for this additional information. This is particularly
true of most of the applications with which come into contact. In
fact, in the majority of applications, you will probably open the
port or ports, set the necessary parameters and modem control
signals, and do nothing more than read and write characters using
one or more of the LiteComm functions. The beauty of LiteComm's
design is that its high degree of granularity doesn't force you to
pay the price of dragging along functions that you are not using.



Page 13
Copyright (c) 1987, 88, 89 Information Technology, Ltd.


LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL



The information that we presented above will help you when it is
necessary to communicate with a device that requires special
handshaking considerations, such as a cash drawer. You may also
need some of the information we presented if you intend to use
serial ports beyond COM2 (serial port 2).

Finally, by presenting the information that we have supplied, we
hope to gain a more informed user. Communications programming is
not the black art that some would have you believe, although it can
easily seem that way at times. Of all of the calls we receive who
need questions answered, more than 75 per cent could have been
answered by the caller himself with a more thorough understanding
of the underlying concepts and rules.


3.5 TOOLBOX NOTES AND WARNINGS
3.5 TOOLBOX NOTES AND WARNINGS


Before you can send or receive information on a serial port using
the ToolBox, you must use the open function to enable the line.
This function initializes the 8250 UART with the correct
parameters, and introduces the UART into the interrupt structure of
the PC. The ToolBox will detect, and report, any errors that you
may make in selecting the port or specifying the initial
parameters. The ToolBox cannot and will not detect an attempt to
open a nonexistent serial port.

The ToolBox interfaces directly with the interrupt structure of the
PC. It is critical before exiting a program that has opened a
serial port that the serial port is closed with the close function.
Because a program may terminate abnormally, the open function
installs an exit routine that will automatically close any open
ports. Good programming practice demands, however, the your program
should close the ports explicitly. By so doing, you may avoid
problems in the future if we find it necessary to remove the auto-
close functionality. Further, the auto-close functionality drops
all modem handshaking signals absolutely, while an explicit close
can decide whether or not to drop these signals. You should review
Borland's documentation about installing exit routines in the Turbo
PASCAL Reference, and you should review the documentation for
CommClose for further information about the features of that
procedure.

Failure of the open function can be the result of either improper
parameters to the open function, or insufficient memory available
to allocate the requested buffers and related control structures
for the port. Memory for the transmit and receive buffers as well
as the port control block are allocated from the heap. It is your
responsibility to insure that adequate memory is available for this
purpose.

The 8250 serial chip and its descendants will not transmit
information until, at a minimum, the DTR (Data Terminal Ready)
signal is asserted. The ToolBox will, at your option, assert both



Page 14
Copyright (c) 1987, 88, 89 Information Technology, Ltd.


LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL



the DTR and RTS signals when you open the port. If you do not
select this option you must use the SetModem function to assert
(raise) this signal. In addition, some modems and other devices
may require you to assert the RTS (Request To Send) signal before
they will respond to data. The use of this, and other handshaking
signals is HIGHLY hardware-dependant. The ToolBox provides all the
functionality necessary for you to implement virtually any
handshaking scheme that might be required.

Due to the use of all available interrupt modes of the 8250, one
user has discovered an unusual set of circumstances that can be
troublesome. If the 8250 chip detects an error condition, such as
a parity error, framing error, or data overrun error, it causes an
interrupt to which the ToolBox will respond. If these errors occur
frequently enough, the ToolBox code will spend too much time
handling the errors, and lose characters as a result, causing
additional errors. If you encounter a situation in which your
application appears to behave erratically, especially at higher
speeds, investigate the following table.

Table 3.1: Possible Error Conditions
Table 3.1

- Is the cabling to the other device sound and solidly
connected.

- Are any of the signals in the cable 'floating' or are they
all properly terminated.

- Is the other device known to be functioning properly. We
have encountered situations in which a serial port on some
devices tend to be sloppy in terms of voltage levels, bit
timings, and similar problems. Any or all of these
situations can cause the erratic operation to which we
referred.

Unless you are very familiar with the interrupt structure of the
PC, do not attempt to manipulate the interrupt enable flag outside
of the ToolBox. The ToolBox sets and clears the interrupt enable
flag at appropriate times and assumes that it has sole control over
the flag.

















Page 15
Copyright (c) 1987, 88, 89 Information Technology, Ltd.


LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL




























































Page 16
Copyright (c) 1987, 88, 89 Information Technology, Ltd.


LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL









Chapter 4
Chapter 4

LITECOMM-TP HISTORY
LITECOMM-TP HISTORY


4.1 VERSION 3.0
4.1 VERSION 3.0


Version 3 of LiteComm-TP was a departure from the precedent
established in previous version. In versions 1 and 2, LiteComm-TP
was implemented strictly in Turbo-PASCAL. The advantages to a
strictly high-level language implementation are obvious...as is the
drawback of speed. In version 3.0, the kernel interrupt handlers
were re-implemented in assembly language. In addition, version 3
contained some fundamental function additions that will be of use
to those attempting to develop bulletin board systems. In
addition, we feel that these routines will serve as a tutorial on
how to approach certain communications problems.

With version 3, we also included interrupt chaining for COM3 and
COM4, that users of the C version of LiteComm have enjoyed since
version 2.


4.2 NEW IN VERSION 5
4.2 NEW IN VERSION 5


There will be no version 4 of the LiteComm-TP ToolBox. We have
opted to bring out the next revision as Revision 5 to maintain
consistency with the C version.

Version 5 features significant enhancement to the kernel interrupt
handlers and supporting code, resulting in higher baud rates on
older, slower systems. In addition, the tighter code should result
in smaller applications.

And with version 5, we have also upgraded and enhanced the XModem
and YModem protocol engines with additional capabilities. If you
are interested in the protocol engines, see the separate
documentation for them. Note that the protocol engines are a part
of the registered version of LiteComm-TP only.

Due to a lack of interest in Windowed XModem, we have decided to
drop support for that engine, in favor of the other, more advanced
protocols. For your convenience, we will continue to provide the
source code for the WXModem engine, but we cannot answer questions
or support it.




Page 17
Copyright (c) 1987, 88, 89 Information Technology, Ltd.


LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL



We had originally planned to include a ZModem protocol engine as
part of version 5. While that engine is nearing completion, we did
not want to hold up the newest version of the main package. Nor did
we want to release something like ZModem until we are satisfied
with its performance. ZModem is coming in the next major release.




















































Page 18
Copyright (c) 1987, 88, 89 Information Technology, Ltd.


LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL









Chapter 5
Chapter 5

BEYOND COM2
BEYOND COM2


5.1 THE TOOLBOX METHODOLOGY
5.1 THE TOOLBOX METHODOLOGY


In the design of the original PC, and in subsequent variations such
as the PC/AT, there were only provision for two serial ports. Many
manufacturers of add-in products, both serial ports and internal
modems have added the capability to support 1 or more additional
ports beyond the COM2 limit. Generally, this can cause problems in
the PC since there is no room in the interrupt request scheme for
additional levels of interrupts, and there are no designated
interrupt vectors for other additional ports.

The ToolBox approach to resolving these issues is to permit the
programmer a degree of control over the parameters that govern the
interrupt mechanism for COM3 and COM4. Specifically, these
parameters are:

1. The interrupt request (IRQ) bit that is used to mask the
8259 interrupt controller.

2. The interrupt vector number (not address) to which the port
is attached.

3. The base i/o register for the port itself. Of course, it is
assumed that the port is based upon the 8250 UART or
compatible device.

Before you attempt to use COM3 and/or COM4, you must determine from
the port's documentation, the appropriate values for these three
parameters. As distributed, the ToolBox assumes the following:

Table 5.1: COM3 and COM4 Default Settings
Table 5.1

COM3 COM4
____ ____

IRQ Bit 4 3
Vector # 0Ch 0Bh
Base Reg 3E8h 2E8h

You may change any or all of these values by using the PortChange
function described below, but only before you open the port with
CommOpen. Once the port has been opened, PortChange is ineffective,
and PortChange will not work at all on COM1 or COM2.



Page 19
Copyright (c) 1987, 88, 89 Information Technology, Ltd.


LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL



At present, LiteComm is not compatible with multiport boards such
as the Digiboard. The structure of these boards generally require
additional programming to be used effectively. If you want to use
such a board with LiteComm, please contact us directly for
information on custom modifications to LiteComm. We have performed
such modifications for other LiteComm users.


5.2 CAUTIONS
5.2 CAUTIONS


There is an intimate relationship between the IRQ setting and the
interrupt vector to which it relates. In the PC, this relationship
is controlled, in part, by the 8259 interrupt controller that is
set during BIOS initialization.
In brief, the BIOS settings for the PC (and most close compatibles)
establish IRQ0 as being vector number 08h, and subsequent IRQ
levels at increasing vector numbers. These vector numbers (or types
in INTEL terms) act as a cpu-directed call table to locations in
the lowest 1K of system memory. We can alter how the system
responds to a given interrupt by replacing or changing the values
in the associated vector position to point to a routine which we
supply.

COM3 and COM4 share two critical parameters with COM1 and COM2
respectively, the IRQ bit and the interrupt vector number. If you
use COM3 and COM4 with the default IRQ and Vector values, and you
have a COM1 or COM2 installed in your system, LiteComm will chain
(share) the interrupt vector. Otherwise you must change both the
IRQ and Vector using the PortChange facility. Please remember, the
ability for your add-on ports to handle such a change is highly
hardware dependent, so check your port's documentation carefully.
Failure to do so will result in loss of data at best, and a system
lockup at worst.

Judging from the questions asked by some users of LiteComm-TP,
there is evidently some misunderstanding about using ports beyond
COM2, and how this all relates to your hardware. Before you can
successfully use COM3 or COM4, you must consider the following:

1. Does the hardware permit a change to the base port and/or
the interrupt vector to which the port responds. Some
expansion cards will support changing one and not the other,
giving rise to potential hardware conflicts and lost data.

2. Does the hardware permit reassignment of the IRQ priority.
Some expansion cards permit you to alter the IRQ priority,
some won't. Suffice it to say from the previous discussion
the any change to the IRQ priority must allow a
corresponding change to the interrupt vector number. Without
this capability, reprogramming of the 8259 chip would be
required.





Page 20
Copyright (c) 1987, 88, 89 Information Technology, Ltd.


LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL



3. In fact, many add-on cards permit this dual change simply by
making a single switch or jumper setting. Unfortunately, the
documentation for these cards generally assume that you are
aware of the dual nature of the IRQ vector relationship, and
may leave you with the impression that you are changing one
and not the other. In most circumstances, this is not the
case.

The point to all of this is that LiteComm-TP can only provide as
much support as the hardware permits, or is capable of responding
to. If you wish to use other than the default base port, interrupt
vector, or irq priority for COM3 or COM4, then your expansion card
must be capable of supporting the new values; in other words, these
values are all hardware-provided, and are recognized by the
LiteComm-TP software. If your hardware does not permit changing a
value, LiteComm-TP cannot improve the situation.

We should, at this point, add one final caution about how interrupt
priorities function, and their relationship to the irq bit the you
may select. The standard PC permits 8 interrupt priority levels,
with the programmable timer having the highest priority, and the
parallel printer port having the lowest priority. When an interrupt
occurs, the interrupt controller (8259 chip) masks out all other
interrupts from the priority of the interrupting device and all
lower priority devices.
As an aid to making COM3 and COM4 "fit", LiteComm-TP supports
interrupt chaining for the COM3 and COM4 ports. If you use COM3 or
COM4, when an interrupt occurs, the kernel will attempt to
determine if the interrupt was caused by the supported port or from
some other source.

If the kernel determines that the supported port did not cause the
interrupt, an automatic chain to the original interrupt handler for
that interrupt level (IRQ level) will take place, allowing you to
"patch in" or share the available interrupt vectors.

If you intend to use other than the provided defaults, be sure that
you understand the interrupt mechanism. The use of the automatic
chaining described above can be particularly troublesome under some
circumstances, resulting in loss of interrupts and, potentially, a
system crash.

DO NOT attempt to mix the ToolBox functions with other seemingly-
related functions (such as the serial port BIOS routines in Turbo
PASCAL). At least two users have attempted to only use the receive
portions of LiteComm, while resorting to the BIOS functions to send
characters or adjust port parameters such as baud rate. The
results, at best, have been failure of the user's application to
function, and, at worst, total system lockup. This mix of
functions is NOT supported and must not be used. If you attempt
such a mix, we cannot help you.

One final caution is in order. One or two users have attempted to
trace through the interrupts as they occur using debuggers. This



Page 21
Copyright (c) 1987, 88, 89 Information Technology, Ltd.


LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL



is a risky proposition at best since most debuggers work by tapping
into, and disturbing, the interrupt mechanism. If you feel you
must use a debugger, try to stay away from the kernel routines of
LiteComm, or use a hardware-based debugger such as Periscope.


5.3 OTHER GENERAL NOTES AND WARNINGS
5.3 OTHER GENERAL NOTES AND WARNINGS


In the discussion of the various functions which follow, you should
assume that any references to the 'port' variable refer to a
variable or constant that may take on a value of from 1 to 4. No
other values are acceptable, and will be rejected.

While we feel that LiteComm-TP is written in the most efficient way
possible, commensurate with good programming practice, we cannot be
responsible for variations caused by hardware configurations or
other factors beyond our control. LiteComm-TP has been tested, and
is known to perform on, the IBM PC-AT and several compatible
systems such as the Zenith and Wyse equivalents. LiteComm-TP has
not been tested in environments in which other software, most
significantly TSR (terminate and stay resident) modules exist. Some
TSR programs that "steal" interrupts for their own purposes present
an unfavorable environment to other programs that rely on the
interrupt structure of the computer.

Should you experience erratic behavior with LiteComm-TP in a TSR-
type situation, try executing your application without the TSR
module being present. If the problems you have experienced
disappear, suspect the TSR module.

Conversely, LiteComm-TP provides an excellent vehicle for
supporting TSR programs that you may write. Since the package is
fully re-entrant, your only concern need be with those aspects of
TSR programs are of normal concern, e.g. the non-reentrant nature
of DOS. LiteComm-TP never uses DOS functions and may therefore be
safely used in a TSR environment.


5.4 USE WITH MULTITASKING ENVIRONMENTS
5.4 USE WITH MULTITASKING ENVIRONMENTS


Some users have made attempts, with varying degrees of success, at
using LiteComm in conjunction with multitasking environments such
as Quarterdesk's DesqView. Use of LiteComm in such an environment
is certain to be affected by the way in which the multitasking
monitor behaves with respect to interrupts.

While we recognize that DesqView has achieved a certain measure of
popularity among so-called power users, LiteComm was not explicitly
designed for such an environment, and its performance may suffer as
a result.





Page 22
Copyright (c) 1987, 88, 89 Information Technology, Ltd.


LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL



5.5 NOTES ON RING DETECTION
5.5 NOTES ON RING DETECTION


Several users have reported difficulty in consistently detecting a
ringing telephone by checking the state of the RI (Ring Indicator)
signal. The problem seems to be highly dependent on the type of
modem that is being used since this signal is provided by the
modem, NOT the serial port. If the duration of the signal is too
short, the program may 'miss' the signal as the modem toggles it on
and off. One workaround that has been used successfully is to
check the DeltaRI bit that can be obtained from the ModemStatus
function, rather that the RI bit itself. The DeltaRI bit will be
set when the RI bit comes on and again when the RI bit goes off.
This is the method we employ in the CheckForCall function.











































Page 23
Copyright (c) 1987, 88, 89 Information Technology, Ltd.


LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL





























































Page 24
Copyright (c) 1987, 88, 89 Information Technology, Ltd.


LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL









Chapter 6
Chapter 6

PACKAGE CONTENTS
PACKAGE CONTENTS


Your distribution diskette contains several files that are
important to you. All distribution diskettes, at a minimum, include
the following files in the diskette's root directory:
Table 6.1: Basic Diskette Contents
Table 6.1

READ.ME LATEST INFORMATION ABOUT
LITECOMM-TP

LTCOMM.ARC SHAREWARE VERSION AND
DOCUMENTATION FILES

LTUNITS.ARC FULLY FUNCTIONAL UNIT FILES

If you registered for the source code modules, the diskette
contains 2 additional source code archives.


LITECOMM-TP SOURCE CODE LTSRC.ARC

XMODEM ENGINE SOURCE CODE LTXMSRC.ARC


6.1 INSTALLATION INSTRUCTIONS
6.1 INSTALLATION INSTRUCTIONS


In the following discussion, we assume that your regular unit files
__ ___ _________ ___________ __ ______ ____ ____ _______ ____ _____
are contained in a directory called \TP.
___ _________ __ _ _________ ______ \TP_
___
To install the unit files used with LiteComm-TP, perform the
following steps:

1. CD \TP

2. ARC E A:LTUNITS

Since Turbo PASCAL permits you the flexibility of having a separate
subdirectory for units, you should execute the above instructions
in whatever directory you use for units.

If you are installing only the units, this completes the
installation procedure. If you have registered for the package's
source code, we recommend that you create a separate subdirectory.
The example below assumes that you will use a directory named COMM




Page 25
Copyright (c) 1987, 88, 89 Information Technology, Ltd.


LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL



to hold the LiteComm-TP and XModem source code modules. To install
the LiteComm-TP source code, do the following:

1. MD \COMM

2. CD \COMM

3. ARC E A:LTSRC *.*

4. ARC E A:LTXMSRC *.*

We strongly urge that you use the recommended approach in handling
the source code to avoid naming conflicts that might arise.












































Page 26
Copyright (c) 1987, 88, 89 Information Technology, Ltd.


LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL









Chapter 7
Chapter 7

PROCEDURE AND FUNCTION REFERENCE
PROCEDURE AND FUNCTION REFERENCE


In the following pages, we provide the detailed information about
each of the available LiteComm-TP ToolBox functions and procedures.
Each definition includes, at a minimum, a summary of how the
function or procedure is referenced, in which unit the function or
procedure is found, a description of what the function or procedure
does, and an indication of those values, if any, that might be
returned.

Where appropriate, we include additional documentation about the
function. Some definitions include examples, in the sense of code
fragments illustrating the function's usage. More importantly,
some definitions include additional notes and warnings as well as
references to other functions within the package.

We have made every effort to insure that the documentation of the
functions is complete and accurate. The style and manner of the
documentation assumes that the reader is thoroughly familiar with
the elements of PASCAL syntax and common conventions.


7.1 UNIT USAGE
7.1 UNIT USAGE


To assist you in developing your own applications, you will need to
know the following information.

Unit Uses

LctKrnl DOS
LctSupp DOS, LctKrnl
LctHayes DOS, LctSupp
LctBBs DOS, CRT, LctKrnl, LctSupp
LTXMKrnl DOS, LctSupp
LTXModem DOS, LctSupp, LTXMKrnl












Page 27
Copyright (c) 1987, 88, 89 Information Technology, Ltd.


LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL









PortChange function
PortChange function


UNIT LctKrnl
UNIT

FUNCTION Changes one or more of the critical parameters for
FUNCTION
port COM3 or COM4.

DECLARATION PortChange(CPort:integer; NewBase:word; NewIrq,
DECLARATION
NewVector:byte)

RESULT TYPE boolean
RESULT TYPE

REMARKS This function must be used before the port is
REMARKS
opened to be effective. To leave any of the
parameters at its default value, make the
corresponding entry 0. Note that vector is a vector
number, not an address or pointer.

The irq parameter should not be taken to be the irq
(interrupt request number), but rather the irq
mask. For example, the correct value for irq4 is
NOT 4, but a byte in which bit 4, using INTEL's bit
numbering, is set to a value of 1. Thus, to use irq
priority 4 as the irq for either COM3 or COM4, you
would specify $10 as the value of irq when calling
PortChange.

If you intend to change the default irq settings,
you MUST also make a corresponding change to the
vector number. See the preceding section about
using COM3 and COM4 for additional details. Failure
to follow this rule may make the port appear to be
nonfunctional.

The PortChange function does NOT check to determine
that you have provided both an IRQ mask AND a new
vector number.
PortChange returns a value of TRUE if the change
was successful, false otherwise.

EXAMPLE Var
EXAMPLE
Newbase : word;
Newirq : byte;
NewVector : byte;
Begin
Newbase := $03E8;
Newirq := $10;



Page 28
Copyright (c) 1987, 88, 89 Information Technology, Ltd.


LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL



NewVector := $0C;

if PortChange(3, Newbase, Newirq, NewVector) then
Writeln('Port 3 Changed')
else
Writeln('Error changing Port 3');
end;






CommOpen function
CommOpen function


UNIT LctKrnl
UNIT

FUNCTION Prepares the specified port for use by the other
FUNCTION
functions

DECLARATION CommOpen(CPort, Baud:integer; Parity:char;
DECLARATION
Databits, Stopbits, InSize, OutSize:integer;
RaiseMdmCtl:BOOLEAN)


RESULT TYPE boolean
RESULT TYPE

REMARKS Opens the specified port for use and attaches an
REMARKS
interrupt handler to DOS for the port. The function
allocates buffers for input and output of the
specified sizes, and sets the port to the
parameters specified. The minimum value for InSize
is 128; the minimum size for OutSize is 64. A port
opened in this manner must be closed using
CommClose before program termination to avoid the
possibility of a system crash.

CommOpen sets aside an additional 512 bytes per
open port. This additional memory is used as the
stack for the port's interrupt handler while
interrupts are being processed. This approach help
avoid the possibility of stack overflows that might
occur under some conditions.

CommOpen installs an exit procedure to protect DOS
from problems that might arise if a program using
LiteComm fails. However, we recommend that you
always close a port opened with CommOpen by calling
CommClose explicitly in your program to gain
maximum control over the port.

The parameters passed to the function are discrete
values, and must be drawn from the following lists:




Page 29
Copyright (c) 1987, 88, 89 Information Technology, Ltd.


LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL



Baud any value that your communication
Baud
equipment, e.g. your modem, will
support.

Parity E, O, N, M, S
Parity
E - Even
O - Odd
N - None
M - Mark
S - Space

Databits 5, 6, 7, 8
Databits

StopBits 1, 2
StopBits


If RaiseMdmCtl has a value of TRUE, CommOpen will
automatically raise the handshaking signals DTR and
RTS. If RaiseMdmCtl has a value of FALSE, the
programmer must raise these signals by calling
SetModemSignals. In general, use the second form
to gain full control over the handshaking signals
if needed, use the first form in those cases where
the control of these two signals is noncritical.

A return of TRUE indicates the port has been
successfully opened and is ready for use. A return
of FALSE indicates an error occurred, either as the
result of an invalid parameter, or insufficient
heap space available to allocate the buffers and
control structures for the port.

EXAMPLE Var
EXAMPLE
Baud, Databits, Stopbits : integer;
Parity : char;
Insize, Outsize : integer;

begin
Baud := 2400;
Parity := 'E';
Databits := 7;
Stopbits := 1;
Insize := 256;
Outsize := 256;

if CommOpen(1, Baud, Parity, Databits, Stopbits,
Insize, Outsize, TRUE) then
Writeln('COM1 available for use')
else
Writeln('Error opening COM1');

The equivalent code to the above is shown below





Page 30
Copyright (c) 1987, 88, 89 Information Technology, Ltd.


LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL



if CommOpen(1, Baud, Parity, Databits, Stopbits,
Insize, Outsize, FALSE) then
Writeln('COM1 is now open')
else
Writeln('Error opening COM1');
if SetModemSignals(1, (DTR OR RTS)) then
Writeln('Port is ready to transmit')
else
Writeln('Unable to set modem signals');

SEE ALSO SetModemSignals
SEE ALSO






CommClose procedure
CommClose procedure


UNIT LctKrnl
UNIT

FUNCTION Closes a port that has been opened by the CommOpen
FUNCTION
function

DECLARATION CommClose(CPort:integer; DropMdmCtl:BOOLEAN)
DECLARATION

REMARKS This function is the companion to CommOpen and, in
REMARKS
effect, performs the opposite action. CommClose
detaches the kernel interrupt handler from the
port, and reconnects the previous interrupt
handler. CommClose also release dynamically
allocated memory used for buffering and control
structures. If DropMdmCtl has a value of TRUE, the
port is closed absolutely; both the DTR and RTS
signals are dropped. If DropMdmCtl has a value of
FALSE, the port is closed conditionally and both
DTR and RTS are left in their current state.

Since CommOpen installs an exit procedure, you are
not required to explicitly close an open port.
However, if you do not use an explicit close, you
will lose control over the handling of DTR and RTS.
The built-in exit procedure always uses the
absolute form of the close.












Page 31
Copyright (c) 1987, 88, 89 Information Technology, Ltd.


LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL









CommSetup function
CommSetup function


UNIT LctKrnl
UNIT

FUNCTION Provides the capability of changing the parameters
FUNCTION
for an open port, without breaking the connection
or closing the port.

DECLARATION CommSetup(CPort, Baud:integer; Parity:char;
DECLARATION
Databits, Stopbits:integer)

RESULT TYPE boolean
RESULT TYPE

REMARKS The CommSetup function is a subset of the CommOpen
REMARKS
function and the remarks made in the description of
CommOpen apply. This function is useful if you wish
to change the basic communication parameters of the
specified port that has already been opened without
CommClose'ing the port and breaking the connection.

SEE ALSO CommOpen
SEE ALSO






BytesInInput function
BytesInInput function


UNIT LctSupp
UNIT

FUNCTION Returns the number of characters currently
FUNCTION
available in the input buffer (BytesInInput) or the
number of untransmitted characters in the output
buffer (ByteInOutput).

DECLARATION BytesInInput(CPort:integer)
DECLARATION
BytesInOutput(CPort:integer)

RESULT TYPE integer
RESULT TYPE

REMARKS May be used to determine the number of characters
REMARKS
currently in the input (BytesInInput) or output
(BytesInOutput) buffers for the port. In the event
of an error (bad port), a value of -1 is returned.




Page 32
Copyright (c) 1987, 88, 89 Information Technology, Ltd.


LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL









ModemStatus function
ModemStatus function


UNIT LctKrnl
UNIT

FUNCTION Returns the last know status of the modem control
FUNCTION
lines for the specified port.

DECLARATION ModemStatus(CPort:integer)
DECLARATION

RESULT TYPE byte
RESULT TYPE

REMARKS Use this function to determine the last known state
REMARKS
of the modem-supplied handshake signals. These may
be tested using the values included in the unit,
using PASCAL's bitwise AND operator.

The byte value returned can be viewed as consisting
of two sub-fields, the current signal state (found
in bits 4-7 of the byte), and the signal
change(DELTA) indicators(found in the bits 0-3 of
the byte). ModemStatus always returns the current
state of the signals in bits 4-7. Bits 0-3 will
reflect which, if any, of the signals has changed.

Whenever this function is called, both subfields
are returned, and represent the current state of
the individual signals. The DELTA settings may be
all reset, if no signals have changed since the
last call to the function. The signals which are
tracked are CTS, DSR, RI, and DCD.

To determine which signals, if any, have changed
use the DeltaXXX bits returned. For example, if CTS
has changed, the DeltaCTS bit will be set. The
actual CTS value (on or off) will be found in the
CTS bit of the returned byte.

In the event of an error, a byte of $00 is
returned.

HINT Detecting a ringing phone (using the RI signal) can
HINT
be tricky and timing dependent. One nearly
foolproof method that we have used is to examine
the DeltaRI value, not the RI value. The DeltaRI
value is set and reset as the telephone starts and
stops ringing. The RI value is set and cleared
independently, and you may miss the fact that the



Page 33
Copyright (c) 1987, 88, 89 Information Technology, Ltd.


LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL



phone is ringing if you don't examine the value at
the right time.

EXAMPLE Var
EXAMPLE
CStat : byte;

begin
CStat := ModemStatus(1);
if CStat and DeltaDCD = DeltaDCD then
if CStat and DCD <> DCD then
Writeln('Remote is off-line, carrier lost');






BreakRecd function
BreakRecd function


UNIT LctKrnl
UNIT

FUNCTION Returns a value of true if a BREAK signal has been
FUNCTION
received from the serial port since that last call
to the function.

DECLARATION BreakRecd(CPort:integer);
DECLARATION

RESULT TYPE boolean;
RESULT TYPE

REMARKS This function returns a value of TRUE if a BREAK
REMARKS
character has been received since the last call to
the function.

EXAMPLE if BreakRecd(2) then
EXAMPLE
Writeln('Break Signal detected on Port 2');






ErrorStatus function
ErrorStatus function


UNIT LctKrnl
UNIT

FUNCTION Return the last known error status for the
FUNCTION
specified port.

DECLARATION ErrorStatus(CPort:integer)
DECLARATION

RESULT TYPE byte
RESULT TYPE




Page 34
Copyright (c) 1987, 88, 89 Information Technology, Ltd.


LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL



REMARKS Returns the last known state of the serial port's
REMARKS
error status bits, encoded in a byte. These may be
tested using the constants defined in the unit in
conjunction with PASCAL's bitwise AND operator.
The applicable values that may be checked are
OverRun, BadParity, and, BadFrame.


1. OverRun - failure to fetch a character from
the port before the next character was
received. Usually caused by a problem in the
interrupt handler.

2. BadParity - One or more characters were
received in which the parity of the
character(s) did not match the current
parity setting of the port. Can be caused
by line noise (electrical interference),
poor connections, or a variety of other
reasons.

3. BadFrame - A framing error has occurred. A
character was received that had too few or
(more likely) too many bits. Usually caused
bye line noise.


Break detection, i.e. the receipt of a BREAK
character, is handled by the BreakRecd
function(qv). In the event of an error, a byte of
$00 is returned.

Once the error status bits have been read in this
fashion, they are reset to $00, and will remain so
until the next error occurs. Since this process
happens asynchronously, it is not possible for your
application to determine which character created
the error, only that the error occurred.

EXAMPLE Var
EXAMPLE
EStat : byte;

begin
EStat := ErrorStatus(2);
if EStat and OverRun = OverRun then
Writeln('Receive Character Over Run');











Page 35
Copyright (c) 1987, 88, 89 Information Technology, Ltd.


LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL









SetModemSignals function
SetModemSignals function


UNIT LctKrnl
UNIT

FUNCTION Allows the programmer to set the individual modem
FUNCTION
control lines for the specified port.

DECLARATION SetModemSignals(CPort:integer; NewSet:byte)
DECLARATION

RESULT TYPE boolean
RESULT TYPE

REMARKS Set one or more of the modem control signals.
REMARKS
Because of the need to always have OUT2 set for
interrupt support, the function always provides the
correct setting for this bit.

The value of NewSet is bitwise OR'ed with the
current set of values to produce a new modem
control setting. The value of NewSet DOES NOT
replace the current values. Use the constants
supplied in the unit to obtain the correct values.
These include DTR and RTS.

Many applications will not require this, and its
companion, functions, if the permit CommOpen to
raise the DTR and RTS signals. More sophisticated
applications may be required to control either or
both of the signals to provide handshaking with an
external device.

EXAMPLE begin
EXAMPLE
(* raise both DTR and RTS *)
if SetModemSignals(1, (DTR OR RTS)) then
Writeln('Port is ready to transmit')
else
Writeln('Unable to set modem signals');

SEE ALSO ClearModemSignals, FlipModemSignals
SEE ALSO












Page 36
Copyright (c) 1987, 88, 89 Information Technology, Ltd.


LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL









ClearModemSignals function
ClearModemSignals function


UNIT LctKrnl
UNIT

FUNCTION Allows the programmer to clear (reset) the
FUNCTION
individual modem control lines for the specified
port.

DECLARATION ClearModemSignals(CPort:integer; NewSet:byte)
DECLARATION

RESULT TYPE boolean
RESULT TYPE

REMARKS Clears (resets) one or more of the modem control
REMARKS
signals. Because of the need to always have OUT2
set for interrupt support, the function always
provides the correct setting for this bit.

The compliment of NewSet is bitwise AND'ed with the
current set of values to produce a new modem
control setting. The value of NewSet DOES NOT
replace the current values. Use the constants
supplied in the unit to obtain the correct values.
These include DTR and RTS.

EXAMPLE begin
EXAMPLE
if ClearModemSignals(1, RTS) then
Writeln('RTS for Port 1 has been dropped')
else
Writeln('Unable to clear RTS');

SEE ALSO SetModemSignals, FlipModemSignals
SEE ALSO






FlipModemSignals function
FlipModemSignals function


UNIT LctKrnl
UNIT

FUNCTION Allows the programmer to compliment(toggle) the
FUNCTION
individual modem control lines for the specified
port. This function only has value if you are
attempting to implement some form of hardware
handshaking with another device. The absolute form



Page 37
Copyright (c) 1987, 88, 89 Information Technology, Ltd.


LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL



of CommClose will automatically lower both RTS AND
DTR, which is generally adequate for many
applications.

DECLARATION FlipModemSignals(CPort:integer; NewSet:byte)
DECLARATION

RESULT TYPE boolean
RESULT TYPE

REMARKS Complements(toggles) one or more of the modem
REMARKS
control signals. Because of the need to always have
OUT2 set for interrupt support, the function always
provides the correct setting for this bit.

The value of NewSet is bitwise XOR'ed with the
current set of values to produce a new modem
control setting. The value of NewSet DOES NOT
replace the current values. Use the constants
supplied in the unit to obtain the correct values.
These include DTR and RTS.

EXAMPLE begin
EXAMPLE
(*
** change the RTS modem control signal to its
other
** state (if raised, lower it, if lowered raise
it)
*)
if FlipModemSignals(1, RTS) then
Writeln('RTS for Port 1 has been changed')
else
Writeln('Unable to change RTS');

SEE ALSO SetModemSignals, ClearModemSignals
SEE ALSO






EnableXon function
EnableXon function


UNIT LctKrnl
UNIT

FUNCTION Enable or disable the semiautomatic flow control
FUNCTION
features of LiteComm-TP

DECLARATION EnableXon(CPort:integer; XonFlag:boolean)
DECLARATION

RESULT TYPE boolean;
RESULT TYPE

REMARKS If XonFlag is TRUE, turns on semiautomatic XON-XOFF
REMARKS
flow control function. If XonFlag is FALSE (the




Page 38
Copyright (c) 1987, 88, 89 Information Technology, Ltd.


LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL



default setting), automatic flow control is
disabled.
When enabled, the kernel will automatically
transmit an XOFF if and when the input buffer is
approximately 2/3 full and will automatically
recognize an XOFF sent by the other device. If the
other device transmits an XOFF, the kernel will
refuse to send any characters until the condition
is cleared, either by receipt of an XON, by calling
the XOffRecd function, or by disabling XON-XOFF
altogether.

The XOFF recognition is implemented in the kernel.
As a result, the transmit buffer will continue to
accept input from your program until the buffer
fills completely, even though the information will
not be sent. Once the matching XON is received,
the contents of the transmit buffer will be sent
rapidly to the other device. It is possible that
the rate with which characters are sent when this
occurs may cause problems for the other device,
depending on its ability to handle the data flow.

If the kernel has sent an XOFF, it is the
programmer's responsibility to transmit XON when
conditions warrant. Use the XoffSent function to
tell if an automatic XOFF has been sent by the
kernel.

If you intended to implement a protocol that might
include the XON-XOFF characters, be sure to disable
the automatic flow control. Failure to do so may
result in a system hang.

SEE ALSO XoffRecd, XoffRecd
SEE ALSO






XoffRecd function
XoffRecd function


UNIT LctKrnl
UNIT

FUNCTION Reports whether or not the kernel has detected an
FUNCTION
XOFF from the other device

DECLARATION XoffRecd(CPort:integer)
DECLARATION

RESULT TYPE boolean
RESULT TYPE





Page 39
Copyright (c) 1987, 88, 89 Information Technology, Ltd.


LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL



REMARKS Returns TRUE if an XOFF has been received, FALSE
REMARKS
otherwise. If an XOFF has been received, the port's
internal flag will be reset, and transmission to
the other device will be permitted. If an XON is
received from the other, the port's flag will also
be reset, permitting further transmissions to
occur.

If you use flow control and the other device never
sends an XON after sending an XOFF, a system hang
is possible. You may wish to call XoffRecd
periodically to test for this condition, and to
cause your port to resume transmitting data.

SEE ALSO EnableXon, XoffSent
SEE ALSO






XoffSent function
XoffSent function


UNIT LctKrnl
UNIT

FUNCTION Reports whether or not the kernel has automatically
FUNCTION
sent an XOFF to the other device.

DECLARATION XoffSent(CPort:integer)
DECLARATION

RESULT TYPE boolean
RESULT TYPE

REMARKS Returns TRUE if the LiteComm kernel has sent an
REMARKS
XOFF to the other device, FALSE otherwise. If an
XOFF has been sent, the port's flag will be reset.
You must send an XON character to the other device
to permit transmissions to proceed.

SEE ALSO EnableXon, XoffRecd
SEE ALSO






LctGet function
LctGet function


UNIT LctSupp
UNIT

FUNCTION Returns an available character from the ports input
FUNCTION
buffer.




Page 40
Copyright (c) 1987, 88, 89 Information Technology, Ltd.


LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL




DECLARATION LctGet(CPort:integer; var Ch:byte)
DECLARATION

RESULT TYPE boolean
RESULT TYPE

REMARKS Places the next available character in the input
REMARKS
buffer for the port in the variable Ch. The
function returns a value of TRUE if there is a
character available, FALSE if there is no character
available or on an error. The contents of Ch are
undefined when the return is FALSE.

If you specified other than N (No Parity) when the
port was opened, you may have to reset (make zero)
the parity bit before you use the character.

EXAMPLE BEGIN
EXAMPLE
IF LctGet(CPort, Ch) THEN
Ch := Ch AND $7F; (* Reset the Parity Bit
*)






LctPeek function
LctPeek function


UNIT LctSupp
UNIT

FUNCTION Permits you to look at the next character in the
FUNCTION
ports input buffer without removing if from the
buffer.

DECLARATION LctPeek(CPort:integer; var Ch:byte)
DECLARATION

RESULT TYPE boolean
RESULT TYPE

REMARKS Places the next available character in the input
REMARKS
buffer for the specified port into the Ch variable,
but does not remove the character from the buffer.
This allows the application to look-ahead by one
look-ahead
__________
character in a nondestructive fashion. Returns
FALSE if the port is not active, or if there are no
characters in the port's buffer, TRUE otherwise.
The contents of Ch are undefined when the result is
FALSE.

The comment made regarding parity setting and the
use of the LctGet function also applies to LctPeek.

SEE ALSO LctGet
SEE ALSO





Page 41
Copyright (c) 1987, 88, 89 Information Technology, Ltd.


LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL









LctPut function
LctPut function


UNIT LctSupp
UNIT

FUNCTION Places a character in the port's transmit buffer to
FUNCTION
be sent when the port is ready.

DECLARATION LctPut(CPort:integer; Ch:byte)
DECLARATION

RESULT TYPE boolean
RESULT TYPE

REMARKS Returns TRUE if successful. Note that this does not
REMARKS
guarantee that the character has been sent, only
that no errors were detected, and there was space
in the transmit buffer to hold the character.
Returns FALSE if the port is not active, or if
there no room in the port's buffer.

Characters are sent from the transmit buffer when
the system has the time to send them, assuming that
all conditions for transmission are satisfied






GetStream function
GetStream function


UNIT LctSupp
UNIT

FUNCTION Gets a stream of N characters from the port's input
FUNCTION
buffer

DECLARATION GetStream(CPort:integer; var Buff; BCnt:integer)
DECLARATION

RESULT TYPE integer
RESULT TYPE

REMARKS Reads a stream of, at most, BCnt characters from
REMARKS
the serial port's input buffer into the Buff array.
Returns the count of characters actually
transferred, or -1 if an error occurs.

NOTE that Buff is an array of characters or bytes,
not a string, although you may treat a string
variable like an array, as shown below. The



Page 42
Copyright (c) 1987, 88, 89 Information Technology, Ltd.


LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL



comments made about parity in the LctGet function
description also apply the the GetStream function.

EXAMPLE Type
EXAMPLE
MaxStr = string[256];

Var
StrBuff : MaxStr;
RecdLen : integer;

begin
RecdLen := GetStream(2, StrBuff[1], 256);
if RecdLen 0 then { error or no char }
StrBuff[0] := 0
else
StrBuff[0] := Chr(RecdLen);
end;

SEE ALSO LctGet
SEE ALSO






PutStream function
PutStream function


UNIT LctSupp
UNIT

FUNCTION Places a stream of, at most, N characters in the
FUNCTION
port's transmit buffer.

DECLARATION PutStream(CPort:integer; var Buff; BCnt:integer)
DECLARATION

RESULT TYPE integer
RESULT TYPE

REMARKS Buff is an array of character or byte, not a
REMARKS
string, although it is possible to specify a string
variable, using the same approach as outlined for
the GetStream function. PutStream returns the
number of characters actually placed into the
buffer. Note that this does not guarantee that the
characters have been sent. A value of 0 will be
returned if any error occurs, or if there no room
in the port's buffer.

EXAMPLE VAR
EXAMPLE
Buff : ARRAY[1..128] OF BYTE;
LeftToSend : INTEGER;
ReallySent : INTEGER;
StartPos : INTEGER;

BEGIN



Page 43
Copyright (c) 1987, 88, 89 Information Technology, Ltd.


LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL



LeftToSend := 128; (* set up for
Full Length *)
ReallySent := 0;
StartPos := 1;
WHILE LeftToSend > 0 DO
BEGIN
ReallySent := PutStream(CPort, Buff[StartPos],
LeftToSend);
IF ReallySent > 0 THEN
BEGIN
StartPos := StartPos + ReallySent; (* adjust
start byte *)
LeftToSend := LeftToSend - ReallySent;
END;
END (* while *);

SEE ALSO PutStream
SEE ALSO






Buffer Flushing functions
Buffer Flushing functions


UNIT LctSupp
UNIT

FUNCTION Provides several high level buffer management
FUNCTION
functions to control the contents of the port's
transmit and receive buffers

DECLARATION function PurgeTxBuff(CPort:integer)
DECLARATION

function PurgeRxBuff(CPort:integer)

procedure FlushUntilMatch(CPort:integer; Ch:byte)

procedure FlushNBytes(CPort:integer; N:integer);

RESULT TYPE boolean for PurgeTxBuff, PurgeRxBuff
RESULT TYPE

REMARKS The PurgeRxBuff and PurgeTxBuff functions remove
REMARKS
all characters from the port's receive and transmit
buffers respectively and discard them;
untransmitted characters in the transmit buffer are
NEVER sent; unprocessed characters in the receive
buffer are lost. Both functions return a value of
TRUE if no errors were encountered, FALSE
otherwise. An empty buffer is NOT considered an
error.

The FlushUntilMatch procedure will continually
dispose of received characters until the character



Page 44
Copyright (c) 1987, 88, 89 Information Technology, Ltd.


LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL



Ch is received. The procedure will return when the
character Ch is detected, or when there are no more
characters in the port's input buffer.
The FlushNBytes procedure removes, at most, N
characters from the port's receive buffer.






SendBreak function
SendBreak function


UNIT LctKrnl
UNIT

FUNCTION Send a true Break signal
FUNCTION

DECLARATION SendBreak(CPort:integer)
DECLARATION

RESULT TYPE boolean
RESULT TYPE

REMARKS SendBreak generates a BREAK signal using a
REMARKS
particular characteristic of the 8250 UART to
generate an accurate BREAK at any baud rate.
BREAKs generated in this manner are timed based
upon the baud rate at which the 8250 is currently
initialized. This function may or may not work
correctly with other than the actual 8250 UART.

Returns TRUE if successful. Returns FALSE if an
error is detected.






CheckEvent Function
CheckEvent Function


UNIT LctBBS
UNIT

FUNCTION Returns a value of TRUE is the Event Timer
FUNCTION
specified in the function call has not expired.
Returns a value of FALSE if the specified Event
Timer has expired. Do not attempt to use
CheckEvent against a variable that was not
initialized bye NewEvent. The results are
unpredictable, and may result in an apparent system
hang.

DECLARATION CheckEvent(EventVal : Event);
DECLARATION




Page 45
Copyright (c) 1987, 88, 89 Information Technology, Ltd.


LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL



RESULT TYPE boolean;
RESULT TYPE

REMARKS The event timer specified by EventVal must have
REMARKS
been set using the NewEvent function

SEE ALSO NewEvent
SEE ALSO






NewEvent Function
NewEvent Function


UNIT LctBBS
UNIT

FUNCTION Initializes an event timer to a value suitable for
FUNCTION
use with CheckEvent. The event timer created in
this fashion can time events up to 32767 seconds in
duration.

DECLARATION NewEvent(Seconds : integer);
DECLARATION

RESULT TYPE Event;
RESULT TYPE

REMARKS When used in conjunction with CheckEvent, the event
REMARKS
timer can be used to time events that span days,
months or years. Actually, it should be termed a
timeout timer, since CheckEvent checks to see if
the period specified by Seconds has elapsed.

EXAMPLE var
EXAMPLE
InputEvent : Event;
Ch : byte;

begin
InputEvent := NewEvent(15);
while CheckEvent(InputEvent) do
if LctGet(Port, Ch) then
exit;
WriteLn('No Input Received in 15 seconds');
end;






CheckForCall Function
CheckForCall Function


UNIT LctBBS
UNIT




Page 46
Copyright (c) 1987, 88, 89 Information Technology, Ltd.


LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL



FUNCTION 'Listens' to the specified port to see if the
FUNCTION
telephone is ringing. If the phone is ringing,
waits for up to 30 seconds for a successful
connection to be established.

DECLARATION CheckForCall(CPort : integer);
DECLARATION

RESULT TYPE integer;
RESULT TYPE

REMARKS This function will return a value of -1 if the
REMARKS
phone is not ringing, or if the modem fails to
respond to the call within the 30 second period
allowed. In all other cases the function returns
the result code that was returned by the modem
itself. It is the programmer's responsibility to
correctly recognize and react to the various codes.
In the case of a failure of the modem to respond,
this function will automatically attempt to
disconnect and reset the modem.

The function assumes that the modem has been set up
to use numeric result codes, and that the S0
register (number of rings before answering) has not
been set to zero. The function ResetModem sets the
correct values to match these assumptions. CAUTION
- do not attempt to use this function on ports not
connected to a modem. The function examines the
modem control status lines and may behave in a
unpredictable fashion if not connected to a modem.

EXAMPLE var
EXAMPLE
ModemResult : integer;

begin
repeat
ModemResult := CheckForCall(CPort);
if ModemResult = -1 then
Delay(1000); (* settling time*)
until ModemResult <> -1;
Writeln('Modem reply to call was ',
ModemResult:2);
end;

SEE ALSO Disconnect, ResetModem
SEE ALSO






Disconnect Procedure
Disconnect Procedure


UNIT LctBBS
UNIT



Page 47
Copyright (c) 1987, 88, 89 Information Technology, Ltd.


LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL



FUNCTION Causes the modem to disconnect from the caller.
FUNCTION

DECLARATION Disconnect(CPort : integer);
DECLARATION

REMARKS Disconnects the modem by dropping the DTR (Data
REMARKS
Terminal Ready) modem status signal for 1 second.
This action will cause most modems to drop carrier
and force the phone on-hook. Please not that if
the modem has been optioned with DTR permanently
set on or ignored, this procedure will have no
effect.






ResetModem Function
ResetModem Function


UNIT LctBBS
UNIT

FUNCTION Returns the modem to a known set of parameters,
FUNCTION
suitable for use with the related functions in this
unit. See the typed constants MODEMSET0 through
MODEMSET2 in the interface portion of the unit.

DECLARATION ResetModem(CPort, : integer);
DECLARATION

RESULT TYPE integer;
RESULT TYPE

REMARKS The modem is reset to a known state, including, but
REMARKS
not limited to 1) answer on the first ring, 2)
numeric result codes, 3) extended code set. The
function returns the result of the reset operation
(a modem response code) or -1 if the modem fails to
respond. This function and related functions are
suitable for use only with HAYES-type modems. It
is the programmer's responsibility to interpret the
result code returned.

SEE ALSO GetModemReply
SEE ALSO






GetModemReply Function
GetModemReply Function


UNIT LctBBS
UNIT





Page 48
Copyright (c) 1987, 88, 89 Information Technology, Ltd.


LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL



FUNCTION Returns the modem's response to the last set of
FUNCTION
instructions that were issued to the modem, in
numeric form.

DECLARATION GetModemReply(CPort : integer);
DECLARATION

RESULT TYPE integer;
RESULT TYPE

REMARKS This function expects the modem to be returning
REMARKS
numeric result codes (set ResetModem) of up to 2
digits. The function will react to 2 digits
returned or the first returned, whichever
occurs first within a 1 second timeout period. In
the case that the modem does not respond in the
timeout period, the function returns a value of -1.
In no case does the function attempt to evaluate
the response...this is left to the programmer.

SEE ALSO ResetModem.
SEE ALSO






HAYES MODEM FUNCTIONS
HAYES MODEM FUNCTIONS


UNIT LctHayes
UNIT

FUNCTION Provides support for various aspects of modems the
FUNCTION
support the Hayes(Tm) command set.

DECLARATIONS const
DECLARATIONS
NUMRES = 0 { numeric result codes}
WRDRES = 1 { word result codes }
SPKOFF = 0 { speaker off }
SPKON = 1 { speaker on until CD }
SPKSPC = 2 { speaker always on }
ONHK = 0 { go on-hook (hang up) }
OFFHK = 1 { go off-hook (lift receiver) }
OFFHKS = 2 { go off-hook, don't close relay }
BASIC = 0 { basic result set }
EXSET1 = 1 { extended results, set 1 }
EXSET3 = 2 { extended results, set 3 }
EXSET4 = 3 { extended results, set 4 }

type
TelNumStr = string[20];

procedure SetType(NType : byte)

procedure SetSet(NSet : byte)




Page 49
Copyright (c) 1987, 88, 89 Information Technology, Ltd.


LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL



function RetType : byte

function RetSet : byte

function ModemCodesOn(CPort : integer):boolean

function ModemCodesOff(CPort : integer):boolean

function ModemWordResponse(CPort : integer):boolean

function ModemDigitResponse(CPort :
integer):boolean

function RepeatModemCommand(CPort :
integer):boolean

function ModemSpeaker(CPort : integer; Mode :
byte):boolean

function SetModemRegister(CPort, Reg, NValue :
integer) : boolean

function GetModemRegister(CPort, Reg, NValue :
integer) : boolean

function ModemHalfDuplex(CPort : integer) : boolean

function ModemFullDuplex(CPort : integer) : boolean

function ModemEchoCmd(CPort : integer) : boolean

function ModemNoEchoCmd(CPort : integer) : boolean

function ModemHookMode(CPort : integer; HMode :
byte) : boolean

function ModemCarrierOn(CPort : integer) : boolean

function ModemCarrierOff(CPort : integer) : boolean

function ModemWordResponse(CPort : integer):boolean

function ModemDigitResponse(CPort :
integer):boolean

function RepeatModemCommand(CPort :
integer):boolean

function ModemSpeaker(CPort : integer; Mode :
byte):boolean

function SetModemRegister(CPort, Reg, NValue :
integer) : boolean




Page 50
Copyright (c) 1987, 88, 89 Information Technology, Ltd.


LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL



function GetModemRegister(CPort, Reg, NValue :
integer) : boolean

function ModemHalfDuplex(CPort : integer) : boolean

function ModemFullDuplex(CPort : integer) : boolean

function ModemEchoCmd(CPort : integer) : boolean

function ModemNoEchoCmd(CPort : integer) : boolean

function ModemHookMode(CPort : integer; HMode :
byte) : boolean

function ModemCarrierOn(CPort : integer) : boolean

function ModemCarrierOff(CPort : integer) : boolean

function ModemCodeSet(CPort : integer; NewSet :
byte) : boolean

function ModemPulse(CPort : integer) : boolean

function ModemTone(CPort : integer) : boolean

function ModemDial(CPort : integer; TelNo :
TelNumStr) : boolean

REMARKS The ModemCodeSet function allows you to change the
REMARKS
set of codes that are returned by the modem when an
action is specified.

ModemDial instructs the modem to dial the number
contained in TelNo. Do not include the dialing
(ATD) prefix, or the trailing . These are
provided by the function. You may include non-
numeric characters as the contents of TelNo are not
checked. The dialing is done in the last known,
pulse or tone, mode. If you use the Modempulse or
ModemTone functions, then dialing will be done in
the mode that was last correctly enabled. If you
have not exercised these functions, then dialing
occurs in the modems default or power-up mode.

The ModemHalfDuplex and ModemFullDuplex functions
place the modem into local echo and remote echo
modes respectively.

The GetModemRegister function requests that the
modem return the current value of S-register Reg.
Reg must be in the range 0 to 13. Use the
GetStream, or similar function, to retrieve the
modem's response. Specifying a register outside the
0 to 13 range will cause a return of FALSE.



Page 51
Copyright (c) 1987, 88, 89 Information Technology, Ltd.


LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL




SetModemRegister is the companion to
GetModemRegister, with the same restrictions. Sets
the S-register Reg to the value contained in
NValue. If NValue contains -1, then the register is
reset to its default (power-up) value. The function
checks the value to be certain that it is within
the limits specified for the particular register,
and returns a value of FALSE if the value is
outside the predefined limits.

ModemCarrierOff enables modem carrier detect, but
disables the modems carrier signal. The
ModemCarrierOn companion enables both carrier
detect and the modems carrier signal. When
ModemCarrierOff is used the modem will receive data
but will be unable to send data.

The ModemNoEchoCmd and ModemEchoCmd functions
determine whether commands sent to the modem are
echoed back to the sending program. With echo
turned off, the modem will continue to accept
commands, but will not try to redisplay the
command's characters.

ModemHookMode allows you to control the current
status of the modem's telephone line connection.
See your modem's documentation and the above
constants for additional information.

The ModemRepeatCommand function instructs the modem
to repeat the last command sequence executed.
Generally, this function is of greatest value in
redialing numbers that are busy, although its use
is not restricted to that.

The way in which your modem responds to commands is
determined, in part, by the ModemWordResponse and
ModemDigitResponse functions. If you call
ModemWordResponse, then modem responses use the
English language response codes, e.g. CONNECT or
OK. Calling ModemDigitResponse instructs the modem
to respond with code numbers only from the
currently selected response set, see the
ModemCodeSet function above.

You may use the functions ModemCodesOn and
ModemCodesOff to specify whether you want your
modem to send back response codes when it receives
a command string. In a sense, these act as
companions to the EchoCmd functions above.






Page 52
Copyright (c) 1987, 88, 89 Information Technology, Ltd.


LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL



Use the ModemSpeaker function to control the
modem's internal speaker, if it has one. See the
above constants for the applicable codes.

The RetSet and RetType functions return,
respectively, the last known command set
(ModemCodeSet) and last known result type
(ModemWordResponse, ModemDigitResponse). The RetSet
and RetType functions are only of value when used
in conjunction with the companion functions.

GENERAL REMARKS Several considerations are in order if you intend
GENERAL REMARKS
to use the Hayes ToolBox functions.

1. You are responsible for checking the return
codes from the modem once you have given
modem a command. To make the task easier, we
suggest that you turn OFF command echo (so
that you don't have to worry about
separating commands from responses) and turn
ON numeric responses (to make the
interpretation of result codes easier and
faster).

2. Be sure that you allow adequate time
between commands for the modem to process
the command and respond. Failure to observe
this rule may result in commands being
misinterpreted or "lost". You can monitor
the number of characters in the receive
buffer to help you with the timing. Or
alternatively, check the response after each
command. The latter approach is more in line
with what we believe to be good programming
practice.

RETURN VALUES All functions return a value of FALSE if a port or
RETURN VALUES
other error is detected, TRUE otherwise.







Index
Index


8250 7, 14 B
B
8259 19 base port 9
baud rate 10
A BIOS 20
A
ASP 1 BIOS functions 21
BREAK 13, 34, 35, 45



Page 53
Copyright (c) 1987, 88, 89 Information Technology, Ltd.


LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL



buffers 14, 29 IRQ 20
irq 28
C IRQ0 20
C
character length 11 ISR 9
CheckForCall 23
COM3 19 L
L
COM4 19 look-ahead 41
look-ahead
__________
CommOpen 19
control structures 14 M
M
CTS 33 modem control 12
modem status 13
D ModemStatus 23
D
data overrun error 15
data path 7 O
O
Data Terminal Ready open function 14
See: DTR OUT2 12
____
DCD 33
DeltaCTS 33 P
P
DSR 33 parallel 7
DTR 12, 14, 31, 36, 37, parity 11
38, 48 parity error 15
poll 8
E PortChange 19
E
error status bits 35
Event Timer 45 R
R
expansion cards 20 Request To Send See:
____
RTS
F RI 23, 33
F
flow control 38 RTS 12, 15, 31, 36, 37,
framing error 15 38

H S
H S
handshake 33 S-register 51
handshaking 12, 13 serial port 7
HAYES 48 stream 42, 43
heap 14, 30
T
T
I TSR 22
I
interrupt 8
interrupt chaining 17, U
U
21 UART 7
interrupt enable flag
15 V
V
Interrupt Service vector numbers 20
Routine 9
interrupt vector 20 X
X
interrupt vectors 19 XOFF 39
XON 39









Page 54
Copyright (c) 1987, 88, 89 Information Technology, Ltd.












Contents
Contents



Chapter 1 OVERVIEW 1
1.1 FEATURES . . . . . . . . . . . . . . . . . . 1
1.2 THE SHAREWARE CONCEPT . . . . . . . . . . . 1

Chapter 2 LICENSE, WARRANTY AND REGISTRATION 3
2.1 LICENSE . . . . . . . . . . . . . . . . . . 3
2.2 WARRANTY . . . . . . . . . . . . . . . . . . 4
2.3 REGISTERING YOUR COPY . . . . . . . . . . . 4
2.4 NOTE . . . . . . . . . . . . . . . . . . . . 5

Chapter 3 Serial Port Fundamentals 7
3.1 The 8250 UART family . . . . . . . . . . . . 7
3.2 Purpose of the port . . . . . . . . . . . . 7
3.3 Internal Details . . . . . . . . . . . . . . 8
3.3.1 The Interrupt Connection . . . . . . . 8
3.3.2 The Programmable Port Registers . . . . 9
3.3.2.1 register 0 - transmit/receive . . 10
3.3.2.2 register 0 - baud rate selection . 10
3.3.2.3 register 1 - interrupt enable . . 10
3.3.2.4 register 1 - baud rate selection . 11
3.3.2.5 register 2 - interrupt
identification . . . . . . . . . . 11
3.3.2.6 register 3 - line control . . . . 11
3.3.2.7 register 4 - modem control . . . . 12
3.3.2.8 register 5 - line status . . . . . 12
3.3.2.9 register 6 - modem status . . . . 13
3.4 The LiteComm Connection . . . . . . . . . . 13
3.5 TOOLBOX NOTES AND WARNINGS . . . . . . . . . 14

Chapter 4 LITECOMM-TP HISTORY 17
4.1 VERSION 3.0 . . . . . . . . . . . . . . . . 17
4.2 NEW IN VERSION 5 . . . . . . . . . . . . . . 17

Chapter 5 BEYOND COM2 19
5.1 THE TOOLBOX METHODOLOGY . . . . . . . . . . 19
5.2 CAUTIONS . . . . . . . . . . . . . . . . . . 20
5.3 OTHER GENERAL NOTES AND WARNINGS . . . . . . 22
5.4 USE WITH MULTITASKING ENVIRONMENTS . . . . . 22
5.5 NOTES ON RING DETECTION . . . . . . . . . . 23

Chapter 6 PACKAGE CONTENTS 25
6.1 INSTALLATION INSTRUCTIONS . . . . . . . . . 25





i







Chapter 7 PROCEDURE AND FUNCTION REFERENCE 27
7.1 UNIT USAGE . . . . . . . . . . . . . . . . . 27

PortChange function 28

CommOpen function 29

CommClose procedure 31

CommSetup function 32

BytesInInput function 32

ModemStatus function 33

BreakRecd function 34

ErrorStatus function 34

SetModemSignals function 36

ClearModemSignals function 37

FlipModemSignals function 37

EnableXon function 38

XoffRecd function 39

XoffSent function 40

LctGet function 40

LctPeek function 41

LctPut function 42

GetStream function 42

PutStream function 43

Buffer Flushing functions 44

SendBreak function 45

CheckEvent Function 45

NewEvent Function 46

CheckForCall Function 46

Disconnect Procedure 47

ResetModem Function 48



ii







GetModemReply Function 48

HAYES MODEM FUNCTIONS 49

Index 54




















































iii
































































iv













Figures
Figures


Figure 3.1: Register 1 Bit Definitions . . . . . . . 10
Figure 3.2: Register 2 Bit Definitions . . . . . . . 11
Figure 3.3: Register 3 Bit Definitions . . . . . . . 12
Figure 3.4: Register 4 Bit Definitions . . . . . . . 12
Figure 3.5: Register 5 Bit Definitions . . . . . . . 13
Figure 3.6: Register 6 Bit Definitions . . . . . . . 13










































v
































































vi













Tables
Tables


Table 3.1: Possible Error Conditions . . . . . . . . 15
Table 5.1: COM3 and COM4 Default Settings . . . . . 19
Table 6.1: Basic Diskette Contents . . . . . . . . . 25













































vii


  3 Responses to “Category : Pascal Source Code
Archive   : LTCOMM50.ZIP
Filename : LCTP.PRN

  1. Very nice! Thank you for this wonderful archive. I wonder why I found it only now. Long live the BBS file archives!

  2. This is so awesome! 😀 I’d be cool if you could download an entire archive of this at once, though.

  3. But one thing that puzzles me is the “mtswslnkmcjklsdlsbdmMICROSOFT” string. There is an article about it here. It is definitely worth a read: http://www.os2museum.com/wp/mtswslnk/