home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / comos2.zip / COMMOS2.TXT < prev    next >
Text File  |  1993-02-22  |  11KB  |  270 lines
  1. COMMOS2 Library
  2. Version 1.0
  3.  
  4. ASH Software, Inc.
  5. December 1992
  6.  
  7. OS/2 is a trademark of International Business Machines Corporation.
  8.  
  9. This file is an abstract of the manual.  It is intended to show the 
  10. capabilities of COMMOS2 library.  If you are interested in receiving a
  11. shareware version of this library, send an EMail message to Compuserve
  12. account 71260,1362 or write to
  13.  
  14.  ASH Software, Inc.
  15.  516 East Fox Den Drive
  16.  Knoxville, TN  37922
  17.  
  18.  or
  19.  
  20.  FAX: 615/675-3907
  21.  
  22. INTRODUCTION
  23.  
  24.   The COMMOS2 library consists of three major components which are:
  25.  
  26.         the COMM API;
  27.         the COMM class; and
  28.         the IOPL functions.
  29.  
  30.   The COMM API consist of the Comm... functions which simplify access to COM 
  31.   ports for which a device driver has been installed.
  32.  
  33.   The COMM class provides the same functionality as the COMM API except that 
  34.   it is provided in the form of a C++ class.
  35.  
  36.   The IOPL functions provide the capability to perform direct port I/O from 
  37.   both 16-bit and 32-bit programs.
  38.  
  39. COMM API
  40.  
  41.   The COMM API provides simplified access to COM ports for which a device 
  42.   driver has been installed.  This sections defines how to use the functions.  
  43.  
  44.   The functions provided can be used in either 16-bit or 32-bit programs.  
  45.   The prototypes are contained in COMMOS2.H.  Before the include statement 
  46.   for the header file you should define
  47.  
  48.     #define INCL_COMMOS2_16BIT or
  49.     #define INCL_COMMOS2_32BIT
  50.  
  51.   for 16-bit and 32-bit programs respectively.
  52.  
  53. System Initialization and Termination
  54.  
  55.   The COMM API requires initialization before use.  The initialization is 
  56.   accomplished by calling CommStartSystem and specifying the maximum number 
  57.   of COM ports to be handled by the system.  CommStartSystem allocates 
  58.   memory required by the COMM API and will fail if there is not enough 
  59.   memory available to satisfy this request.  CommStopSystem should be 
  60.   called when the system is no longer needed to free these resources.
  61.  
  62. Opening and Closing Ports
  63.  
  64.   The CommOpen function opens a COM port and initializes the COM structures 
  65.   for that port.  This call returns a handle to the COM port which is needed 
  66.   by other functions in the COMM API.  This handle IS NOT the same handle 
  67.   obtained from DosOpen and cannot be used by the Dos... APIs.  When a COM 
  68.   port is no longer needed CommClose should be called.  CommClose closes 
  69.   the COM port and prepares the COM structures for reuse.
  70.  
  71. Initializing Port Parameters
  72.  
  73.   A number of functions are provided for initializing COM ports.  CommInit 
  74.   is provided for setting the baud rate, parity, data bits, stop bits, and 
  75.   transmit break.  CommClear is provided for clearing both the transmit and 
  76.   receive buffers while CommClearTxBuffer and CommClearRxBuffer will clear 
  77.   the transmit and receive buffers respectively.
  78.  
  79. Reading and Writing Data
  80.  
  81.   The CommWrite function writes a block of data to the indicated COM port 
  82.   and is the only supplied function for writing data.  Several functions 
  83.   are provided for reading the port and their use will vary depending on 
  84.   your requirements.  
  85.  
  86.   CommRead will read a block of data from the indicated port.  This function 
  87.   does not wait for data to arrive at the port, but will return with the 
  88.   characters available at the time the function is called.
  89.  
  90.   CommReadTimeOut will also read a block a data from the indicated port 
  91.   provided the amount of data requested is present or appears within the 
  92.   time limit specified.  If the number of characters requested are not 
  93.   present when the time limit elapses, the function returns without reading 
  94.   any data from the port.
  95.  
  96.   CommReadUntilByte reads data from the port on a character by character 
  97.   basis.  The function returns when the number of characters specified have 
  98.   been read, the specified character has been read, or the time limit 
  99.   specified has elapsed.  The function returns all characters read to the 
  100.   calling program.
  101.  
  102. Informational Functions
  103.  
  104.   Several functions are provided to return information from the COMM API to 
  105.   your program.
  106.  
  107.   CommGetLastError returns information about the last error which occurred 
  108.   for the port specified.  The information returned includes the Comm error 
  109.   code, the Dos error code, and the Comm mode when the error occurred.
  110.  
  111.   CommQueryRxCount and CommQueryTxCount return the number of characters in 
  112.   the receive and transmit buffers respectively.  These functions are 
  113.   useful for determining if the transmit buffer is empty or if the 
  114.   necessary number of characters are waiting in the receive buffer.
  115.  
  116.   CommQueryRxBufSize and CommQueryTxBufSize return the size of the receive 
  117.   and transmit buffers respectively.  These functions are useful for 
  118.   determining optimum block sizes to use for I/O operations.
  119.  
  120. COMM Class
  121.  
  122.   The COMM class provides a number of methods which simplify the 
  123.   programming of COM ports for which a device driver has been installed.  
  124.   The definition of the class is provided in the header file COMMOS2.HPP  
  125.   The class methods, error codes, and modes are described below.  A 
  126.   detailed discussion of the class methods is found in the Class Methods 
  127.   section.
  128.  
  129. Opening and Closing Ports
  130.  
  131.   The Open method opens a COM port and initializes the structures for that
  132.   port.  When a COM port is no longer needed the Close method should be 
  133.   called.  Close closes the COM port and initializes the structures for 
  134.   later use.
  135.  
  136. Initializing Port Parameters
  137.  
  138.   A number of methods are provided for initializing COM ports.  Initialize 
  139.   is provided for setting the baud rate, parity, data bits, stop bits, and 
  140.   transmit break.  ClearBuffers is provided for clearing both the transmit 
  141.   and receive buffers while ClearTxBuffer and ClearRxBuffer will clear the 
  142.   transmit and receive buffers respectively.
  143.  
  144. Reading and Writing Data
  145.  
  146.   The Write method writes a block of data to the indicated COM port and is 
  147.   the only supplied method for writing data.  Several methods are provided 
  148.   for reading the port and their use will vary depending on your 
  149.   requirements.  
  150.  
  151.   Read will read a block of data from the indicated port.  This method does 
  152.   not wait for data to arrive at the port, but will return with the 
  153.   characters available at the time the method is called.
  154.  
  155.   ReadTimeOut will also read a block a data from the indicated port provided 
  156.   the amount of data requested is present or appears within the time limit 
  157.   specified.  If the number of characters requested are not present when the 
  158.   time limit elapses, the method returns without reading any data from the 
  159.   port.
  160.  
  161.   ReadUntilByte reads data from the port on a character by character basis.  
  162.   The method returns when the number of characters specified have been read, 
  163.   the specified character has been read, or the time limit specified has 
  164.   elapsed.  The method returns all characters read to the calling program.
  165.  
  166. Informational Functions
  167.  
  168.   Several functions are provided to return information from the COMM class 
  169.   to your program.  
  170.  
  171.   GetLastError returns information about the last error which occurred for 
  172.   the port.  The information returned includes the Comm error code, the 
  173.   Dos error code, and the Comm mode when the error occurred.
  174.  
  175.   QueryRxCount and QueryTxCount return the number of characters in the 
  176.   receive and transmit buffers respectively.  These methods are useful for 
  177.   determining if the transmit buffer is empty or if the necessary number 
  178.   of characters are waiting in the receive buffer.
  179.  
  180.   QueryRxBufferSize and QueryTxBufferSize return the size of the receive 
  181.   and transmit buffers respectively.  These methods are useful for 
  182.   determining optimum block sizes to use for I/O operations.
  183.  
  184. IOPL Functions
  185.  
  186.   Since IOPL privilege code must be 16-bit, there needs to be an interface 
  187.   between the 32-bit code and the 16-bit code if you are writing a 32-bit 
  188.   program.  If you are writing a 16-bit program, you may use either the 
  189.   interface functions or make a direct call to the IOPL functions.  The 
  190.   header file COMMOS2.H provides function prototypes for both 16-bit and 
  191.   32-bit programs.  To obtain the 16-bit prototypes define
  192.  
  193.         #define INCL_16BIT or
  194.         #define INCL_32bit
  195.  
  196.   before the include statement for the header file.  These prototypes allow 
  197.   the compiler to properly handle the "thunking" required to call a 16-bit 
  198.   procedure from 32-bit code.  The four interface functions which have been 
  199.   provided are:
  200.  
  201.      VOID PortOutByte(USHORT usPort,BYTE bParam)
  202.         which outputs a single byte (8 bits) to the port address 
  203.           indicated;
  204.  
  205.      VOID PortOutWord(USHORT usPort,USHORT usParam)
  206.       which outputs a single word (16 bits) to the port address 
  207.           indicated;
  208.  
  209.      USHORT PortInpByte(USHORT usPort)
  210.       which returns a single byte (8 bits) from the port address 
  211.           indicated; and
  212.  
  213.      USHORT PortInpWord(USHORT usPort)
  214.       which returns a single word (16 bits) from the port address 
  215.           indicated.
  216.  
  217.   The actual prototypes differ from the above depending on whether 32-bit 
  218.   or 16-bit prototypes have been requested, however the values returned and 
  219.   passed are the same as shown.
  220.  
  221.   16-bit programs may call the IOPL functions directly.  For portability 
  222.   purposes, 16-bit programs may also use the interface routines.  The IOPL 
  223.   routines which have been provided are:
  224.  
  225.      void ioplout(unsigned short usPort,unsigned char usByte)
  226.           which outputs a single byte (8 bits) to the port address 
  227.           indicated;
  228.  
  229.      void ioploutw(unsigned short usPort,unsigned short usParam)
  230.           which outputs a single word (16 bits) to the port address 
  231.           indicated;
  232.  
  233.      unsigned short ioplinp(unsigned short usPort);
  234.           which returns a single byte (8 bits) from the port address 
  235.           indicated; and
  236.  
  237.      unsigned short ioplinpw(unsigned short usPort)
  238.           which returns a single word (16 bits) from the port address 
  239.           indicated.
  240.  
  241.  
  242. "DEF" Files
  243.  
  244.   An entire application is not granted IOPL privilege, but rather only 
  245.   those segments so designated in the linker definition (DEF) file.  For 
  246.   an application to make use of the routines provided for direct port I/O 
  247.   access, the DEF file for each application will have to be modified to 
  248.   include the following statements.
  249.  
  250.   SEGMENTS        _PORTIOPL       CLASS    'CODE'    IOPL
  251.                   EXPORTS      IOPLINP       1
  252.                     IOPLOUT     2
  253.                   IOPLINPW    1
  254.                   IOPLOUTW    2
  255.  
  256.   These statements grant IOPL privilege to the code segment named _PORTIOPL 
  257.   and specify that there are four exported procedures in this segment.  The 
  258.   number after the name of each procedure represents the number of words 
  259.   which are passed as arguments to that procedure.
  260.  
  261. System Requirements
  262.  
  263.   The only system requirement is that the statement
  264.  
  265.     IOPL=YES
  266.  
  267.   must appear in the CONFIG.SYS file before IOPL access can be granted to 
  268.   your program.
  269.  
  270.