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 3 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 PASCAL1 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. ____________________ 1 Turbo PASCAL is a registerd trademark of Borland International LITECOMM-TP (tm) COMMUNICATIONS TOOLBOX for Microsoft, Datalight and Turbo C 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 COM1 only. 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 not charge a fee for providing such a copy, beyond a maximum $4.00 copying or duplication fee, without the express, written consent of Information Technology, Ltd, 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. Page 2 CopyRight (c) 1988 Information Technology, Ltd. LITECOMM-TP (tm) COMMUNICATIONS TOOLBOX for Microsoft, Datalight and Turbo C 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. Page 3 CopyRight (c) 1988 Information Technology, Ltd. LITECOMM-TP (tm) COMMUNICATIONS TOOLBOX for Microsoft, Datalight and Turbo C 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 4 CopyRight (c) 1988 Information Technology, Ltd. LITECOMM-TP (tm) COMMUNICATIONS TOOLBOX for Microsoft, Datalight and Turbo C 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. Page 5 CopyRight (c) 1988 Information Technology, Ltd. LITECOMM-TP (tm) COMMUNICATIONS TOOLBOX for Microsoft, Datalight and Turbo C 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, and YModem protocols. We plan to follow these with similar engines for Windowed XModem 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 6 CopyRight (c) 1988 Information Technology, Ltd. LITECOMM-TP (tm) COMMUNICATIONS TOOLBOX for Microsoft, Datalight and Turbo C 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 7 CopyRight (c) 1988 Information Technology, Ltd. LITECOMM-TP (tm) COMMUNICATIONS TOOLBOX for Microsoft, Datalight and Turbo C 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. Page 8 CopyRight (c) 1988 Information Technology, Ltd. LITECOMM-TP (tm) COMMUNICATIONS TOOLBOX for Microsoft, Datalight and Turbo C 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. | | _______________________________________________________________ | | The header file 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. Page 9 CopyRight (c) 1988 Information Technology, Ltd. LITECOMM-TP (tm) COMMUNICATIONS TOOLBOX for Microsoft, Datalight and Turbo C 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. 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, except for YModem support which is still undergoing development for the C environment. Page 10 CopyRight (c) 1988 Information Technology, Ltd. LITECOMM-TP (tm) COMMUNICATIONS TOOLBOX for Microsoft, Datalight and Turbo C 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 vector 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. CAUTIONS CAUTIONS ________ Page 11 CopyRight (c) 1988 Information Technology, Ltd. LITECOMM-TP (tm) COMMUNICATIONS TOOLBOX for Microsoft, Datalight and Turbo C 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. 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. Page 12 CopyRight (c) 1988 Information Technology, Ltd. LITECOMM-TP (tm) COMMUNICATIONS TOOLBOX for Microsoft, Datalight and Turbo C 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. Page 13 CopyRight (c) 1988 Information Technology, Ltd. LITECOMM-TP (tm) COMMUNICATIONS TOOLBOX for Microsoft, Datalight and Turbo C 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: .fo off 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 a sub directory called SOURCE. The SOURCE directory contains 2 source code archives. LITECOMM-TP SOURCE CODE LTSRC.ARC XMODEM ENGINE SOURCE CODE LTXMSRC.ARC Page 14 CopyRight (c) 1988 Information Technology, Ltd. LITECOMM-TP (tm) COMMUNICATIONS TOOLBOX for Microsoft, Datalight and Turbo C 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. GENERAL NOTES GENERAL NOTES _____________ Page 15 CopyRight (c) 1988 Information Technology, Ltd. LITECOMM-TP (tm) COMMUNICATIONS TOOLBOX for Microsoft, Datalight and Turbo C 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 16 CopyRight (c) 1988 Information Technology, Ltd. LITECOMM-TP (tm) COMMUNICATIONS TOOLBOX for Microsoft, Datalight and Turbo C 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 LcTimer DOS * LTXMKrnl DOS, LctSupp, LcTimer * LTXModem DOS, LctSupp, LTXMKrnl LcTimer * * This unit part of registered version only. Page 17 CopyRight (c) 1988 Information Technology, Ltd. LITECOMM-TP (tm) COMMUNICATIONS TOOLBOX for Microsoft, Datalight and Turbo C _______________________________________________________________ _______________________________________________________________ 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. The PortChange function does NOT check to determine that you have provided both an IRQ mask AND a new vector number. Page 18 CopyRight (c) 1988 Information Technology, Ltd. LITECOMM-TP (tm) COMMUNICATIONS TOOLBOX for Microsoft, Datalight and Turbo C PortChange returns a value of TRUE if the change was successful, false otherwise. Page 19 CopyRight (c) 1988 Information Technology, Ltd. LITECOMM-TP (tm) COMMUNICATIONS TOOLBOX for Microsoft, Datalight and Turbo C 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 20 CopyRight (c) 1988 Information Technology, Ltd. LITECOMM-TP (tm) COMMUNICATIONS TOOLBOX for Microsoft, Datalight and Turbo C _______________________________________________________________ _______________________________________________________________ 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. The parameters passed to the function are discrete values, and must be drawn from the following lists: Baud: 110, 300, 600, 1200, 2400, 4800, 9600, 19200 Parity: E, O, N, M, S E - Even O - Odd N - None M - Mark S - Space Databits: 5, 6, 7, 8 StopBits: 1, 2 Page 21 CopyRight (c) 1988 Information Technology, Ltd. LITECOMM-TP (tm) COMMUNICATIONS TOOLBOX for Microsoft, Datalight and Turbo C 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. Page 22 CopyRight (c) 1988 Information Technology, Ltd. LITECOMM-TP (tm) COMMUNICATIONS TOOLBOX for Microsoft, Datalight and Turbo C 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 23 CopyRight (c) 1988 Information Technology, Ltd. LITECOMM-TP (tm) COMMUNICATIONS TOOLBOX for Microsoft, Datalight and Turbo C _______________________________________________________________ _______________________________________________________________ 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 24 CopyRight (c) 1988 Information Technology, Ltd. LITECOMM-TP (tm) COMMUNICATIONS TOOLBOX for Microsoft, Datalight and Turbo C _______________________________________________________________ _______________________________________________________________ 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 25 CopyRight (c) 1988 Information Technology, Ltd. LITECOMM-TP (tm) COMMUNICATIONS TOOLBOX for Microsoft, Datalight and Turbo C _______________________________________________________________ _______________________________________________________________ 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 26 CopyRight (c) 1988 Information Technology, Ltd. LITECOMM-TP (tm) COMMUNICATIONS TOOLBOX for Microsoft, Datalight and Turbo C _______________________________________________________________ _______________________________________________________________ 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 27 CopyRight (c) 1988 Information Technology, Ltd. LITECOMM-TP (tm) COMMUNICATIONS TOOLBOX for Microsoft, Datalight and Turbo C _______________________________________________________________ _______________________________________________________________ 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: You should be aware that the handshake signals returned are reset once this function is called. Subsequent calls to this function will return to last known value for all signals. 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. EXAMPLE EXAMPLE _______ Page 28 CopyRight (c) 1988 Information Technology, Ltd. LITECOMM-TP (tm) COMMUNICATIONS TOOLBOX for Microsoft, Datalight and Turbo C 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 29 CopyRight (c) 1988 Information Technology, Ltd. LITECOMM-TP (tm) COMMUNICATIONS TOOLBOX for Microsoft, Datalight and Turbo C _______________________________________________________________ _______________________________________________________________ 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, BadFrame, and BreakDet. 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 EXAMPLE _______ Var EStat : byte; begin EStat := ErrorStatus(2); if EStat and BreakDet = BreakDet then Writeln('Break Signal detected on Port 2'); Page 30 CopyRight (c) 1988 Information Technology, Ltd. LITECOMM-TP (tm) COMMUNICATIONS TOOLBOX for Microsoft, Datalight and Turbo C _______________________________________________________________ _______________________________________________________________ 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. 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 Page 31 CopyRight (c) 1988 Information Technology, Ltd. LITECOMM-TP (tm) COMMUNICATIONS TOOLBOX for Microsoft, Datalight and Turbo C _______________________________________________________________ _______________________________________________________________ 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 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 32 CopyRight (c) 1988 Information Technology, Ltd. LITECOMM-TP (tm) COMMUNICATIONS TOOLBOX for Microsoft, Datalight and Turbo C _______________________________________________________________ _______________________________________________________________ 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 33 CopyRight (c) 1988 Information Technology, Ltd. LITECOMM-TP (tm) COMMUNICATIONS TOOLBOX for Microsoft, Datalight and Turbo C _______________________________________________________________ _______________________________________________________________ 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 34 CopyRight (c) 1988 Information Technology, Ltd. LITECOMM-TP (tm) COMMUNICATIONS TOOLBOX for Microsoft, Datalight and Turbo C _______________________________________________________________ _______________________________________________________________ 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 35 CopyRight (c) 1988 Information Technology, Ltd. LITECOMM-TP (tm) COMMUNICATIONS TOOLBOX for Microsoft, Datalight and Turbo C _______________________________________________________________ _______________________________________________________________ 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 36 CopyRight (c) 1988 Information Technology, Ltd. LITECOMM-TP (tm) COMMUNICATIONS TOOLBOX for Microsoft, Datalight and Turbo C _______________________________________________________________ _______________________________________________________________ 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 37 CopyRight (c) 1988 Information Technology, Ltd. LITECOMM-TP (tm) COMMUNICATIONS TOOLBOX for Microsoft, Datalight and Turbo C _______________________________________________________________ _______________________________________________________________ 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 38 CopyRight (c) 1988 Information Technology, Ltd. LITECOMM-TP (tm) COMMUNICATIONS TOOLBOX for Microsoft, Datalight and Turbo C _______________________________________________________________ _______________________________________________________________ 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 39 CopyRight (c) 1988 Information Technology, Ltd. LITECOMM-TP (tm) COMMUNICATIONS TOOLBOX for Microsoft, Datalight and Turbo C _______________________________________________________________ _______________________________________________________________ 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 <= 0 then { error or no char } StrBuff[0] := 0 else StrBuff[0] := Chr(RecdLen); end; Page 40 CopyRight (c) 1988 Information Technology, Ltd. LITECOMM-TP (tm) COMMUNICATIONS TOOLBOX for Microsoft, Datalight and Turbo C _______________________________________________________________ _______________________________________________________________ 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 41 CopyRight (c) 1988 Information Technology, Ltd. LITECOMM-TP (tm) COMMUNICATIONS TOOLBOX for Microsoft, Datalight and Turbo C _______________________________________________________________ _______________________________________________________________ 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 42 CopyRight (c) 1988 Information Technology, Ltd. LITECOMM-TP (tm) COMMUNICATIONS TOOLBOX for Microsoft, Datalight and Turbo C _______________________________________________________________ _______________________________________________________________ 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 43 CopyRight (c) 1988 Information Technology, Ltd. LITECOMM-TP (tm) COMMUNICATIONS TOOLBOX for Microsoft, Datalight and Turbo C _______________________________________________________________ _______________________________________________________________ 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 44 CopyRight (c) 1988 Information Technology, Ltd. LITECOMM-TP (tm) COMMUNICATIONS TOOLBOX for Microsoft, Datalight and Turbo C 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 function GetModemRegister(CPort, Reg, NValue : integer) : boolean Page 45 CopyRight (c) 1988 Information Technology, Ltd. LITECOMM-TP (tm) COMMUNICATIONS TOOLBOX for Microsoft, Datalight and Turbo C 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 . 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 MpdemPulse 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 46 CopyRight (c) 1988 Information Technology, Ltd. LITECOMM-TP (tm) COMMUNICATIONS TOOLBOX for Microsoft, Datalight and Turbo C 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 47 CopyRight (c) 1988 Information Technology, Ltd. LITECOMM-TP (tm) COMMUNICATIONS TOOLBOX for Microsoft, Datalight and Turbo C 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. Page 48 CopyRight (c) 1988 Information Technology, Ltd. LITECOMM-TP (tm) COMMUNICATIONS TOOLBOX for Microsoft, Datalight and Turbo C 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 49 CopyRight (c) 1988 Information Technology, Ltd. LITECOMM-TP (tm) COMMUNICATIONS TOOLBOX for Microsoft, Datalight and Turbo C Page 50 CopyRight (c) 1988 Information Technology, Ltd. 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 � � � � � � 쳐컴컴탠컴컴컴컴컵컴컴컴컴컴컴컴컴컴컵컴컴컴컴컴컴컴컴컴컴캑 � � � � � � � BOTH � LIBRARIES @ $30 � � � � INCLUDE � � � 쳐컴컴� 탠컴컴컴컴컴컴컴컴컴탠컴컴컴컴컴컴컴컴컴컴� � � PRINTED � � � � � MANUAL � LIBRARIES AND � � � � � SOURCE @ $55 � � � � � � � 쳐컴컴탠컴컴컴컴컵컴컴컴컴컴컴컴컴컴컵컴컴컴컴컴컴컴컴컴컴캑 � � � � � � � � RI 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 _______________