home *** CD-ROM | disk | FTP | other *** search
/ Programmer 7500 / MAX_PROGRAMMERS.iso / PASCAL / LTCOMM.ZIP / LCTP.PRN < prev    next >
Encoding:
Text File  |  1993-01-04  |  138.9 KB  |  3,895 lines

  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.                                      Chapter 1
  16.                                      Chapter 1
  17.  
  18.                                       OVERVIEW
  19.                                       OVERVIEW
  20.  
  21.  
  22.        1.1  FEATURES
  23.        1.1  FEATURES
  24.  
  25.  
  26.        The LiteComm-TP Toolbox(Tm) is a set of powerful routines designed to
  27.        provide easy access to the full capabilities of the PC's asynchronous
  28.        communications ports. The LiteComm-TP ToolBox supports fully
  29.        interrupt-driven and buffered communications support on COM1 through
  30.        COM4 simultaneously. Now you can quickly incorporate sophisticated
  31.        communications support in your applications without having in-depth
  32.        knowledge of how the hardware functions.
  33.  
  34.        LiteComm-TP is implemented as a set of 4 units for the basic product,
  35.        with additional units providing the protocol-engine capability.  The
  36.        protocol engines are a part of the registered version of the package.
  37.  
  38.        The LiteComm ToolBox was originally developed in the C language for
  39.        use in CAD/CAM applications that required the ability to have PC
  40.        compatible systems communicating with a variety of devices.
  41.        LiteComm-TP extends the same capabilities to the PASCAL programmer.
  42.  
  43.  
  44.        1.2  THE SHAREWARE CONCEPT
  45.        1.2  THE SHAREWARE CONCEPT
  46.  
  47.  
  48.        Shareware is a "try before you buy" means of software distribution. If
  49.        you find a shareware product useful, pay the registration fee, and let
  50.        the authors know that you support their efforts.
  51.  
  52.        Information Technology is a member of the Association of Shareware
  53.        Professionals (ASP).  ASP wants to make sure that the shareware
  54.        principle works for you.  If you are unable to resolve a shareware-
  55.        related problem with an ASP member by contacting the member directly,
  56.        ASP may be able to help.  The ASP Ombudsman can help you resolve a
  57.        dispute or problem with an ASP member, but does not provide technical
  58.        support for members' products.  Please write to the ASP Ombudsman at
  59.        P.O.  Box 5786, Bellevue, WA 98006 or send a Compuserve message via
  60.        easyplex to ASP Ombudsman 70007,3536.
  61.  
  62.  
  63.  
  64.                    LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.  
  73.  
  74.  
  75.  
  76.  
  77.  
  78.  
  79.  
  80.  
  81.  
  82.  
  83.  
  84.  
  85.  
  86.  
  87.  
  88.  
  89.  
  90.  
  91.  
  92.  
  93.  
  94.  
  95.  
  96.  
  97.  
  98.  
  99.  
  100.  
  101.  
  102.  
  103.  
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.                                     Page 2
  126.             Copyright (c) 1987, 88, 89 Information Technology, Ltd.
  127.  
  128.  
  129.                    LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.  
  139.                                      Chapter 2
  140.                                      Chapter 2
  141.  
  142.                          LICENSE, WARRANTY AND REGISTRATION
  143.                          LICENSE, WARRANTY AND REGISTRATION
  144.  
  145.  
  146.        2.1  LICENSE
  147.        2.1  LICENSE
  148.  
  149.  
  150.        The LiteComm-TP ToolBox, is distributed as a shareware product. We
  151.        urge you to register your copy today. See the registration form at the
  152.        end of this manual.
  153.  
  154.        Information Technology, Ltd, grants to registered users a
  155.        nonexclusive, perpetual license to the LiteComm-TP ToolBox, subject to
  156.        these terms and conditions:
  157.  
  158.           1.  You must treat your copy of the LiteComm-TP Toolbox as you
  159.               would a book.  You may install the LiteComm-TP ToolBox on more
  160.               than one machine, but you may use only one copy at a time.  If
  161.               you desire, site licenses are available at a reduced cost.  You
  162.               may make as many copies of the LiteComm-TP ToolBox as you
  163.               require for the sole purpose of backup.
  164.  
  165.           2.  You may incorporate portions of the LiteComm-TP ToolBox into
  166.               products that you develop without the payment of additional
  167.               royalties or license fees.  You must include the statement
  168.               'Portions Copyright 1987, 1988, Information Technology, Ltd' in
  169.               your product's documentation.
  170.  
  171.           3.  You may copy and redistribute the shareware portion of the
  172.               LiteComm-TP ToolBox, commonly known as LCOMMTP.ARC, but you may
  173.               not modify in any way, the contents of the shareware package.
  174.  
  175.           4.  Information Technology grants to ASP-approved vendors only the
  176.               right to charge a duplication fee, not to exceed $8.00 for
  177.               providing a copy of the shareware version of the product.  No
  178.               other individual or vendor is permitted to charge a fee for
  179.               providing such a copy without the express, written consent of
  180.               Information Technology, Ltd,
  181.  
  182.           5.  You may not redistribute, in any form, the source code for the
  183.               LiteComm-TP ToolBox.  Further, you may not translate the source
  184.               code for the LiteComm-TP ToolBox into any other language
  185.               without the express, written consent of Information Technology,
  186.               Ltd.
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.                                     Page 3
  194.             Copyright (c) 1987, 88, 89 Information Technology, Ltd.
  195.  
  196.  
  197.                    LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL
  198.  
  199.  
  200.  
  201.           6.  Information Technology reserves the right to change both the
  202.               LiteComm-TP ToolBox or its documentation without prior notice,
  203.               with no obligation to you, the licensee.
  204.  
  205.           7.  You agree that any disputes arising from this license will be
  206.               subject to the laws of the state of Rhode Island.
  207.  
  208.           8.  You agree to hold the developer and distributors of the
  209.               LiteComm-TP ToolBox harmless for any damages, either direct or
  210.               consequential, that might arise from the use of this product.
  211.  
  212.           9.  You acknowledge that the LiteComm-TP ToolBox, libraries, source
  213.               code, and documentation are the copyrighted property of
  214.               Information Technology, Ltd.
  215.  
  216.          10.  By your use of the LiteComm-TP ToolBox, you acknowledge that
  217.               you have read, and understand the terms and conditions of this
  218.               license.
  219.  
  220.  
  221.        2.2  WARRANTY
  222.        2.2  WARRANTY
  223.  
  224.  
  225.        The LiteComm-TP ToolBox is distributed as-is and without warranty,
  226.        including, but not limited to, the implied warranties of
  227.        merchantability and fitness for a particular purpose.
  228.  
  229.        Information Technology, Ltd does warrant the distribution media for a
  230.        period of 30 days.  During that period, Information Technology, Ltd
  231.        will replace the distribution media or provide a refund at its option.
  232.  
  233.  
  234.        2.3  REGISTERING YOUR COPY
  235.        2.3  REGISTERING YOUR COPY
  236.  
  237.  
  238.        Registration of your copy of the LiteComm-TP ToolBox provides you with
  239.        several benefits:
  240.  
  241.           1.  Puts you on our mailing list for low-cost updates,
  242.               enhancements, and alert bulletins when they occur.
  243.  
  244.           2.  Gives you access to telephone support. Sorry, but we cannot
  245.               provide support by telephone to unregistered user's of the
  246.               ToolBox. Unregistered users can leave EMAIL on Compuserve to
  247.               70166,1152 and on GEnie to I.TECH. We will respond to EMAIL on
  248.               an as-available basis.
  249.  
  250.           3.  Helps to further the shareware concept.
  251.  
  252.        You can order directly from us or from the Public (Software) Library
  253.        1-800-2424-PSL (for orders only. For information call 1-713-665-7017)
  254.        or by writing PSL; P.O.Box 35705; Houston, TX 77235-5705.  MC/Visa
  255.        Accepted.
  256.  
  257.  
  258.  
  259.  
  260.                                     Page 4
  261.             Copyright (c) 1987, 88, 89 Information Technology, Ltd.
  262.  
  263.  
  264.                    LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL
  265.  
  266.  
  267.  
  268.        If you want to order directly from us, print the file REG.FRM and
  269.        follow the instructions there.
  270.  
  271.  
  272.        2.4  NOTE
  273.        2.4  NOTE
  274.  
  275.  
  276.        LiteComm-TP is a package undergoing continuing development.
  277.        Registered users of the product receive, in addition to the fully-
  278.        functional base package, units that provide protocol engines
  279.        supporting XModem, XModem-1K, and YModem protocols.
  280.  
  281.        We plan to follow these with similar engines for CompuServe B, Telink,
  282.        and other protocols. These engines, as they are released, will only be
  283.        made available to registered ToolBox users. The shareware version, as
  284.        enhanced but without the protocol engines, will continue to be
  285.        offered.
  286.  
  287.  
  288.  
  289.  
  290.  
  291.  
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.                                     Page 5
  327.             Copyright (c) 1987, 88, 89 Information Technology, Ltd.
  328.  
  329.  
  330.                    LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL
  331.  
  332.  
  333.  
  334.  
  335.  
  336.  
  337.  
  338.  
  339.  
  340.  
  341.  
  342.  
  343.  
  344.  
  345.  
  346.  
  347.  
  348.  
  349.  
  350.  
  351.  
  352.  
  353.  
  354.  
  355.  
  356.  
  357.  
  358.  
  359.  
  360.  
  361.  
  362.  
  363.  
  364.  
  365.  
  366.  
  367.  
  368.  
  369.  
  370.  
  371.  
  372.  
  373.  
  374.  
  375.  
  376.  
  377.  
  378.  
  379.  
  380.  
  381.  
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.                                     Page 6
  392.             Copyright (c) 1987, 88, 89 Information Technology, Ltd.
  393.  
  394.  
  395.                    LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403.  
  404.  
  405.                                      Chapter 3
  406.                                      Chapter 3
  407.  
  408.                               Serial Port Fundamentals
  409.                               Serial Port Fundamentals
  410.  
  411.  
  412.        3.1  The 8250 UART family
  413.        3.1  The 8250 UART family
  414.  
  415.  
  416.           This portion of the manual provides you with some details about the
  417.           working of the 8250 (and related) UART'S, the basic component of
  418.           your system's serial port.  Some close compatibles use enhanced
  419.           versions of this chip, such as the Intel 16450.  LiteComm is known
  420.           to work successfully with such devices.  If you have questions
  421.           about the kind of serial port you are using, refer to the
  422.           manufacturer's documentation.  If your serial port does not use an
  423.           8250 or similar chip, LiteComm will not function.
  424.  
  425.  
  426.        3.2  Purpose of the port
  427.        3.2  Purpose of the port
  428.  
  429.  
  430.           The purpose of the serial port is to convert information from the
  431.           form in which it is used within your system, to a form that can be
  432.           easily used outside your system.  Modern computers, by design, are
  433.           parallel in nature.  By this we mean that information travels
  434.           through the computer's circuitry as whole units or as multiples of
  435.           whole units. In the IBM PC and related systems, information travels
  436.           as bytes (8 bits at a time), as words (16 bits at a time), or, on
  437.           80386 based systems, as double words (32 bits at a time).
  438.  
  439.           Within the computer, such arrangements are convenient and fast. But
  440.           when the computer must transfer information to an external device,
  441.           the problem of data path width is introduced.  To provide a true,
  442.           parallel path between the computer and external devices, there
  443.           would have to be, at a minimum, enough data lines or circuits
  444.           between the two to satisfy the data path.  For most modern computer
  445.           systems, this would mean a minimum of 8 data lines, not counting
  446.           any additional control information that might also be required.
  447.           For certain newer systems, the requirement might be for as many as
  448.           32 data lines.  In effect, it might be necessary to have several
  449.           different versions of a device, dependent upon the data path width
  450.           of the computer to which it is connected.
  451.  
  452.           The purpose of a serial port is to convert the information from its
  453.           internal, parallel form, to a more common, external form and back
  454.           again.  By using such an approach, we simplify the interconnection
  455.           of devices, reducing information to its lowest common denominator,
  456.           the bit. And it allows us to transfer information 1 bit at a time,
  457.  
  458.  
  459.  
  460.                                     Page 7
  461.             Copyright (c) 1987, 88, 89 Information Technology, Ltd.
  462.  
  463.  
  464.                    LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL
  465.  
  466.  
  467.  
  468.           using a single data path, between devices. The real beauty of this
  469.           approach is that, by 'agreeing' on how this external form appears,
  470.           each device can hide the details of how it works, and still
  471.           accomplish the required task.
  472.  
  473.  
  474.        3.3  Internal Details
  475.        3.3  Internal Details
  476.  
  477.  
  478.           In this section we discuss the fundamental working of serial ports
  479.           as they are implemented of the IBM PC and close compatible systems.
  480.           It is not essential that you understand this material thoroughly to
  481.           be successful with LiteComm. However, it may help to answer some of
  482.           the more important questions that may arise as you proceed with
  483.           your development.
  484.  
  485.        3.3.1  The Interrupt Connection
  486.        3.3.1  The Interrupt Connection
  487.  
  488.           The PC is an interrupt driven system. This is a sophisticated way
  489.           of saying that the PC can 'pay attention' to a number of internal
  490.           devices without the necessity of having to check on them
  491.           periodically.
  492.  
  493.           When we describe interrupts to clients, we use the school room as a
  494.           metaphor. Think of a teacher lecturing to a group of students
  495.           during a class.  The teacher knows that, on occasion, one or more
  496.           students may not understand the material that is being presented.
  497.           So the teacher has the choice of either asking each student
  498.           periodically if they understand or permitting the students to raise
  499.           a hand to ask a question.  As you can imagine, stopping the class
  500.           to 'poll' each student will waste valuable time, particularly if no
  501.           one wants to ask a question. Not only is it wasteful of time, but
  502.           the last student polled may have forgotten the question he or she
  503.           wanted to ask by the time the teacher gets to him.  If the teacher
  504.           permits students to 'interrupt' his lecture by raising a hand, much
  505.           less time is wasted, but the teacher has to be careful to identify
  506.           each raised hand by name and answer the question quickly and
  507.           accurately, lest some student forget his question or looses
  508.           interest altogether.
  509.  
  510.           The internal working of most modern computers is identical to the
  511.           teacher that permits hand raising.  The computer focuses on the
  512.           task at hand, stopping only to identify and pay attention to
  513.           devices when they signal that they require this attention.  So much
  514.           for the hardware end of things.  The PC has this same capability.
  515.           But at least some of the work that has to be done requires software
  516.           in a general purpose computer, otherwise the computer wouldn't be
  517.           general purpose.
  518.  
  519.           The serial port on the PC is no less capable of asking for
  520.           attention from the computer, at least from the standpoint of
  521.           hardware.  But, for whatever the reason, MS-DOS and PC-DOS do not
  522.           provide the needed software to exploit the full capabilities of the
  523.           serial port. OS/2 does provide such support, we are told, but, at
  524.  
  525.  
  526.  
  527.                                     Page 8
  528.             Copyright (c) 1987, 88, 89 Information Technology, Ltd.
  529.  
  530.  
  531.                    LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL
  532.  
  533.  
  534.  
  535.           least for the foreseeable future, its an MS-DOS world. On PC's and
  536.           true compatibles, the only support for the serial port that is
  537.           provided is through the system's ROM BIOS.  And that support is
  538.           only for the polled mode of operation.
  539.  
  540.           The method by which 80x86 family systems, of which the PC is a
  541.           part, is elegant in its simplicity.  When a device needs the
  542.           attention of the system, its asserts a control signal and
  543.           identifies itself with a number ranging from 0 to 255. On the basic
  544.           PC, the numbers used actually range from 8 through 15 decimal.  The
  545.           identification is translated to a memory location by multiplying
  546.           the identification by 4, and the system simulates a special form of
  547.           a call to the routine whose address is stored at that location.
  548.           Since it is impossible to predict when a device will require
  549.           attention, the full address of the routine is stored, both segment
  550.           and offset, hence the 4.
  551.  
  552.           Once the routine, called the Interrupt Service Routine or ISR is
  553.           invoked, it has a duty to save the state of the system when the
  554.           interrupt occurred, take care of the interrupt as quickly as
  555.           possible, and return control to the interrupted process.  But it
  556.           must also be aware that, while it is doing its work, other, more
  557.           important devices may require attention, too.
  558.  
  559.           One such device that is likely to require attention is the system
  560.           clock which ticks roughly 18 times per second.  In part, the PC
  561.           makes provision for this by prioritizing the interrupt scheme.  The
  562.           ISR must allow for this by re- enabling the interrupt control
  563.           system as rapidly as it is practical to do so.  The PC's interrupt
  564.           structure, if left undisturbed, will prevent interrupts of the same
  565.           or lower priority from occurring. To help your organize your
  566.           thoughts, the standard identification for the first two serial
  567.           ports on the system are 12 (0C) and 11 (0B) for ports 1 and 2
  568.           respectively.
  569.  
  570.           As you can see, dealing with the PC's interrupt structure is not
  571.           for the faint of heart.  It requires a significant amount of
  572.           knowledge, and close attention to detail.  With LiteComm, these
  573.           details have already been taken care of for you.  You are free to
  574.           focus on your application, treating the serial port in much the
  575.           same way that you would any DOS file.
  576.  
  577.        3.3.2  The Programmable Port Registers
  578.        3.3.2  The Programmable Port Registers
  579.  
  580.           The 8250 port, and its close relatives, are fully programmable.
  581.           You are fortunate that LiteComm has already taken care of the
  582.           intricacies of this programming. But some additional information
  583.           about each of the registers used in the serial port may be of use
  584.           when you are attempting to communicate with an external device. For
  585.           the sake of this discussion, we use the basic register numbers,
  586.           although the register number that is employed in programming is
  587.           actually the register number referenced below used as an offset to
  588.           a base port number. In the case of COM1 (port 1), this base is
  589.           3F8(hexadecimal).
  590.  
  591.  
  592.  
  593.                                     Page 9
  594.             Copyright (c) 1987, 88, 89 Information Technology, Ltd.
  595.  
  596.  
  597.                    LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL
  598.  
  599.  
  600.  
  601.           3.3.2.1  register 0 - transmit/receive
  602.           3.3.2.1  register 0 - transmit/receive
  603.  
  604.           In normal operation, individual characters are read from register 0
  605.           when the become available, and are written to register 0 when the
  606.           transmitter portion of the 8250 is ready to accept a character.
  607.  
  608.           3.3.2.2  register 0 - baud rate selection
  609.           3.3.2.2  register 0 - baud rate selection
  610.  
  611.           During initialization, register 0 is used as part of the mechanism
  612.           that sets baud rate.  During this process, register 0 and its
  613.           companion register 1 are used to specify the baud rate divisor (not
  614.           the actual baud rate). The baud rate divisor is a value which, when
  615.           divided into a given, preset constant, yields the desired baud
  616.           rate.  To use registers 0 and 1 to set the baud rate, access to
  617.           this mode must be first enabled by writing a value of 80H to
  618.           register 3, the line control register.  Once access is enabled, the
  619.           least significant byte (LSB) of the divisor is written to register
  620.           0; the most significant byte is written to register 1.  Access to
  621.           the normal modes of registers 0 and 1 are re- enabled by writing
  622.           any value less than 80H to the line control register.  Of course,
  623.           only certain values less than 80H would be meaningful (see the line
  624.           control register description below).
  625.  
  626.           3.3.2.3  register 1 - interrupt enable
  627.           3.3.2.3  register 1 - interrupt enable
  628.  
  629.           Values written to register 1 control which conditions will cause
  630.           the 8250 to interrupt the system. There are four possible
  631.           conditions that can cause interrupts:
  632.  
  633.              1.  A character has been received (RDI)
  634.  
  635.              2.  The transmitter is ready to send a character (TDI)
  636.  
  637.              3.  An error or BREAK signal has been detected (ERI)
  638.  
  639.              4.  A modem status  signal has changed (MSI)
  640.  
  641.           The designations, in parentheses, are for our purposes only. They
  642.           are not 'standard' designations. To enable a particular type of
  643.           interrupt, you must set the corresponding bit in a byte to a 1,
  644.           then write the byte to register 1.  To reset (ignore) the
  645.           condition, set the corresponding bit to 0.  The diagram that
  646.           follows shows the bit positions the correspond to the various
  647.           conditions described above.
  648.  
  649.           +------+------+------+------+------+------+------+------+
  650.           |      |      |      |      |      |      |      |      |
  651.           |  N/A |  N/A |  N/A |  N/A |Modem |Error/| Xmit | Recv |
  652.           |      |      |      |      |Status|Break |Ready | Char |
  653.           +------+------+------+------+------+------+------+------+
  654.               7     6      5      4       3      2      1      0
  655.                         Figure 3.1: Register 1 Bit Definitions
  656.                         Figure 3.1
  657.  
  658.  
  659.  
  660.  
  661.  
  662.                                     Page 10
  663.             Copyright (c) 1987, 88, 89 Information Technology, Ltd.
  664.  
  665.  
  666.                    LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL
  667.  
  668.  
  669.  
  670.           3.3.2.4  register 1 - baud rate selection
  671.           3.3.2.4  register 1 - baud rate selection
  672.  
  673.           See the description under register 0, baud rate selection.
  674.  
  675.           3.3.2.5  register 2 - interrupt identification
  676.           3.3.2.5  register 2 - interrupt identification
  677.  
  678.           Register 2, in normal operation, acts as a companion to register 1.
  679.           Register 1 determines the conditions that can cause an interrupt.
  680.           Register 2 is used to determine which condition actually caused the
  681.           interrupt, when more than one condition has been enabled.  Only
  682.           least significant 3 bits of the register are actually employed.
  683.           See the diagram of register 2 below.
  684.  
  685.           +------+------+------+------+------+------+------+------+
  686.           |      |      |      |      |      |      |      |      |
  687.           |  N/A |  N/A |  N/A |  N/A |  N/A |  see |below |  Int |
  688.           |      |      |      |      |      |      |      | pend |
  689.           +------+------+------+------+------+------+------+------+
  690.               7      6      5      4      3      2      1      0
  691.                         Figure 3.2: Register 2 Bit Definitions
  692.                         Figure 3.2
  693.  
  694.           Since it is possible, even likely, that more than one condition may
  695.           occur at the same time, bit 0 is used to determine whether all
  696.           conditions that currently exist have been handled.  When bit 0 has
  697.           a value of 0 (yes zero), there are conditions waiting to be
  698.           handled.  When bit 0 has a value of 1, all outstanding conditions
  699.           have been handled.  Bits 2 and 1 taken together identify the actual
  700.           cause of the interrupt.
  701.  
  702.           Again, because of the multiple conditions which may occur, the 8250
  703.           presents the conditions in a prioritized order.  When bits 2 and 1
  704.           have a value of 3 (the most important), an ERI condition has been
  705.           identified. The actual error is determined by reading the line
  706.           status register(register 5). Reading this register also clears the
  707.           condition.
  708.  
  709.           When a value of 2 is present, an RDI condition has occurred, and a
  710.           character should be read. from port 0. If the character is not read
  711.           quickly enough, a data overrun error may occur, indicating that a
  712.           character was lost.
  713.  
  714.           When bits 2 and 1 have a value of 1, a TDI condition has occurred
  715.           and a character may be written to register 0.
  716.  
  717.           A value of zero in bits 2 and 1(least important) indicates that one
  718.           or more of the modem status lines (so called) have changed. The
  719.           condition is cleared by reading the contents of the modem status
  720.           register, register 6.
  721.  
  722.           3.3.2.6  register 3 - line control
  723.           3.3.2.6  register 3 - line control
  724.  
  725.           The line control register provides the means for setting those
  726.           values that affect the way in which the serial port appears to the
  727.           outside world.  It is through this register that character length,
  728.  
  729.  
  730.  
  731.                                     Page 11
  732.             Copyright (c) 1987, 88, 89 Information Technology, Ltd.
  733.  
  734.  
  735.                    LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL
  736.  
  737.  
  738.  
  739.           parity, and other significant values are established. Indirectly,
  740.           register 3 also plays a role in setting the speed (baud rate) of
  741.           the port. (See the description of registers 0 and 1 above.)
  742.  
  743.           +------+------+------+------+------+------+------+------+
  744.           | Baud |      |      |      |      |      |      |      |
  745.           |  Div | Send |Force |Parity|Enable| Stop |  Character  |
  746.           |Enable|Break |Parity| Type |Parity| Bits |    Length   |
  747.           +------+------+------+------+------+------+------+------+
  748.               7     6      5      4       3      2      1      0
  749.                         Figure 3.3: Register 3 Bit Definitions
  750.                         Figure 3.3
  751.  
  752.           3.3.2.7  register 4 - modem control
  753.           3.3.2.7  register 4 - modem control
  754.  
  755.           The modem control register permits control of the two modem-
  756.           related signals that the serial port generates as an output.  The
  757.           signals are RTS and DTR.
  758.  
  759.           These two signals are called 'handshaking' signals, since they, in
  760.           part, help a connected device determine the state of the
  761.           connection.  You should be aware that although these signals were
  762.           originally designated to be used in a specific fashion,
  763.           manufacturers of specific devices have used them to meet their own
  764.           needs. Your success or failure in dealing with any specific device
  765.           may depend, in part, on your understanding of how the device's
  766.           manufacturer uses these signals. LiteComm provides you the means
  767.           for manipulating these signals in a variety of ways.
  768.  
  769.           You will notice in the register 4 diagram, below that some
  770.           additional positions are identified.
  771.  
  772.           +------+------+------+------+------+------+------+------+
  773.           |      |      |      |      |      |      |      |      |
  774.           |  N/A |  N/A |  N/A |Enable| OUT2 |  N/A |Enable|Enable|
  775.           |      |      |      |Loopbk|(reqd)|      | RTS  | DTR  |
  776.           +------+------+------+------+------+------+------+------+
  777.               7     6       5     4      3       2      1      0
  778.                         Figure 3.4: Register 4 Bit Definitions
  779.                         Figure 3.4
  780.  
  781.           LiteComm controls all of these additional positions for your
  782.           benefit.  Only one deserves mention, the position labeled OUT2.  It
  783.           is necessary for this position to have a value of 1 for the serial
  784.           port to function as an interrupting device. Since LiteComm relies
  785.           on interrupts to perform it's job, it insures that this position is
  786.           always set correctly.
  787.  
  788.           3.3.2.8  register 5 - line status
  789.           3.3.2.8  register 5 - line status
  790.  
  791.           The line status register is read normally when an ERI condition
  792.           occurs.  Each bit of the character returned when the port is read
  793.           has significance, as shown in the accompanying diagram. Using the
  794.           appropriate functions in LiteComm, you can interrogate the value in
  795.           this register, and test for the various conditions using the
  796.           LiteComm- provided definitions. Note that, due to the special
  797.  
  798.  
  799.  
  800.                                     Page 12
  801.             Copyright (c) 1987, 88, 89 Information Technology, Ltd.
  802.  
  803.  
  804.                    LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL
  805.  
  806.  
  807.  
  808.           nature of the BREAK signal, LiteComm treats this one condition as a
  809.           separate entity.
  810.  
  811.           +------+------+------+------+------+------+------+------+
  812.           |      |Shift | Hold |      |      |      |      |      |
  813.           | Time |Reg   | Reg  | Recd |Frame |Parity| Data | Char |
  814.           | Out  |Empty |Empty |Break |Error |Error |OvrRun| Recd |
  815.           +------+------+------+------+------+------+------+------+
  816.               7     6      5      4      3       2      1      0
  817.                         Figure 3.5: Register 5 Bit Definitions
  818.                         Figure 3.5
  819.  
  820.           3.3.2.9  register 6 - modem status
  821.           3.3.2.9  register 6 - modem status
  822.  
  823.           Just as the serial port can generate certain 'handshaking' signals,
  824.           it can also read, and report on the status of similar signals that
  825.           are generated by an external device.  In their original form, these
  826.           signals had special significance when a terminal was connected to a
  827.           modem. We refer you to our comments, above, about present day use
  828.           of the handshaking signals.
  829.  
  830.           One special note is appropriate here.  The modem status register
  831.           actually provides two types of information.  The most significant 4
  832.           bits (see the diagram) show the current state of the 4 covered
  833.           signals.  The least significant 4 bits indicate which, if any, of
  834.           the signals have changed state (from zero to one, or vice-versa),
  835.           since the last time the register was interrogated.  LiteComm
  836.           updates its internal tables with this value in real-time, and
  837.           reports the results when asked to do so.  You can test the signals
  838.           individually or in combination using the LiteComm-provided
  839.           definitions.
  840.  
  841.           +------+------+------+------+------+------+------+------+
  842.           |  DCD |  RI  |  DSR |  CTS |      |      |      |      |
  843.           | carr | ring |data  |clr to|DELTA |DELTA |DELTA |DELTA |
  844.           |detect|indic |set rd| send | DCD  |  RI  | DSR  | CTS  |
  845.           +------+------+------+------+------+------+------+------+
  846.               7      6      5      4     3       2      1      0
  847.  
  848.  
  849.        3.4  The LiteComm Connection
  850.        3.4  The LiteComm Connection
  851.  
  852.  
  853.                         Figure 3.6: Register 6 Bit Definitions
  854.                         Figure 3.6
  855.  
  856.           In the design of LiteComm, we have purposely 'hidden' many of the
  857.           underlying details we presented above. In many cases, you will have
  858.           little use for this additional information. This is particularly
  859.           true of most of the applications with which come into contact.  In
  860.           fact, in the majority of applications, you will probably open the
  861.           port or ports, set the necessary parameters and modem control
  862.           signals, and do nothing more than read and write characters using
  863.           one or more of the LiteComm functions.  The beauty of LiteComm's
  864.           design is that its high degree of granularity doesn't force you to
  865.           pay the price of dragging along functions that you are not using.
  866.  
  867.  
  868.  
  869.                                     Page 13
  870.             Copyright (c) 1987, 88, 89 Information Technology, Ltd.
  871.  
  872.  
  873.                    LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL
  874.  
  875.  
  876.  
  877.           The information that we presented above will help you when  it is
  878.           necessary to communicate with a device that requires special
  879.           handshaking considerations, such as a cash drawer.  You may also
  880.           need some of the information we presented if you intend to use
  881.           serial ports beyond COM2 (serial port 2).
  882.  
  883.           Finally, by presenting the information that we have supplied, we
  884.           hope to gain a more informed user.  Communications programming is
  885.           not the black art that some would have you believe, although it can
  886.           easily seem that way at times.  Of all of the calls we receive who
  887.           need  questions answered, more than 75 per cent could have been
  888.           answered by the caller himself with a more thorough understanding
  889.           of the underlying concepts and rules.
  890.  
  891.  
  892.        3.5  TOOLBOX NOTES AND WARNINGS
  893.        3.5  TOOLBOX NOTES AND WARNINGS
  894.  
  895.  
  896.           Before you can send or receive information on a serial port using
  897.           the ToolBox, you must use the open function to enable the line.
  898.           This function initializes the 8250 UART with the correct
  899.           parameters, and introduces the UART into the interrupt structure of
  900.           the PC. The ToolBox will detect, and report, any errors that you
  901.           may make in selecting the port or specifying the initial
  902.           parameters. The ToolBox cannot and will not detect an attempt to
  903.           open a nonexistent serial port.
  904.  
  905.           The ToolBox interfaces directly with the interrupt structure of the
  906.           PC. It is critical before exiting a program that has opened a
  907.           serial port that the serial port is closed with the close function.
  908.           Because a program may terminate abnormally, the open function
  909.           installs an exit routine that will automatically close any open
  910.           ports. Good programming practice demands, however, the your program
  911.           should close the ports explicitly.  By so doing, you may avoid
  912.           problems in the future if we find it necessary to remove the auto-
  913.           close functionality. Further, the auto-close functionality drops
  914.           all modem handshaking signals absolutely, while an explicit close
  915.           can decide whether or not to drop these signals. You should review
  916.           Borland's documentation about installing exit routines in the Turbo
  917.           PASCAL Reference, and you should review the documentation for
  918.           CommClose for further information about the features of that
  919.           procedure.
  920.  
  921.           Failure of the open function can be the result of either improper
  922.           parameters to the open function, or insufficient memory available
  923.           to allocate the requested buffers and related control structures
  924.           for the port. Memory for the transmit and receive buffers as well
  925.           as the port control block are allocated from the heap. It is your
  926.           responsibility to insure that adequate memory is available for this
  927.           purpose.
  928.  
  929.           The 8250 serial chip and its descendants will not transmit
  930.           information until, at a minimum, the DTR (Data Terminal Ready)
  931.           signal is asserted. The ToolBox will, at your option, assert both
  932.  
  933.  
  934.  
  935.                                     Page 14
  936.             Copyright (c) 1987, 88, 89 Information Technology, Ltd.
  937.  
  938.  
  939.                    LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL
  940.  
  941.  
  942.  
  943.           the DTR and RTS signals when you open the port.  If you do not
  944.           select this option  you must use the SetModem function to assert
  945.           (raise) this signal.  In addition, some modems and other devices
  946.           may require you to assert the RTS (Request To Send) signal before
  947.           they will respond to data.  The use of this, and other handshaking
  948.           signals is HIGHLY hardware-dependant.  The ToolBox provides all the
  949.           functionality necessary for you to implement virtually any
  950.           handshaking scheme that might be required.
  951.  
  952.           Due to the use of all available interrupt modes of the 8250, one
  953.           user has discovered an unusual set of circumstances that can be
  954.           troublesome.  If the 8250 chip detects an error condition, such as
  955.           a parity error, framing error, or data overrun error, it causes an
  956.           interrupt to which the ToolBox will respond.  If these errors occur
  957.           frequently enough, the ToolBox code will spend too much time
  958.           handling the errors, and lose characters as a result, causing
  959.           additional errors.  If you encounter a situation in which your
  960.           application appears to behave erratically, especially at higher
  961.           speeds, investigate the following table.
  962.  
  963.                          Table 3.1: Possible Error Conditions
  964.                          Table 3.1
  965.  
  966.               -  Is the cabling to the other device sound and solidly
  967.                  connected.
  968.  
  969.               -  Are any of the signals in the cable 'floating' or are they
  970.                  all properly terminated.
  971.  
  972.               -  Is the other device known to be functioning properly. We
  973.                  have encountered situations in which a serial port on some
  974.                  devices tend to be sloppy in terms of voltage levels, bit
  975.                  timings, and similar problems.  Any or all of these
  976.                  situations can cause the erratic operation to which we
  977.                  referred.
  978.  
  979.           Unless you are very familiar with the interrupt structure of the
  980.           PC, do not attempt to manipulate the interrupt enable flag outside
  981.           of the ToolBox. The ToolBox sets and clears the interrupt enable
  982.           flag at appropriate times and assumes that it has sole control over
  983.           the flag.
  984.  
  985.  
  986.  
  987.  
  988.  
  989.  
  990.  
  991.  
  992.  
  993.  
  994.  
  995.  
  996.  
  997.  
  998.  
  999.  
  1000.  
  1001.                                     Page 15
  1002.             Copyright (c) 1987, 88, 89 Information Technology, Ltd.
  1003.  
  1004.  
  1005.                    LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL
  1006.  
  1007.  
  1008.  
  1009.  
  1010.  
  1011.  
  1012.  
  1013.  
  1014.  
  1015.  
  1016.  
  1017.  
  1018.  
  1019.  
  1020.  
  1021.  
  1022.  
  1023.  
  1024.  
  1025.  
  1026.  
  1027.  
  1028.  
  1029.  
  1030.  
  1031.  
  1032.  
  1033.  
  1034.  
  1035.  
  1036.  
  1037.  
  1038.  
  1039.  
  1040.  
  1041.  
  1042.  
  1043.  
  1044.  
  1045.  
  1046.  
  1047.  
  1048.  
  1049.  
  1050.  
  1051.  
  1052.  
  1053.  
  1054.  
  1055.  
  1056.  
  1057.  
  1058.  
  1059.  
  1060.  
  1061.  
  1062.  
  1063.  
  1064.  
  1065.  
  1066.                                     Page 16
  1067.             Copyright (c) 1987, 88, 89 Information Technology, Ltd.
  1068.  
  1069.  
  1070.                    LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL
  1071.  
  1072.  
  1073.  
  1074.  
  1075.  
  1076.  
  1077.  
  1078.  
  1079.  
  1080.                                      Chapter 4
  1081.                                      Chapter 4
  1082.  
  1083.                                 LITECOMM-TP HISTORY
  1084.                                 LITECOMM-TP HISTORY
  1085.  
  1086.  
  1087.        4.1  VERSION 3.0
  1088.        4.1  VERSION 3.0
  1089.  
  1090.  
  1091.           Version 3 of LiteComm-TP was a departure from the precedent
  1092.           established in previous version.  In versions 1 and 2, LiteComm-TP
  1093.           was implemented strictly in Turbo-PASCAL.  The advantages to a
  1094.           strictly high-level language implementation are obvious...as is the
  1095.           drawback of speed.  In version 3.0, the kernel interrupt handlers
  1096.           were re-implemented in assembly language.  In addition, version 3
  1097.           contained some fundamental function additions that will be of use
  1098.           to those attempting to develop bulletin board systems.  In
  1099.           addition, we feel that these routines will serve as a tutorial on
  1100.           how to approach certain communications problems.
  1101.  
  1102.           With version 3, we also included interrupt chaining for COM3 and
  1103.           COM4, that users of the C version of LiteComm have enjoyed since
  1104.           version 2.
  1105.  
  1106.  
  1107.        4.2  NEW IN VERSION 5
  1108.        4.2  NEW IN VERSION 5
  1109.  
  1110.  
  1111.           There will be no version 4 of the LiteComm-TP ToolBox.  We have
  1112.           opted to bring out the next revision as Revision 5 to maintain
  1113.           consistency with the C version.
  1114.  
  1115.           Version 5 features significant enhancement to the kernel interrupt
  1116.           handlers and supporting code, resulting in higher baud rates on
  1117.           older, slower systems.  In addition, the tighter code should result
  1118.           in smaller applications.
  1119.  
  1120.           And with version 5, we have also upgraded and enhanced the XModem
  1121.           and YModem protocol engines with additional capabilities.  If you
  1122.           are interested in the protocol engines, see the separate
  1123.           documentation for them.  Note that the protocol engines are a part
  1124.           of the registered version of LiteComm-TP only.
  1125.  
  1126.           Due to a lack of interest in Windowed XModem, we have decided to
  1127.           drop support for that engine, in favor of the other, more advanced
  1128.           protocols.  For your convenience, we will continue to provide the
  1129.           source code for the WXModem engine, but we cannot answer questions
  1130.           or support it.
  1131.  
  1132.  
  1133.  
  1134.  
  1135.                                     Page 17
  1136.             Copyright (c) 1987, 88, 89 Information Technology, Ltd.
  1137.  
  1138.  
  1139.                    LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL
  1140.  
  1141.  
  1142.  
  1143.           We had originally planned to include a ZModem protocol engine as
  1144.           part of version 5.  While that engine is nearing completion, we did
  1145.           not want to hold up the newest version of the main package. Nor did
  1146.           we want to release something like ZModem until we are satisfied
  1147.           with its performance. ZModem is coming in the next major release.
  1148.  
  1149.  
  1150.  
  1151.  
  1152.  
  1153.  
  1154.  
  1155.  
  1156.  
  1157.  
  1158.  
  1159.  
  1160.  
  1161.  
  1162.  
  1163.  
  1164.  
  1165.  
  1166.  
  1167.  
  1168.  
  1169.  
  1170.  
  1171.  
  1172.  
  1173.  
  1174.  
  1175.  
  1176.  
  1177.  
  1178.  
  1179.  
  1180.  
  1181.  
  1182.  
  1183.  
  1184.  
  1185.  
  1186.  
  1187.  
  1188.  
  1189.  
  1190.  
  1191.  
  1192.  
  1193.  
  1194.  
  1195.  
  1196.  
  1197.  
  1198.  
  1199.  
  1200.                                     Page 18
  1201.             Copyright (c) 1987, 88, 89 Information Technology, Ltd.
  1202.  
  1203.  
  1204.                    LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL
  1205.  
  1206.  
  1207.  
  1208.  
  1209.  
  1210.  
  1211.  
  1212.  
  1213.  
  1214.                                      Chapter 5
  1215.                                      Chapter 5
  1216.  
  1217.                                     BEYOND COM2
  1218.                                     BEYOND COM2
  1219.  
  1220.  
  1221.        5.1  THE TOOLBOX METHODOLOGY
  1222.        5.1  THE TOOLBOX METHODOLOGY
  1223.  
  1224.  
  1225.           In the design of the original PC, and in subsequent variations such
  1226.           as the PC/AT, there were only provision for two serial ports. Many
  1227.           manufacturers of add-in products, both serial ports and internal
  1228.           modems have added the capability to support 1 or more additional
  1229.           ports beyond the COM2 limit. Generally, this can cause problems in
  1230.           the PC since there is no room in the interrupt request scheme for
  1231.           additional levels of interrupts, and there are no designated
  1232.           interrupt vectors for other additional ports.
  1233.  
  1234.           The ToolBox approach to resolving these issues is to permit the
  1235.           programmer a degree of control over the parameters that govern the
  1236.           interrupt mechanism for COM3 and COM4. Specifically, these
  1237.           parameters are:
  1238.  
  1239.              1.  The interrupt request (IRQ) bit that is used to mask the
  1240.                  8259 interrupt controller.
  1241.  
  1242.              2.  The interrupt vector number (not address) to which the port
  1243.                  is attached.
  1244.  
  1245.              3.  The base i/o register for the port itself. Of course, it is
  1246.                  assumed that the port is based upon the 8250 UART or
  1247.                  compatible device.
  1248.  
  1249.           Before you attempt to use COM3 and/or COM4, you must determine from
  1250.           the port's documentation, the appropriate values for these three
  1251.           parameters. As distributed, the ToolBox assumes the following:
  1252.  
  1253.                        Table 5.1: COM3 and COM4 Default Settings
  1254.                        Table 5.1
  1255.  
  1256.                                            COM3             COM4
  1257.                                            ____             ____
  1258.  
  1259.           IRQ Bit                          4                3
  1260.           Vector #                         0Ch              0Bh
  1261.           Base Reg                         3E8h             2E8h
  1262.  
  1263.           You may change any or all of these values by using the PortChange
  1264.           function described below, but only before you open the port with
  1265.           CommOpen. Once the port has been opened, PortChange is ineffective,
  1266.           and PortChange will not work at all on COM1 or COM2.
  1267.  
  1268.  
  1269.  
  1270.                                     Page 19
  1271.             Copyright (c) 1987, 88, 89 Information Technology, Ltd.
  1272.  
  1273.  
  1274.                    LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL
  1275.  
  1276.  
  1277.  
  1278.           At present, LiteComm is not compatible with multiport boards such
  1279.           as the Digiboard.  The structure of these boards generally require
  1280.           additional programming to be used effectively.  If you want to use
  1281.           such a board with LiteComm, please contact us directly for
  1282.           information on custom modifications to LiteComm.  We have performed
  1283.           such modifications for other LiteComm users.
  1284.  
  1285.  
  1286.        5.2  CAUTIONS
  1287.        5.2  CAUTIONS
  1288.  
  1289.  
  1290.           There is an intimate relationship between the IRQ setting and the
  1291.           interrupt vector to which it relates. In the PC, this relationship
  1292.           is controlled, in part, by the 8259 interrupt controller that is
  1293.           set during BIOS initialization.
  1294.           In brief, the BIOS settings for the PC (and most close compatibles)
  1295.           establish IRQ0 as being vector number 08h, and subsequent IRQ
  1296.           levels at increasing vector numbers. These vector numbers (or types
  1297.           in INTEL terms) act as a cpu-directed call table to locations in
  1298.           the lowest 1K of system memory. We can alter how the system
  1299.           responds to a given interrupt by replacing or changing the values
  1300.           in the associated vector position to point to a routine which we
  1301.           supply.
  1302.  
  1303.           COM3 and COM4 share two critical parameters with COM1 and COM2
  1304.           respectively, the IRQ bit and the interrupt vector number. If you
  1305.           use COM3 and COM4 with the default IRQ and Vector values, and you
  1306.           have a COM1 or COM2 installed in your system, LiteComm will chain
  1307.           (share) the interrupt vector. Otherwise you must change both the
  1308.           IRQ and Vector using the PortChange facility. Please remember, the
  1309.           ability for your add-on ports to handle such a change is highly
  1310.           hardware dependent, so check your port's documentation carefully.
  1311.           Failure to do so will result in loss of data at best, and a system
  1312.           lockup at worst.
  1313.  
  1314.           Judging from the questions asked by some users of LiteComm-TP,
  1315.           there is evidently some misunderstanding about using ports beyond
  1316.           COM2, and how this all relates to your hardware. Before you can
  1317.           successfully use COM3 or COM4, you must consider the following:
  1318.  
  1319.              1.  Does the hardware permit a change to the base port and/or
  1320.                  the interrupt vector to which the port responds.  Some
  1321.                  expansion cards will support changing one and not the other,
  1322.                  giving rise to potential hardware conflicts and lost data.
  1323.  
  1324.              2.  Does the hardware permit  reassignment of the IRQ priority.
  1325.                  Some expansion cards permit you to alter the IRQ priority,
  1326.                  some won't. Suffice it to say from the previous discussion
  1327.                  the any change to the IRQ priority must allow a
  1328.                  corresponding change to the interrupt vector number. Without
  1329.                  this capability, reprogramming of the 8259 chip would be
  1330.                  required.
  1331.  
  1332.  
  1333.  
  1334.  
  1335.  
  1336.                                     Page 20
  1337.             Copyright (c) 1987, 88, 89 Information Technology, Ltd.
  1338.  
  1339.  
  1340.                    LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL
  1341.  
  1342.  
  1343.  
  1344.              3.  In fact, many add-on cards permit this dual change simply by
  1345.                  making a single switch or jumper setting. Unfortunately, the
  1346.                  documentation for these cards  generally assume that you are
  1347.                  aware of the dual nature of the IRQ vector relationship, and
  1348.                  may leave you with the impression that you are changing one
  1349.                  and not the other. In most circumstances, this is not the
  1350.                  case.
  1351.  
  1352.           The point to all of this is that LiteComm-TP can only provide as
  1353.           much support as the hardware permits, or is capable of responding
  1354.           to. If you wish to use other than the default base port, interrupt
  1355.           vector, or irq priority for COM3 or COM4, then your expansion card
  1356.           must be capable of supporting the new values; in other words, these
  1357.           values are all hardware-provided, and are recognized by the
  1358.           LiteComm-TP software. If your hardware does not permit changing a
  1359.           value, LiteComm-TP cannot improve the situation.
  1360.  
  1361.           We should, at this point, add one final caution about how interrupt
  1362.           priorities function, and their relationship to the irq bit the you
  1363.           may select. The standard PC permits 8 interrupt priority levels,
  1364.           with the programmable timer having the highest priority, and the
  1365.           parallel printer port having the lowest priority. When an interrupt
  1366.           occurs, the interrupt controller (8259 chip) masks out all other
  1367.           interrupts from the priority of the interrupting device and all
  1368.           lower priority devices.
  1369.           As an aid to making COM3 and COM4 "fit", LiteComm-TP supports
  1370.           interrupt chaining for the COM3 and COM4 ports. If you use COM3 or
  1371.           COM4, when an interrupt occurs, the kernel will attempt to
  1372.           determine if the interrupt was caused by the supported port or from
  1373.           some other source.
  1374.  
  1375.           If the kernel determines that the supported port did not cause the
  1376.           interrupt, an automatic chain to the original interrupt handler for
  1377.           that interrupt level (IRQ level) will take place, allowing you to
  1378.           "patch in" or share the available interrupt vectors.
  1379.  
  1380.           If you intend to use other than the provided defaults, be sure that
  1381.           you understand the interrupt mechanism. The use of the automatic
  1382.           chaining described above can be particularly troublesome under some
  1383.           circumstances, resulting in loss of interrupts and, potentially, a
  1384.           system crash.
  1385.  
  1386.           DO NOT attempt to mix the ToolBox functions with other seemingly-
  1387.           related functions (such as the serial port BIOS routines in Turbo
  1388.           PASCAL).  At least two users have attempted to only use the receive
  1389.           portions of LiteComm, while resorting to the BIOS functions to send
  1390.           characters or adjust port parameters such as baud rate. The
  1391.           results, at best, have been failure of the user's application to
  1392.           function, and, at worst, total system lockup.  This mix of
  1393.           functions is NOT supported and must not be used.  If you attempt
  1394.           such a mix, we cannot help you.
  1395.  
  1396.           One final caution is in order.  One or two users have attempted to
  1397.           trace through the interrupts as they occur using debuggers.  This
  1398.  
  1399.  
  1400.  
  1401.                                     Page 21
  1402.             Copyright (c) 1987, 88, 89 Information Technology, Ltd.
  1403.  
  1404.  
  1405.                    LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL
  1406.  
  1407.  
  1408.  
  1409.           is a risky proposition at best since most debuggers work by tapping
  1410.           into, and disturbing, the interrupt mechanism.  If you feel you
  1411.           must use a debugger, try to stay away from the kernel routines of
  1412.           LiteComm, or use a hardware-based debugger such as Periscope.
  1413.  
  1414.  
  1415.        5.3  OTHER GENERAL NOTES AND WARNINGS
  1416.        5.3  OTHER GENERAL NOTES AND WARNINGS
  1417.  
  1418.  
  1419.           In the discussion of the various functions which follow, you should
  1420.           assume that any references to the 'port' variable refer to a
  1421.           variable or constant that may take on a value of from 1 to 4. No
  1422.           other values are acceptable, and will be rejected.
  1423.  
  1424.           While we feel that LiteComm-TP is written in the most efficient way
  1425.           possible, commensurate with good programming practice, we cannot be
  1426.           responsible for variations caused by hardware configurations or
  1427.           other factors beyond our control. LiteComm-TP has been tested, and
  1428.           is known to perform on, the IBM PC-AT and several compatible
  1429.           systems such as the Zenith and Wyse equivalents. LiteComm-TP has
  1430.           not been tested in environments in which other software, most
  1431.           significantly TSR (terminate and stay resident) modules exist. Some
  1432.           TSR programs that "steal" interrupts for their own purposes present
  1433.           an unfavorable environment to other programs that rely on the
  1434.           interrupt structure of the computer.
  1435.  
  1436.           Should you experience erratic behavior with LiteComm-TP in a TSR-
  1437.           type situation, try executing your application without the TSR
  1438.           module being present. If the problems you have experienced
  1439.           disappear, suspect the TSR module.
  1440.  
  1441.           Conversely, LiteComm-TP provides an excellent vehicle for
  1442.           supporting TSR programs that you may write. Since the package is
  1443.           fully re-entrant, your only concern need be with those aspects of
  1444.           TSR programs are of normal concern, e.g. the non-reentrant nature
  1445.           of DOS. LiteComm-TP never uses DOS functions and may therefore be
  1446.           safely used in a TSR environment.
  1447.  
  1448.  
  1449.        5.4  USE WITH MULTITASKING ENVIRONMENTS
  1450.        5.4  USE WITH MULTITASKING ENVIRONMENTS
  1451.  
  1452.  
  1453.           Some users have made attempts, with varying degrees of success, at
  1454.           using LiteComm in conjunction with multitasking environments such
  1455.           as Quarterdesk's DesqView.  Use of LiteComm in such an environment
  1456.           is certain to be affected by the way in which the multitasking
  1457.           monitor behaves with respect to interrupts.
  1458.  
  1459.           While we recognize that DesqView has achieved a certain measure of
  1460.           popularity among so-called power users, LiteComm was not explicitly
  1461.           designed for such an environment, and its performance may suffer as
  1462.           a result.
  1463.  
  1464.  
  1465.  
  1466.  
  1467.  
  1468.                                     Page 22
  1469.             Copyright (c) 1987, 88, 89 Information Technology, Ltd.
  1470.  
  1471.  
  1472.                    LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL
  1473.  
  1474.  
  1475.  
  1476.        5.5  NOTES ON RING DETECTION
  1477.        5.5  NOTES ON RING DETECTION
  1478.  
  1479.  
  1480.           Several users have reported difficulty in consistently detecting a
  1481.           ringing telephone by checking the state of the RI (Ring Indicator)
  1482.           signal.  The problem seems to be highly dependent on the type of
  1483.           modem that is being used since this signal is provided by the
  1484.           modem, NOT the serial port.  If the duration of the signal is too
  1485.           short, the program may 'miss' the signal as the modem toggles it on
  1486.           and off.  One workaround that has been used successfully is to
  1487.           check the DeltaRI bit that can be obtained from the ModemStatus
  1488.           function, rather that the RI bit itself.  The DeltaRI bit will be
  1489.           set when the RI bit comes on and again when the RI bit goes off.
  1490.           This is the method we employ in the CheckForCall function.
  1491.  
  1492.  
  1493.  
  1494.  
  1495.  
  1496.  
  1497.  
  1498.  
  1499.  
  1500.  
  1501.  
  1502.  
  1503.  
  1504.  
  1505.  
  1506.  
  1507.  
  1508.  
  1509.  
  1510.  
  1511.  
  1512.  
  1513.  
  1514.  
  1515.  
  1516.  
  1517.  
  1518.  
  1519.  
  1520.  
  1521.  
  1522.  
  1523.  
  1524.  
  1525.  
  1526.  
  1527.  
  1528.  
  1529.  
  1530.  
  1531.  
  1532.  
  1533.  
  1534.                                     Page 23
  1535.             Copyright (c) 1987, 88, 89 Information Technology, Ltd.
  1536.  
  1537.  
  1538.                    LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL
  1539.  
  1540.  
  1541.  
  1542.  
  1543.  
  1544.  
  1545.  
  1546.  
  1547.  
  1548.  
  1549.  
  1550.  
  1551.  
  1552.  
  1553.  
  1554.  
  1555.  
  1556.  
  1557.  
  1558.  
  1559.  
  1560.  
  1561.  
  1562.  
  1563.  
  1564.  
  1565.  
  1566.  
  1567.  
  1568.  
  1569.  
  1570.  
  1571.  
  1572.  
  1573.  
  1574.  
  1575.  
  1576.  
  1577.  
  1578.  
  1579.  
  1580.  
  1581.  
  1582.  
  1583.  
  1584.  
  1585.  
  1586.  
  1587.  
  1588.  
  1589.  
  1590.  
  1591.  
  1592.  
  1593.  
  1594.  
  1595.  
  1596.  
  1597.  
  1598.  
  1599.                                     Page 24
  1600.             Copyright (c) 1987, 88, 89 Information Technology, Ltd.
  1601.  
  1602.  
  1603.                    LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL
  1604.  
  1605.  
  1606.  
  1607.  
  1608.  
  1609.  
  1610.  
  1611.  
  1612.  
  1613.                                      Chapter 6
  1614.                                      Chapter 6
  1615.  
  1616.                                   PACKAGE CONTENTS
  1617.                                   PACKAGE CONTENTS
  1618.  
  1619.  
  1620.           Your distribution diskette contains several files that are
  1621.           important to you. All distribution diskettes, at a minimum, include
  1622.           the following files in the diskette's root directory:
  1623.                           Table 6.1: Basic Diskette Contents
  1624.                           Table 6.1
  1625.  
  1626.                       READ.ME           LATEST INFORMATION ABOUT
  1627.                                              LITECOMM-TP
  1628.  
  1629.                       LTCOMM.ARC        SHAREWARE VERSION AND
  1630.                                              DOCUMENTATION FILES
  1631.  
  1632.                       LTUNITS.ARC       FULLY FUNCTIONAL UNIT FILES
  1633.  
  1634.           If you registered for the source code modules, the diskette
  1635.           contains 2 additional source code archives.
  1636.  
  1637.  
  1638.                       LITECOMM-TP SOURCE CODE          LTSRC.ARC
  1639.  
  1640.                       XMODEM ENGINE SOURCE CODE      LTXMSRC.ARC
  1641.  
  1642.  
  1643.        6.1  INSTALLATION INSTRUCTIONS
  1644.        6.1  INSTALLATION INSTRUCTIONS
  1645.  
  1646.  
  1647.           In the following discussion, we assume that your regular unit files
  1648.           __ ___ _________ ___________ __ ______ ____ ____ _______ ____ _____
  1649.           are contained in a directory called \TP.
  1650.           ___ _________ __ _ _________ ______ \TP_
  1651.                                               ___
  1652.           To install the unit files used with LiteComm-TP, perform the
  1653.           following steps:
  1654.  
  1655.              1.  CD \TP
  1656.  
  1657.              2.  ARC E A:LTUNITS
  1658.  
  1659.           Since Turbo PASCAL permits you the flexibility of having a separate
  1660.           subdirectory for units, you should execute the above instructions
  1661.           in whatever directory you use for units.
  1662.  
  1663.           If you are installing only the units, this completes the
  1664.           installation procedure. If you have registered for the package's
  1665.           source code, we recommend that you create a separate subdirectory.
  1666.           The example below assumes that you will use a directory named COMM
  1667.  
  1668.  
  1669.  
  1670.  
  1671.                                     Page 25
  1672.             Copyright (c) 1987, 88, 89 Information Technology, Ltd.
  1673.  
  1674.  
  1675.                    LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL
  1676.  
  1677.  
  1678.  
  1679.           to hold the LiteComm-TP and XModem source code modules. To install
  1680.           the LiteComm-TP source code, do the following:
  1681.  
  1682.              1.  MD \COMM
  1683.  
  1684.              2.  CD \COMM
  1685.  
  1686.              3.  ARC E A:LTSRC *.*
  1687.  
  1688.              4.  ARC E A:LTXMSRC *.*
  1689.  
  1690.           We strongly urge that you use the recommended approach in handling
  1691.           the source code to avoid naming conflicts that might arise.
  1692.  
  1693.  
  1694.  
  1695.  
  1696.  
  1697.  
  1698.  
  1699.  
  1700.  
  1701.  
  1702.  
  1703.  
  1704.  
  1705.  
  1706.  
  1707.  
  1708.  
  1709.  
  1710.  
  1711.  
  1712.  
  1713.  
  1714.  
  1715.  
  1716.  
  1717.  
  1718.  
  1719.  
  1720.  
  1721.  
  1722.  
  1723.  
  1724.  
  1725.  
  1726.  
  1727.  
  1728.  
  1729.  
  1730.  
  1731.  
  1732.  
  1733.  
  1734.  
  1735.  
  1736.                                     Page 26
  1737.             Copyright (c) 1987, 88, 89 Information Technology, Ltd.
  1738.  
  1739.  
  1740.                    LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL
  1741.  
  1742.  
  1743.  
  1744.  
  1745.  
  1746.  
  1747.  
  1748.  
  1749.  
  1750.                                      Chapter 7
  1751.                                      Chapter 7
  1752.  
  1753.                           PROCEDURE AND FUNCTION REFERENCE
  1754.                           PROCEDURE AND FUNCTION REFERENCE
  1755.  
  1756.  
  1757.           In the following pages, we provide the detailed information about
  1758.           each of the available LiteComm-TP ToolBox functions and procedures.
  1759.           Each definition includes, at a minimum, a summary of how the
  1760.           function or procedure is referenced, in which unit the function or
  1761.           procedure is found, a description of what the function or procedure
  1762.           does, and an indication of those values, if any, that might be
  1763.           returned.
  1764.  
  1765.           Where appropriate, we include additional documentation about the
  1766.           function.  Some definitions include examples, in the sense of code
  1767.           fragments illustrating the function's usage.  More importantly,
  1768.           some definitions include additional notes and warnings as well as
  1769.           references to other functions within the package.
  1770.  
  1771.           We have made every effort to insure that the documentation of the
  1772.           functions is complete and accurate.  The style and manner of the
  1773.           documentation assumes that the reader is thoroughly familiar with
  1774.           the elements of PASCAL syntax and common conventions.
  1775.  
  1776.  
  1777.        7.1  UNIT USAGE
  1778.        7.1  UNIT USAGE
  1779.  
  1780.  
  1781.           To assist you in developing your own applications, you will need to
  1782.           know the following information.
  1783.  
  1784.                          Unit           Uses
  1785.  
  1786.                          LctKrnl        DOS
  1787.                          LctSupp        DOS, LctKrnl
  1788.                          LctHayes       DOS, LctSupp
  1789.                          LctBBs         DOS, CRT, LctKrnl, LctSupp
  1790.                          LTXMKrnl       DOS, LctSupp
  1791.                          LTXModem       DOS, LctSupp, LTXMKrnl
  1792.  
  1793.  
  1794.  
  1795.  
  1796.  
  1797.  
  1798.  
  1799.  
  1800.  
  1801.  
  1802.  
  1803.  
  1804.                                     Page 27
  1805.             Copyright (c) 1987, 88, 89 Information Technology, Ltd.
  1806.  
  1807.  
  1808.                    LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL
  1809.  
  1810.  
  1811.  
  1812.  
  1813.  
  1814.  
  1815.  
  1816.  
  1817.  
  1818.                                 PortChange function
  1819.                                 PortChange function
  1820.  
  1821.  
  1822.           UNIT            LctKrnl
  1823.           UNIT
  1824.  
  1825.           FUNCTION        Changes one or more of the critical parameters for
  1826.           FUNCTION
  1827.                           port COM3 or COM4.
  1828.  
  1829.           DECLARATION     PortChange(CPort:integer; NewBase:word; NewIrq,
  1830.           DECLARATION
  1831.                           NewVector:byte)
  1832.  
  1833.           RESULT TYPE     boolean
  1834.           RESULT TYPE
  1835.  
  1836.           REMARKS         This function must be used before the port is
  1837.           REMARKS
  1838.                           opened to be effective. To leave any of the
  1839.                           parameters at its default value, make the
  1840.                           corresponding entry 0. Note that vector is a vector
  1841.                           number, not an address or pointer.
  1842.                            
  1843.                           The irq parameter should not be taken to be the irq
  1844.                           (interrupt request number), but rather the irq
  1845.                           mask. For example, the correct value for irq4 is
  1846.                           NOT 4, but a byte in which bit 4, using INTEL's bit
  1847.                           numbering, is set to a value of 1. Thus, to use irq
  1848.                           priority 4 as the irq for either COM3 or COM4, you
  1849.                           would specify $10 as the value of irq when calling
  1850.                           PortChange.
  1851.                            
  1852.                           If you intend to change the default irq settings,
  1853.                           you MUST also make a corresponding change to the
  1854.                           vector number. See the preceding section about
  1855.                           using COM3 and COM4 for additional details. Failure
  1856.                           to follow this rule may make the port appear to be
  1857.                           nonfunctional.
  1858.                            
  1859.                           The PortChange function does NOT check to determine
  1860.                           that you have provided both an IRQ mask AND a new
  1861.                           vector number.
  1862.                           PortChange returns a value of TRUE if the change
  1863.                           was successful, false otherwise.
  1864.  
  1865.           EXAMPLE         Var
  1866.           EXAMPLE
  1867.                             Newbase : word;
  1868.                             Newirq : byte;
  1869.                             NewVector : byte;
  1870.                           Begin
  1871.                             Newbase := $03E8;
  1872.                             Newirq := $10;
  1873.  
  1874.  
  1875.  
  1876.                                     Page 28
  1877.             Copyright (c) 1987, 88, 89 Information Technology, Ltd.
  1878.  
  1879.  
  1880.                    LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL
  1881.  
  1882.  
  1883.  
  1884.                             NewVector := $0C;
  1885.                            
  1886.                             if PortChange(3, Newbase, Newirq, NewVector) then
  1887.                               Writeln('Port 3 Changed')
  1888.                             else
  1889.                               Writeln('Error changing Port 3');
  1890.                             end;
  1891.  
  1892.  
  1893.  
  1894.  
  1895.  
  1896.  
  1897.                                  CommOpen function
  1898.                                  CommOpen function
  1899.  
  1900.  
  1901.           UNIT            LctKrnl
  1902.           UNIT
  1903.  
  1904.           FUNCTION        Prepares the specified port for use by the other
  1905.           FUNCTION
  1906.                           functions
  1907.  
  1908.           DECLARATION     CommOpen(CPort, Baud:integer; Parity:char;
  1909.           DECLARATION
  1910.                           Databits, Stopbits, InSize, OutSize:integer;
  1911.                           RaiseMdmCtl:BOOLEAN)
  1912.  
  1913.           RESULT TYPE     boolean
  1914.           RESULT TYPE
  1915.  
  1916.           REMARKS         Opens the specified port for use and attaches an
  1917.           REMARKS
  1918.                           interrupt handler to DOS for the port. The function
  1919.                           allocates buffers for input and output of the
  1920.                           specified sizes, and sets the port to the
  1921.                           parameters specified. The minimum value for InSize
  1922.                           is 128; the minimum size for OutSize is 64. A port
  1923.                           opened in this manner must be closed using
  1924.                           CommClose before program termination to avoid the
  1925.                           possibility of a system crash.
  1926.                            
  1927.                           CommOpen sets aside an additional 512 bytes per
  1928.                           open port. This additional memory is used as the
  1929.                           stack for the port's interrupt handler while
  1930.                           interrupts are being processed.  This approach help
  1931.                           avoid the possibility of stack overflows that might
  1932.                           occur under some conditions.
  1933.                            
  1934.                           CommOpen installs an exit procedure to protect DOS
  1935.                           from problems that might arise if a program using
  1936.                           LiteComm fails.  However, we recommend that you
  1937.                           always close a port opened with CommOpen by calling
  1938.                           CommClose explicitly in your program to gain
  1939.                           maximum control over the port.
  1940.                            
  1941.                           The parameters passed to the function are discrete
  1942.                           values, and must be drawn from the following lists:
  1943.                            
  1944.  
  1945.  
  1946.  
  1947.                                     Page 29
  1948.             Copyright (c) 1987, 88, 89 Information Technology, Ltd.
  1949.  
  1950.  
  1951.                    LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL
  1952.  
  1953.  
  1954.  
  1955.                           Baud        any value that your communication
  1956.                           Baud
  1957.                                       equipment, e.g. your modem, will
  1958.                                       support.
  1959.  
  1960.                           Parity      E, O, N, M, S
  1961.                           Parity
  1962.                                       E - Even
  1963.                                       O - Odd
  1964.                                       N - None
  1965.                                       M - Mark
  1966.                                       S - Space
  1967.  
  1968.                           Databits    5, 6, 7, 8
  1969.                           Databits
  1970.  
  1971.                           StopBits    1, 2
  1972.                           StopBits
  1973.  
  1974.                            
  1975.                           If RaiseMdmCtl has a value of TRUE, CommOpen will
  1976.                           automatically raise the handshaking signals DTR and
  1977.                           RTS.  If RaiseMdmCtl has a value of FALSE, the
  1978.                           programmer must raise these signals by calling
  1979.                           SetModemSignals.  In general, use the second form
  1980.                           to gain full control over the handshaking signals
  1981.                           if needed, use the first form in those cases where
  1982.                           the control of these two signals is noncritical.
  1983.                            
  1984.                           A return of TRUE indicates the port has been
  1985.                           successfully opened and is ready for use.  A return
  1986.                           of FALSE indicates an error occurred, either as the
  1987.                           result of an invalid parameter, or insufficient
  1988.                           heap space available to allocate the buffers and
  1989.                           control structures for the port.
  1990.  
  1991.           EXAMPLE         Var
  1992.           EXAMPLE
  1993.                             Baud, Databits, Stopbits : integer;
  1994.                             Parity : char;
  1995.                             Insize, Outsize : integer;
  1996.                            
  1997.                           begin
  1998.                             Baud := 2400;
  1999.                             Parity := 'E';
  2000.                             Databits := 7;
  2001.                             Stopbits := 1;
  2002.                             Insize := 256;
  2003.                             Outsize := 256;
  2004.                            
  2005.                             if CommOpen(1, Baud, Parity, Databits, Stopbits,
  2006.                           Insize, Outsize, TRUE) then
  2007.                               Writeln('COM1 available for use')
  2008.                             else
  2009.                               Writeln('Error opening COM1');
  2010.                            
  2011.                           The equivalent code to the above is shown below
  2012.                            
  2013.  
  2014.  
  2015.  
  2016.  
  2017.                                     Page 30
  2018.             Copyright (c) 1987, 88, 89 Information Technology, Ltd.
  2019.  
  2020.  
  2021.                    LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL
  2022.  
  2023.  
  2024.  
  2025.                             if CommOpen(1, Baud, Parity, Databits, Stopbits,
  2026.                           Insize, Outsize, FALSE) then
  2027.                               Writeln('COM1 is now open')
  2028.                             else
  2029.                               Writeln('Error opening COM1');
  2030.                             if SetModemSignals(1, (DTR OR RTS)) then
  2031.                               Writeln('Port is ready to transmit')
  2032.                             else
  2033.                               Writeln('Unable to set modem signals');
  2034.  
  2035.           SEE ALSO        SetModemSignals
  2036.           SEE ALSO
  2037.  
  2038.  
  2039.  
  2040.  
  2041.  
  2042.  
  2043.                                 CommClose procedure
  2044.                                 CommClose procedure
  2045.  
  2046.  
  2047.           UNIT            LctKrnl
  2048.           UNIT
  2049.  
  2050.           FUNCTION        Closes a port that has been opened by the CommOpen
  2051.           FUNCTION
  2052.                           function
  2053.  
  2054.           DECLARATION     CommClose(CPort:integer; DropMdmCtl:BOOLEAN)
  2055.           DECLARATION
  2056.  
  2057.           REMARKS         This function is the companion to CommOpen and, in
  2058.           REMARKS
  2059.                           effect, performs the opposite action. CommClose
  2060.                           detaches the kernel interrupt handler from the
  2061.                           port, and reconnects the previous interrupt
  2062.                           handler.  CommClose also release dynamically
  2063.                           allocated memory used for buffering and control
  2064.                           structures. If DropMdmCtl has a value of TRUE, the
  2065.                           port is closed absolutely; both the DTR and RTS
  2066.                           signals are dropped.  If DropMdmCtl has a value of
  2067.                           FALSE, the port is closed conditionally and both
  2068.                           DTR and RTS are left in their current state.
  2069.                            
  2070.                           Since CommOpen installs an exit procedure, you are
  2071.                           not required to explicitly close an open port.
  2072.                           However, if you do not use an explicit close, you
  2073.                           will lose control over the handling of DTR and RTS.
  2074.                           The built-in exit procedure always uses the
  2075.                           absolute form of the close.
  2076.  
  2077.  
  2078.  
  2079.  
  2080.  
  2081.  
  2082.  
  2083.  
  2084.  
  2085.  
  2086.  
  2087.  
  2088.                                     Page 31
  2089.             Copyright (c) 1987, 88, 89 Information Technology, Ltd.
  2090.  
  2091.  
  2092.                    LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL
  2093.  
  2094.  
  2095.  
  2096.  
  2097.  
  2098.  
  2099.  
  2100.  
  2101.  
  2102.                                  CommSetup function
  2103.                                  CommSetup function
  2104.  
  2105.  
  2106.           UNIT            LctKrnl
  2107.           UNIT
  2108.  
  2109.           FUNCTION        Provides the capability of changing the parameters
  2110.           FUNCTION
  2111.                           for an open port, without breaking the connection
  2112.                           or closing the port.
  2113.  
  2114.           DECLARATION     CommSetup(CPort, Baud:integer; Parity:char;
  2115.           DECLARATION
  2116.                           Databits, Stopbits:integer)
  2117.  
  2118.           RESULT TYPE     boolean
  2119.           RESULT TYPE
  2120.  
  2121.           REMARKS         The CommSetup function is a subset of the CommOpen
  2122.           REMARKS
  2123.                           function and the remarks made in the description of
  2124.                           CommOpen apply. This function is useful if you wish
  2125.                           to change the basic communication parameters of the
  2126.                           specified port that has already been opened without
  2127.                           CommClose'ing the port and breaking the connection.
  2128.  
  2129.           SEE ALSO        CommOpen
  2130.           SEE ALSO
  2131.  
  2132.  
  2133.  
  2134.  
  2135.  
  2136.  
  2137.                                BytesInInput function
  2138.                                BytesInInput function
  2139.  
  2140.  
  2141.           UNIT            LctSupp
  2142.           UNIT
  2143.  
  2144.           FUNCTION        Returns the number of characters currently
  2145.           FUNCTION
  2146.                           available in the input buffer (BytesInInput) or the
  2147.                           number of untransmitted characters in the output
  2148.                           buffer (ByteInOutput).
  2149.  
  2150.           DECLARATION     BytesInInput(CPort:integer)
  2151.           DECLARATION
  2152.                           BytesInOutput(CPort:integer)
  2153.  
  2154.           RESULT TYPE     integer
  2155.           RESULT TYPE
  2156.  
  2157.           REMARKS         May be used to determine the number of characters
  2158.           REMARKS
  2159.                           currently in the input (BytesInInput) or output
  2160.                           (BytesInOutput) buffers for the port. In the event
  2161.                           of an error (bad port), a value of -1 is returned.
  2162.  
  2163.  
  2164.  
  2165.  
  2166.                                     Page 32
  2167.             Copyright (c) 1987, 88, 89 Information Technology, Ltd.
  2168.  
  2169.  
  2170.                    LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL
  2171.  
  2172.  
  2173.  
  2174.  
  2175.  
  2176.  
  2177.  
  2178.  
  2179.  
  2180.                                 ModemStatus function
  2181.                                 ModemStatus function
  2182.  
  2183.  
  2184.           UNIT            LctKrnl
  2185.           UNIT
  2186.  
  2187.           FUNCTION        Returns the last know status of the modem control
  2188.           FUNCTION
  2189.                           lines for the specified port.
  2190.  
  2191.           DECLARATION     ModemStatus(CPort:integer)
  2192.           DECLARATION
  2193.  
  2194.           RESULT TYPE     byte
  2195.           RESULT TYPE
  2196.  
  2197.           REMARKS         Use this function to determine the last known state
  2198.           REMARKS
  2199.                           of the modem-supplied handshake signals. These may
  2200.                           be tested using the values included in the unit,
  2201.                           using PASCAL's bitwise AND operator.
  2202.                            
  2203.                           The byte value returned can be viewed as consisting
  2204.                           of two sub-fields, the current signal state (found
  2205.                           in bits 4-7 of the byte), and the signal
  2206.                           change(DELTA) indicators(found in the bits 0-3 of
  2207.                           the byte).  ModemStatus always returns the current
  2208.                           state of the signals in bits 4-7.  Bits 0-3 will
  2209.                           reflect which, if any, of the signals has changed.
  2210.                            
  2211.                           Whenever this function is called, both subfields
  2212.                           are returned, and represent the current state of
  2213.                           the individual signals.  The DELTA settings may be
  2214.                           all reset, if no signals have changed since the
  2215.                           last call to the function.  The signals which are
  2216.                           tracked are CTS, DSR, RI, and DCD.
  2217.                            
  2218.                           To determine which signals, if any, have changed
  2219.                           use the DeltaXXX bits returned. For example, if CTS
  2220.                           has changed, the DeltaCTS bit will be set.  The
  2221.                           actual CTS value (on or off) will be found in the
  2222.                           CTS bit of the returned byte.
  2223.                            
  2224.                           In the event of an error, a byte of $00 is
  2225.                           returned.
  2226.  
  2227.           HINT            Detecting a ringing phone (using the RI signal) can
  2228.           HINT
  2229.                           be tricky and timing dependent.  One nearly
  2230.                           foolproof method that we have used is to examine
  2231.                           the DeltaRI value, not the RI value.  The DeltaRI
  2232.                           value is set and reset as the telephone starts and
  2233.                           stops ringing.  The RI value is set and cleared
  2234.                           independently, and you may miss the fact that the
  2235.  
  2236.  
  2237.  
  2238.                                     Page 33
  2239.             Copyright (c) 1987, 88, 89 Information Technology, Ltd.
  2240.  
  2241.  
  2242.                    LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL
  2243.  
  2244.  
  2245.  
  2246.                           phone is ringing if you don't examine the value at
  2247.                           the right time.
  2248.  
  2249.           EXAMPLE         Var
  2250.           EXAMPLE
  2251.                             CStat : byte;
  2252.                             
  2253.                           begin
  2254.                             CStat := ModemStatus(1);
  2255.                             if CStat and DeltaDCD = DeltaDCD then
  2256.                               if CStat and DCD <> DCD then
  2257.                                 Writeln('Remote is off-line, carrier lost');
  2258.  
  2259.  
  2260.  
  2261.  
  2262.  
  2263.  
  2264.                                  BreakRecd function
  2265.                                  BreakRecd function
  2266.  
  2267.  
  2268.           UNIT            LctKrnl
  2269.           UNIT
  2270.  
  2271.           FUNCTION        Returns a value of true if a BREAK signal has been
  2272.           FUNCTION
  2273.                           received from the serial port since that last call
  2274.                           to the function.
  2275.  
  2276.           DECLARATION     BreakRecd(CPort:integer);
  2277.           DECLARATION
  2278.  
  2279.           RESULT TYPE     boolean;
  2280.           RESULT TYPE
  2281.  
  2282.           REMARKS         This function returns a value of TRUE if a BREAK
  2283.           REMARKS
  2284.                           character has been received since the last call to
  2285.                           the function.
  2286.  
  2287.           EXAMPLE         if BreakRecd(2) then
  2288.           EXAMPLE
  2289.                             Writeln('Break Signal detected on Port 2');
  2290.  
  2291.  
  2292.  
  2293.  
  2294.  
  2295.  
  2296.                                 ErrorStatus function
  2297.                                 ErrorStatus function
  2298.  
  2299.  
  2300.           UNIT            LctKrnl
  2301.           UNIT
  2302.  
  2303.           FUNCTION        Return the last known error status for the
  2304.           FUNCTION
  2305.                           specified port.
  2306.  
  2307.           DECLARATION     ErrorStatus(CPort:integer)
  2308.           DECLARATION
  2309.  
  2310.           RESULT TYPE     byte
  2311.           RESULT TYPE
  2312.  
  2313.  
  2314.  
  2315.  
  2316.                                     Page 34
  2317.             Copyright (c) 1987, 88, 89 Information Technology, Ltd.
  2318.  
  2319.  
  2320.                    LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL
  2321.  
  2322.  
  2323.  
  2324.           REMARKS         Returns the last known state of the serial port's
  2325.           REMARKS
  2326.                           error status bits, encoded in a byte. These may be
  2327.                           tested using the constants defined in the unit in
  2328.                           conjunction with PASCAL's bitwise AND operator.
  2329.                           The applicable values that may be checked are
  2330.                           OverRun, BadParity, and, BadFrame.
  2331.                            
  2332.  
  2333.                              1.  OverRun - failure to fetch a character from
  2334.                                  the port before the next character was
  2335.                                  received. Usually caused by a problem in the
  2336.                                  interrupt handler.
  2337.  
  2338.                              2.  BadParity - One or more characters were
  2339.                                  received in which the parity of the
  2340.                                  character(s) did not match the current
  2341.                                  parity setting of the port.  Can be caused
  2342.                                  by line noise (electrical interference),
  2343.                                  poor connections, or a variety of other
  2344.                                  reasons.
  2345.  
  2346.                              3.  BadFrame - A framing error has occurred.  A
  2347.                                  character was received that had too few or
  2348.                                  (more likely) too many bits.  Usually caused
  2349.                                  bye line noise.
  2350.  
  2351.                            
  2352.                           Break detection, i.e. the receipt of a BREAK
  2353.                           character, is handled by the BreakRecd
  2354.                           function(qv).  In the event of an error, a byte of
  2355.                           $00 is returned.
  2356.                            
  2357.                           Once the error status bits have been read in this
  2358.                           fashion, they are reset to $00, and will remain so
  2359.                           until the next error occurs.  Since this process
  2360.                           happens asynchronously, it is not possible for your
  2361.                           application to determine which character created
  2362.                           the error, only that the error occurred.
  2363.  
  2364.           EXAMPLE         Var
  2365.           EXAMPLE
  2366.                             EStat : byte;
  2367.                            
  2368.                           begin
  2369.                             EStat := ErrorStatus(2);
  2370.                             if EStat and OverRun = OverRun then
  2371.                               Writeln('Receive Character Over Run');
  2372.  
  2373.  
  2374.  
  2375.  
  2376.  
  2377.  
  2378.  
  2379.  
  2380.  
  2381.  
  2382.  
  2383.                                     Page 35
  2384.             Copyright (c) 1987, 88, 89 Information Technology, Ltd.
  2385.  
  2386.  
  2387.                    LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL
  2388.  
  2389.  
  2390.  
  2391.  
  2392.  
  2393.  
  2394.  
  2395.  
  2396.  
  2397.                               SetModemSignals function
  2398.                               SetModemSignals function
  2399.  
  2400.  
  2401.           UNIT            LctKrnl
  2402.           UNIT
  2403.  
  2404.           FUNCTION        Allows the programmer to set the individual modem
  2405.           FUNCTION
  2406.                           control lines for the specified port.
  2407.  
  2408.           DECLARATION     SetModemSignals(CPort:integer; NewSet:byte)
  2409.           DECLARATION
  2410.  
  2411.           RESULT TYPE     boolean
  2412.           RESULT TYPE
  2413.  
  2414.           REMARKS         Set one or more of the modem control signals.
  2415.           REMARKS
  2416.                           Because of the need to always have OUT2 set for
  2417.                           interrupt support, the function always provides the
  2418.                           correct setting for this bit.
  2419.                            
  2420.                           The value of NewSet is bitwise OR'ed with the
  2421.                           current set of values to produce a new modem
  2422.                           control setting.  The value of NewSet DOES NOT
  2423.                           replace the current values. Use the constants
  2424.                           supplied in the unit to obtain the correct values.
  2425.                           These include DTR and RTS.
  2426.                            
  2427.                           Many applications will not require this, and its
  2428.                           companion, functions, if the permit CommOpen to
  2429.                           raise the DTR and RTS signals.  More sophisticated
  2430.                           applications may be required to control either or
  2431.                           both of the signals to provide handshaking with an
  2432.                           external device.
  2433.  
  2434.           EXAMPLE         begin
  2435.           EXAMPLE
  2436.                             (* raise both DTR and RTS *)
  2437.                             if SetModemSignals(1, (DTR OR RTS)) then
  2438.                               Writeln('Port is ready to transmit')
  2439.                             else
  2440.                               Writeln('Unable to set modem signals');
  2441.  
  2442.           SEE ALSO        ClearModemSignals, FlipModemSignals
  2443.           SEE ALSO
  2444.  
  2445.  
  2446.  
  2447.  
  2448.  
  2449.  
  2450.  
  2451.  
  2452.  
  2453.  
  2454.  
  2455.  
  2456.                                     Page 36
  2457.             Copyright (c) 1987, 88, 89 Information Technology, Ltd.
  2458.  
  2459.  
  2460.                    LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL
  2461.  
  2462.  
  2463.  
  2464.  
  2465.  
  2466.  
  2467.  
  2468.  
  2469.  
  2470.                              ClearModemSignals function
  2471.                              ClearModemSignals function
  2472.  
  2473.  
  2474.           UNIT            LctKrnl
  2475.           UNIT
  2476.  
  2477.           FUNCTION        Allows the programmer to clear (reset) the
  2478.           FUNCTION
  2479.                           individual modem control lines for the specified
  2480.                           port.
  2481.  
  2482.           DECLARATION     ClearModemSignals(CPort:integer; NewSet:byte)
  2483.           DECLARATION
  2484.  
  2485.           RESULT TYPE     boolean
  2486.           RESULT TYPE
  2487.  
  2488.           REMARKS         Clears (resets) one or more of the modem control
  2489.           REMARKS
  2490.                           signals. Because of the need to always have OUT2
  2491.                           set for interrupt support, the function always
  2492.                           provides the correct setting for this bit.
  2493.                            
  2494.                           The compliment of NewSet is bitwise AND'ed with the
  2495.                           current set of values to produce a new modem
  2496.                           control setting.  The value of NewSet DOES NOT
  2497.                           replace the current values. Use the constants
  2498.                           supplied in the unit to obtain the correct values.
  2499.                           These include DTR and RTS.
  2500.  
  2501.           EXAMPLE         begin
  2502.           EXAMPLE
  2503.                             if ClearModemSignals(1,  RTS) then
  2504.                               Writeln('RTS for Port 1 has been dropped')
  2505.                             else
  2506.                               Writeln('Unable to clear RTS');
  2507.  
  2508.           SEE ALSO        SetModemSignals, FlipModemSignals
  2509.           SEE ALSO
  2510.  
  2511.  
  2512.  
  2513.  
  2514.  
  2515.  
  2516.                              FlipModemSignals function
  2517.                              FlipModemSignals function
  2518.  
  2519.  
  2520.           UNIT            LctKrnl
  2521.           UNIT
  2522.  
  2523.           FUNCTION        Allows the programmer to compliment(toggle) the
  2524.           FUNCTION
  2525.                           individual modem control lines for the specified
  2526.                           port.  This function only has value if you are
  2527.                           attempting to implement some form of hardware
  2528.                           handshaking with another device.  The absolute form
  2529.  
  2530.  
  2531.  
  2532.                                     Page 37
  2533.             Copyright (c) 1987, 88, 89 Information Technology, Ltd.
  2534.  
  2535.  
  2536.                    LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL
  2537.  
  2538.  
  2539.  
  2540.                           of CommClose will automatically lower both RTS AND
  2541.                           DTR, which is generally adequate for many
  2542.                           applications.
  2543.  
  2544.           DECLARATION     FlipModemSignals(CPort:integer; NewSet:byte)
  2545.           DECLARATION
  2546.  
  2547.           RESULT TYPE     boolean
  2548.           RESULT TYPE
  2549.  
  2550.           REMARKS         Complements(toggles) one or more of the modem
  2551.           REMARKS
  2552.                           control signals. Because of the need to always have
  2553.                           OUT2 set for interrupt support, the function always
  2554.                           provides the correct setting for this bit.
  2555.                            
  2556.                           The value of NewSet is bitwise XOR'ed with the
  2557.                           current set of values to produce a new modem
  2558.                           control setting.  The value of NewSet DOES NOT
  2559.                           replace the current values. Use the constants
  2560.                           supplied in the unit to obtain the correct values.
  2561.                           These include DTR and RTS.
  2562.  
  2563.           EXAMPLE         begin
  2564.           EXAMPLE
  2565.                             (*
  2566.                             ** change the RTS modem control signal to its
  2567.                           other
  2568.                             ** state (if raised, lower it, if lowered raise
  2569.                           it)
  2570.                             *)
  2571.                             if FlipModemSignals(1, RTS) then
  2572.                               Writeln('RTS for Port 1 has been changed')
  2573.                             else
  2574.                               Writeln('Unable to change RTS');
  2575.  
  2576.           SEE ALSO        SetModemSignals, ClearModemSignals
  2577.           SEE ALSO
  2578.  
  2579.  
  2580.  
  2581.  
  2582.  
  2583.  
  2584.                                  EnableXon function
  2585.                                  EnableXon function
  2586.  
  2587.  
  2588.           UNIT            LctKrnl
  2589.           UNIT
  2590.  
  2591.           FUNCTION        Enable or disable the semiautomatic flow control
  2592.           FUNCTION
  2593.                           features of LiteComm-TP
  2594.  
  2595.           DECLARATION     EnableXon(CPort:integer; XonFlag:boolean)
  2596.           DECLARATION
  2597.  
  2598.           RESULT TYPE     boolean;
  2599.           RESULT TYPE
  2600.  
  2601.           REMARKS         If XonFlag is TRUE, turns on semiautomatic XON-XOFF
  2602.           REMARKS
  2603.                           flow control function. If XonFlag is FALSE (the
  2604.  
  2605.  
  2606.  
  2607.  
  2608.                                     Page 38
  2609.             Copyright (c) 1987, 88, 89 Information Technology, Ltd.
  2610.  
  2611.  
  2612.                    LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL
  2613.  
  2614.  
  2615.  
  2616.                           default setting), automatic flow control is
  2617.                           disabled.  
  2618.                           When enabled, the kernel will automatically
  2619.                           transmit an XOFF if and when the input buffer is
  2620.                           approximately 2/3 full and will automatically
  2621.                           recognize an XOFF sent by the other device. If the
  2622.                           other device transmits an XOFF, the kernel will
  2623.                           refuse to send any characters until the condition
  2624.                           is cleared, either by receipt of an XON, by calling
  2625.                           the XOffRecd function, or by disabling XON-XOFF
  2626.                           altogether.
  2627.                            
  2628.                           The XOFF recognition is implemented in the kernel.
  2629.                           As a result, the transmit buffer will continue to
  2630.                           accept input from your program until the buffer
  2631.                           fills completely, even though the information will
  2632.                           not be sent.  Once the matching XON is received,
  2633.                           the contents of the transmit buffer will be sent
  2634.                           rapidly to the other device.  It is possible that
  2635.                           the rate with which characters are sent when this
  2636.                           occurs may cause problems for the other device,
  2637.                           depending on its ability to handle the data flow.
  2638.                            
  2639.                           If the kernel has sent an XOFF, it is the
  2640.                           programmer's responsibility to transmit XON when
  2641.                           conditions warrant. Use the XoffSent function to
  2642.                           tell if an automatic XOFF has been sent by the
  2643.                           kernel.
  2644.                            
  2645.                           If you intended to implement a protocol that might
  2646.                           include the XON-XOFF characters, be sure to disable
  2647.                           the automatic flow control. Failure to do so may
  2648.                           result in a system hang.
  2649.  
  2650.           SEE ALSO        XoffRecd, XoffRecd
  2651.           SEE ALSO
  2652.  
  2653.  
  2654.  
  2655.  
  2656.  
  2657.  
  2658.                                  XoffRecd function
  2659.                                  XoffRecd function
  2660.  
  2661.  
  2662.           UNIT            LctKrnl
  2663.           UNIT
  2664.  
  2665.           FUNCTION        Reports whether or not the kernel has detected an
  2666.           FUNCTION
  2667.                           XOFF from the other device
  2668.  
  2669.           DECLARATION     XoffRecd(CPort:integer)
  2670.           DECLARATION
  2671.  
  2672.           RESULT TYPE     boolean
  2673.           RESULT TYPE
  2674.  
  2675.  
  2676.  
  2677.  
  2678.  
  2679.                                     Page 39
  2680.             Copyright (c) 1987, 88, 89 Information Technology, Ltd.
  2681.  
  2682.  
  2683.                    LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL
  2684.  
  2685.  
  2686.  
  2687.           REMARKS         Returns TRUE if an XOFF has been received, FALSE
  2688.           REMARKS
  2689.                           otherwise. If an XOFF has been received, the port's
  2690.                           internal flag will be reset, and transmission to
  2691.                           the other device will be permitted. If an XON is
  2692.                           received from the other, the port's flag will also
  2693.                           be reset, permitting further transmissions to
  2694.                           occur.
  2695.                            
  2696.                           If you use flow control and the other device never
  2697.                           sends an XON after sending an XOFF, a system hang
  2698.                           is possible. You may wish to call XoffRecd
  2699.                           periodically to test for this condition, and to
  2700.                           cause your port to resume transmitting data.
  2701.  
  2702.           SEE ALSO        EnableXon, XoffSent
  2703.           SEE ALSO
  2704.  
  2705.  
  2706.  
  2707.  
  2708.  
  2709.  
  2710.                                  XoffSent function
  2711.                                  XoffSent function
  2712.  
  2713.  
  2714.           UNIT            LctKrnl
  2715.           UNIT
  2716.  
  2717.           FUNCTION        Reports whether or not the kernel has automatically
  2718.           FUNCTION
  2719.                           sent an XOFF to the other device.
  2720.  
  2721.           DECLARATION     XoffSent(CPort:integer)
  2722.           DECLARATION
  2723.  
  2724.           RESULT TYPE     boolean
  2725.           RESULT TYPE
  2726.  
  2727.           REMARKS         Returns TRUE if the LiteComm kernel has sent an
  2728.           REMARKS
  2729.                           XOFF to the other device, FALSE otherwise. If an
  2730.                           XOFF has been sent, the port's flag will be reset.
  2731.                           You must send an XON character to the other device
  2732.                           to permit transmissions to proceed.
  2733.  
  2734.           SEE ALSO        EnableXon, XoffRecd
  2735.           SEE ALSO
  2736.  
  2737.  
  2738.  
  2739.  
  2740.  
  2741.  
  2742.                                   LctGet function
  2743.                                   LctGet function
  2744.  
  2745.  
  2746.           UNIT            LctSupp
  2747.           UNIT
  2748.  
  2749.           FUNCTION        Returns an available character from the ports input
  2750.           FUNCTION
  2751.                           buffer.
  2752.  
  2753.  
  2754.  
  2755.  
  2756.                                     Page 40
  2757.             Copyright (c) 1987, 88, 89 Information Technology, Ltd.
  2758.  
  2759.  
  2760.                    LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL
  2761.  
  2762.  
  2763.  
  2764.           DECLARATION     LctGet(CPort:integer; var Ch:byte)
  2765.           DECLARATION
  2766.  
  2767.           RESULT TYPE     boolean
  2768.           RESULT TYPE
  2769.  
  2770.           REMARKS         Places the next available character in the input
  2771.           REMARKS
  2772.                           buffer for the port in the variable Ch. The
  2773.                           function returns a value of TRUE if there is a
  2774.                           character available, FALSE if there is no character
  2775.                           available or on an error.  The contents of Ch are
  2776.                           undefined when the return is FALSE.
  2777.                            
  2778.                           If you specified other than N (No Parity) when the
  2779.                           port was opened, you may have to reset (make zero)
  2780.                           the parity bit before you use the character.
  2781.  
  2782.           EXAMPLE         BEGIN
  2783.           EXAMPLE
  2784.                             IF LctGet(CPort, Ch) THEN
  2785.                               Ch := Ch AND $7F;       (* Reset the Parity Bit
  2786.                           *)
  2787.  
  2788.  
  2789.  
  2790.  
  2791.  
  2792.  
  2793.                                   LctPeek function
  2794.                                   LctPeek function
  2795.  
  2796.  
  2797.           UNIT            LctSupp
  2798.           UNIT
  2799.  
  2800.           FUNCTION        Permits you to look at the next character in the
  2801.           FUNCTION
  2802.                           ports input buffer without removing if from the
  2803.                           buffer.
  2804.  
  2805.           DECLARATION     LctPeek(CPort:integer; var Ch:byte)
  2806.           DECLARATION
  2807.  
  2808.           RESULT TYPE     boolean
  2809.           RESULT TYPE
  2810.  
  2811.           REMARKS         Places the next available character in the input
  2812.           REMARKS
  2813.                           buffer for the specified port into the Ch variable,
  2814.                           but does not remove the character from the buffer.
  2815.                           This allows the application to look-ahead by one
  2816.                                                          look-ahead
  2817.                                                          __________
  2818.                           character in a nondestructive fashion. Returns
  2819.                           FALSE if the port is not active, or if there are no
  2820.                           characters in the port's buffer, TRUE otherwise.
  2821.                           The contents of Ch are undefined when the result is
  2822.                           FALSE.
  2823.                            
  2824.                           The comment made regarding parity setting and the
  2825.                           use of the LctGet function also applies to LctPeek.
  2826.  
  2827.           SEE ALSO        LctGet
  2828.           SEE ALSO
  2829.  
  2830.  
  2831.  
  2832.  
  2833.  
  2834.                                     Page 41
  2835.             Copyright (c) 1987, 88, 89 Information Technology, Ltd.
  2836.  
  2837.  
  2838.                    LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL
  2839.  
  2840.  
  2841.  
  2842.  
  2843.  
  2844.  
  2845.  
  2846.  
  2847.  
  2848.                                   LctPut function
  2849.                                   LctPut function
  2850.  
  2851.  
  2852.           UNIT            LctSupp
  2853.           UNIT
  2854.  
  2855.           FUNCTION        Places a character in the port's transmit buffer to
  2856.           FUNCTION
  2857.                           be sent when the port is ready.
  2858.  
  2859.           DECLARATION     LctPut(CPort:integer; Ch:byte)
  2860.           DECLARATION
  2861.  
  2862.           RESULT TYPE     boolean
  2863.           RESULT TYPE
  2864.  
  2865.           REMARKS         Returns TRUE if successful. Note that this does not
  2866.           REMARKS
  2867.                           guarantee that the character has been sent, only
  2868.                           that no errors were detected, and there was space
  2869.                           in the transmit buffer to hold the character.
  2870.                           Returns FALSE if the port is not active, or if
  2871.                           there no room in the port's buffer.
  2872.                            
  2873.                           Characters are sent from the transmit buffer when
  2874.                           the system has the time to send them, assuming that
  2875.                           all conditions for transmission are satisfied
  2876.  
  2877.  
  2878.  
  2879.  
  2880.  
  2881.  
  2882.                                  GetStream function
  2883.                                  GetStream function
  2884.  
  2885.  
  2886.           UNIT            LctSupp
  2887.           UNIT
  2888.  
  2889.           FUNCTION        Gets a stream of N characters from the port's input
  2890.           FUNCTION
  2891.                           buffer
  2892.  
  2893.           DECLARATION     GetStream(CPort:integer; var Buff; BCnt:integer)
  2894.           DECLARATION
  2895.  
  2896.           RESULT TYPE     integer
  2897.           RESULT TYPE
  2898.  
  2899.           REMARKS         Reads a stream of, at most, BCnt characters from
  2900.           REMARKS
  2901.                           the serial port's input buffer into the Buff array.
  2902.                           Returns the count of characters actually
  2903.                           transferred, or -1 if an error occurs.
  2904.                            
  2905.                           NOTE that Buff is an array of characters or bytes,
  2906.                           not a string, although you may treat a string
  2907.                           variable like an array, as shown below.  The
  2908.  
  2909.  
  2910.  
  2911.                                     Page 42
  2912.             Copyright (c) 1987, 88, 89 Information Technology, Ltd.
  2913.  
  2914.  
  2915.                    LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL
  2916.  
  2917.  
  2918.  
  2919.                           comments made about parity in the LctGet function
  2920.                           description also apply the the GetStream function.
  2921.  
  2922.           EXAMPLE         Type
  2923.           EXAMPLE
  2924.                             MaxStr = string[256];
  2925.                            
  2926.                           Var
  2927.                             StrBuff : MaxStr;
  2928.                             RecdLen : integer;
  2929.                            
  2930.                           begin
  2931.                             RecdLen := GetStream(2, StrBuff[1], 256);
  2932.                             if RecdLen <M=> 0 then     { error or no char }
  2933.                               StrBuff[0] := 0
  2934.                             else
  2935.                               StrBuff[0] := Chr(RecdLen);
  2936.                           end;
  2937.  
  2938.           SEE ALSO        LctGet
  2939.           SEE ALSO
  2940.  
  2941.  
  2942.  
  2943.  
  2944.  
  2945.  
  2946.                                  PutStream function
  2947.                                  PutStream function
  2948.  
  2949.  
  2950.           UNIT            LctSupp
  2951.           UNIT
  2952.  
  2953.           FUNCTION        Places a stream of, at most, N characters in the
  2954.           FUNCTION
  2955.                           port's transmit buffer.
  2956.  
  2957.           DECLARATION     PutStream(CPort:integer; var Buff; BCnt:integer)
  2958.           DECLARATION
  2959.  
  2960.           RESULT TYPE     integer
  2961.           RESULT TYPE
  2962.  
  2963.           REMARKS         Buff is an array of character or byte, not a
  2964.           REMARKS
  2965.                           string, although it is possible to specify a string
  2966.                           variable, using the same approach as outlined for
  2967.                           the GetStream function. PutStream returns the
  2968.                           number of characters actually placed into the
  2969.                           buffer. Note that this does not guarantee that the
  2970.                           characters have been sent. A value of 0 will be
  2971.                           returned if any error occurs, or if there no room
  2972.                           in the port's buffer.
  2973.  
  2974.           EXAMPLE         VAR
  2975.           EXAMPLE
  2976.                             Buff : ARRAY[1..128] OF BYTE;
  2977.                             LeftToSend : INTEGER;
  2978.                             ReallySent : INTEGER;
  2979.                             StartPos   : INTEGER;
  2980.                            
  2981.                           BEGIN
  2982.  
  2983.  
  2984.  
  2985.                                     Page 43
  2986.             Copyright (c) 1987, 88, 89 Information Technology, Ltd.
  2987.  
  2988.  
  2989.                    LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL
  2990.  
  2991.  
  2992.  
  2993.                             LeftToSend := 128;               (* set up for
  2994.                           Full Length *)
  2995.                           ReallySent :=  0;
  2996.                             StartPos := 1;
  2997.                             WHILE LeftToSend > 0 DO
  2998.                             BEGIN
  2999.                               ReallySent := PutStream(CPort, Buff[StartPos],
  3000.                           LeftToSend);
  3001.                               IF ReallySent > 0 THEN
  3002.                               BEGIN
  3003.                                 StartPos := StartPos + ReallySent; (* adjust
  3004.                           start byte *)
  3005.                                 LeftToSend := LeftToSend - ReallySent;
  3006.                               END;
  3007.                             END (* while *);
  3008.  
  3009.           SEE ALSO        PutStream
  3010.           SEE ALSO
  3011.  
  3012.  
  3013.  
  3014.  
  3015.  
  3016.  
  3017.                              Buffer Flushing functions
  3018.                              Buffer Flushing functions
  3019.  
  3020.  
  3021.           UNIT            LctSupp
  3022.           UNIT
  3023.  
  3024.           FUNCTION        Provides several high level buffer management
  3025.           FUNCTION
  3026.                           functions to control the contents of the port's
  3027.                           transmit and receive buffers
  3028.  
  3029.           DECLARATION     function PurgeTxBuff(CPort:integer)
  3030.           DECLARATION
  3031.                            
  3032.                           function PurgeRxBuff(CPort:integer)
  3033.                            
  3034.                           procedure FlushUntilMatch(CPort:integer; Ch:byte)
  3035.                            
  3036.                           procedure FlushNBytes(CPort:integer; N:integer);
  3037.  
  3038.           RESULT TYPE     boolean for PurgeTxBuff, PurgeRxBuff
  3039.           RESULT TYPE
  3040.  
  3041.           REMARKS         The PurgeRxBuff and PurgeTxBuff functions remove
  3042.           REMARKS
  3043.                           all characters from the port's receive and transmit
  3044.                           buffers respectively and discard them;
  3045.                           untransmitted characters in the transmit buffer are
  3046.                           NEVER sent; unprocessed characters in the receive
  3047.                           buffer are lost. Both functions return a value of
  3048.                           TRUE if no errors were encountered, FALSE
  3049.                           otherwise.  An empty buffer is NOT considered an
  3050.                           error.
  3051.                            
  3052.                           The FlushUntilMatch procedure will continually
  3053.                           dispose of received characters until the character
  3054.  
  3055.  
  3056.  
  3057.                                     Page 44
  3058.             Copyright (c) 1987, 88, 89 Information Technology, Ltd.
  3059.  
  3060.  
  3061.                    LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL
  3062.  
  3063.  
  3064.  
  3065.                           Ch is received. The procedure will return when the
  3066.                           character Ch is detected, or when there are no more
  3067.                           characters in the port's input buffer.
  3068.                           The FlushNBytes procedure removes, at most, N
  3069.                           characters from the port's receive buffer.
  3070.  
  3071.  
  3072.  
  3073.  
  3074.  
  3075.  
  3076.                                  SendBreak function
  3077.                                  SendBreak function
  3078.  
  3079.  
  3080.           UNIT            LctKrnl
  3081.           UNIT
  3082.  
  3083.           FUNCTION        Send a true Break signal
  3084.           FUNCTION
  3085.  
  3086.           DECLARATION     SendBreak(CPort:integer)
  3087.           DECLARATION
  3088.  
  3089.           RESULT TYPE     boolean
  3090.           RESULT TYPE
  3091.  
  3092.           REMARKS         SendBreak generates a BREAK signal using a
  3093.           REMARKS
  3094.                           particular characteristic of the 8250 UART to
  3095.                           generate an accurate BREAK at any baud rate.
  3096.                           BREAKs generated in this manner are timed based
  3097.                           upon the baud rate at which the 8250 is currently
  3098.                           initialized.  This function may or may not work
  3099.                           correctly with other than the actual 8250 UART.
  3100.                            
  3101.                           Returns TRUE if successful. Returns FALSE if an
  3102.                           error is detected.
  3103.  
  3104.  
  3105.  
  3106.  
  3107.  
  3108.  
  3109.                                 CheckEvent Function
  3110.                                 CheckEvent Function
  3111.  
  3112.  
  3113.           UNIT            LctBBS
  3114.           UNIT
  3115.  
  3116.           FUNCTION        Returns a value of TRUE is the Event Timer
  3117.           FUNCTION
  3118.                           specified in the function call has not expired.
  3119.                           Returns a value of FALSE if the specified Event
  3120.                           Timer has expired.  Do not attempt to use
  3121.                           CheckEvent against a variable that was not
  3122.                           initialized bye NewEvent.  The results are
  3123.                           unpredictable, and may result in an apparent system
  3124.                           hang.
  3125.  
  3126.           DECLARATION     CheckEvent(EventVal : Event);
  3127.           DECLARATION
  3128.  
  3129.  
  3130.  
  3131.  
  3132.                                     Page 45
  3133.             Copyright (c) 1987, 88, 89 Information Technology, Ltd.
  3134.  
  3135.  
  3136.                    LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL
  3137.  
  3138.  
  3139.  
  3140.           RESULT TYPE     boolean;
  3141.           RESULT TYPE
  3142.  
  3143.           REMARKS         The event timer specified by EventVal must have
  3144.           REMARKS
  3145.                           been set using the NewEvent function
  3146.  
  3147.           SEE ALSO        NewEvent
  3148.           SEE ALSO
  3149.  
  3150.  
  3151.  
  3152.  
  3153.  
  3154.  
  3155.                                  NewEvent Function
  3156.                                  NewEvent Function
  3157.  
  3158.  
  3159.           UNIT            LctBBS
  3160.           UNIT
  3161.  
  3162.           FUNCTION        Initializes an event timer to a value suitable for
  3163.           FUNCTION
  3164.                           use with CheckEvent.  The event timer created in
  3165.                           this fashion can time events up to 32767 seconds in
  3166.                           duration.
  3167.  
  3168.           DECLARATION     NewEvent(Seconds : integer);
  3169.           DECLARATION
  3170.  
  3171.           RESULT TYPE     Event;
  3172.           RESULT TYPE
  3173.  
  3174.           REMARKS         When used in conjunction with CheckEvent, the event
  3175.           REMARKS
  3176.                           timer can be used to time events that span days,
  3177.                           months or years.  Actually, it should be termed a
  3178.                           timeout timer, since CheckEvent checks to see if
  3179.                           the period specified by Seconds has elapsed.
  3180.  
  3181.           EXAMPLE         var
  3182.           EXAMPLE
  3183.                             InputEvent : Event;
  3184.                             Ch : byte;
  3185.                            
  3186.                           begin
  3187.                             InputEvent := NewEvent(15);
  3188.                             while CheckEvent(InputEvent) do
  3189.                             if LctGet(Port, Ch) then
  3190.                               exit;
  3191.                             WriteLn('No Input Received in 15 seconds');
  3192.                           end;
  3193.  
  3194.  
  3195.  
  3196.  
  3197.  
  3198.  
  3199.                                CheckForCall Function
  3200.                                CheckForCall Function
  3201.  
  3202.  
  3203.           UNIT            LctBBS
  3204.           UNIT
  3205.  
  3206.  
  3207.  
  3208.  
  3209.                                     Page 46
  3210.             Copyright (c) 1987, 88, 89 Information Technology, Ltd.
  3211.  
  3212.  
  3213.                    LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL
  3214.  
  3215.  
  3216.  
  3217.           FUNCTION        'Listens' to the specified port to see if the
  3218.           FUNCTION
  3219.                           telephone is ringing.  If the phone is ringing,
  3220.                           waits for up to 30 seconds for a successful
  3221.                           connection to be established.
  3222.  
  3223.           DECLARATION     CheckForCall(CPort : integer);
  3224.           DECLARATION
  3225.  
  3226.           RESULT TYPE     integer;
  3227.           RESULT TYPE
  3228.  
  3229.           REMARKS         This function will return a value of -1 if the
  3230.           REMARKS
  3231.                           phone is not ringing, or if the modem fails to
  3232.                           respond to the call within the 30 second period
  3233.                           allowed.  In all other cases the function returns
  3234.                           the result code that was returned by the modem
  3235.                           itself.  It is the programmer's responsibility to
  3236.                           correctly recognize and react to the various codes.
  3237.                           In the case of a failure of the modem to respond,
  3238.                           this function will automatically attempt to
  3239.                           disconnect and reset the modem.
  3240.                            
  3241.                           The function assumes that the modem has been set up
  3242.                           to use numeric result codes, and that the S0
  3243.                           register (number of rings before answering) has not
  3244.                           been set to zero.  The function ResetModem sets the
  3245.                           correct values to match these assumptions.  CAUTION
  3246.                           - do not attempt to use this function on ports not
  3247.                           connected to a modem.  The function examines the
  3248.                           modem control status lines and may behave in a
  3249.                           unpredictable fashion if not connected to a modem.
  3250.  
  3251.           EXAMPLE         var
  3252.           EXAMPLE
  3253.                             ModemResult : integer;
  3254.                            
  3255.                           begin
  3256.                             repeat
  3257.                             ModemResult := CheckForCall(CPort);
  3258.                             if ModemResult = -1 then
  3259.                               Delay(1000);  (* settling time*)
  3260.                             until ModemResult <> -1;
  3261.                             Writeln('Modem reply to call was ',
  3262.                           ModemResult:2);
  3263.                           end;
  3264.  
  3265.           SEE ALSO        Disconnect, ResetModem
  3266.           SEE ALSO
  3267.  
  3268.  
  3269.  
  3270.  
  3271.  
  3272.  
  3273.                                 Disconnect Procedure
  3274.                                 Disconnect Procedure
  3275.  
  3276.  
  3277.           UNIT            LctBBS
  3278.           UNIT
  3279.  
  3280.  
  3281.  
  3282.                                     Page 47
  3283.             Copyright (c) 1987, 88, 89 Information Technology, Ltd.
  3284.  
  3285.  
  3286.                    LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL
  3287.  
  3288.  
  3289.  
  3290.           FUNCTION        Causes the modem to disconnect from the caller.
  3291.           FUNCTION
  3292.  
  3293.           DECLARATION     Disconnect(CPort : integer);
  3294.           DECLARATION
  3295.  
  3296.           REMARKS         Disconnects the modem by dropping the DTR (Data
  3297.           REMARKS
  3298.                           Terminal Ready) modem status signal for 1 second.
  3299.                           This action will cause most modems to drop carrier
  3300.                           and force the phone on-hook.  Please not that if
  3301.                           the modem has been optioned with DTR permanently
  3302.                           set on or ignored, this procedure will have no
  3303.                           effect.
  3304.  
  3305.  
  3306.  
  3307.  
  3308.  
  3309.  
  3310.                                 ResetModem Function
  3311.                                 ResetModem Function
  3312.  
  3313.  
  3314.           UNIT            LctBBS
  3315.           UNIT
  3316.  
  3317.           FUNCTION        Returns the modem to a known set of parameters,
  3318.           FUNCTION
  3319.                           suitable for use with the related functions in this
  3320.                           unit.  See the typed constants MODEMSET0 through
  3321.                           MODEMSET2 in the interface portion of the unit.
  3322.  
  3323.           DECLARATION     ResetModem(CPort, : integer);
  3324.           DECLARATION
  3325.  
  3326.           RESULT TYPE     integer;
  3327.           RESULT TYPE
  3328.  
  3329.           REMARKS         The modem is reset to a known state, including, but
  3330.           REMARKS
  3331.                           not limited to 1) answer on the first ring, 2)
  3332.                           numeric result codes, 3) extended code set.  The
  3333.                           function returns the result of the reset operation
  3334.                           (a modem response code) or -1 if the modem fails to
  3335.                           respond.  This function and related functions are
  3336.                           suitable for use only with HAYES-type modems.  It
  3337.                           is the programmer's responsibility to interpret the
  3338.                           result code returned.
  3339.  
  3340.           SEE ALSO        GetModemReply
  3341.           SEE ALSO
  3342.  
  3343.  
  3344.  
  3345.  
  3346.  
  3347.  
  3348.                                GetModemReply Function
  3349.                                GetModemReply Function
  3350.  
  3351.  
  3352.           UNIT            LctBBS
  3353.           UNIT
  3354.  
  3355.  
  3356.  
  3357.  
  3358.  
  3359.                                     Page 48
  3360.             Copyright (c) 1987, 88, 89 Information Technology, Ltd.
  3361.  
  3362.  
  3363.                    LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL
  3364.  
  3365.  
  3366.  
  3367.           FUNCTION        Returns the modem's response to the last set of
  3368.           FUNCTION
  3369.                           instructions that were issued to the modem, in
  3370.                           numeric form.
  3371.  
  3372.           DECLARATION     GetModemReply(CPort : integer);
  3373.           DECLARATION
  3374.  
  3375.           RESULT TYPE     integer;
  3376.           RESULT TYPE
  3377.  
  3378.           REMARKS         This function expects the modem to be returning
  3379.           REMARKS
  3380.                           numeric result codes (set ResetModem) of up to 2
  3381.                           digits.  The function will react to 2 digits
  3382.                           returned or the first <CR> returned, whichever
  3383.                           occurs first within a 1 second timeout period.  In
  3384.                           the case that the modem does not respond in the
  3385.                           timeout period, the function returns a value of -1.
  3386.                           In no case does the function attempt to evaluate
  3387.                           the response...this is left to the programmer.
  3388.  
  3389.           SEE ALSO        ResetModem.
  3390.           SEE ALSO
  3391.  
  3392.  
  3393.  
  3394.  
  3395.  
  3396.  
  3397.                                HAYES MODEM FUNCTIONS
  3398.                                HAYES MODEM FUNCTIONS
  3399.  
  3400.  
  3401.           UNIT            LctHayes
  3402.           UNIT
  3403.  
  3404.           FUNCTION        Provides support for various aspects of modems the
  3405.           FUNCTION
  3406.                           support the Hayes(Tm) command set.
  3407.  
  3408.           DECLARATIONS    const
  3409.           DECLARATIONS
  3410.                             NUMRES = 0     { numeric result codes}
  3411.                             WRDRES = 1     { word result codes }
  3412.                             SPKOFF = 0     { speaker off }
  3413.                             SPKON  = 1     { speaker on until CD }
  3414.                             SPKSPC = 2     { speaker always on }
  3415.                             ONHK   = 0     { go on-hook (hang up) }
  3416.                             OFFHK  = 1     { go off-hook (lift receiver) }
  3417.                             OFFHKS = 2     { go off-hook, don't close relay }
  3418.                             BASIC  = 0     { basic result set }
  3419.                             EXSET1 = 1     { extended results, set 1 }
  3420.                             EXSET3 = 2     { extended results, set 3 }
  3421.                             EXSET4 = 3     { extended results, set 4 }
  3422.                            
  3423.                           type
  3424.                             TelNumStr = string[20];
  3425.                            
  3426.                           procedure SetType(NType : byte)
  3427.                            
  3428.                           procedure SetSet(NSet : byte)
  3429.                            
  3430.  
  3431.  
  3432.  
  3433.                                     Page 49
  3434.             Copyright (c) 1987, 88, 89 Information Technology, Ltd.
  3435.  
  3436.  
  3437.                    LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL
  3438.  
  3439.  
  3440.  
  3441.                           function RetType : byte
  3442.                            
  3443.                           function RetSet : byte
  3444.                            
  3445.                           function ModemCodesOn(CPort : integer):boolean
  3446.                            
  3447.                           function ModemCodesOff(CPort : integer):boolean
  3448.                            
  3449.                           function ModemWordResponse(CPort : integer):boolean
  3450.                            
  3451.                           function ModemDigitResponse(CPort :
  3452.                           integer):boolean
  3453.                            
  3454.                           function RepeatModemCommand(CPort :
  3455.                           integer):boolean
  3456.                            
  3457.                           function ModemSpeaker(CPort : integer; Mode :
  3458.                           byte):boolean
  3459.                            
  3460.                           function SetModemRegister(CPort, Reg, NValue :
  3461.                           integer) : boolean
  3462.                            
  3463.                           function GetModemRegister(CPort, Reg, NValue :
  3464.                           integer) : boolean
  3465.                            
  3466.                           function ModemHalfDuplex(CPort : integer) : boolean
  3467.                            
  3468.                           function ModemFullDuplex(CPort : integer) : boolean
  3469.                            
  3470.                           function ModemEchoCmd(CPort : integer) : boolean
  3471.                            
  3472.                           function ModemNoEchoCmd(CPort : integer) : boolean
  3473.                            
  3474.                           function ModemHookMode(CPort : integer; HMode :
  3475.                           byte) : boolean
  3476.                            
  3477.                           function ModemCarrierOn(CPort : integer) : boolean
  3478.                            
  3479.                           function ModemCarrierOff(CPort : integer) : boolean
  3480.                            
  3481.                           function ModemWordResponse(CPort : integer):boolean
  3482.                            
  3483.                           function ModemDigitResponse(CPort :
  3484.                           integer):boolean
  3485.                            
  3486.                           function RepeatModemCommand(CPort :
  3487.                           integer):boolean
  3488.                            
  3489.                           function ModemSpeaker(CPort : integer; Mode :
  3490.                           byte):boolean
  3491.                            
  3492.                           function SetModemRegister(CPort, Reg, NValue :
  3493.                           integer) : boolean
  3494.                            
  3495.  
  3496.  
  3497.  
  3498.                                     Page 50
  3499.             Copyright (c) 1987, 88, 89 Information Technology, Ltd.
  3500.  
  3501.  
  3502.                    LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL
  3503.  
  3504.  
  3505.  
  3506.                           function GetModemRegister(CPort, Reg, NValue :
  3507.                           integer) : boolean
  3508.                            
  3509.                           function ModemHalfDuplex(CPort : integer) : boolean
  3510.                            
  3511.                           function ModemFullDuplex(CPort : integer) : boolean
  3512.                            
  3513.                           function ModemEchoCmd(CPort : integer) : boolean
  3514.                            
  3515.                           function ModemNoEchoCmd(CPort : integer) : boolean
  3516.                            
  3517.                           function ModemHookMode(CPort : integer; HMode :
  3518.                           byte) : boolean
  3519.                            
  3520.                           function ModemCarrierOn(CPort : integer) : boolean
  3521.                            
  3522.                           function ModemCarrierOff(CPort : integer) : boolean
  3523.                            
  3524.                           function ModemCodeSet(CPort : integer; NewSet :
  3525.                           byte) : boolean
  3526.                            
  3527.                           function ModemPulse(CPort : integer) : boolean
  3528.                            
  3529.                           function ModemTone(CPort : integer) : boolean
  3530.                            
  3531.                           function ModemDial(CPort : integer; TelNo :
  3532.                           TelNumStr) : boolean
  3533.  
  3534.           REMARKS         The ModemCodeSet function allows you to change the
  3535.           REMARKS
  3536.                           set of codes that are returned by the modem when an
  3537.                           action is specified.
  3538.                            
  3539.                           ModemDial instructs the modem to dial the number
  3540.                           contained in TelNo. Do not include the dialing
  3541.                           (ATD) prefix, or the trailing <CR>. These are
  3542.                           provided by the function. You may include non-
  3543.                           numeric characters as the contents of TelNo are not
  3544.                           checked. The dialing is done in the last known,
  3545.                           pulse or tone, mode. If you use the Modempulse or
  3546.                           ModemTone functions, then dialing will be done in
  3547.                           the mode that was last correctly enabled. If you
  3548.                           have not exercised these functions, then dialing
  3549.                           occurs in the modems default or power-up mode.
  3550.                            
  3551.                           The ModemHalfDuplex and ModemFullDuplex functions
  3552.                           place the modem into local echo and remote echo
  3553.                           modes respectively.
  3554.                            
  3555.                           The GetModemRegister function requests that the
  3556.                           modem return the current value of S-register Reg.
  3557.                           Reg must be in the range 0 to 13. Use the
  3558.                           GetStream, or similar function, to retrieve the
  3559.                           modem's response. Specifying a register outside the
  3560.                           0 to 13 range will cause a return of FALSE.
  3561.  
  3562.  
  3563.  
  3564.                                     Page 51
  3565.             Copyright (c) 1987, 88, 89 Information Technology, Ltd.
  3566.  
  3567.  
  3568.                    LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL
  3569.  
  3570.  
  3571.  
  3572.                            
  3573.                           SetModemRegister is the companion to
  3574.                           GetModemRegister, with the same restrictions. Sets
  3575.                           the S-register Reg to the value contained in
  3576.                           NValue. If NValue contains -1, then the register is
  3577.                           reset to its default (power-up) value. The function
  3578.                           checks the value to be certain that it is within
  3579.                           the limits specified for the particular register,
  3580.                           and returns a value of FALSE if the value is
  3581.                           outside the predefined limits.
  3582.                            
  3583.                           ModemCarrierOff enables modem carrier detect, but
  3584.                           disables the modems carrier signal. The
  3585.                           ModemCarrierOn companion enables both carrier
  3586.                           detect and the modems carrier signal. When
  3587.                           ModemCarrierOff is used the modem will receive data
  3588.                           but will be unable to send data.
  3589.                            
  3590.                           The ModemNoEchoCmd and ModemEchoCmd functions
  3591.                           determine whether commands sent to the modem are
  3592.                           echoed back to the sending program. With echo
  3593.                           turned off, the modem will continue to accept
  3594.                           commands, but will not try to redisplay the
  3595.                           command's characters.
  3596.                            
  3597.                           ModemHookMode allows you to control the current
  3598.                           status of the modem's telephone line connection.
  3599.                           See your modem's documentation and the above
  3600.                           constants for additional information.
  3601.                            
  3602.                           The ModemRepeatCommand function instructs the modem
  3603.                           to repeat the last command sequence executed.
  3604.                           Generally, this function is of greatest value in
  3605.                           redialing numbers that are busy, although its use
  3606.                           is not restricted to that.
  3607.                            
  3608.                           The way in which your modem responds to commands is
  3609.                           determined, in part, by the ModemWordResponse and
  3610.                           ModemDigitResponse functions. If you call
  3611.                           ModemWordResponse, then modem responses use the
  3612.                           English language response codes, e.g. CONNECT or
  3613.                           OK. Calling ModemDigitResponse instructs the modem
  3614.                           to respond with code numbers only from the
  3615.                           currently selected response set, see the
  3616.                           ModemCodeSet function above.
  3617.                            
  3618.                           You may use the functions ModemCodesOn and
  3619.                           ModemCodesOff to specify whether you want your
  3620.                           modem to send back response codes when it receives
  3621.                           a command string. In a sense, these act as
  3622.                           companions to the EchoCmd functions above.
  3623.                            
  3624.  
  3625.  
  3626.  
  3627.  
  3628.  
  3629.                                     Page 52
  3630.             Copyright (c) 1987, 88, 89 Information Technology, Ltd.
  3631.  
  3632.  
  3633.                    LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL
  3634.  
  3635.  
  3636.  
  3637.                           Use the ModemSpeaker function to control the
  3638.                           modem's internal speaker, if it has one. See the
  3639.                           above constants for the applicable codes.
  3640.                            
  3641.                           The RetSet and RetType functions return,
  3642.                           respectively, the last known command set
  3643.                           (ModemCodeSet) and last known result type
  3644.                           (ModemWordResponse, ModemDigitResponse). The RetSet
  3645.                           and RetType  functions are only of value when used
  3646.                           in conjunction with the companion functions.
  3647.  
  3648.           GENERAL REMARKS Several considerations are in order if you intend
  3649.           GENERAL REMARKS
  3650.                           to use the Hayes ToolBox functions.
  3651.  
  3652.                              1.  You are responsible for checking the return
  3653.                                  codes from the modem once you have given
  3654.                                  modem a command. To make the task easier, we
  3655.                                  suggest that you turn OFF command echo (so
  3656.                                  that you don't have to worry about
  3657.                                  separating commands from responses) and turn
  3658.                                  ON numeric responses (to make the
  3659.                                  interpretation of result codes easier and
  3660.                                  faster).
  3661.  
  3662.                              2.  Be sure that you allow  adequate time
  3663.                                  between commands for the modem to process
  3664.                                  the command and respond. Failure to observe
  3665.                                  this rule may result in commands being
  3666.                                  misinterpreted or "lost". You can monitor
  3667.                                  the number of characters in the receive
  3668.                                  buffer to help you with the timing. Or
  3669.                                  alternatively, check the response after each
  3670.                                  command. The latter approach is more in line
  3671.                                  with what we believe to be good programming
  3672.                                  practice.
  3673.  
  3674.           RETURN VALUES   All functions return a value of FALSE if a port or
  3675.           RETURN VALUES
  3676.                           other error is detected, TRUE otherwise.
  3677.  
  3678.  
  3679.  
  3680.  
  3681.  
  3682.  
  3683.  
  3684.                                      Index
  3685.                                      Index
  3686.  
  3687.  
  3688.               8250 7, 14                  B
  3689.                                           B
  3690.               8259 19                     base port 9
  3691.                                           baud rate 10
  3692.               A                           BIOS 20
  3693.               A
  3694.               ASP 1                       BIOS functions 21
  3695.                                           BREAK 13, 34, 35, 45
  3696.  
  3697.  
  3698.  
  3699.                                     Page 53
  3700.             Copyright (c) 1987, 88, 89 Information Technology, Ltd.
  3701.  
  3702.  
  3703.                    LITECOMM-TP (Tm) TOOLBOX for Turbo-PASCAL
  3704.  
  3705.  
  3706.  
  3707.               buffers 14, 29              IRQ 20
  3708.                                           irq 28
  3709.               C                           IRQ0 20
  3710.               C
  3711.               character length 11         ISR 9
  3712.               CheckForCall 23
  3713.               COM3 19                     L
  3714.                                           L
  3715.               COM4 19                     look-ahead 41
  3716.                                           look-ahead
  3717.                                           __________
  3718.               CommOpen 19
  3719.               control structures 14       M
  3720.                                           M
  3721.               CTS 33                      modem control 12
  3722.                                           modem status 13
  3723.               D                           ModemStatus 23
  3724.               D
  3725.               data overrun error 15
  3726.               data path 7                 O
  3727.                                           O
  3728.               Data Terminal Ready         open function 14
  3729.                  See: DTR                 OUT2 12
  3730.                  ____
  3731.               DCD 33
  3732.               DeltaCTS 33                 P
  3733.                                           P
  3734.               DSR 33                      parallel 7
  3735.               DTR 12, 14, 31, 36, 37,     parity 11
  3736.                  38, 48                   parity error 15
  3737.                                           poll 8
  3738.               E                           PortChange 19
  3739.               E
  3740.               error status bits 35
  3741.               Event Timer 45              R
  3742.                                           R
  3743.               expansion cards 20          Request To Send See:
  3744.                                                           ____
  3745.                                              RTS
  3746.               F                           RI 23, 33
  3747.               F
  3748.               flow control 38             RTS 12, 15, 31, 36, 37,
  3749.               framing error 15               38
  3750.  
  3751.               H                           S
  3752.               H                           S
  3753.               handshake 33                S-register 51
  3754.               handshaking 12, 13          serial port 7
  3755.               HAYES 48                    stream 42, 43
  3756.               heap 14, 30
  3757.                                           T
  3758.                                           T
  3759.               I                           TSR 22
  3760.               I
  3761.               interrupt 8
  3762.               interrupt chaining 17,      U
  3763.                                           U
  3764.                  21                       UART 7
  3765.               interrupt enable flag
  3766.                  15                       V
  3767.                                           V
  3768.               Interrupt Service           vector numbers 20
  3769.                  Routine 9
  3770.               interrupt vector 20         X
  3771.                                           X
  3772.               interrupt vectors 19        XOFF 39
  3773.                                           XON 39
  3774.  
  3775.  
  3776.  
  3777.  
  3778.  
  3779.  
  3780.  
  3781.  
  3782.  
  3783.                                     Page 54
  3784.             Copyright (c) 1987, 88, 89 Information Technology, Ltd.
  3785.  
  3786.  
  3787.  
  3788.  
  3789.  
  3790.  
  3791.  
  3792.  
  3793.  
  3794.  
  3795.  
  3796.  
  3797.                                  Contents
  3798.                                  Contents
  3799.  
  3800.  
  3801.  
  3802.             Chapter 1  OVERVIEW                                   1
  3803.                1.1  FEATURES . . . . . . . . . . . . . . . . . .  1
  3804.                1.2  THE SHAREWARE CONCEPT  . . . . . . . . . . .  1
  3805.  
  3806.             Chapter 2  LICENSE, WARRANTY AND REGISTRATION         3
  3807.                2.1  LICENSE  . . . . . . . . . . . . . . . . . .  3
  3808.                2.2  WARRANTY . . . . . . . . . . . . . . . . . .  4
  3809.                2.3  REGISTERING YOUR COPY  . . . . . . . . . . .  4
  3810.                2.4  NOTE . . . . . . . . . . . . . . . . . . . .  5
  3811.  
  3812.             Chapter 3  Serial Port Fundamentals                   7
  3813.                3.1  The 8250 UART family . . . . . . . . . . . .  7
  3814.                3.2  Purpose of the port  . . . . . . . . . . . .  7
  3815.                3.3  Internal Details . . . . . . . . . . . . . .  8
  3816.                   3.3.1  The Interrupt Connection  . . . . . . .  8
  3817.                   3.3.2  The Programmable Port Registers . . . .  9
  3818.                      3.3.2.1  register 0 - transmit/receive  . . 10
  3819.                      3.3.2.2  register 0 - baud rate selection . 10
  3820.                      3.3.2.3  register 1 - interrupt enable  . . 10
  3821.                      3.3.2.4  register 1 - baud rate selection . 11
  3822.                      3.3.2.5  register 2 - interrupt
  3823.                               identification . . . . . . . . . . 11
  3824.                      3.3.2.6  register 3 - line control  . . . . 11
  3825.                      3.3.2.7  register 4 - modem control . . . . 12
  3826.                      3.3.2.8  register 5 - line status . . . . . 12
  3827.                      3.3.2.9  register 6 - modem status  . . . . 13
  3828.                3.4  The LiteComm Connection  . . . . . . . . . . 13
  3829.                3.5  TOOLBOX NOTES AND WARNINGS . . . . . . . . . 14
  3830.  
  3831.             Chapter 4  LITECOMM-TP HISTORY                       17
  3832.                4.1  VERSION 3.0  . . . . . . . . . . . . . . . . 17
  3833.                4.2  NEW IN VERSION 5 . . . . . . . . . . . . . . 17
  3834.  
  3835.             Chapter 5  BEYOND COM2                               19
  3836.                5.1  THE TOOLBOX METHODOLOGY  . . . . . . . . . . 19
  3837.                5.2  CAUTIONS . . . . . . . . . . . . . . . . . . 20
  3838.                5.3  OTHER GENERAL NOTES AND WARNINGS . . . . . . 22
  3839.                5.4  USE WITH MULTITASKING ENVIRONMENTS . . . . . 22
  3840.                5.5  NOTES ON RING DETECTION  . . . . . . . . . . 23
  3841.  
  3842.             Chapter 6  PACKAGE CONTENTS                          25
  3843.                6.1  INSTALLATION INSTRUCTIONS  . . . . . . . . . 25
  3844.  
  3845.  
  3846.  
  3847.  
  3848.  
  3849.                                        i
  3850.  
  3851.  
  3852.  
  3853.  
  3854.  
  3855.  
  3856.  
  3857.             Chapter 7  PROCEDURE AND FUNCTION REFERENCE          27
  3858.                7.1  UNIT USAGE . . . . . . . . . . . . . . . . . 27
  3859.  
  3860.             PortChange function                                  28
  3861.  
  3862.             CommOpen function                                    29
  3863.  
  3864.             CommClose procedure                                  31
  3865.  
  3866.             CommSetup function                                   32
  3867.  
  3868.             BytesInInput function                                32
  3869.  
  3870.             ModemStatus function                                 33
  3871.  
  3872.             BreakRecd function                                   34
  3873.  
  3874.             ErrorStatus function                                 34
  3875.  
  3876.             SetModemSignals function                             36
  3877.  
  3878.             ClearModemSignals function                           37
  3879.  
  3880.             FlipModemSignals function                            37
  3881.  
  3882.             EnableXon function                                   38
  3883.  
  3884.             XoffRecd function                                    39
  3885.  
  3886.             XoffSent function                                    40
  3887.  
  3888.             LctGet function                                      40
  3889.  
  3890.             LctPeek function                                     41
  3891.  
  3892.             LctPut function                                      42
  3893.  
  3894.             GetStream function                                   42
  3895.  
  3896.             PutStream function                                   43
  3897.  
  3898.             Buffer Flushing functions                            44
  3899.  
  3900.             SendBreak function                                   45
  3901.  
  3902.             CheckEvent Function                                  45
  3903.  
  3904.             NewEvent Function                                    46
  3905.  
  3906.             CheckForCall Function                                46
  3907.  
  3908.             Disconnect Procedure                                 47
  3909.  
  3910.             ResetModem Function                                  48
  3911.  
  3912.  
  3913.  
  3914.                                       ii
  3915.  
  3916.  
  3917.  
  3918.  
  3919.  
  3920.  
  3921.  
  3922.             GetModemReply Function                               48
  3923.  
  3924.             HAYES MODEM FUNCTIONS                                49
  3925.  
  3926.             Index                                                54
  3927.  
  3928.  
  3929.  
  3930.  
  3931.  
  3932.  
  3933.  
  3934.  
  3935.  
  3936.  
  3937.  
  3938.  
  3939.  
  3940.  
  3941.  
  3942.  
  3943.  
  3944.  
  3945.  
  3946.  
  3947.  
  3948.  
  3949.  
  3950.  
  3951.  
  3952.  
  3953.  
  3954.  
  3955.  
  3956.  
  3957.  
  3958.  
  3959.  
  3960.  
  3961.  
  3962.  
  3963.  
  3964.  
  3965.  
  3966.  
  3967.  
  3968.  
  3969.  
  3970.  
  3971.  
  3972.  
  3973.  
  3974.  
  3975.  
  3976.  
  3977.  
  3978.  
  3979.                                       iii
  3980.  
  3981.  
  3982.  
  3983.  
  3984.  
  3985.  
  3986.  
  3987.  
  3988.  
  3989.  
  3990.  
  3991.  
  3992.  
  3993.  
  3994.  
  3995.  
  3996.  
  3997.  
  3998.  
  3999.  
  4000.  
  4001.  
  4002.  
  4003.  
  4004.  
  4005.  
  4006.  
  4007.  
  4008.  
  4009.  
  4010.  
  4011.  
  4012.  
  4013.  
  4014.  
  4015.  
  4016.  
  4017.  
  4018.  
  4019.  
  4020.  
  4021.  
  4022.  
  4023.  
  4024.  
  4025.  
  4026.  
  4027.  
  4028.  
  4029.  
  4030.  
  4031.  
  4032.  
  4033.  
  4034.  
  4035.  
  4036.  
  4037.  
  4038.  
  4039.  
  4040.  
  4041.  
  4042.  
  4043.  
  4044.                                       iv
  4045.  
  4046.  
  4047.  
  4048.  
  4049.  
  4050.  
  4051.  
  4052.  
  4053.  
  4054.  
  4055.  
  4056.  
  4057.  
  4058.                                  Figures
  4059.                                  Figures
  4060.  
  4061.  
  4062.             Figure 3.1: Register 1 Bit Definitions . . . . . . . 10
  4063.             Figure 3.2: Register 2 Bit Definitions . . . . . . . 11
  4064.             Figure 3.3: Register 3 Bit Definitions . . . . . . . 12
  4065.             Figure 3.4: Register 4 Bit Definitions . . . . . . . 12
  4066.             Figure 3.5: Register 5 Bit Definitions . . . . . . . 13
  4067.             Figure 3.6: Register 6 Bit Definitions . . . . . . . 13
  4068.  
  4069.  
  4070.  
  4071.  
  4072.  
  4073.  
  4074.  
  4075.  
  4076.  
  4077.  
  4078.  
  4079.  
  4080.  
  4081.  
  4082.  
  4083.  
  4084.  
  4085.  
  4086.  
  4087.  
  4088.  
  4089.  
  4090.  
  4091.  
  4092.  
  4093.  
  4094.  
  4095.  
  4096.  
  4097.  
  4098.  
  4099.  
  4100.  
  4101.  
  4102.  
  4103.  
  4104.  
  4105.  
  4106.  
  4107.  
  4108.  
  4109.  
  4110.                                        v
  4111.  
  4112.  
  4113.  
  4114.  
  4115.  
  4116.  
  4117.  
  4118.  
  4119.  
  4120.  
  4121.  
  4122.  
  4123.  
  4124.  
  4125.  
  4126.  
  4127.  
  4128.  
  4129.  
  4130.  
  4131.  
  4132.  
  4133.  
  4134.  
  4135.  
  4136.  
  4137.  
  4138.  
  4139.  
  4140.  
  4141.  
  4142.  
  4143.  
  4144.  
  4145.  
  4146.  
  4147.  
  4148.  
  4149.  
  4150.  
  4151.  
  4152.  
  4153.  
  4154.  
  4155.  
  4156.  
  4157.  
  4158.  
  4159.  
  4160.  
  4161.  
  4162.  
  4163.  
  4164.  
  4165.  
  4166.  
  4167.  
  4168.  
  4169.  
  4170.  
  4171.  
  4172.  
  4173.  
  4174.  
  4175.                                       vi
  4176.  
  4177.  
  4178.  
  4179.  
  4180.  
  4181.  
  4182.  
  4183.  
  4184.  
  4185.  
  4186.  
  4187.  
  4188.  
  4189.                                   Tables
  4190.                                   Tables
  4191.  
  4192.  
  4193.             Table 3.1: Possible Error Conditions . . . . . . . . 15
  4194.             Table 5.1: COM3 and COM4 Default Settings  . . . . . 19
  4195.             Table 6.1: Basic Diskette Contents . . . . . . . . . 25
  4196.  
  4197.  
  4198.  
  4199.  
  4200.  
  4201.  
  4202.  
  4203.  
  4204.  
  4205.  
  4206.  
  4207.  
  4208.  
  4209.  
  4210.  
  4211.  
  4212.  
  4213.  
  4214.  
  4215.  
  4216.  
  4217.  
  4218.  
  4219.  
  4220.  
  4221.  
  4222.  
  4223.  
  4224.  
  4225.  
  4226.  
  4227.  
  4228.  
  4229.  
  4230.  
  4231.  
  4232.  
  4233.  
  4234.  
  4235.  
  4236.  
  4237.  
  4238.  
  4239.  
  4240.  
  4241.                                       vii
  4242.