COMMOS2 Library Version 1.0 ASH Software, Inc. December 1992 OS/2 is a trademark of International Business Machines Corporation. This file is an abstract of the manual. It is intended to show the capabilities of COMMOS2 library. If you are interested in receiving a shareware version of this library, send an EMail message to Compuserve account 71260,1362 or write to ASH Software, Inc. 516 East Fox Den Drive Knoxville, TN 37922 or FAX: 615/675-3907 INTRODUCTION The COMMOS2 library consists of three major components which are: the COMM API; the COMM class; and the IOPL functions. The COMM API consist of the Comm... functions which simplify access to COM ports for which a device driver has been installed. The COMM class provides the same functionality as the COMM API except that it is provided in the form of a C++ class. The IOPL functions provide the capability to perform direct port I/O from both 16-bit and 32-bit programs. COMM API The COMM API provides simplified access to COM ports for which a device driver has been installed. This sections defines how to use the functions. The functions provided can be used in either 16-bit or 32-bit programs. The prototypes are contained in COMMOS2.H. Before the include statement for the header file you should define #define INCL_COMMOS2_16BIT or #define INCL_COMMOS2_32BIT for 16-bit and 32-bit programs respectively. System Initialization and Termination The COMM API requires initialization before use. The initialization is accomplished by calling CommStartSystem and specifying the maximum number of COM ports to be handled by the system. CommStartSystem allocates memory required by the COMM API and will fail if there is not enough memory available to satisfy this request. CommStopSystem should be called when the system is no longer needed to free these resources. Opening and Closing Ports The CommOpen function opens a COM port and initializes the COM structures for that port. This call returns a handle to the COM port which is needed by other functions in the COMM API. This handle IS NOT the same handle obtained from DosOpen and cannot be used by the Dos... APIs. When a COM port is no longer needed CommClose should be called. CommClose closes the COM port and prepares the COM structures for reuse. Initializing Port Parameters A number of functions are provided for initializing COM ports. CommInit is provided for setting the baud rate, parity, data bits, stop bits, and transmit break. CommClear is provided for clearing both the transmit and receive buffers while CommClearTxBuffer and CommClearRxBuffer will clear the transmit and receive buffers respectively. Reading and Writing Data The CommWrite function writes a block of data to the indicated COM port and is the only supplied function for writing data. Several functions are provided for reading the port and their use will vary depending on your requirements. CommRead will read a block of data from the indicated port. This function does not wait for data to arrive at the port, but will return with the characters available at the time the function is called. CommReadTimeOut will also read a block a data from the indicated port provided the amount of data requested is present or appears within the time limit specified. If the number of characters requested are not present when the time limit elapses, the function returns without reading any data from the port. CommReadUntilByte reads data from the port on a character by character basis. The function returns when the number of characters specified have been read, the specified character has been read, or the time limit specified has elapsed. The function returns all characters read to the calling program. Informational Functions Several functions are provided to return information from the COMM API to your program. CommGetLastError returns information about the last error which occurred for the port specified. The information returned includes the Comm error code, the Dos error code, and the Comm mode when the error occurred. CommQueryRxCount and CommQueryTxCount return the number of characters in the receive and transmit buffers respectively. These functions are useful for determining if the transmit buffer is empty or if the necessary number of characters are waiting in the receive buffer. CommQueryRxBufSize and CommQueryTxBufSize return the size of the receive and transmit buffers respectively. These functions are useful for determining optimum block sizes to use for I/O operations. COMM Class The COMM class provides a number of methods which simplify the programming of COM ports for which a device driver has been installed. The definition of the class is provided in the header file COMMOS2.HPP The class methods, error codes, and modes are described below. A detailed discussion of the class methods is found in the Class Methods section. Opening and Closing Ports The Open method opens a COM port and initializes the structures for that port. When a COM port is no longer needed the Close method should be called. Close closes the COM port and initializes the structures for later use. Initializing Port Parameters A number of methods are provided for initializing COM ports. Initialize is provided for setting the baud rate, parity, data bits, stop bits, and transmit break. ClearBuffers is provided for clearing both the transmit and receive buffers while ClearTxBuffer and ClearRxBuffer will clear the transmit and receive buffers respectively. Reading and Writing Data The Write method writes a block of data to the indicated COM port and is the only supplied method for writing data. Several methods are provided for reading the port and their use will vary depending on your requirements. Read will read a block of data from the indicated port. This method does not wait for data to arrive at the port, but will return with the characters available at the time the method is called. ReadTimeOut will also read a block a data from the indicated port provided the amount of data requested is present or appears within the time limit specified. If the number of characters requested are not present when the time limit elapses, the method returns without reading any data from the port. ReadUntilByte reads data from the port on a character by character basis. The method returns when the number of characters specified have been read, the specified character has been read, or the time limit specified has elapsed. The method returns all characters read to the calling program. Informational Functions Several functions are provided to return information from the COMM class to your program. GetLastError returns information about the last error which occurred for the port. The information returned includes the Comm error code, the Dos error code, and the Comm mode when the error occurred. QueryRxCount and QueryTxCount return the number of characters in the receive and transmit buffers respectively. These methods are useful for determining if the transmit buffer is empty or if the necessary number of characters are waiting in the receive buffer. QueryRxBufferSize and QueryTxBufferSize return the size of the receive and transmit buffers respectively. These methods are useful for determining optimum block sizes to use for I/O operations. IOPL Functions Since IOPL privilege code must be 16-bit, there needs to be an interface between the 32-bit code and the 16-bit code if you are writing a 32-bit program. If you are writing a 16-bit program, you may use either the interface functions or make a direct call to the IOPL functions. The header file COMMOS2.H provides function prototypes for both 16-bit and 32-bit programs. To obtain the 16-bit prototypes define #define INCL_16BIT or #define INCL_32bit before the include statement for the header file. These prototypes allow the compiler to properly handle the "thunking" required to call a 16-bit procedure from 32-bit code. The four interface functions which have been provided are: VOID PortOutByte(USHORT usPort,BYTE bParam) which outputs a single byte (8 bits) to the port address indicated; VOID PortOutWord(USHORT usPort,USHORT usParam) which outputs a single word (16 bits) to the port address indicated; USHORT PortInpByte(USHORT usPort) which returns a single byte (8 bits) from the port address indicated; and USHORT PortInpWord(USHORT usPort) which returns a single word (16 bits) from the port address indicated. The actual prototypes differ from the above depending on whether 32-bit or 16-bit prototypes have been requested, however the values returned and passed are the same as shown. 16-bit programs may call the IOPL functions directly. For portability purposes, 16-bit programs may also use the interface routines. The IOPL routines which have been provided are: void ioplout(unsigned short usPort,unsigned char usByte) which outputs a single byte (8 bits) to the port address indicated; void ioploutw(unsigned short usPort,unsigned short usParam) which outputs a single word (16 bits) to the port address indicated; unsigned short ioplinp(unsigned short usPort); which returns a single byte (8 bits) from the port address indicated; and unsigned short ioplinpw(unsigned short usPort) which returns a single word (16 bits) from the port address indicated. "DEF" Files An entire application is not granted IOPL privilege, but rather only those segments so designated in the linker definition (DEF) file. For an application to make use of the routines provided for direct port I/O access, the DEF file for each application will have to be modified to include the following statements. SEGMENTS _PORTIOPL CLASS 'CODE' IOPL EXPORTS IOPLINP 1 IOPLOUT 2 IOPLINPW 1 IOPLOUTW 2 These statements grant IOPL privilege to the code segment named _PORTIOPL and specify that there are four exported procedures in this segment. The number after the name of each procedure represents the number of words which are passed as arguments to that procedure. System Requirements The only system requirement is that the statement IOPL=YES must appear in the CONFIG.SYS file before IOPL access can be granted to your program.