Programmer 7500

home *** CD-ROM | disk | FTP | other *** search

/ Programmer 7500 / MAX_PROGRAMMERS.iso / PASCAL / LCOMMT.ZIP / LCTP.TXT < prev next >

Wrap

Text File | 1988-10-06 | 113.9 KB | 3,829 lines

OVERVIEW OVERVIEW ________ FEATURES 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. In its initial release, the LiteComm-TP ToolBox supports fully interrupt- driven and buffered communications support on COM1 thru 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. The introduction of version 4.0 of Turbo PASCAL<> has made it possible for use to extend the power and flexibility of the original LiteComm ToolBox(Tm) to Turbo PASCAL programmers. THE SHAREWARE CONCEPT 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, Ltd., is a member of, and supports the standards of, ASP, The Association of Shareware Professionals. Page 1 CopyRight (c) 1987,1988 Information Technology, Ltd. LITECOMM-TP (tm) TOOLBOX for Turbo-PASCAL LICENSE, WARRANTY AND REGISTRATION LICENSE, WARRANTY AND REGISTRATION __________________________________ LICENSE LICENSE _______ The LiteComm-TP ToolBox, is distributed as a shareware product. In its shareware form, support is limited to all COM ports, but only at sppeds of 1200 baud and below. To receive the units that support the extended features of LiteComm-TP and/or the source code for the product, register your copy today. See the registration form at the end of this manual. Information Technology, Ltd, grants to registered users a non-exclusive, 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 in 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. Further, you may charge a fee for providing such a copy, beyond a maximum $8.00 copying or duplication fee, without the express, written consent of Information Technology, Ltd, Page 2 CopyRight (c) 1987,1988 Information Technology, Ltd. LITECOMM-TP (tm) TOOLBOX for Turbo-PASCAL 4. 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. 5. 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. 6. You agree that any disputes arising from this license will be subject to the laws of the state of Rhode Island. 7. 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. 8. You acknowledge that the LiteComm-TP ToolBox, libraries, source code, and documentation are the copyrighted property of Information Technology, Ltd. 9. By your use of the LiteComm-TP ToolBox, you acknowledge that you have read, and understand the terms and conditions of this license. WARRANTY 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. Page 3 CopyRight (c) 1987,1988 Information Technology, Ltd. LITECOMM-TP (tm) TOOLBOX for Turbo-PASCAL REGISTERING YOUR COPY 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; on GEnie to I.TECH; and on DELPHI to RBMACE. We will respond to EMAIL on an as- available basis. 3.Helps to further the shareware concept. To register your copy, use the form at the end of this documentation. You may also register on-line through Compuserve, GEnie, or DELPHI, using EMAIL. NOTE 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, Windowed XModem, 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 4 CopyRight (c) 1987,1988 Information Technology, Ltd. LITECOMM-TP (tm) TOOLBOX for Turbo-PASCAL COMMUNICATIONS AND THE PC COMMUNICATIONS AND THE PC _________________________ PC SHORTCOMINGS PC SHORTCOMINGS _______________ This section is intended as a mini-tutorial on ______________________________________________ communications concepts. We encourage you to read it, _____________________________________________________ although it is not strictly necessary to do so. _______________________________________________ The IBM-PC, and its close compatibles, is a generally well thought-out, flexible, and well-executed computer. Unfortunately, not as much can be said for the thought which was given to the software which is meant to provide access to that hardware. One of the shortcomings which is most noticeable is in the support, or rather lack of it, that is provided to handle access to the serial port. Support for the serial port is limited by the BIOS to polled mode only, i.e. a program must interrogate the port on a regular basis to avoid losing received characters, and to check to determine whether or not the port is ready to send a character. Not only is this mode of operation primitive; it also tends to cause complications when attempting to perform any but the simplest of tasks, at slow speeds. A novice might think that the hardware, in some way, is the limiting factor. In fact, everything that is needed, hardware-wise, to support a more sophisticated method of handling the serial port is already there. All that is missing is the software follow-through. The LiteComm-TP ToolBox provides this missing software. THE 8250 UART THE 8250 UART _____________ The term serial port comes from the fact that both incoming and outgoing characters entering and leaving the port do so in a bitwise fashion. When we send a character out the serial port, the responsible circuitry sends out information one bit at a time. When we receive a character, this circuitry accepts the individual bits and reassembles them into a recognizable character. These very complex operations are performed automatically by the 8250 UART (Universal Asynchronous Receiver-Transmitter). Page 5 CopyRight (c) 1987,1988 Information Technology, Ltd. LITECOMM-TP (tm) TOOLBOX for Turbo-PASCAL The 8250 UART is a fully programmable device that permits independent control of the various parameters that affect serial communications, i.e. baud rate, parity, number of data bits, and number of stop bits. The 8250 also optionally supports four types of interrupts, error/break detection, modem status change detection, transmitter ready, and received character ready. The LiteComm-TP ToolBox fully supports all four type of interrupts. The term asynchronous implies that there is no absolute asynchronous ____________ timing associated with the transmission of information. Instead, the clocking-in of the data bits is done by clocking-in ___________ counting the bits. The first bit sent or received is call the start bit and signals the beginning of a new character. The individual data bits follow the start bit which are clocked out and in at the specified data rate, with the least significant bit transferred first and the parity bit, if present, transferred last. Finally one or more stop bits follow, signalling the end of the character. The 8250 UART takes care of all of the mechanics associated with the process described in the preceding paragraph. The UART will also detect and report error which may occur in the process. For example, if the parity bit is incorrect, the UART reports the fact. If too few or too many bits are received, the UART will report a framing error or overrun error respectively. Since the transmission of information may depend on complex interactions with another device, such as a modem or computer, the 8250 can also report on the status of the handshaking lines used to provide information about the handshaking ___________ status of the connection with the other device. These signals are explained below. SIGNAL DESCRIPTIONS CTS Clear To Send The other device will accept a transmission. DSR Data Set Ready The other device is enabled. RI Ring Indicator Usually reserved for modems only. The phone is ringing DCD Carrier Detect Usually reserved for modems. The other modem's carrier signal was detected. Page 6 CopyRight (c) 1987,1988 Information Technology, Ltd. LITECOMM-TP (tm) TOOLBOX for Turbo-PASCAL The units for the LiteComm-TP ToolBox contains the various bit masks required for you to make use of the information provided by the 8250 UART. TOOLBOX NOTES AND WARNINGS 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 non-existent serial port. The ToolBox interfaces directly with the interrupt structure of the PC. It is critical that, before exiting a program that has opened a serial port that the serial port is closed with the close function. If you exit your program without closing the port, you may cause your system to crash since the interrupt vector for the port might point to a section of memory that no longer contains the needed code to support the interrupt. As an alternative, Turbo PASCAL permits you to install one or more exit handlers (see the PASCAL reference). You may use this approach to provide a safe shutdown, but be follow carefully Borland's recommendations about implementing exit handlers. 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. 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 7 CopyRight (c) 1987,1988 Information Technology, Ltd. LITECOMM-TP (tm) TOOLBOX for Turbo-PASCAL Unless otherwise specified, all library functions have been compiled with the default structure alignment, i.e. the structure alignment switch has not been used in creating the ToolBox library. LITECOMM-TP HISTORY LITECOMM-TP HISTORY ___________________ VERSION 1.0 VERSION 1.0 ___________ Version 1.0 is the first version of LiteComm-TP to be offered to the general public, although there have been 2 Beta releases prior to Version 1.0 release. Version 1.0 is the functional equivalent of the original LiteComm ToolBox, version 2.5. At present, Windowed XModem is still under development VERSION 2.0 VERSION 2.0 ___________ Version 2.0 represent some major tuning to the heart of LiteComm-TP, the kernel routines. In version 2.0, the kernel routines have been tightened and made more efficient, resulting in improved reliability of LiteComm-TP at higher baud rates than before. In addition new functionality has been added in the support of Break Detection. The ModemStatus function has also been enhanced to make it simpler to use. Finally, with version 2.0, we have introduced support for the Windowed XModem protocol, and we have also added additional support to the existing engines in the nature of a user-written 'hook' that permits a limited view of the engine in operation. Finally, several minor bugs have been corrected that were detected in version 1.o of the product. Page 8 CopyRight (c) 1987,1988 Information Technology, Ltd. LITECOMM-TP (tm) TOOLBOX for Turbo-PASCAL VERSION 3.0 VERSION 3.0 ___________ Version 3 of LiteComm-TP is 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 have been recoded in assembly language. In addition, version 3 contains 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 have also included interrupt chaining for COM3 and COM4, that users of the C version of LiteComm have enjoyed since version 2. Note also that, with version 3, we have changed the shareware distribution package. The shareware package now supports all COM ports, but only at speeds of 1200 baud or less. Page 9 CopyRight (c) 1987,1988 Information Technology, Ltd. LITECOMM-TP (tm) TOOLBOX for Turbo-PASCAL BEYOND COM2 BEYOND COM2 ___________ THE TOOLBOX METHODOLOGY 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; and 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: 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 on COM1 or COM2. Page 10 CopyRight (c) 1987,1988 Information Technology, Ltd. LITECOMM-TP (tm) TOOLBOX for Turbo-PASCAL CAUTIONS 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 intend to use COM1 with COM3 or COM2 with COM4 simultaneously, you must change the BOTH the vector number and the IRQ for COM3 or COM4 to an unused or un- needed vector. 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 mis-understanding 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. Page 11 CopyRight (c) 1987,1988 Information Technology, Ltd. LITECOMM-TP (tm) TOOLBOX for Turbo-PASCAL 2. Does the hardware permit re-assignment 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. 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. Page 12 CopyRight (c) 1987,1988 Information Technology, Ltd. LITECOMM-TP (tm) TOOLBOX for Turbo-PASCAL 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. 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: PSERIAL.NUM SERIAL NUMBER OF THIS COPY 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 Page 13 CopyRight (c) 1987,1988 Information Technology, Ltd. LITECOMM-TP (tm) TOOLBOX for Turbo-PASCAL INSTALLATION INSTRUCTIONS 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 sub-directory 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 sub-directory. The example below assumes that you will use a directory named COMM 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 14 CopyRight (c) 1987,1988 Information Technology, Ltd. LITECOMM-TP (tm) TOOLBOX for Turbo-PASCAL GENERAL NOTES GENERAL NOTES _____________ 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 reentrant, 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. Page 15 CopyRight (c) 1987,1988 Information Technology, Ltd. LITECOMM-TP (tm) TOOLBOX for Turbo-PASCAL 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 C syntax and common conventions. UNIT USAGE 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 LcTimer DOS * LTXMKrnl DOS, LctSupp, LcTimer * LTXModem DOS, LctSupp, LTXMKrnl LcTimer * * This unit part of registered version only. Page 16 CopyRight (c) 1987,1988 Information Technology, Ltd. LITECOMM-TP (tm) TOOLBOX for Turbo-PASCAL _______________________________________________________________ PortChange function LctKrnl PortChange function LctKrnl _______________________________________________________________ FUNCTION FUNCTION ________ Changes one or more of the critical parameters for port COM3 or COM4. DECLARATION DECLARATION ___________ Portchange(CPort:integer; NewBase:word; NewIrq, NewVector:byte) RESULT TYPE RESULT TYPE ___________ boolean REMARKS REMARKS _______ This function must be used before the port is 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 non-functional. Page 17 CopyRight (c) 1987,1988 Information Technology, Ltd. LITECOMM-TP (tm) TOOLBOX for Turbo-PASCAL 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 EXAMPLE _______ Var Newbase : word; Newirq : byte; NewVector : byte; Begin Newbase := $03E8; Newirq := $10; NewVector := $0C; if PortChange(3, Newbase, Newirq, NewVector) then Writeln('Port 3 Changed') else Writeln('Error changing Port 3'); end; Page 18 CopyRight (c) 1987,1988 Information Technology, Ltd. LITECOMM-TP (tm) TOOLBOX for Turbo-PASCAL _______________________________________________________________ CommOpen function LctKrnl CommOpen function LctKrnl _______________________________________________________________ FUNCTION FUNCTION ________ Prepares the specified port for use by the other functions DECLARATION DECLARATION ___________ CommOpen(CPort, Baud:integer; Parity:char; Databits, Stopbits, InSize, OutSize:integer) RESULT TYPE RESULT TYPE ___________ boolean REMARKS REMARKS _______ Opens the specified port for use and attaches an 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 possiblity of stack overflows that might occur under some conditions. Page 19 CopyRight (c) 1987,1988 Information Technology, Ltd. LITECOMM-TP (tm) TOOLBOX for Turbo-PASCAL The parameters passed to the function are discrete values, and must be drawn from the following lists: Baud: any value that your communication equipment, e.g. your modem, will support. Parity: E, O, N, M, S E - Even O - Odd N - None M - Mark S - Space Databits: 5, 6, 7, 8 StopBits: 1, 2 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 EXAMPLE _______ Var 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) then Writeln('COM1 available for use') else Writeln('Error opening COM1'); Page 20 CopyRight (c) 1987,1988 Information Technology, Ltd. LITECOMM-TP (tm) TOOLBOX for Turbo-PASCAL _______________________________________________________________ _______________________________________________________________ CommClose procedure LctKrnl CommClose procedure LctKrnl _______________________________________________________________ _______________________________________________________________ FUNCTION FUNCTION ________ Closes a port that has been opened by the CommOpen function DECLARATION DECLARATION ___________ CommClose(CPort:integer) REMARKS REMARKS _______ This function is the companion to CommOpen and, in 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. Failure to call CommClose before terminating a program may result in unexplained system crashes or hangs. Page 21 CopyRight (c) 1987,1988 Information Technology, Ltd. LITECOMM-TP (tm) TOOLBOX for Turbo-PASCAL _______________________________________________________________ _______________________________________________________________ CommSetup function LctKrnl CommSetup function LctKrnl _______________________________________________________________ _______________________________________________________________ FUNCTION FUNCTION ________ Provides the capability of changing the parameters for an open port, without breaking the connection or closing the port. DECLARATION DECLARATION ___________ CommSetup(CPort, Baud:integer; Parity:char; Databits, Stopbits:integer) RESULT TYPE RESULT TYPE ___________ boolean REMARKS REMARKS _______ The CommSetup function is a subset of the CommOpen 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 SEE ALSO ________ CommOpen Page 22 CopyRight (c) 1987,1988 Information Technology, Ltd. LITECOMM-TP (tm) TOOLBOX for Turbo-PASCAL _______________________________________________________________ _______________________________________________________________ ValidatePort function LctKrnl ValidatePort function LctKrnl _______________________________________________________________ _______________________________________________________________ FUNCTION FUNCTION ________ Verifies that the specified port has been opened and returns a pointer to the Communications Control Block for the port. DECLARATION DECLARATION ___________ ValidatePort(CPort:integer) RESULT TYPE RESULT TYPE ___________ CCBPTR REMARKS REMARKS _______ Used internally to validate that the port number specified is correct and has been opened with the CommOpen function. May be of use to you in writing certain applications that require access to the Communications Control Block. The function returns a value of NIL if the specified port is incorrect or not open. EXAMPLE EXAMPLE _______ if ValidatePort(2) = NIL then Writeln('The port has been opened') else Writeln('The port is nor presently open'); Page 23 CopyRight (c) 1987,1988 Information Technology, Ltd. LITECOMM-TP (tm) TOOLBOX for Turbo-PASCAL _______________________________________________________________ _______________________________________________________________ BytesInInput function LctSupp BytesInInput function LctSupp _______________________________________________________________ _______________________________________________________________ FUNCTION FUNCTION ________ Returns the number of characters currently available in the input buffer (BytesInInput) or the number of untransmitted characters in the output buffer (ByteInOutput). DECLARATION DECLARATION ___________ BytesInInput(CPort:integer) BytesInOutput(CPort:integer) RESULT TYPE RESULT TYPE ___________ integer REMARKS REMARKS _______ May be used to determine the number of characters 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 24 CopyRight (c) 1987,1988 Information Technology, Ltd. LITECOMM-TP (tm) TOOLBOX for Turbo-PASCAL _______________________________________________________________ _______________________________________________________________ ModemStatus function LctKrnl ModemStatus function LctKrnl _______________________________________________________________ _______________________________________________________________ FUNCTION FUNCTION ________ Returns the last know status of the modem control lines for the specified port. DECLARATION DECLARATION ___________ ModemStatus(CPort:integer) RESULT TYPE RESULT TYPE ___________ byte REMARKS REMARKS _______ Use this function to determine the last known state of the modem-supplied handshake signals. These may be tested using the values included in the unit, using PASCAL's bitwise AND operator. NOTE: The byte value returned can be viewed as consisting of two sub-fields, the current signal state (found in the high order 4 bits of the byte), and the signal change(DELTA) indicators(found in the low-order 4 bits of the byte). 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. Page 25 CopyRight (c) 1987,1988 Information Technology, Ltd. LITECOMM-TP (tm) TOOLBOX for Turbo-PASCAL HINT HINT ____ Detecting a ringing phone (using the RI signal) can 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 independantly, and you may miss the fact that the phone is ringing if you don't examine the value at the right time. EXAMPLE EXAMPLE _______ Var CStat : byte; begin CStat := ModemStatus(1); if CStat and DeltaCTS = DeltaCTS then if CStat and CTS <> CTS then Writeln('The connection is broken'); Page 26 CopyRight (c) 1987,1988 Information Technology, Ltd. LITECOMM-TP (tm) TOOLBOX for Turbo-PASCAL _______________________________________________________________ _______________________________________________________________ BreakRecd function LctKrnl BreakRecd function LctKrnl _______________________________________________________________ _______________________________________________________________ FUNCTION FUNCTION ________ Returns a value of true if a BREAK signal has been received from the serial port since that last call to the function. DECLARATION DECLARATION ___________ BreakRecd(CPort:integer); RESULT TYPE RESULT TYPE ___________ boolean; REMARKS REMARKS _______ This function returns a value of TRUE if a BREAK character has been received since the last call to the function. EXAMPLE EXAMPLE _______ if BreakRecd(2) then Writeln('Break Signal detected on Port 2'); Page 27 CopyRight (c) 1987,1988 Information Technology, Ltd. LITECOMM-TP (tm) TOOLBOX for Turbo-PASCAL _______________________________________________________________ _______________________________________________________________ ErrorStatus function LctKrnl ErrorStatus function LctKrnl _______________________________________________________________ _______________________________________________________________ FUNCTION FUNCTION ________ Return the last known error status for the specified port. DECLARATION DECLARATION ___________ ErrorStatus(CPort:integer) RESULT TYPE RESULT TYPE ___________ byte REMARKS REMARKS _______ Returns the last known state of the serial port's 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. 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. Page 28 CopyRight (c) 1987,1988 Information Technology, Ltd. LITECOMM-TP (tm) TOOLBOX for Turbo-PASCAL EXAMPLE EXAMPLE _______ Var EStat : byte; begin EStat := ErrorStatus(2); if EStat and OverRun = OverRun then Writeln('Receive Character Over Run'); _______________________________________________________________ _______________________________________________________________ SetModemSignals function LctKrnl SetModemSignals function LctKrnl _______________________________________________________________ _______________________________________________________________ FUNCTION FUNCTION ________ Allows the programmer to set the individual modem control lines for the specified port. DECLARATION DECLARATION ___________ SetModemSignals(CPort:integer; NewSet:byte) RESULT TYPE RESULT TYPE ___________ boolean REMARKS REMARKS _______ Set one or more of the modem 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 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. Page 29 CopyRight (c) 1987,1988 Information Technology, Ltd. LITECOMM-TP (tm) TOOLBOX for Turbo-PASCAL EXAMPLE EXAMPLE _______ begin if SetModemSignals(1, (DTR and RTS)) then Writeln('Port is ready to transmit') else Writeln('Unable to set modem signals'); SEE ALSO SEE ALSO ________ ClearModemSignals, FlipModemSignals _______________________________________________________________ _______________________________________________________________ ClearModemSignals function LctKrnl ClearModemSignals function LctKrnl _______________________________________________________________ _______________________________________________________________ FUNCTION FUNCTION ________ Allows the programmer to clear (reset) the individual modem control lines for the specified port. DECLARATION DECLARATION ___________ ClearModemSignals(CPort:integer; NewSet:byte) RESULT TYPE RESULT TYPE ___________ boolean Page 30 CopyRight (c) 1987,1988 Information Technology, Ltd. LITECOMM-TP (tm) TOOLBOX for Turbo-PASCAL REMARKS REMARKS _______ Clears (resets) one or more of the modem 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 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 EXAMPLE _______ begin if ClearModemSignals(1, RTS) then Writeln('RTS for Port 1 has been dropped') else Writeln('Unable to clear RTS'); SEE ALSO SEE ALSO ________ SetModemSignals, FlipModemSignals Page 31 CopyRight (c) 1987,1988 Information Technology, Ltd. LITECOMM-TP (tm) TOOLBOX for Turbo-PASCAL _______________________________________________________________ _______________________________________________________________ FlipModemSignals function LctKrnl FlipModemSignals function LctKrnl _______________________________________________________________ _______________________________________________________________ FUNCTION FUNCTION ________ Allows the programmer to compliment(toggle) the individual modem control lines for the specified port. DECLARATION DECLARATION ___________ FlipModemSignals(CPort:integer; NewSet:byte) RESULT TYPE RESULT TYPE ___________ boolean REMARKS REMARKS _______ Complements(toggles) one or more of the modem 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 EXAMPLE _______ begin if FlipModemSignals(1, RTS) then Writeln('RTS for Port 1 has been changed') else Writeln('Unable to change RTS'); SEE ALSO SEE ALSO ________ SetModemSignals, ClearModemSignals Page 32 CopyRight (c) 1987,1988 Information Technology, Ltd. LITECOMM-TP (tm) TOOLBOX for Turbo-PASCAL _______________________________________________________________ _______________________________________________________________ EnableXon function LctKrnl EnableXon function LctKrnl _______________________________________________________________ _______________________________________________________________ FUNCTION FUNCTION ________ Enable or disable the semi-automatic flow control features of LiteComm-TP DECLARATION DECLARATION ___________ EnableXon(CPort:integer; XonFlag:boolean) RESULT TYPE RESULT TYPE ___________ boolean; DESCRIPTION DESCRIPTION ___________ If XonFlag is TRUE, turns on semi-automatic XON-XOFF flow control function. If XonFlag is FALSE (the 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 companion system. If the companion system transmits an XOFF, the kernel will refuse to send any characters until the condition is cleared. It is the programmer's responsibility to transmit XON when conditions permit. See the XoffSent function to tell if an automatic XOFF has been sent by the kernel. See the XoffRecd function to determine if the kernel has detected an XOFF. 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 SEE ALSO ________ XoffRecd, XoffRecd Page 33 CopyRight (c) 1987,1988 Information Technology, Ltd. LITECOMM-TP (tm) TOOLBOX for Turbo-PASCAL _______________________________________________________________ _______________________________________________________________ XoffRecd function LctKrnl XoffRecd function LctKrnl _______________________________________________________________ _______________________________________________________________ FUNCTION FUNCTION ________ Reports whether or not the kernel has detected an XOFF from the companion system DECLARATION DECLARATION ___________ XoffRecd(CPort:integer) RESULT TYPE RESULT TYPE ___________ boolean REMARKS REMARKS _______ Returns TRUE if an XOFF has been received, FALSE otherwise. If an XOFF has been received, the port's flag will be reset, and transmission to the companion system will be permitted. If an XON is received from the companion system, the port's flag will also be reset, permitting further transmissions to occur. Be aware that if the companion system never sends an XON after sending an XOFF, a possible race condition may race ____ occur, resulting in a system hang. SEE ALSO SEE ALSO ________ EnableXon, XoffSent Page 34 CopyRight (c) 1987,1988 Information Technology, Ltd. LITECOMM-TP (tm) TOOLBOX for Turbo-PASCAL _______________________________________________________________ _______________________________________________________________ XoffSent function LctKrnl XoffSent function LctKrnl _______________________________________________________________ _______________________________________________________________ FUNCTION FUNCTION ________ Reports whether or not the kernel has automatically sent an XOFF to the companion system. DECLARATION DECLARATION ___________ XoffSent(CPort:integer) RESULT TYPE RESULT TYPE ___________ boolean REMARKS REMARKS _______ Returns TRUE if the kernel has sent an XOFF to the companion system, FALSE otherwise. If an XOFF has been sent, the port's flag will be reset. You must send an XON character to the companion system to permit transmissions to proceed. SEE ALSO SEE ALSO ________ EnableXon, XoffRecd Page 35 CopyRight (c) 1987,1988 Information Technology, Ltd. LITECOMM-TP (tm) TOOLBOX for Turbo-PASCAL _______________________________________________________________ _______________________________________________________________ LctGet function LctSupp LctGet function LctSupp _______________________________________________________________ _______________________________________________________________ FUNCTION FUNCTION ________ Returns an available character from the ports input buffer. DECLARATION DECLARATION ___________ LctGet(CPort:integer; var Ch:byte) RESULT TYPE RESULT TYPE ___________ boolean REMARKS REMARKS _______ Places the next available character in the input buffer for the port in 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. Page 36 CopyRight (c) 1987,1988 Information Technology, Ltd. LITECOMM-TP (tm) TOOLBOX for Turbo-PASCAL _______________________________________________________________ _______________________________________________________________ LctPeek function LctSupp LctPeek function LctSupp _______________________________________________________________ _______________________________________________________________ FUNCTION FUNCTION ________ Permits you to look at the next character in the ports input buffer without removing if from the buffer. DECLARATION DECLARATION ___________ LctPeek(CPort:integer; var Ch:byte) RESULT TYPE RESULT TYPE ___________ boolean REMARKS REMARKS _______ Places the next available character in the input 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 character in a non-destructive fashion. look-ahead __________ 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 Page 37 CopyRight (c) 1987,1988 Information Technology, Ltd. LITECOMM-TP (tm) TOOLBOX for Turbo-PASCAL _______________________________________________________________ _______________________________________________________________ LctPut function LctSupp LctPut function LctSupp _______________________________________________________________ _______________________________________________________________ FUNCTION FUNCTION ________ Places a character in the port's transmit buffer to be sent when the port is ready. DECLARATION DECLARATION ___________ LctPut(CPort:integer; Ch:byte) RESULT TYPE RESULT TYPE ___________ boolean REMARKS REMARKS _______ Returns TRUE if successful. Note that this does not guarantee that the character has been sent, only that no errors were detected. Returns FALSE if the port is not active, or if there no room in the port's buffer. Page 38 CopyRight (c) 1987,1988 Information Technology, Ltd. LITECOMM-TP (tm) TOOLBOX for Turbo-PASCAL _______________________________________________________________ _______________________________________________________________ GetStream function LctSupp GetStream function LctSupp _______________________________________________________________ _______________________________________________________________ FUNCTION FUNCTION ________ Gets a stream of N characters from the port's input buffer DECLARATION DECLARATION ___________ GetStream(CPort:integer; var Buff; BCnt:integer) RESULT TYPE RESULT TYPE ___________ integer REMARKS REMARKS _______ Reads a stream of, at most, BCnt characters from 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. EXAMPLE EXAMPLE _______ Type MaxStr = string[256]; Var StrBuff : MaxStr; RecdLen : integer; begin RecdLen := GetStream(2, StrBuff[1], 256); if RecdLen <M=> 0 then { error or no char } StrBuff[0] := 0 else StrBuff[0] := Chr(RecdLen); end; Page 39 CopyRight (c) 1987,1988 Information Technology, Ltd. LITECOMM-TP (tm) TOOLBOX for Turbo-PASCAL _______________________________________________________________ _______________________________________________________________ PutStream function LctSupp PutStream function LctSupp _______________________________________________________________ _______________________________________________________________ FUNCTION FUNCTION ________ Places a stream of, at most, N characters in the port's transmit buffer. DECLARATION DECLARATION ___________ PutStream(CPort:integer; var Buff; BCnt:integer) RESULT TYPE RESULT TYPE ___________ integer REMARKS REMARKS _______ Buff is an array of character or byte, not a 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. SEE ALSO SEE ALSO ________ PutStream Page 40 CopyRight (c) 1987,1988 Information Technology, Ltd. LITECOMM-TP (tm) TOOLBOX for Turbo-PASCAL _______________________________________________________________ _______________________________________________________________ Buffer Flushing functions LctSupp Buffer Flushing functions LctSupp _______________________________________________________________ _______________________________________________________________ FUNCTION FUNCTION ________ Provides several high level buffer management functions to control the contents of the port's transmit and receive buffers DELCLARATION DELCLARATION ____________ function PurgeTxBuff(CPort:integer) function PurgeRxBuff(CPort:integer) procedure FlushUntilMatch(CPort:integer; Ch:byte) procedure FlushNBytes(CPort:integer; N:integer); RESULT TYPE RESULT TYPE ___________ boolean for PurgeTxBuff, PurgeRxBuff REMARKS REMARKS _______ The PurgeRxBuff and PurgeTxBuff functions remove 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 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. Page 41 CopyRight (c) 1987,1988 Information Technology, Ltd. LITECOMM-TP (tm) TOOLBOX for Turbo-PASCAL _______________________________________________________________ _______________________________________________________________ SendBreak function LctKrnl SendBreak function LctKrnl _______________________________________________________________ _______________________________________________________________ FUNCTION FUNCTION ________ Send a true Break signal DECLARATION DECLARATION ___________ SendBreak(CPort:integer) RESULT TYPE RESULT TYPE ___________ boolean REMARKS REMARKS _______ SendBreak generates a BREAK signal using a 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. Page 42 CopyRight (c) 1987,1988 Information Technology, Ltd. LITECOMM-TP (tm) TOOLBOX for Turbo-PASCAL BBS Functions _______________________________________________________________ _______________________________________________________________ CheckEvent Function LctBBS CheckEvent Function LctBBS _______________________________________________________________ _______________________________________________________________ FUNCTION FUNCTION ________ Returns a value of TRUE is the Event Timer specified in the function call has not expired. Returns a value of FALSE if the specified Event Timer has expired. DECLARATION DECLARATION ___________ CheckEvent(EventVal : Event); RESULT TYPE RESULT TYPE ___________ boolean; REMARKS REMARKS _______ The event timer specified by EventVal must have been set using the NewEvent function SEE ALSO SEE ALSO ________ NewEvent Page 43 CopyRight (c) 1987,1988 Information Technology, Ltd. LITECOMM-TP (tm) TOOLBOX for Turbo-PASCAL _______________________________________________________________ _______________________________________________________________ NewEvent Function LctBBS NewEvent Function LctBBS _______________________________________________________________ _______________________________________________________________ FUNCTION FUNCTION ________ Initializes an event timer to a value suitable for use with CheckEvent. The event timer created in this fashion can time events up to 32767 seconds in duration. DECLARATION DECLARATION ___________ NewEvent(Seconds : integer); RESULT TYPE RESULT TYPE ___________ Event; REMARKS REMARKS _______ When used in conjunction with CheckEvent, the event 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 EXAMPLE _______ var 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; Page 44 CopyRight (c) 1987,1988 Information Technology, Ltd. LITECOMM-TP (tm) TOOLBOX for Turbo-PASCAL _______________________________________________________________ _______________________________________________________________ CheckForCall Function LctBBS CheckForCall Function LctBBS _______________________________________________________________ _______________________________________________________________ FUNCTION FUNCTION ________ 'Listens' to the specified port to see if the telephone is ringing. If the phone is ringing, waits for up to 30 seconds for a successful connection to be established. DECLARATION DECLARATION ___________ CheckForCall(CPort : integer); RESULT TYPE RESULT TYPE ___________ integer; REMARKS REMARKS _______ This function will return a value of -1 if the 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 present 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. Page 45 CopyRight (c) 1987,1988 Information Technology, Ltd. LITECOMM-TP (tm) TOOLBOX for Turbo-PASCAL EXAMPLE EXAMPLE _______ var 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 SEE ALSO ________ Disconnect, ResetModem Page 46 CopyRight (c) 1987,1988 Information Technology, Ltd. LITECOMM-TP (tm) TOOLBOX for Turbo-PASCAL _______________________________________________________________ _______________________________________________________________ Disconnect Procedure LctBBS Disconnect Procedure LctBBS _______________________________________________________________ _______________________________________________________________ FUNCTION FUNCTION ________ Causes the modem to disconnect from the caller. DECLARATION DECLARATION ___________ Disconnect(CPort : integer); REMARKS REMARKS _______ Forceablly disconnects the modem by dropping the DTR (Data 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. Page 47 CopyRight (c) 1987,1988 Information Technology, Ltd. LITECOMM-TP (tm) TOOLBOX for Turbo-PASCAL _______________________________________________________________ _______________________________________________________________ ResetModem Function LctBBS ResetModem Function LctBBS _______________________________________________________________ _______________________________________________________________ FUNCTION FUNCTION ________ Returns the modem to a known set of parameters, suitable for use with the related functions in this unit. See the typed constants MODEMSET0 thru MODEMSET2 in the interface portion of the unit. DECLARATION DECLARATION ___________ ResetModem(CPort, : integer); RESULT TYPE RESULT TYPE ___________ integer; REMARKS REMARKS _______ The modem is reset to a known state, including, but 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 SEE ALSO ________ GetModemReply Page 48 CopyRight (c) 1987,1988 Information Technology, Ltd. LITECOMM-TP (tm) TOOLBOX for Turbo-PASCAL _______________________________________________________________ _______________________________________________________________ GetModemReply Function LctBBS GetModemReply Function LctBBS _______________________________________________________________ _______________________________________________________________ FUNCTION FUNCTION ________ Returns the modem's response to the last set of instructions that were issued to the modem, in numeric form. DECLARATION DECLARATION ___________ GetModemReply(CPort : integer); RESULT TYPE RESULT TYPE ___________ integer; REMARKS REMARKS _______ This function expects the modem to be returning numeric result codes (set ResetModem) of up to 2 digits. The function will react to 2 digits returned or the first <CR> 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 SEE ALSO ________ ResetModem. Page 49 CopyRight (c) 1987,1988 Information Technology, Ltd. LITECOMM-TP (tm) TOOLBOX for Turbo-PASCAL _______________________________________________________________ _______________________________________________________________ HAYES MODEM FUNCTIONS LctHayes HAYES MODEM FUNCTIONS LctHayes _______________________________________________________________ _______________________________________________________________ FUNCTION FUNCTION ________ Provides support for various aspects of modems the support the Hayes(Tm) command set. DECLARATIONS DECLARATIONS ____________ const 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]; Page 50 CopyRight (c) 1987,1988 Information Technology, Ltd. LITECOMM-TP (tm) TOOLBOX for Turbo-PASCAL procedure SetType(NType : byte) procedure SetSet(NSet : byte) 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 51 CopyRight (c) 1987,1988 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 REMARKS _______ The ModemCodeSet function allows you to change the 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 <CR>. 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. Page 52 CopyRight (c) 1987,1988 Information Technology, Ltd. LITECOMM-TP (tm) TOOLBOX for Turbo-PASCAL 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. 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 re-dialing 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. Page 53 CopyRight (c) 1987,1988 Information Technology, Ltd. LITECOMM-TP (tm) TOOLBOX for Turbo-PASCAL 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. 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 GENERAL REMARKS _______________ Several considerations are in order if you intend 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 RETURN VALUES _____________ All functions return a value of FALSE if a port or other error is detected, TRUE otherwise. Page 54 CopyRight (c) 1987,1988 Information Technology, Ltd. LITECOMM-TP (tm) TOOLBOX for Turbo-PASCAL LITECOMM-TP REGISTRATION FORM LITECOMM-TP REGISTRATION FORM _____________________________ Please complete the following information. Note that the prices below are for a single-use registration only. Please contact us directly for site licensing. Mail to: Information Technology PO Box 554 Coventry, RI 02816 Telephone Orders or Information (401) 826-2223 SHIP TO: Name ________________________________________ Company ________________________________________ Street ________________________________________ ________________________________________ City ___________________ State __ Zip _____ Telephone _______________________ QTY REGISTRATION TYPE REGISTRATION FEE LIBRARIES @ $25 LIBRARIES AND SOURCE @ $50 [ ] Check here for 3.5" disks, add $1.00 RI residents, Sales Tax 6% Method of Payment (Check, Mastercard, Visa) _____________ Credit Card Number __________________________ Expiration Date __________________________ Name as it appears on card ___________________________ Signature for MC/VISA ________________________________ All MasterCard/Visa orders must include a telephone number, We regret that we cannot accept COD orders (office use only) Date Received ______________ Date Sent _____________ Version ______________ Serial Number _______________ Page 55 CopyRight (c) 1987,1988 Information Technology, Ltd. LITECOMM-TP (tm) TOOLBOX for Turbo-PASCAL Page 56 CopyRight (c) 1987,1988 Information Technology, Ltd. 8250 5, 6, 7 ResetModem 48 8259 10 RetSet 51 Asynchronous 6 RetType 51 BIOS 5, 11 SendBreak 42 BREAK 27, 28, 42 SetModemRegister 51 BreakRecd 27 SetModemSignals 29 Buffer Flushing 41 ValidatePort 23 Buffers 7, 19 XoffRecd 34 COM3 10 XoffSent 35 COM4 10 Handshake 25 CommOpen 10 Handshaking 6 Control structures 7 HAYES 48 CTS 25 HAYES MODEM 50 DCD 25 Heap 7, 20 DeltaCTS 25 Interrupt chaining 9, 12 DSR 25 Interrupt enable flag 7 DTR 29, 31, 32, 47 Interrupt vector 11 Error status bits 28 Interrupt vectors 10 Event Timer 43 IRQ 11, 17 Expansion cards 11 IRQ0 11 Flow control 33 Look-ahead 37 Functions Open function 7 BytesInInput 24 PortChange 10 CheckEvent 43 Procedures CheckForCall 45 CommClose 21 ClearModemSignals 30 Disconnect 47 CommOpen 19 FlushNBytes 41 CommSetup 22 FlushUntilMatch 41 EnableXon 33 SetSet 51 ErrorStatus 28 SetType 51 FlipModemSignals 32 RI 25 GetModemRegister 51, 52 RTS 29, 31, 32 GetModemReply 49 S-register 53 GetStream 39 Stream 39, 40 LctGet 36 TSR 15 LctPeek 37 Vector numbers 11 LctPut 38 XOFF 33 ModemCarrierOff 51, 52 XON 33 ModemCarrierOn 51, 52 ModemCodeSet 52 ModemCodesOff 51 ModemCodesOn 51 ModemDial 52 ModemDigitResponse 51 ModemEchoCmd 51, 52 ModemFullDuplex 51, 52 ModemHalfDuplex 51, 52 ModemHookMode 51, 52 ModemNoEchoCmd 51, 52 ModemPulse 52 ModemSpeaker 51 ModemStatus 25 ModemTone 52 ModemWordResponse 51 NewEvent 44 PortChange 17 PurgeRxBuff 41 PurgeTxBuff 41 PutStream 40 RepeatModemCommand 51 1 OVERVIEW........................................... 1 FEATURES....................................... 1 THE SHAREWARE CONCEPT.......................... 1 LICENSE, WARRANTY AND REGISTRATION................. 2 LICENSE........................................ 2 WARRANTY....................................... 3 REGISTERING YOUR COPY.......................... 4 NOTE........................................... 4 COMMUNICATIONS AND THE PC.......................... 5 PC SHORTCOMINGS................................ 5 THE 8250 UART.................................. 5 TOOLBOX NOTES AND WARNINGS..................... 7 LITECOMM-TP HISTORY................................ 8 VERSION 1.0.................................... 8 VERSION 2.0.................................... 8 VERSION 3.0.................................... 9 BEYOND COM2........................................ 10 THE TOOLBOX METHODOLOGY........................ 10 CAUTIONS....................................... 11 PACKAGE CONTENTS................................... 13 INSTALLATION INSTRUCTIONS.......................... 14 GENERAL NOTES...................................... 15 PROCEDURE AND FUNCTION REFERENCE................... 16 UNIT USAGE..................................... 16 BBS Functions...................................... 43 HAYES MODEM FUNCTIONS.............................. 50 LITECOMM-TP REGISTRATION FORM...................... 55 Turbo PASCAL is a registered trademark of Borland International