home *** CD-ROM | disk | FTP | other *** search
/ Power Programming / powerprogramming1994.iso / progtool / modem / tcomm11.arc / TCOMM.DOC < prev    next >
Text File  |  1987-06-09  |  47KB  |  2,308 lines

  1.                 TurboCom Communications Toolbox for TURBO C
  2.  
  3.                                   INTRODUCTION
  4.  
  5.         The TurboCom Toolbox(tm) is a set of powerful routines designed 
  6.         to provide easy access to the full capabilities of the PC's 
  7.         asynchronous communications ports. In its initial release, the 
  8.         TurboCom ToolBox supports fully interrupt-driven and buffered 
  9.         communications support on both COM1 and COM2 simultaneously. 
  10.         Version 1.1, supplied here, supports COM3 and COM4 as well. Now 
  11.         you can quickly incorporate sophisticated communications support 
  12.         in your applications without having in-depth knowledge of how the 
  13.         hardware functions.
  14.  
  15.         The ToolBox was developed as the result of a need to provide just 
  16.         this type of support in CAM applications which were developed for 
  17.         a client. We have found that the TURBO C (tm) package 
  18.         provides an excellent vehicle for our work, and the ToolBox is 
  19.         closely integrated with the TURBO package. 
  20.  
  21.  
  22.                               THE SHAREWARE CONCEPT
  23.  
  24.         Shareware is a "try before you buy" means of software 
  25.         distribution. If you find a shareware product useful, pay the 
  26.         registration fee, and let the authors know that you support their 
  27.         efforts.
  28.  
  29.         The TurboCom ToolBox, tiny model library only, is distributed as 
  30.         a shareware product. To receive all model libraries and/or the 
  31.         source code for the product, register your copy today. See the 
  32.         registration form at the end of the documentation.
  33.  
  34.         The TurboCom ToolBox is not public-domain software. Information 
  35.         Technology, Ltd. grants to individuals the right to use the 
  36.         TurboCom ToolBox as a part of other products they may develop. 
  37.         Commercial use by corporations or distribution of the ToolBox for 
  38.         profit is prohibited, except with the written consent of 
  39.         Information Technology, Ltd., and may subject violators to civil 
  40.         penalties. Further, neither the TurboCom ToolBox nor its 
  41.         documentation may be distributed in any modified form.
  42.  
  43.  
  44.                                     WARRANTY
  45.  
  46.         The TurboCom ToolBox is distributed as-is and without warranty, 
  47.         including, but not limited to, the implied warranties of 
  48.         merchantability and fitness for a particular purpose.
  49.  
  50.         The user(s) of the TurboCom ToolBox agree to hold the author and 
  51.         distributors of this product harmless for any damages, either 
  52.         direct or consequential, which arise from the use of this 
  53.         product.
  54.  
  55.     TURBO C is a registered trademark of Borland International, Inc.
  56.  
  57.  
  58.                 Copyright (c) 1987 Information Technology, Ltd.
  59.  
  60.  
  61.  
  62.  
  63.  
  64.                 TurboCom Communications 
  65.  
  66.  
  67.                               REGISTERING YOUR COPY
  68.  
  69.         Registration of your copy of the TurboCom ToolBox provides you 
  70.         with several benefits:
  71.  
  72.              1. Puts you on our mailing list for low-cost updates and 
  73.              enhancements, when they occur.
  74.  
  75.              2. Gives you access to telephone support. Sorry, but we 
  76.              cannot provide support by telephone to unregistered user's 
  77.              of the ToolBox. Unregistered users can leave EMAIL on 
  78.              Compuserve to 70166,1152. We will respond to EMAIL on an 
  79.              as-available basis.
  80.  
  81.              3. Helps to further the shareware concept.
  82.  
  83.         To register your copy, use the form at the end of this 
  84.         documentation.
  85.  
  86.                                       NOTE
  87.  
  88.         We are already planning enhancements to this product. The first 
  89.         to be released will be a super-efficient XMODEM engine for file 
  90.         transfers, followed by similar engines for CompuServe B and 
  91.         Kermit protocols. These engines, as they are released, will only 
  92.         be made available to registered ToolBox users. The tiny model 
  93.         library, as enhanced but without the protocol engines, will 
  94.         continue to be offered as shareware.
  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.                 Copyright (c) 1987 Information Technology, Ltd.
  125.  
  126.  
  127.  
  128.  
  129.  
  130.                 TurboCom Communications 
  131.  
  132.  
  133.         COMMUNICATIONS AND THE PC
  134.  
  135.         This section is intended as a mini-tutorial on commumnications 
  136.         concepts. We encourage you to read it, although it is not 
  137.         strictly necessary to do so.
  138.  
  139.         The IBM-PC, and its close compatables, is a generally well 
  140.         thought-out, flexible, and well-executed computer. 
  141.         Unfortunately, not as much can be said for the thought which was 
  142.         given to the software which is meant to provide access to that 
  143.         hardware. One of the shortcomings which is most noticable is in 
  144.         the support, or rather lack of it, that is provided to handle 
  145.         access to the serial port. Support for the serial port is 
  146.         limited by the BIOS to polled mode only, i.e. a program must 
  147.         interrogate the port on a regular basis to avoid losing received 
  148.         characters, and to check to determine whether or not the port is 
  149.         ready to send a character. Not only is this mode of operation 
  150.         primitive; it also tends to cause complications when attempting 
  151.         to perform any but the simplest of tasks.
  152.  
  153.         A novice might think that the hardware, in some way, is the 
  154.         limiting factor. In fact, everything that is needed, hardware-
  155.         wise, to support a more sophisticated method of handling the 
  156.         serial port is already there. All we are missing is the software 
  157.         follow-through. The TurboCom ToolBox provides this missing 
  158.         software.
  159.  
  160.         The term serial port comes from the fact that both incoming and 
  161.         outgoing characters entering and leaving the port do so in a 
  162.         bitwise fashion. When we send a character out the serial port, 
  163.         the responsible circuitry sends out information one bit at a 
  164.         time. When we receive a character, this circuitry accepts the 
  165.         individual bits and reassembles them into a recognizable 
  166.         character. These very complex operations are performed 
  167.         automatically by the 8250 UART (Universal Asynchronous Receiver-
  168.         Transmitter).
  169.  
  170.         The 8250 UART is a fully programmable device that permits 
  171.         independant control of the various parameters that affect 
  172.         serial communications, i.e. baud rate, parity, number of data 
  173.         bits, and number of stop bits. The 8250 also optionally supports 
  174.         four types of interrupts, error/break detection, modem status 
  175.         change detection, transmitter ready, and received character 
  176.         ready. The TurboCom ToolBox fully supports all four type of 
  177.         interrupts.
  178.  
  179.         The term "asynchronous" implies that there is no timing 
  180.         associated with the transmission of information. Instead, the 
  181.         "clocking-in" of the data bits is done by counting the bits. The 
  182.         first bit sent or received is call the start bit and signals the 
  183.         beginning of a new character. The individual data bits follow 
  184.         the start bit which are clocked out and in at the specified data 
  185.         rate, with the least significant bit transferred first and the 
  186.         parity bit, if present, transferred last. Finally one or more 
  187.         stop bits follow, signalling the end of the character.
  188.  
  189.  
  190.                 Copyright (c) 1987 Information Technology, Ltd.
  191.  
  192.  
  193.  
  194.  
  195.  
  196.                 TurboCom Communications 
  197.  
  198.  
  199.  
  200.         The 8250 UART takes care of all of the mechanics associated with 
  201.         the process described in the preceeding paragraph. The UART will 
  202.         also detect and report error which may occur in the process. For 
  203.         example, if the parity bit is incorrect, the UART reports the 
  204.         fact. If too few or too many bits are received, the UART will 
  205.         report a framing error or overrun error respectivally.
  206.  
  207.         Since the transmission of information may depend on complex 
  208.         interactions with another device, such as a modem or computer, 
  209.         the 8250 can also report on the status of the "handshaking" lines 
  210.         used to provide information about the status of the connection 
  211.         with the other device. These signals are explained below:
  212.  
  213.               SIGNAL DESCRIPTION
  214.  
  215.                  CTS Clear To Send - The other device 
  216.                                will accept a transmission.
  217.  
  218.                  DSR Data Set Ready - The other device 
  219.                                is enabled.
  220.  
  221.                  RI Ring Indicator - Usually reserved
  222.                                for modems only. The phone is 
  223.                                ringing.
  224.  
  225.                  DCD Data Carrier Detect - Usually re-
  226.                                served for modems. The other 
  227.                                modem's carrier signal was 
  228.                                detected.
  229.  
  230.         The header file for the TurboCom ToolBox contains the various bit 
  231.         masks required for you to make use of the information provided by 
  232.         the 8250 UART.
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.                 Copyright (c) 1987 Information Technology, Ltd.
  257.  
  258.  
  259.  
  260.  
  261.  
  262.                 TurboCom Communications 
  263.  
  264.  
  265.         DO's and DONT's of the ToolBox
  266.  
  267.         Before you can send or receive information on a serial port using 
  268.         the ToolBox, you must use the open function to enable the line. 
  269.         This function initializes the 8250 UART with the correct 
  270.         parameters, and introduces the UART into the interrupt structure 
  271.         of the PC. The ToolBox will detect, and report, any errors that 
  272.         you may make in selecting the port or specifying the initial 
  273.         parameters. The ToolBox cannot and will not detect an attempt to 
  274.         open a non-existant serial port.
  275.  
  276.         The ToolBox interfaces directly with the interrupt structure of 
  277.         the PC. It is critical that, before exiting a program that has 
  278.         opened a serial port that the serial port is closed with the 
  279.         close function. If you exit your program without closing the 
  280.         port, you may cause you system to crash since the interrupt 
  281.         vector for the port might point to a section of memory that no 
  282.         longer contains the needed code to support the interrupt.
  283.  
  284.         Failure of the open function can be the result of either improper 
  285.         parameters to the open function, or insufficient memory available 
  286.         to allocate the requested buffers and related control structures 
  287.         for the port. Memory for the transmit and receive buffers as 
  288.         well as the port control block are allocated from free memory. 
  289.         It is your responsibility to insure that adequate memory is 
  290.         available for this purpose.
  291.  
  292.         Unless you are very familiar with the interrupt structure of the 
  293.         PC, do not attempt to manipulate the interrupt enable flag 
  294.         outside of the ToolBox. The ToolBox sets and clears the 
  295.         interrupt enable flag at appropriate times and assumes that it 
  296.         has sole control over the flag.
  297.  
  298.         Unless otherwise specified, all library functions have been 
  299.         compiled with the default alignment, i.e. the structure alignment 
  300.         switch has not been used in creating the ToolBox library.
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.                 Copyright (c) 1987 Information Technology, Ltd.
  323.  
  324.  
  325.  
  326.  
  327.  
  328.                 TurboCom Communications 
  329.  
  330.  
  331.                                NEW IN VERSION 1.1
  332.  
  333.         With version 1.1 we have made several changes of signifigance. 
  334.         The ToolBox now fully supports both COM3 and COM4, in addition to 
  335.         COM1 and COM2. Within certain restrictions, and dependant upon 
  336.         the particular system, it is now possible to handle interrupt-
  337.         driven communications on all four ports simultaneously. See the 
  338.         section GOING PAST COM2 for additional details.
  339.  
  340.         Version 1.1 of the ToolBox has also been shrunk by some using 
  341.         some different techniques in the kernel, and by changing the 
  342.         organization of the library itself. Please be aware that change 
  343.         have been made to the litecomm.h file which require that 
  344.         applications using the ToolBox be recompiled and re-linked.
  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.                 Copyright (c) 1987 Information Technology, Ltd.
  389.  
  390.  
  391.  
  392.  
  393.  
  394.                 TurboCom Communications 
  395.  
  396.  
  397.                                NEW IN VERSION 1.2
  398.  
  399.         Version 1.2 adds 21 new functions designed to aid you in the use 
  400.         of Hayes and Hayes compatible modems. It is not the intent of 
  401.         these new functions to replace your knowledge of the Hayes 
  402.         command set, but rather to augment it by relieving the burden of 
  403.         re-inventing the wheel. In our experience, the most successful 
  404.         programs rely heavily upon the use of pre-written and proven 
  405.         modules. The new functions provide just such capability.
  406.  
  407.         As with the original ToolBox functions, the new functions do 
  408.         error checking, where appropriate. They will not, however, 
  409.         prevent you from feeding a modem a set of nonsense or conflicting 
  410.         commands. It is your responsibility to insure that the commands 
  411.         you are issuing to the modem make sense. Therefore, when you are 
  412.         using the modem-related function, we strongly urge you to check 
  413.         the modem result codes, unless you've turned them off of course.
  414.  
  415.  
  416.  
  417.  
  418.  
  419.  
  420.  
  421.  
  422.  
  423.  
  424.  
  425.  
  426.  
  427.  
  428.  
  429.  
  430.  
  431.  
  432.  
  433.  
  434.  
  435.  
  436.  
  437.  
  438.  
  439.  
  440.  
  441.  
  442.  
  443.  
  444.  
  445.  
  446.  
  447.  
  448.  
  449.  
  450.  
  451.  
  452.  
  453.  
  454.                 Copyright (c) 1987 Information Technology, Ltd.
  455.  
  456.  
  457.  
  458.  
  459.  
  460.                 TurboCom Communications 
  461.  
  462.  
  463.                                  GOING PAST COM2
  464.  
  465.         In the design of the original PC, and in subsequent variations 
  466.         such as the PC/AT, there were only provision for two serial 
  467.         ports. Many manufacturers of add-in products, both serial ports 
  468.         and internal modems have added the capability to support 1 or 
  469.         more additional ports beyond the COM2 limit. Generally, this can 
  470.         cause problems in the PC since there is no room in the interrupt 
  471.         request scheme for additional levels of interrupts, and there are 
  472.         no designated interrupt vector for other additional ports.
  473.  
  474.         The ToolBox approach to resolving these issues is to permit the 
  475.         programmer a degree of control over the parameters that govern 
  476.         the interrupt mechanism for COM3 and COM4. Specifically, these 
  477.         parameters are: 1) the interrupt request (IRQ) bit that is used 
  478.         to mask the 8259 interrupt controller; 2) the interrupt vector 
  479.         number (not address) to which the port is attached; and 3) the 
  480.         base i/o register for the port itself. Of course, it is assumed 
  481.         that the port is based upon the 8250 UART or compatible device.
  482.  
  483.         Before you attempt to use COM3 and/or COM4, you must determine 
  484.         from the port's documentation, the appropriate values for these 
  485.         three parameters. As distributed, the ToolBox assumes the 
  486.         following:
  487.  
  488.                             COM3 COM4
  489.  
  490.              IRQ Bit 4 3
  491.  
  492.              Vector # 0Ch 0Bh
  493.  
  494.              Base Reg 3E8h 2E8h
  495.  
  496.         You may change any or all of these values by using the _portchg 
  497.         function described below, but only before you open the port with 
  498.         comm_opn. Once the port has been opened, _portchg is 
  499.         ineffective, and _portchg will not work on COM1 or COM2.
  500.  
  501.         CAUTION
  502.         As you can see from the above, COM3 and COM4 share two critical 
  503.         parameters with COM1 and COM2 respectively, the IRQ bit and the 
  504.         interrupt vector number. If you intend to use COM1 and COM3 or 
  505.         COM2 and COM4 simultaneously, you must change the vector number 
  506.         for COM3 or COM4 to an unused vector. The ability for your add-
  507.         on ports to handle such a change is highly hardware dependant, so 
  508.         check your port's documentation carefully. Failure to do so will 
  509.         result in loss of data at best, and a system lockup at worst. 
  510.  
  511.  
  512.  
  513.  
  514.  
  515.  
  516.  
  517.  
  518.  
  519.  
  520.                 Copyright (c) 1987 Information Technology, Ltd.
  521.  
  522.  
  523.  
  524.  
  525.  
  526.                 TurboCom Communications 
  527.  
  528.  
  529.         FUNCTION _portchg
  530.  
  531.         SUMMARY
  532.  
  533.         #include <litecomm.h>
  534.  
  535.         int _portchg(port, base, irq, vector)
  536.  
  537.              unsigned port;
  538.              unsigned base;
  539.              unsigned vector;
  540.              char irq;
  541.  
  542.         DESCRIPTION
  543.  
  544.         Changes one or more of the critical parameters for COM3 or COM4. 
  545.         This function must be used before the port is opened to be 
  546.         effective. To leave any of the parameters at its default value, 
  547.         make the corresponding entry 0. Note that vector is a vector 
  548.         number, not and address or pointer.
  549.          
  550.         The default parameters are shown in the litecomm.h include file.
  551.  
  552.  
  553.         EXAMPLE
  554.  
  555.          if (_portchg(port, 0x408, 0, 0, 0) == -1)
  556.          {
  557.              printf("Error Changing Port %d\n", port);
  558.              exit(1);
  559.          }
  560.  
  561.         RETURN VALUES
  562.  
  563.         Returns 0 if the function is successful, -1 if you attempt to 
  564.         change a port other that 3 or 4.
  565.  
  566.  
  567.  
  568.  
  569.  
  570.  
  571.  
  572.  
  573.  
  574.  
  575.  
  576.  
  577.  
  578.  
  579.  
  580.  
  581.  
  582.  
  583.  
  584.  
  585.  
  586.                 Copyright (c) 1987 Information Technology, Ltd.
  587.  
  588.  
  589.  
  590.  
  591.  
  592.                 TurboCom Communications 
  593.  
  594.  
  595.         FUNCTION comm_opn
  596.  
  597.         SUMMARY
  598.  
  599.         #include <litecomm.h>
  600.  
  601.         int comm_opn(port, baud, parity, datab, stopb, inbufsz, outbufsz)
  602.  
  603.              unsigned port;
  604.              unsigned baud;
  605.              unsigned parity;
  606.              unsigned datab;
  607.              unsigned stopb;
  608.              unsigned inbufsz;
  609.              unsigned outbufsz;
  610.  
  611.         DESCRIPTION
  612.  
  613.         Opens the specified port for use and attaches an interrupt 
  614.         handler to DOS for the port. The function allocates buffers for 
  615.         input and output of the specified sizes, and sets the port to the 
  616.         parameters specified. The minimum value for inbufsz is 128; the 
  617.         minimum size for outbufsz is 64. A port opened in this manner 
  618.         must be closed using comm_close before program termination to 
  619.         avoid the possibility of a system crash.
  620.  
  621.         The parameters passed to the function should be from the 
  622.         parameter set in the litecomm.h include file.
  623.  
  624.  
  625.         EXAMPLE
  626.  
  627.          if (comm_opn(port, B1200, NPARITY, BIT8, STOP1, 256, 256) == -1)
  628.          {
  629.              printf("Error Opening Port %d\n", port);
  630.              exit(1);
  631.          }
  632.  
  633.         RETURN VALUES
  634.  
  635.              Upon successful open, the function returns port. If any 
  636.              error occurs, regardless of type, the function returns -1.
  637.  
  638.  
  639.  
  640.  
  641.  
  642.  
  643.  
  644.  
  645.  
  646.  
  647.  
  648.  
  649.  
  650.  
  651.  
  652.                 Copyright (c) 1987 Information Technology, Ltd.
  653.  
  654.  
  655.  
  656.  
  657.  
  658.                 TurboCom Communications 
  659.  
  660.  
  661.         FUNCTION comm_close
  662.  
  663.         SUMMARY
  664.  
  665.         #include <litecomm.h>
  666.  
  667.         int comm_close(port)
  668.  
  669.              unsigned port;
  670.  
  671.         DESCRIPTION
  672.  
  673.              This function is the companion to comm_opn and, in effect, 
  674.              performs the opposite action. Comm_close detaches the 
  675.              library routines from the interrupt handler, and reconnects 
  676.              the previous interrupt handler. Comm_close also release 
  677.              dynamically allocated member used for buffering and control 
  678.              structures. Failure to call comm_close before terminating a 
  679.              program may result in unexplained system crashes or hangs.
  680.  
  681.         RETURN VALUES
  682.  
  683.              If any error occurs, regardless of type, the function 
  684.              returns -1.
  685.  
  686.  
  687.  
  688.  
  689.  
  690.  
  691.  
  692.  
  693.  
  694.  
  695.  
  696.  
  697.  
  698.  
  699.  
  700.  
  701.  
  702.  
  703.  
  704.  
  705.  
  706.  
  707.  
  708.  
  709.  
  710.  
  711.  
  712.  
  713.  
  714.  
  715.  
  716.  
  717.  
  718.                 Copyright (c) 1987 Information Technology, Ltd.
  719.  
  720.  
  721.  
  722.  
  723.  
  724.                 TurboCom Communications 
  725.  
  726.  
  727.         FUNCTION comm_setup
  728.  
  729.         SUMMARY
  730.  
  731.         #include <litecomm.h>
  732.  
  733.         int comm_setup(port,baud,parity,datab,stopb)
  734.  
  735.              unsigned port;
  736.              unsigned baud;
  737.              unsigned parity;
  738.              unsigned datab;
  739.              unsigned stopb;
  740.  
  741.  
  742.         DESCRIPTION
  743.  
  744.              The comm_setup function is a subset of the comm_opn function 
  745.              and the remarks made in the description of comm_opn apply. 
  746.              This function is useful if you wish to change the basic 
  747.              communication parameters of the specified port that has 
  748.              already been opened without comm_close'ing the port and 
  749.              breaking the telephone connection.
  750.  
  751.         EXAMPLE
  752.  
  753.              if (comm_setup(port, B1200, NPARITY, BIT8, STOP1) == -1)
  754.              {
  755.                  printf("Error Changing Port %d\n", port);
  756.                  exit(1);
  757.              }
  758.  
  759.         RETURN VALUES
  760.  
  761.              If any error occurs, regardless of type, the function 
  762.              returns -1.
  763.  
  764.         SEE ALSO
  765.              comm_opn
  766.  
  767.  
  768.  
  769.  
  770.  
  771.  
  772.  
  773.  
  774.  
  775.  
  776.  
  777.  
  778.  
  779.  
  780.  
  781.  
  782.  
  783.  
  784.                 Copyright (c) 1987 Information Technology, Ltd.
  785.  
  786.  
  787.  
  788.  
  789.  
  790.                 TurboCom Communications 
  791.  
  792.  
  793.         FUNCTION lc_vport
  794.  
  795.         SUMMARY
  796.  
  797.         #include <litecomm.h>
  798.  
  799.         COMM *lc_vport(port)
  800.  
  801.              unsigned port;
  802.  
  803.  
  804.         DESCRIPTION
  805.  
  806.              Used internally to validate that the port number specified 
  807.              is correct and has been opened with the comm_opn function. 
  808.              May be of use to you in writing certain applications.
  809.  
  810.         RETURN VALUES
  811.  
  812.              If the port is valid and has been opened, returns a pointer 
  813.              to the control block for the port. Returns NULL if an error 
  814.              occurs;
  815.          
  816.  
  817.  
  818.  
  819.  
  820.  
  821.  
  822.  
  823.  
  824.  
  825.  
  826.  
  827.  
  828.  
  829.  
  830.  
  831.  
  832.  
  833.  
  834.  
  835.  
  836.  
  837.  
  838.  
  839.  
  840.  
  841.  
  842.  
  843.  
  844.  
  845.  
  846.  
  847.  
  848.  
  849.  
  850.                 Copyright (c) 1987 Information Technology, Ltd.
  851.  
  852.  
  853.  
  854.  
  855.  
  856.                 TurboCom Communications 
  857.  
  858.  
  859.         FUNCTION lc_icnt
  860.  
  861.         SUMMARY
  862.  
  863.         #include <litecomm.h>
  864.  
  865.         int lc_icnt(port)
  866.  
  867.              unsigned port;
  868.  
  869.  
  870.         DESCRIPTION
  871.  
  872.              May be used to determine the number of characters currently 
  873.              in the input buffer for the port. 
  874.  
  875.         RETURN VALUES
  876.  
  877.              If the port is valid and has been opened, returns the number 
  878.              of character in the port's input buffer. Returns -1 if an 
  879.              error occurs;
  880.          
  881.  
  882.  
  883.  
  884.  
  885.  
  886.  
  887.  
  888.  
  889.  
  890.  
  891.  
  892.  
  893.  
  894.  
  895.  
  896.  
  897.  
  898.  
  899.  
  900.  
  901.  
  902.  
  903.  
  904.  
  905.  
  906.  
  907.  
  908.  
  909.  
  910.  
  911.  
  912.  
  913.  
  914.  
  915.  
  916.                 Copyright (c) 1987 Information Technology, Ltd.
  917.  
  918.  
  919.  
  920.  
  921.  
  922.                 TurboCom Communications 
  923.  
  924.  
  925.         FUNCTION lc_mstat
  926.  
  927.         SUMMARY
  928.  
  929.         #include <litecomm.h>
  930.  
  931.         int lc_mstat(port)
  932.  
  933.              unsigned port;
  934.  
  935.  
  936.         DESCRIPTION
  937.  
  938.              May be used to determine the last known state of the modem-
  939.              supplied handshake signals. These may be tested using the 
  940.              values in the include'd litecomm.h file.
  941.  
  942.         RETURN VALUES
  943.  
  944.              If the port is valid and has been opened, returns the 
  945.              current modem status bits. Returns -1 if an error occurs;
  946.          
  947.  
  948.  
  949.  
  950.  
  951.  
  952.  
  953.  
  954.  
  955.  
  956.  
  957.  
  958.  
  959.  
  960.  
  961.  
  962.  
  963.  
  964.  
  965.  
  966.  
  967.  
  968.  
  969.  
  970.  
  971.  
  972.  
  973.  
  974.  
  975.  
  976.  
  977.  
  978.  
  979.  
  980.  
  981.  
  982.                 Copyright (c) 1987 Information Technology, Ltd.
  983.  
  984.  
  985.  
  986.  
  987.  
  988.                 TurboCom Communications 
  989.  
  990.  
  991.         FUNCTION lc_estat
  992.  
  993.         SUMMARY
  994.  
  995.         #include <litecomm.h>
  996.  
  997.         int lc_estat(port)
  998.  
  999.              unsigned port;
  1000.  
  1001.  
  1002.         DESCRIPTION
  1003.  
  1004.              May be used to determine the last known state of the serial 
  1005.              port's error status bits. These may be tested using the 
  1006.              values in the include'd litecomm.h file.
  1007.  
  1008.         RETURN VALUES
  1009.  
  1010.              If the port is valid and has been opened, returns the 
  1011.              current error status bits. Returns -1 if an error occurs;
  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.                 Copyright (c) 1987 Information Technology, Ltd.
  1049.  
  1050.  
  1051.  
  1052.  
  1053.  
  1054.                 TurboCom Communications 
  1055.  
  1056.  
  1057.         FUNCTION lc_getw
  1058.  
  1059.         SUMMARY
  1060.  
  1061.         #include <litecomm.h>
  1062.  
  1063.         int lc_getw(port)
  1064.  
  1065.              unsigned port;
  1066.  
  1067.  
  1068.         DESCRIPTION
  1069.  
  1070.              Read a character from the serial port's input buffer. Pend 
  1071.              idefinitely until a character is available.
  1072.  
  1073.         RETURN VALUES
  1074.  
  1075.              Returns the next available character in the input buffer for 
  1076.              the port. Returns -1 if the port is not active.
  1077.          
  1078.  
  1079.  
  1080.  
  1081.  
  1082.  
  1083.  
  1084.  
  1085.  
  1086.  
  1087.  
  1088.  
  1089.  
  1090.  
  1091.  
  1092.  
  1093.  
  1094.  
  1095.  
  1096.  
  1097.  
  1098.  
  1099.  
  1100.  
  1101.  
  1102.  
  1103.  
  1104.  
  1105.  
  1106.  
  1107.  
  1108.  
  1109.  
  1110.  
  1111.  
  1112.  
  1113.  
  1114.                 Copyright (c) 1987 Information Technology, Ltd.
  1115.  
  1116.  
  1117.  
  1118.  
  1119.  
  1120.                 TurboCom Communications 
  1121.  
  1122.  
  1123.         FUNCTION lc_setmdm
  1124.  
  1125.         SUMMARY
  1126.  
  1127.         #include <litecomm.h>
  1128.  
  1129.         int lc_setmdm(port, newset)
  1130.  
  1131.              unsigned port;
  1132.              unsigned newset;
  1133.  
  1134.         DESCRIPTION
  1135.  
  1136.              Set one or more of the modem control signals. Because of 
  1137.              the need to always have OUT2 set for interrupt support, the 
  1138.              function always provides the correct setting for this bit. 
  1139.              Use the values found in the include file.
  1140.  
  1141.         RETURN VALUES
  1142.  
  1143.              Returns 0 if the operation was successful, returns -1 
  1144.              otherwise.
  1145.  
  1146.         SEE ALSO
  1147.  
  1148.              lc_clrmdm, lc_togmdm 
  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.                 Copyright (c) 1987 Information Technology, Ltd.
  1181.  
  1182.  
  1183.  
  1184.  
  1185.  
  1186.                 TurboCom Communications 
  1187.  
  1188.  
  1189.         FUNCTION lc_clrmdm
  1190.  
  1191.         SUMMARY
  1192.  
  1193.         #include <litecomm.h>
  1194.  
  1195.         int lc_clrmdm(port, newset)
  1196.  
  1197.              unsigned port;
  1198.              unsigned newset;
  1199.  
  1200.         DESCRIPTION
  1201.  
  1202.              Companion to setmdm function. Clears one or more of the 
  1203.              modem control signals. Because of the need to always have 
  1204.              OUT2 set for interrupt support, the function always provides 
  1205.              the correct setting for this bit. Use the values found in 
  1206.              the include file.
  1207.  
  1208.         RETURN VALUES
  1209.  
  1210.              Returns 0 if the operation was successful, returns -1 
  1211.              otherwise.
  1212.  
  1213.         SEE ALSO
  1214.  
  1215.              lc_setmdm, lc_togmdm 
  1216.  
  1217.  
  1218.  
  1219.  
  1220.  
  1221.  
  1222.  
  1223.  
  1224.  
  1225.  
  1226.  
  1227.  
  1228.  
  1229.  
  1230.  
  1231.  
  1232.  
  1233.  
  1234.  
  1235.  
  1236.  
  1237.  
  1238.  
  1239.  
  1240.  
  1241.  
  1242.  
  1243.  
  1244.  
  1245.  
  1246.                 Copyright (c) 1987 Information Technology, Ltd.
  1247.  
  1248.  
  1249.  
  1250.  
  1251.  
  1252.                 TurboCom Communications 
  1253.  
  1254.  
  1255.         FUNCTION lc_togmdm
  1256.  
  1257.         SUMMARY
  1258.  
  1259.         #include <litecomm.h>
  1260.  
  1261.         int lc_togmdm(port, newset)
  1262.  
  1263.              unsigned port;
  1264.              unsigned newset;
  1265.  
  1266.         DESCRIPTION
  1267.  
  1268.              Companion to setmdm function. Flip-flops one or more of the 
  1269.              modem control signals. Because of the need to always have 
  1270.              OUT2 set for interrupt support, the function always provides 
  1271.              the correct setting for this bit. Use the values found in 
  1272.              the include file.
  1273.  
  1274.         RETURN VALUES
  1275.  
  1276.              Returns 0 if the operation was successful, returns -1 
  1277.              otherwise.
  1278.  
  1279.         SEE ALSO
  1280.  
  1281.              lc_setmdm, lc_clrmdm 
  1282.  
  1283.  
  1284.  
  1285.  
  1286.  
  1287.  
  1288.  
  1289.  
  1290.  
  1291.  
  1292.  
  1293.  
  1294.  
  1295.  
  1296.  
  1297.  
  1298.  
  1299.  
  1300.  
  1301.  
  1302.  
  1303.  
  1304.  
  1305.  
  1306.  
  1307.  
  1308.  
  1309.  
  1310.  
  1311.  
  1312.                 Copyright (c) 1987 Information Technology, Ltd.
  1313.  
  1314.  
  1315.  
  1316.  
  1317.  
  1318.                 TurboCom Communications 
  1319.  
  1320.  
  1321.         FUNCTION lc_xoff
  1322.  
  1323.         SUMMARY
  1324.  
  1325.         #include <litecomm.h>
  1326.  
  1327.         int lc_xoff(port, flag)
  1328.  
  1329.              unsigned port;
  1330.              BOOL flag; /* #define BOOL int */
  1331.  
  1332.         DESCRIPTION
  1333.  
  1334.              If flag is TRUE, turns on semi-automatic XON-XOFF flow 
  1335.              control function. If flag is FALSE (the default setting), 
  1336.              automatic flow control is disabled. When enabled, the comm 
  1337.              handler will automatically transmit an XOFF if and when the 
  1338.              input buffer is approximately 2/3 full and will 
  1339.              automatically recognize an XOFF sent by the companion 
  1340.              system. If the companion system transmits an XOFF, the comm 
  1341.              handler will refuse to send any characters until the 
  1342.              condition is cleared.
  1343.  
  1344.              It is the programmer's responsibility to transmit XON when 
  1345.              conditions permit. See the lc_putxoff function to tell if 
  1346.              an automatic XOFF has been sent by the comm handler. See 
  1347.              the lc_gotxoff function to see if the companion system has 
  1348.              sent an XOFF.
  1349.  
  1350.              If you intended to impliment a protocol that might include 
  1351.              the XON-XOFF characters, be sure to disable the automatic 
  1352.              flow control. Failure to do so may result in a system hang.
  1353.  
  1354.         RETURN VALUES
  1355.  
  1356.              Returns 0 if the operation was successful, returns -1 
  1357.              otherwise.
  1358.  
  1359.         SEE ALSO
  1360.  
  1361.              lc_gotxoff, lc_putxoff 
  1362.  
  1363.  
  1364.  
  1365.  
  1366.  
  1367.  
  1368.  
  1369.  
  1370.  
  1371.  
  1372.  
  1373.  
  1374.  
  1375.  
  1376.  
  1377.  
  1378.                 Copyright (c) 1987 Information Technology, Ltd.
  1379.  
  1380.  
  1381.  
  1382.  
  1383.  
  1384.                 TurboCom Communications 
  1385.  
  1386.  
  1387.         FUNCTION lc_gotoff
  1388.  
  1389.         SUMMARY
  1390.  
  1391.         #include <litecomm.h>
  1392.  
  1393.         BOOL lc_gotxoff(port)
  1394.  
  1395.              unsigned port;
  1396.         /* #define BOOL int */
  1397.  
  1398.         DESCRIPTION
  1399.  
  1400.              See below for the values returned. If an XOFF has been 
  1401.              received, the port's flag will be reset, and transmission to 
  1402.              the companion system will be permitted.
  1403.  
  1404.         RETURN VALUES
  1405.  
  1406.              Returns TRUE if XOFF received from the companion system, 
  1407.              FALSE if XOFF not received. Will return -1 in the case of 
  1408.              an error.
  1409.  
  1410.         SEE ALSO
  1411.  
  1412.              lc_xoff, lc_putxoff 
  1413.  
  1414.  
  1415.  
  1416.  
  1417.  
  1418.  
  1419.  
  1420.  
  1421.  
  1422.  
  1423.  
  1424.  
  1425.  
  1426.  
  1427.  
  1428.  
  1429.  
  1430.  
  1431.  
  1432.  
  1433.  
  1434.  
  1435.  
  1436.  
  1437.  
  1438.  
  1439.  
  1440.  
  1441.  
  1442.  
  1443.  
  1444.                 Copyright (c) 1987 Information Technology, Ltd.
  1445.  
  1446.  
  1447.  
  1448.  
  1449.  
  1450.                 TurboCom Communications 
  1451.  
  1452.  
  1453.         FUNCTION lc_putoff
  1454.  
  1455.         SUMMARY
  1456.  
  1457.         #include <litecomm.h>
  1458.  
  1459.         BOOL lc_putxoff(port)
  1460.  
  1461.              unsigned port;
  1462.         /* #define BOOL int */
  1463.  
  1464.         DESCRIPTION
  1465.  
  1466.              See below for the values returned. If an XOFF has been 
  1467.              sent, the port's flag will be reset. Use this function in 
  1468.              concert with transmission of an XON character to the 
  1469.              companion system to permit transmissions to proceed. 
  1470.  
  1471.         RETURN VALUES
  1472.  
  1473.              Returns TRUE if XOFF was sent to the companion system, 
  1474.              FALSE if XOFF not sent since the last time the function was 
  1475.              called. Will return -1 in the case of an error.
  1476.  
  1477.         SEE ALSO
  1478.  
  1479.              lc_xoff, lc_putxoff 
  1480.  
  1481.  
  1482.  
  1483.  
  1484.  
  1485.  
  1486.  
  1487.  
  1488.  
  1489.  
  1490.  
  1491.  
  1492.  
  1493.  
  1494.  
  1495.  
  1496.  
  1497.  
  1498.  
  1499.  
  1500.  
  1501.  
  1502.  
  1503.  
  1504.  
  1505.  
  1506.  
  1507.  
  1508.  
  1509.  
  1510.                 Copyright (c) 1987 Information Technology, Ltd.
  1511.  
  1512.  
  1513.  
  1514.  
  1515.  
  1516.                 TurboCom Communications 
  1517.  
  1518.  
  1519.         FUNCTION lc_get
  1520.  
  1521.         SUMMARY
  1522.  
  1523.         #include <litecomm.h>
  1524.  
  1525.         int lc_get(port)
  1526.  
  1527.              unsigned port;
  1528.  
  1529.  
  1530.         DESCRIPTION
  1531.  
  1532.              Read a character from the serial port's input buffer.
  1533.  
  1534.         RETURN VALUES
  1535.  
  1536.              Returns the next available character in the input buffer for 
  1537.              the port. Returns -1 if the port is not active, or if there 
  1538.              are not characters in the port's buffer.
  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.                 Copyright (c) 1987 Information Technology, Ltd.
  1577.  
  1578.  
  1579.  
  1580.  
  1581.  
  1582.                 TurboCom Communications 
  1583.  
  1584.  
  1585.         FUNCTION lc_put
  1586.  
  1587.         SUMMARY
  1588.  
  1589.         #include <litecomm.h>
  1590.  
  1591.         int lc_put(port,ch)
  1592.  
  1593.              unsigned port;
  1594.              char ch;
  1595.  
  1596.         DESCRIPTION
  1597.  
  1598.              Place a character into the serial port's output buffer.
  1599.  
  1600.         RETURN VALUES
  1601.  
  1602.              Returns 0 if successful. Note that this does not guarantee 
  1603.              that the character has been sent, only that no errors were 
  1604.              detected. Returns -1 if the port is not active, or if there 
  1605.              no room in the port's buffer.
  1606.          
  1607.  
  1608.  
  1609.  
  1610.  
  1611.  
  1612.  
  1613.  
  1614.  
  1615.  
  1616.  
  1617.  
  1618.  
  1619.  
  1620.  
  1621.  
  1622.  
  1623.  
  1624.  
  1625.  
  1626.  
  1627.  
  1628.  
  1629.  
  1630.  
  1631.  
  1632.  
  1633.  
  1634.  
  1635.  
  1636.  
  1637.  
  1638.  
  1639.  
  1640.  
  1641.  
  1642.                 Copyright (c) 1987 Information Technology, Ltd.
  1643.  
  1644.  
  1645.  
  1646.  
  1647.  
  1648.                 TurboCom Communications 
  1649.  
  1650.  
  1651.         FUNCTION lc_gets
  1652.  
  1653.         SUMMARY
  1654.  
  1655.         #include <litecomm.h>
  1656.  
  1657.         int lc_gets(port, buff, cnt)
  1658.  
  1659.              unsigned port;
  1660.              char *buff;
  1661.              int cnt;
  1662.  
  1663.         DESCRIPTION
  1664.  
  1665.              Read a stream of, at most, cnt characters from the serial 
  1666.              port's input buffer into the buff location. Not sensitive 
  1667.              to NULL character.
  1668.  
  1669.         RETURN VALUES
  1670.  
  1671.              Returns the count of characters actually transferred, or -1 
  1672.              if an error occurs. 
  1673.          
  1674.  
  1675.  
  1676.  
  1677.  
  1678.  
  1679.  
  1680.  
  1681.  
  1682.  
  1683.  
  1684.  
  1685.  
  1686.  
  1687.  
  1688.  
  1689.  
  1690.  
  1691.  
  1692.  
  1693.  
  1694.  
  1695.  
  1696.  
  1697.  
  1698.  
  1699.  
  1700.  
  1701.  
  1702.  
  1703.  
  1704.  
  1705.  
  1706.  
  1707.  
  1708.                 Copyright (c) 1987 Information Technology, Ltd.
  1709.  
  1710.  
  1711.  
  1712.  
  1713.  
  1714.                 TurboCom Communications 
  1715.  
  1716.  
  1717.         FUNCTION lc_puts
  1718.  
  1719.         SUMMARY
  1720.  
  1721.         #include <litecomm.h>
  1722.  
  1723.         int lc_puts(port, buff, cnt)
  1724.  
  1725.              unsigned port;
  1726.              char *buff;
  1727.              int cnt;
  1728.  
  1729.         DESCRIPTION
  1730.  
  1731.              Place a stream of, at most, character into the serial port's 
  1732.              output buffer.
  1733.  
  1734.         RETURN VALUES
  1735.  
  1736.              Returns the number of characters actually placed into the 
  1737.              buffer. Note that this does not guarantee that the 
  1738.              characters have been sent. Returns 0 if any error occurs, or 
  1739.              if there no room in the port's buffer.
  1740.          
  1741.  
  1742.  
  1743.  
  1744.  
  1745.  
  1746.  
  1747.  
  1748.  
  1749.  
  1750.  
  1751.  
  1752.  
  1753.  
  1754.  
  1755.  
  1756.  
  1757.  
  1758.  
  1759.  
  1760.  
  1761.  
  1762.  
  1763.  
  1764.  
  1765.  
  1766.  
  1767.  
  1768.  
  1769.  
  1770.  
  1771.  
  1772.  
  1773.  
  1774.                 Copyright (c) 1987 Information Technology, Ltd.
  1775.  
  1776.  
  1777.  
  1778.  
  1779.  
  1780.                 TurboCom Communications 
  1781.  
  1782.  
  1783.         FUNCTION lc_flush
  1784.  
  1785.         SUMMARY
  1786.  
  1787.         #include <litecomm.h>
  1788.  
  1789.         int lc_tflush(port)
  1790.  
  1791.         int lc_rflush(port)
  1792.  
  1793.         int lc_flshtrue(port, ch)
  1794.  
  1795.         int lc_nflush(port, cnt)
  1796.  
  1797.              unsigned port;
  1798.              char ch;
  1799.              int cnt;
  1800.  
  1801.         DESCRIPTION
  1802.  
  1803.              lc_tflush empties the port's tranmit buffer immediately.
  1804.  
  1805.              lc_rflush empties the port's receive buffer immediately.
  1806.  
  1807.              lc_flshtrue will continually dispose of received characters 
  1808.              until the character ch is received. Use caution with this 
  1809.              one since it does not detect port number errors.
  1810.  
  1811.              lc_nflush flushes, at most, cnt characters from the port's 
  1812.              receive buffer.
  1813.  
  1814.         RETURN VALUES
  1815.  
  1816.              lc_flshtrue returns no values. lc_tflush and lc_rflush 
  1817.              return 0 if successful and -1 if an error occurs. lc_nflush 
  1818.              returns the number of characters actually flushed from the 
  1819.              receive buffer or 0 in the case of no characters to flush, 
  1820.              or an error.
  1821.          
  1822.  
  1823.  
  1824.  
  1825.  
  1826.  
  1827.  
  1828.  
  1829.  
  1830.  
  1831.  
  1832.  
  1833.  
  1834.  
  1835.  
  1836.  
  1837.  
  1838.  
  1839.  
  1840.                 Copyright (c) 1987 Information Technology, Ltd.
  1841.  
  1842.  
  1843.  
  1844.  
  1845.  
  1846.                 TurboCom Communications 
  1847.  
  1848.  
  1849.         FUNCTION lc_sbrk
  1850.  
  1851.         SUMMARY
  1852.  
  1853.         #include <litecomm.h>
  1854.  
  1855.         int lc_sbrk(port)
  1856.  
  1857.              unsigned port;
  1858.  
  1859.         DESCRIPTION
  1860.  
  1861.              Send a break out the port;
  1862.  
  1863.         RETURN VALUES
  1864.  
  1865.              Returns 0 if successful. Returns -1 if the port is not 
  1866.              active.
  1867.          
  1868.  
  1869.  
  1870.  
  1871.  
  1872.  
  1873.  
  1874.  
  1875.  
  1876.  
  1877.  
  1878.  
  1879.  
  1880.  
  1881.  
  1882.  
  1883.  
  1884.  
  1885.  
  1886.  
  1887.  
  1888.  
  1889.  
  1890.  
  1891.  
  1892.  
  1893.  
  1894.  
  1895.  
  1896.  
  1897.  
  1898.  
  1899.  
  1900.  
  1901.  
  1902.  
  1903.  
  1904.  
  1905.  
  1906.                 Copyright (c) 1987 Information Technology, Ltd.
  1907.  
  1908.  
  1909.  
  1910.  
  1911.  
  1912.                 TurboCom Communications 
  1913.  
  1914.  
  1915.                               HAYES MODEM FUNCTIONS
  1916.  
  1917.         Note - When using the following functions, you must include the 
  1918.         file litehcm.h in your program. litehcm.h automatically includes 
  1919.         the litecomm.h header file.
  1920.  
  1921.         FUNCTIONS lch_codeset
  1922.                     lch_dial
  1923.                     lch_fduplex
  1924.                     lch_hduplex
  1925.                     lch_greg
  1926.                     lch_sreg
  1927.                     lch_offcarr
  1928.                     lch_oncarr
  1929.                     lch_offecho
  1930.                     lch_onecho
  1931.                     lch_hook
  1932.                     lch_redo
  1933.                     lch_numres
  1934.                     lch_wrdres
  1935.                     lch_codesoff
  1936.                     lch_codeson
  1937.                     lch_pulse
  1938.                     lch_tone
  1939.                     lch_speaker
  1940.                     _retset
  1941.                     _rettype
  1942.  
  1943.         SUMMARY
  1944.  
  1945.         #include <litehcm.h>
  1946.  
  1947.         int lch_codeset(port,mode)
  1948.  
  1949.         int lch_dial(port,dstr)
  1950.  
  1951.         int lch_fduplex(port)
  1952.  
  1953.         int lch_hduplex(port)
  1954.  
  1955.         int lch_greg(port,reg)
  1956.  
  1957.         int lch_sreg(port,reg,value)
  1958.  
  1959.         int lch_offcarr(port)
  1960.  
  1961.         int lch_oncarr(port)
  1962.  
  1963.         int lch_offecho(port)
  1964.  
  1965.         int lch_onecho(port)
  1966.  
  1967.         int lch_hook(port,hmode)
  1968.  
  1969.         int lch_redo(port)
  1970.  
  1971.  
  1972.                 Copyright (c) 1987 Information Technology, Ltd.
  1973.  
  1974.  
  1975.  
  1976.  
  1977.  
  1978.                 TurboCom Communications 
  1979.  
  1980.  
  1981.         SUMMARY (ctd.)
  1982.  
  1983.         int lch_numres(port)
  1984.  
  1985.         int lch_wrdres(port)
  1986.  
  1987.  
  1988.         int lch_codesoff(port)
  1989.  
  1990.         int lch_codeson(port)
  1991.  
  1992.         int lch_pulse(port)
  1993.  
  1994.         int lch_tone(port)
  1995.  
  1996.         int lch_speaker(port,spkmode)
  1997.  
  1998.         int _retset()
  1999.  
  2000.         int _rettype()
  2001.  
  2002.              unsigned port;
  2003.              unsigned mode;
  2004.              char *dstr;
  2005.              unsigned reg;
  2006.              int value;
  2007.              unsigned hmode;
  2008.              unsigned spkmode; 
  2009.  
  2010.         DESCRIPTION
  2011.              
  2012.              The values to be used in conjunction with mode, hmode, and 
  2013.              spkmode are defined in the #include-d file litehcm.h.
  2014.  
  2015.              The lch_codeset function allows you to change the set of 
  2016.              codes that are returned by the modem when an action is 
  2017.              specified.
  2018.  
  2019.              lch_dial instructs the modem to dial the number contained in 
  2020.              dstr. Do not include the dialing (ATD) prefix, or the 
  2021.              trailing <CR>. These are provided by the function. You may 
  2022.              include non-numeric characters as the contents of dstr are 
  2023.              not checked. The dialing is done in the last known, pulse or 
  2024.              tone, mode. If you use the lch_pulse or lch_tone functions, 
  2025.              then dialing will be done in the mode that was last 
  2026.              correctly enabled. If you have not exercised these 
  2027.              functions, then dialing occurs in the modems default or 
  2028.              power-up mode.
  2029.  
  2030.              The lch_hduplex and lch_fduplex functions place the modem 
  2031.              into local echo and remote echo modes respectively.
  2032.  
  2033.              The lch_greg function requests that the modem report the 
  2034.              current value of S-register reg. Reg must be in the range 0 
  2035.              to 13. Use the lch_gets, or similar function, to retrieve 
  2036.  
  2037.  
  2038.                 Copyright (c) 1987 Information Technology, Ltd.
  2039.  
  2040.  
  2041.  
  2042.  
  2043.  
  2044.                 TurboCom Communications 
  2045.  
  2046.  
  2047.              the modem's response. Specifying a register outside the 0 
  2048.              to 13 range will cause a return of -1.
  2049.  
  2050.              lch_sreg is the companion to lch_greg, with the same 
  2051.              restrictions. Sets the S-register reg to the value 
  2052.              contained in value. If value contains -1, then the register 
  2053.              is reset to its default (power-up) value. The function 
  2054.              checks the value to be certain that it is within the limits 
  2055.              specified for the particular register, and returns a value 
  2056.              of -1 if the value is outside the predefined limits.
  2057.  
  2058.              lch_offcarr enables modem carrier detect, but disables the 
  2059.              modems carrier signal. The lch_oncarr companion enables 
  2060.              both carrier detect and the modems carrier signal. When 
  2061.              lch_offcarr is used the modem will receive data but will be 
  2062.              unable to send data.
  2063.  
  2064.              The lch_offecho and lch_onecho functions determine whether 
  2065.              commands sent to the modem are echoed back to the sending 
  2066.              program. With echo turned off, the modem will continue to 
  2067.              accept commands, but will not try to redisplay the command's 
  2068.              characters.
  2069.  
  2070.              lch_hook allows you to control the current status of the 
  2071.              modem's telephone line connection. See your modem's 
  2072.              documentation and the include file for additional 
  2073.              information.
  2074.  
  2075.              The lch_redo function instructs the modem to repeat the last 
  2076.              command sequence executed. Generally, this function is of 
  2077.              greatest value in re-dialing numbers that are busy, although 
  2078.              its use is not restricted to that.
  2079.  
  2080.              The way in which your modem responds to commands is 
  2081.              determined, in part by the lch_wrdres and lch_numres 
  2082.              functions. If you call lch_wrdres, then modem responses use 
  2083.              the english language response codes, e.g. CONNECT or OK. 
  2084.              Calling lch_numres instructs the modem to respond with code 
  2085.              numbers only from the currently selected response set, see 
  2086.              the lch_codeset function above.
  2087.  
  2088.              You may use the functions lch_codeson and lch_codesoff to 
  2089.              specify whether you want your modem to send back response 
  2090.              codes when it receives a command string. In a sense, these 
  2091.              act as companions to the lch_xxxecho functions above.
  2092.  
  2093.              Use the lch_speaker function to control the modem's internal 
  2094.              speaker, if it has one. See litehcm.h for the applicable 
  2095.              codes.
  2096.  
  2097.              The _retset and _rettype functions return, respectively, the 
  2098.              last known command set (lch_codeset) and last known result 
  2099.              type (lch_wrdres, lch_numres). These functions (_retset, 
  2100.              _rettype) are only of value when used in conjunction with 
  2101.              the companion functions.
  2102.  
  2103.  
  2104.                 Copyright (c) 1987 Information Technology, Ltd.
  2105.  
  2106.  
  2107.  
  2108.  
  2109.  
  2110.                 TurboCom Communications 
  2111.  
  2112.  
  2113.         GENERAL REMARKS
  2114.  
  2115.              Several considerations are in order if you intend to use the 
  2116.              Hayes ToolBox functions.
  2117.  
  2118.              You are responsible for checking the return codes from the 
  2119.              modem once you have given modem a command. To make the task 
  2120.              easier, we suggest that you turn OFF command echo (so that 
  2121.              you don't have to worry about separating commands from 
  2122.              responses) and turn ON numeric responses (to make the 
  2123.              interpretation of result codes easier and faster).
  2124.  
  2125.              One final caution is in order. Be sure that you allow 
  2126.              adequate time between commands for the modem to process the 
  2127.              command and respond. Failure to observe this rule may 
  2128.              result in commands being misinterpreted or "lost". You can 
  2129.              monitor the number of characters in the receive buffer to 
  2130.              help you with the timing. Or alternatively, check the 
  2131.              reponse after each command. The latter approach is more in 
  2132.              line with what we believe to be good programming practice. 
  2133.  
  2134.         RETURN VALUES
  2135.  
  2136.              All functions return a value of -1 if a port or other error 
  2137.              is detected, zero otherwise.
  2138.  
  2139.  
  2140.  
  2141.  
  2142.  
  2143.  
  2144.  
  2145.  
  2146.  
  2147.  
  2148.  
  2149.  
  2150.  
  2151.  
  2152.  
  2153.  
  2154.  
  2155.  
  2156.  
  2157.  
  2158.  
  2159.  
  2160.  
  2161.  
  2162.  
  2163.  
  2164.  
  2165.  
  2166.  
  2167.  
  2168.  
  2169.  
  2170.                 Copyright (c) 1987 Information Technology, Ltd.
  2171.  
  2172.  
  2173.  
  2174.  
  2175.  
  2176.  
  2177.  
  2178.  
  2179.                                 REGISTRATION FORM
  2180.  
  2181.         Please complete the following information. Note that the prices 
  2182.         below are for a single-use registration only. Please contact us 
  2183.         directly for site licensing.
  2184.  
  2185.              Mail to:
  2186.                   Information Technology
  2187.                   PO Box 554
  2188.                   Coventry, RI 02816
  2189.                   (401) 826-2223
  2190.          
  2191.                   Name: _____________________________________
  2192.  
  2193.                   Company: __________________________________
  2194.  
  2195.                   Street Addr: ______________________________
  2196.  
  2197.                                ______________________________
  2198.  
  2199.                  City: ______________________ State: ____
  2200.  
  2201.                  Zip Code: _________________
  2202.  
  2203.                  Telephone: _______________________
  2204.  
  2205.  
  2206.             Indicate the type and number of registrations below. All
  2207.             prices include postage and handling.
  2208.  
  2209.             Number Type Registration Amount
  2210.  
  2211.             _____ Libraries ONLY - $25 ______________
  2212.  
  2213.             _____ Libraries and Source Code ______________
  2214.                           $50
  2215.  
  2216.             Method of Payment (Check, Mastercard, Visa) _____________
  2217.  
  2218.             MasterCard/Visa Number __________________________
  2219.  
  2220.             Expiration Date __________________________
  2221.  
  2222.             Name as it appears on card ______________________________
  2223.  
  2224.             Signature for MC/VISA ___________________________________
  2225.  
  2226.             All MasterCard/Visa orders must include a telephone number,
  2227.  
  2228.             We regret that we cannot accept COD orders
  2229.         -----------------------------------------------------------------
  2230.         (office use only)
  2231.             Date Received ______________
  2232.             Date Sent ______________
  2233.             Version ______________ Serial Number _______________
  2234.  
  2235.  
  2236.                                        34
  2237.  
  2238.  
  2239.  
  2240.  
  2241.  
  2242.  
  2243.  
  2244.  
  2245.                     
  2246.  
  2247.  
  2248.  
  2249.  
  2250.  
  2251.  
  2252.  
  2253.  
  2254.  
  2255.  
  2256.  
  2257.  
  2258.  
  2259.  
  2260.  
  2261.  
  2262.  
  2263.  
  2264.  
  2265.  
  2266.  
  2267.  
  2268.  
  2269.  
  2270.  
  2271.  
  2272.  
  2273.  
  2274.  
  2275.  
  2276.  
  2277.  
  2278.  
  2279.  
  2280.  
  2281.  
  2282.  
  2283.  
  2284.  
  2285.  
  2286.  
  2287.  
  2288.  
  2289.  
  2290.  
  2291.  
  2292.  
  2293.  
  2294.  
  2295.  
  2296.  
  2297.  
  2298.  
  2299.  
  2300.  
  2301.  
  2302.                                        35
  2303.  
  2304.  
  2305.  
  2306.  
  2307.  
  2308.