═══ 1. Introduction ═══ COMi is a multi-port asynchronous serial device driver for the OS/2* operating system. This version of COMi will work in any system running OS/2 2.0 and above. There is a different version for OS/2 1.x that is still available and supported by OS/tools. By multi-port we mean that with COMi there is no limit (logically) to the number of COM devices that can be made available to OS/2 sessions or applications. There is a practical limit, of course, because there is a limit to the number of COM devices that can be installed in any single system (server, client, workstation, CPU). COMi will allow you to install devices with names from COM1 to COM99. ═══ 2. Installation ═══ COMi comes with an easy to use installation program (INSTALL.EXE). This program can transfer all required files to the directories of your choice, create a desktop folder and necessary program objects, and initiate the configuration process. If you have multiple COMi licenses you can reuse a COMi initialization file for similar installations by copying that initiaization file to the distribution diskette. When INSTALL finds a COMi initialization file in the directory it is run from it will transfer that file to the installation destination directory. The transferred COMi initialization file will be presented for modification during each subsequent installation process. Multiple licenses for COMi can be installed from a network drive or directory. To do this you must first use INSTALL to transfer both COMi and INSTALL to a network drive, then complete the configuration process just as though you were installing it to a local drive. Once installation and configuration are complete you can run INSTALL on a workstation from the network directory to install COMi to that workstation. Any initialization file you created in the INSTALL (network) directory will also be transferred to the workstation. You can then make any necessary changes to the initialization file by selecting the Config COMi... menu item after INSTALL has transferred the required files to the local drive. ═══ 2.1. Installing Print Spooler Support ═══ To install and configure COMi Print Spooler support you must have elected to transfer the spooler support files while installing COMi by selecting the "Print Spooler Utilities" check box in the "Install Options" dialog, configured COMi for your serial hardware, and you must have re-booted your machine since that install session. Once you have completed transferring the files, installing and configuring serial devices for COMi access, and re-booting your machine, you will need to do the following: 1. Click mouse button two (usually the right button) on a local printer object. If you have not created a local printer object yet, then you will need to drag a non-network printer object from the "Templates" folder onto your desktop. If you are creating a printer object as part of this installation then skip to item three, as the printer object's settings notebook will have been presented immediately after you drag the printer object from the "Templates" folder. When creating a new printer object, you will also have to select a printer driver and will possibly need to set other parameters in the printer's settings notebook. 2. Select the "Settings" menu item from the pop-up menu that appears. 3. Click on the "Output" tab from the settings notebook. 4. Click mouse button two on any port icon in the container window. 5. Select the "Install" menu item. A new dialog will be presented. 6. In the "Directory" entry field enter the following (without the quotes): "\OS2\DLL", then press the key or select the "Refresh" button. The Spooler software will read each spooler support library in that directory, including the COMi spooler support library, and show an icon in the container area of the dialog for each device these spooler support libraries support. Only ports that have been installed with a COMi configuration program (COMscope or Install) will be available for installation as spooler ports by the system spooler software. COMi must have been loaded at system initialization before COMi print Spooler support can be installed, or accessed. 7. Select one, or more, of the COMi Spooler ports and select the "Install" button. 8. When the Spooler software is finished installing the ports you have selected, it will show a message box indicating that the ports you selected have been installed. Click on the "OK" button. 9. When you are through installing print spooler ports, click on the "Cancel" button. Once you have installed at least one COMi spooler port using this procedure, you will be able to install and delete spooler ports from the COMi Configuration program (either Install or COMscope). You can set the port parameters to match the requirements of a printer by clicking mouse button two on an icon in the container area and selecting the "Settings" menu item. Help for setting port printer initialization parameters will be available once you have entered the setup dialog. Note: Configuration of COMi print spooler ports for device and printer communications parameter initialization will always have to be completed from the printer object's settings notebook, as described here. The system spooler software will not be aware of any initialization parameters selected from the COMi configuration program. ═══ 2.2. Configuration ═══ The COMi device driver can only be configured using COMscope or Install. These two programs create, or modify, an initialization file for the device driver. Each time your system is started, COMi reads this initialization file to determine where to look for serial devices and how to configure those devices. Additional Information: o Industry Standard Architecture o Micro Channel Architecture o Starting Configuration Program ═══ 2.2.1. Industry Standard Architecture Machines ═══ The COMi device driver will not operate in ISA systems until a valid initialization file is created. There can be no access to COM devices in ISA systems until the configuration process has been completed and a valid initialization file has been created. ═══ 2.2.2. Micro Channel Architecture Machines ═══ The COMi device driver does not need an initialization file to initialize the eight pre-defined serial ports in a PS/2* or other MCA system that has ABIOS or equivalent. You will need to create an initialization file for MCA machines only if you: 1. Need to support more than eight serial devices. 2. Want to access devices that may be owned by other serial device drivers. 3. Need to support hardware that has base I/O addresses and/or interrupt levels different than the MCA pre-defined serial device base addresses and/or interrupt levels. 4. Your MCA system does not have an ABIOS or equivalent. ═══ 2.2.3. Starting Configuration Program ═══ During the installation process the configuration process is started by the installation program supplied with COMi. After Installation is completed you will need to re-boot your machine before you will be able to access serial devices with COMi. After installation you can configure COMi either from a program object (icon) or from an OS/2* command prompt. Starting from a program object: If there is a program object for COMscope or Install you can double click on the object to begin the configuration process. If there is no program object for COMscope or Install, you can either start the program from the command line (in an OS/2 window or full screen session) or create a program object using the following procedure: 1. Open the Templates folder. 2. Drag a Program object off onto the desktop. 3. When the settings notebook appears select the Program tab, if that page is not currently shown. 4. In the Path and File Name field, enter the absolute path and file name of the configuration program. Example: C:\COMM\COMscope.EXE 5. In the Working Directory field enter the absolute path, to the configuration program. Example: C:\COMM 6. Select the General tab. 7. Enter the program name in the Title field. Example: COMi Configuration 8. Close the settings notebook by double clicking on the system menu (small box in the upper left-hand corner). Starting from an OS/2 command prompt: If the COMi device driver is loaded you will only need to enter the program name on the command line. Example: [C:\]COMscope If the COMi device driver is not loaded you will be to prompted for a path and file name after starting the COMscope or Install. The COMi initialization file must be located in the same directory as the device driver, and must have the same base name as the drvice driver file with a ".INI" extension. ═══ 3. Extensions ═══ COMi has extensions that allow it to perform in some special situations. These extensions are: 1. Modem interrupts can be disabled for any device. Enabling this extension will cause modem signals to be polled when handshaking protocols are enabled that use modem signaling. The device driver will function normally, just not as efficiently. The purpose for this extension is to support serial adapters that inadvertently left one or more modem signal input pins floating, and will only be required if an application is going to enable hardware handshaking when such an adapter is being used. 2. The device driver can be configured to allow applications to have control of the OUT1 output signal of any device. The purpose of this extension is to support adapters that use the OUT1 pin to control some special function (e.g., baud rate clock selection, or RS-485 tri-state enable). Support is included for control of the LOOP function, but is not very useful at the normal application level. 3. The baud rate divisor can be specified explicitly by an application. When this feature is enabled the application selected baud rate value is written directly to, or read directly from, the baud rate registers of the device. This extension is to support adapters that allow users to select non-standard baud rate clocks. When using this extension, an application will need to calculate the proper baud rate divisor for their particular adapter set-up. 4. Normally each user defined serial device (UART) is tested to determine if the defined device is a supported UART, if the defined hardware interrupt level is available for use by the device driver, if the device is physically connected to the defined hardware interrupt level, and if the device has hardware buffering capabilities. This extension prevents all but the test for hardware interrupt availability from being performed. The purpose of this extension is to allow for UARTs that are part of a motherboard chip set that may not be initialized at the time the device driver is loaded (initialized), or other UARTs that may not be completely compatible with the 8250 standard, but close enough to work with COMi. 5. Each device can be configured to enable the OUT1 signal at initialization. When this extension is enabled the OUT1 signal is enabled at the very beginning of the initialization sequence and will remain enabled for that entire OS/2* session, unless Extended Modem Signals is enabled and an extension aware application disables that signal. 6. COMi will allow you to connect multiple devices to a single interrupt in ISA machines. Interrupt sharing in an ISA machine will NOT work unless your hardware is specifically designed to do so. 7. COMi will support the Texas Instruments 16C550B UART in the FIFO mode. This UART requires special processing when its receive FIFO is enabled. 8. The COMi device driver has other extensions that are application specific. if you have an application that takes advantage of one or more of these extensions, that application's documentation will explain the necessary steps for use of the required extensions. 9. The most important extension in COMi, we feel, is support for COMscope. COMscope and COMi allow for total control and monitoring of serial devices. COMscope can monitor all the device and device driver states an application can access. COMscope can also capture and display both the transmit and receive streams. ═══ 4. API Compatibility ═══ The COMi application interface is exactly as described in the "Physical Device Driver" technical reference for Category One, Asynchronous Serial Device Drivers. COMi supports all features and functions as described in that reference, except the Enhanced Mode functions (functions 0x54 and 0x74). Differences from COM.SYS: There are some differences in how COMi is initialized compared to the COM.SYS device driver. Here is a list of the differences: 1. COM.SYS initializes at 1200 baud. COMi defaults to 9600 baud. 2. COM.SYS initializes to a protocol of seven data bits, even parity, and one stop bit. COMi defaults to a protocol of eight data bits, no parity, and one stop bit. 3. COM.SYS defaults with hardware buffer functionality set to Automatic Protocol Override with a receive trigger level of eight bytes. COMi defaults to hardware buffers on, with a receive trigger level of fourteen bytes and a transmit buffer depth of sixteen bytes. 4. COM.SYS has fixed receive and transmit buffers. COMi's buffer sizes are user definable. 5. All COM.SYS defaults are fixed. With COMi, all startup defaults, including protocol, baud rate, buffers sizes, read and write time-out processing and time-out values, FIFO functionality, and handshaking protocols are user definable. This feature allows COMi to use startup defaults defined by the user. 6. COM.SYS does not support COMscope or COMspool, COMi does (this is important!). There should be one other difference noted here, though it pertains only to documentation. The "Physical Device Driver" technical reference stated that the COM.SYS device driver starts up with CTS and DTR output handshaking, DSR input sensitivity, and RTS input handshaking, enabled. The COM.SYS device driver starts up with no handshaking enabled and neither does COMi, unless the end-user makes it so. ═══ 5. System and Adapter Support ═══ COMi can work with any adapter that uses any of the required serial devices, in any combination and in any quantity your OS/2* system can accommodate. There are some restrictions and caveats, though, and these are what this part of the manual will explain. COMi is designed to allow an OS/2 system to access multiple serial devices at baud rates of 115.2K and above, using "dumb", inexpensive, Universal Asynchronous Receiver Transmitters (UARTs). The device driver will support any UART of the 16550 family. This includes the 8250, 8250A, 16450, 16450A, 16550A, 16550B, and some others, including most built-in UARTs that are part of a motherboard chip set. Systems Supported: o Micro Channel Architecture Machines o Industry Standard Architecture Machines ISA shared interrupt capable adapters supported: o Serial Adapters Supported Devices Supported: o 16550 UART o 16450 UART o 8250 UART ═══ 5.1. 16550 UART Support ═══ For now, the 16550 UART is the device of choice for OS/2* systems. These UARTs have both receive and transmit First In First Out (FIFO) buffers. These buffers allow a greater throughput with less interrupt overhead. When the 16550 UART's FIFO modes are enabled the device will normally interrupt the CPU every 14 received characters or every 16 transmitted characters. This means that a device receiving data at 57600 baud will get an interrupt about every 2.5 milliseconds. For comparison, without FIFOs, a device running at 57600 baud would get an interrupt about every 170 microseconds. The COMi device driver will automatically determine if any device it is configured to support has hardware buffers, and will take full advantage of those buffers when they are available ═══ 5.2. 16450 UART Support ═══ It is not recommended that you use any adapter that contains 16450 UARTs. These UARTs have no hardware buffering capabilities and will interrupt the CPU whenever a character is received or transmitted. This means that if you are running a communications program at 9600 baud there will be an interrupt about every one millisecond, possibly more if your application is receiving and streaming data (transmitting/receiving large strings) in a full duplex mode. ═══ 5.3. 8250 UART Support ═══ As with the 16450 UART, the 8250 UART does not contain FIFOs, and it is not recommended that you use serial adapters that use 8250 UARTs in OS/2* systems. COMi will work with these UARTs but your system performance may be greatly diminished when using them at higher baud rates. ═══ 5.4. MCA Support ═══ MCA machines are designed to allow adapters and/or devices to share hardware interrupts. This architecture makes it easy for COMi to support any number of serial devices in any combinations of device base addresses and hardware interrupts, with the following recommendations and restrictions: 1. Try to evenly distribute the number of devices per hardware interrupt, or use the least number of devices per hardware interrupt level when using higher baud rates. 2. Try not to use more than eight serial devices per hardware interrupt level. 3. If you need more than eight serial ports you must use adapters that support base addresses other than the eight pre-assigned MCA serial device base addresses and hardware interrupt levels. ═══ 5.5. ISA Support ═══ ISA machines do not normally allow adapters, or devices, to share hardware interrupt levels. Because of this (deficiency) there are certain restrictions for configuring the device driver for access to serial adapters and multiple serial devices. These restrictions include: 1. Shared interrupts are supported only when used with adapters that support shared interrupts. 2. If you assign the same hardware interrupt level to two different adapters, or devices, that do not support shared interrupts, you may lose received characters. 3. If you assign the same hardware interrupt level to two different adapters, or devices, that do not support shared interrupts, you will probably lock-up your system, especially if you are not accessing the port in a separate thread from your window procedure. 4. You may connect multiple, non-interrupt sharing, devices to a single interrupt without problems if the device is connected to the bus in a "wired-OR" circuit, and if you open and access only one of those devices at a time. Related Information: o Installing ISA Serial Devices o Serial Adapters Supported o Shared Interrupt Adapter Types ═══ 6. Installing ISA Serial Devices ═══ If you are installing serial device support in an ISA machine and you intend to connect multiple devices to a single hardware interrupt level you need to be aware of the following: 1. Your adapter must have special features to support interrupt sharing. 2. The adapter's special features that allow interrupt sharing must be enabled and configured correctly. 3. You must know the hardware address of your adapter's interrupt status or ID register. 4. You must open the adapter set-up dialog by clicking on the Adpter Set-up button from the Device Driver Configuration dialog to specify the adapter type, hardware interrupt level, and address of the interrupt status/ID register in order to define more than one device to a hardware interrupt level. Note: Sharing interrupts on an MCA machine requires no special configuation. Please note, though, that it is not recommended that you connect more than eight devices to any one hardware interrupt level. Related Information: o Serial Adapters Supported o Shared Interrupt Adapter Types ═══ 6.1. Shared Interrupt Adapter Types ═══ In order for COMi to support shared interrupts on an ISA machine, an adapter of one of the types described below must be used. Type One: 1. All devices on an adapter can be connected to a single IRQ line. 2. The adapter has an interrupt ID register at adapter base I/O address +7. 3. Each bit in the interrupt ID register represents one, and only one, serial device. 4. When there is no device with a pending interrupt, the ID register will be read as a zero. Type Two: 1. A Texas Instruments 16C550B UARTs are installed on the adapter. 2. All devices on an adapter can be connected to a single IRQ line. 3. The adapter has an interrupt ID register at adapter base I/O address +7. 4. Each bit in the interrupt ID register represents one, and only one, serial device. 5. When there is no device with a pending interrupt, the ID register will be read as a zero. Type Three: 1. All devices on an adapter can be connected to a single IRQ line. 2. The adapter has an interrupt ID register at a fixed or user defined address. 3. Each bit in the interrupt ID register represents one, and only one, serial device. 4. When there is no device with a pending interrupt, the ID register will be read as a zero. Type Four: 1. The adapter has an interrupt ID register at a user definable address. 2. The address of the interrupt ID register is as defined by the user for odd interrupts (3, 5, 7, 9, 11, 13, 15) and is at the user defined address +1 for even interrupts (2, 4, 6, 8, 10, 12, 14). 3. The value read from the interrupt ID register indicates the highest priority device that has an interrupt pending. 4. When there is no device with a pending interrupt, the ID register will be read as all ones (0xFF). This adapter type should be used to support DigiBoard's PC/4 and PC/8 serial adapters, only. Type Five: 1. All devices on an adapter can be connected to a single IRQ line. 2. The adapter has an interrupt ID register at a fixed address that is based on which of four available PALs is installed on the adapter. 3. The value read from the interrupt ID register indicates the highest priority device that has an interrupt pending. 4. When there is no device with a pending interrupt, the ID register will be read as all ones (0xFF). This adapter type should be used to support DigiBoard's PC/16 serial adapters, only. Related Information: o Serial Adapters Supported ═══ 6.2. Serial Adapters Supported ═══ COMi has been tested with the following serial adapters. ┌─────┬──────────────────┬────────────┐ │Type │Manufacturer │Model │ ├─────┼──────────────────┼────────────┤ │One │Sealevel Systems │COMM+4 │ ├─────┼──────────────────┼────────────┤ │ │ │TURBOCOMM+8 │ ├─────┼──────────────────┼────────────┤ │ │Globetek │Four Port │ ├─────┼──────────────────┼────────────┤ │ │Quatech │ES-xxx │ ├─────┼──────────────────┼────────────┤ │ │ │QS-xxx │ ├─────┼──────────────────┼────────────┤ │Two │Comtrol │Hostess RJ45│ ├─────┼──────────────────┼────────────┤ │ │ │Hostess RJ11│ ├─────┼──────────────────┼────────────┤ │Three│Connect Tech │DFLEX │ ├─────┼──────────────────┼────────────┤ │Four │DigiBoard │PC/4 │ ├─────┼──────────────────┼────────────┤ │ │ │PC/8 │ ├─────┼──────────────────┼────────────┤ │Five │DigiBoard │PC/16 │ └─────┴──────────────────┴────────────┘ COMi will support shared interrupts with all of the adapters listed above and any other adapter that uses one of the interrupt sharing schemes described under COMi Adapter Types. ═══ 7. Troubleshooting ═══ Believe it or not, the COMi installation and configuration process is not always as simple and straight forward as we would like it to be. The following is help and explanation for the most common problems encountered when attempting to install, configure, and access the COMi device driver: o Hardware Interrupt Level Selection o Base I/O Address Selection o Errors During System Start-up o Loading with COM.SYS o Run-time Problems o Read/Write Errors o Device I/O control (DosDevIOCtl) Errors o Lock-up, Pointer Moves o Lock-up, Pointer Does Not Move ═══ 7.1. Hardware Interrupt Level Selection ═══ The COMi configuration program will not normally allow you to configure more than one device per hardware interrupt level on ISA machines unless you have selected an adapter type from the Adpter Set-up dialog, supplied an interrupt status register address, and selected an interrupt level. CAUTION If you supply an interrupt status register address and there is no such register with that function your, system WILL lock-up. You may configure more than one device to share an interrupt level by selecting the Extensions... button when configuring a device, and selecting the "Share Interrupt Connection" check box. In order to share interrupts using this "extension", your hardware must have a "wired-OR" interrupt circuit that ties each device to the system board's Interrupt Request (IRQ) circuit. You can expect this to be the case any time you are using a multi-device adapter that allows you to connect more than one device to any one interrupt level. Adapters that contain only one serial device rarely use this type of circuit. In general it is not a good idea to configure devices on more than one adapter to share interrupts. The exception is when your are using any adapter that specifically supports multi-adapter interrupt sharing. MCA machines are designed to allow interrupt sharing. You can select any hardware interrupt level, though we do not recommend assigning more than eight devices to any one hardware interrupt level. ═══ 7.2. Base I/O Address Selection ═══ The configuration programs will not allow you to select a base I/O address for any device that is assigned to another COMi controlled device, nor will it allow you to select a base address that is not at an eight byte boundary. ═══ 7.3. Errors During System Start-up ═══ During each load of the COMi device driver each defined device is normally tested to determine the following: 1. If the device is a qualified UART. 2. If the configured hardware interrupt level is available. 3. If the device is connected to the configured hardware interrupt level. 4. If the configured interrupt status register (if any) is correct. 5. If the UART has FIFO capabilities (hardware buffers). Any device failing the first four tests will not be installed and will not be available at run-time. If you KNOW that the device is valid as defined, you can select Disable Start-up UART Tests in the Extensions dialog box for this device. Enabling this extension will cause all tests to be bypassed except the interrupt level availability test (number two). This may be necessary if you have a UART that is built into the motherboard chip set, or a device that is not quite compatible with the 8250/16450/16550 UART. ═══ 7.4. Loading with COM.SYS ═══ COMi will work when COM.SYS and VCOM.SYS are loaded. If you want to use both COMi and COM.SYS you will need to insure that COM.SYS is loaded before COMi. The configuration program will normally place COMi "DEVICE=" statements at the end of the CONFIG.SYS file, so this should not be a problem. You will also have to refrain from naming COMi devices with the same names COM.SYS will use. Naming a COMi device COM1 through COM4 will cause COM.SYS to drop access to any device it owns with those device names. If you know that you do not have serial hardware at a traditional, or pre-defined, COMx location you can use that device name without problems. If you want to use COM.SYS for some COM ports and COMi for other's you need only configure COMi to use the device name (COMx) you want COM.SYS to drop. Additional Considerations: 1. ISA machines 2. MCA machines ═══ 7.4.1. ISA Considerations ═══ ISA machines have traditionally defined serial devices for COM1 through COM4. Below is a listing of traditional ISA serial port specifications. ┌─────────┬─────────┬─────────┐ │Device │Base │Interrupt│ │Name │Address │Level │ ├─────────┼─────────┼─────────┤ │COM1 │0x3F8 │4 │ ├─────────┼─────────┼─────────┤ │COM2 │0x2F8 │3 │ ├─────────┼─────────┼─────────┤ │COM3 │0x3E8 │4 │ ├─────────┼─────────┼─────────┤ │COM4 │0x2E8 │3 │ └─────────┴─────────┴─────────┘ The COM.SYS device driver will normally connect only to COM1 and COM2. However, you can request access to COM3 and COM4 by defining the port number, base address, and interrupt level on the "DEVICE=d:\path\COM.SYS" command line in the CONFIG.SYS file. Using this method will not allow you to share interrupts, but you could get sequential access to devices defined with the same hardware interrupt level. If you want to have COM.SYS and VCOM.SYS control any of the above listed devices you will not be able to use their respective COMx device names when configuring COMi. For information on how to configure COM.SYS for COM3 and COM4 access enter "HELP COM.SYS" from any command prompt, or search in the "Command Reference" for "COM.SYS". ═══ 7.4.2. MCA Considerations ═══ MCA machines have eight pre-defined serial port designations. COM1 through COM4 can be controlled by COM.SYS. Below is a listing of pre-defined MCA serial port specifications. ┌─────────┬─────────┬─────────┐ │Device │Base │Interrupt│ │Name │Address │Level │ ├─────────┼─────────┼─────────┤ │COM1 │0x3F8 │4 │ ├─────────┼─────────┼─────────┤ │COM2 │0x2F8 │3 │ ├─────────┼─────────┼─────────┤ │COM3 │0x3220 │3 │ ├─────────┼─────────┼─────────┤ │COM4 │0x3228 │3 │ ├─────────┼─────────┼─────────┤ │COM5 │0x4220 │3 │ ├─────────┼─────────┼─────────┤ │COM6 │0x4228 │3 │ ├─────────┼─────────┼─────────┤ │COM7 │0x5220 │3 │ ├─────────┼─────────┼─────────┤ │COM8 │0x5228 │3 │ └─────────┴─────────┴─────────┘ COM.SYS will allow you to access up to four devices from this list and will automatically use COM1 through COM4 for the first four serial devices it detects from the above list. The COMi device driver will also automatically configure itself, but it will allow you to access all eight devices defined in the list above. COMi will try to automatically configure itself for any unowned device it detects in the list above. If COM.SYS or any other ABIOS aware serial device driver is loaded, COMi will not install any COMx port or device that is already owned by a previously loaded device driver. You will need to create an initialization file with a COMi configuration program (COMscope or Install) if you want COMi to control any device that a previously loaded device driver owns. If you need access to more than eight serial devices and/or serial devices that are not configured as defined in the above table, you will also need to create an initialization file with a COMi configuration program. ═══ 7.5. Run-time Problems ═══ Improperly configuring COMi and/or the serial adapter can cause various kinds of problems, none of which result in increased productivity. The following items are the most common problems: o Read/Write Errors o Device I/O control (DosDevIOCtl) Errors o Lock-up, Pointer Moves o Lock-up, Pointer Does Not Move ═══ 7.5.1. Read/Write Errors ═══ When an application writes to, or reads from, a COMx device, the device driver does not normally return to the calling thread until all requested characters have been either received or transmitted. If a time-out occurs before all characters have been transmitted, or received, the device driver will return to the calling thread with a count of the actual characters written, or read. An application should test the returned count to determine if it should try to re-transmit, or read again, any remaining characters. Write time-outs normally occur only when some output handshaking has been enabled and some event has caused the device driver to stop transmitting before it could transmit all of the requested characters. Read time-outs can occur anytime the "far-end" stops transmitting, before all requested characters have been received. ═══ 7.5.2. Device I/O control (DosDevIOCtl) Errors ═══ See the "Physical Device Driver". technical reference, Category One, Asynchronous Serial Device Drivers, for a complete description of the device I/O control commands and their various input and output parameters. COMi is designed to operate according to that application interface. Your distribution diskette contains a "C" source file that has sample code for most of the DosDevIOCtl functions defined in the Technical Reference. The file name is "IOCTL.C". ═══ 7.5.3. Lock-up, Pointer Moves ═══ An application has probably tried to read the COM device from the window procedure thread, the time-out is set for the default one minute read time-out, and no characters are arriving at the UART. The device driver does not return to the calling thread until no characters have been received for the user configured read time-out count. It is recommended that an application access any COM device with a thread separate from the thread in which its window procedure is running. Of course there are other reasons for system lock-up, but this one seems to be the most common when accessing COM devices. ═══ 7.5.4. Lock-up, Pointer Does Not Move ═══ This problem, when related to COM devices, is almost always caused by improper configuration of the device driver and/or serial adapter and/or device, and is the result of an endless loop within the interrupt service routine while interrupts have been disabled. Make sure that the COMi device driver is configured correctly for your adapter and that the serial adapter and/or device is configured as you intended. ═══ 8. Communications Concepts ═══ This section is a "catch-all" for information we thought might be useful. Concepts: o Why Handshaking? o Automatic Protocol Override ═══ 8.1. Why Handshaking? ═══ In any system it is important that all real-time activities, like serial communications, be truly asynchronous. Basically this means that no information should be lost because the operating system was busy doing something else. In operating systems like DOS, or DOS and Windows**, there is never any guarantee the operating system will be able to get to a "real-time" process in a timely manner. Each process in these systems "owns" the machine until it relinquishes control. If a real-time process needs service it has to wait until any currently running process has completed. In OS/2* this is not normally a problem. Its structure is such that hardware interrupts have the highest priority and are serviced almost immediately, and other processes are given a time-slice in which to execute. Problems can occur in two ways. The first is when hardware interrupts come in faster than the operating system can respond. For asynchronous serial communications this problem is addressed mostly by serial devices with hardware buffers (FIFOs). The second problem is that an application may not be able to read and process incoming information as fast as the hardware and device driver can receive and store information. This problem is addressed by the handshaking features of the serial device driver. When handshaking is enabled the receiving system will signal the transmitting system to stop transmitting when its receive buffer nears full capacity. The transmitting system should stop transmitting when it receives a signal to stop. In OS/2, a serial device driver must be capable of handshaking without intervention or control by the controlling higher level process. All a controlling process needs to do is command the device driver into a handshaking mode and the device driver must do all of the processing to be sure that the controlling process does not lose any information. This includes detecting when its own receive buffer is nearly full so it can send a "stop transmitting" signal and then detecting when its receive buffer has been emptied enough so that it can send a "start transmitting" signal. It also includes detecting when the device it is transmitting to has sent a "stop transmitting" or "start transmitting" signal and act accordingly. ═══ 8.2. Why Automatic Protocol Override ═══ This feature can only be enabled when a device has hardware buffers (FIFOs). Normally you would want to enable hardware buffers to reduce system overhead. When handshaking is required between this hardware (near-end) and some external hardware (far-end) it may be required that a far-end's request to stop transmitting be acted upon immediately. If hardware buffers are enabled it would be possible for that hardware to transmit up to twenty bytes after the far-end sends a "stop transmitting" signal. This is because once the device driver has filled the hardware buffer, transmission will continue until the buffer is empty. This may cause a problem for some far-end equipment. This problem can occur when any output handshaking is enabled. This includes CTS, DSR, and/or DCD output handshaking and transmit Xon/Xoff handshaking. The CTS, DSR, and DCD signals are "hardware" flow control signals and transmit Xon/Xoff handshaking is "software" flow control signaling. There are two output handshaking scenarios to consider. The first is the "hardware" signaling case. When the far-end's receive buffer is full (or nearly full) it may signal to the near-end by making one or more of the "hardware" signals inactive. When the near-end detects an inactive signal it should stop transmitting. If the transmit buffer is enabled at the near-end it may transmit up to 16 bytes before it can act on that signal to stop. The second case is "software" signaling. When the far-end's receive buffer is full (or nearly full) it may signal to the near-end by transmitting an Xoff character. When the near-end receives the Xoff character it should stop transmitting. If, at the near-end, the receive buffer is enabled, it will not detect the request to stop transmitting until it has read the Xoff character from the receive buffer, and if the transmit buffer is enabled it may transmit up to sixteen bytes before it stops transmitting. The worst case could occur when "software" signaling is enabled. When hardware buffers are enabled it would be possible for an Xoff character to be received by the hardware and not read by the device driver for up to four character-times after the byte was received. The worst case would be for the Xoff character to arrive at the near-end hardware just as there are four characters left in the transmit buffer to be transmitted. The device would cause a transmit interrupt just as the last or the four bytes is transmitted and the device driver would refill the transmit buffer, then the device would cause a receive FIFO time-out interrupt and the device driver would read, and detect, the Xoff character, preventing further transmissions. This case could allow up to twenty bytes to be transmitted after the far-end transmitted the Xoff character. All of these potential problems go away if the transmit buffer is disabled when any output handshaking is enabled and the receive buffer is disabled when transmit Xon/Xoff handshaking is enabled. When Automatic Protocol Override (APO) is enabled the device driver adjusts hardware buffer functionality according to handshaking requirements. When APO is enabled and an application requests CTS, DSR, or DCD output handshaking the device driver will disable the transmit buffer. When APO is enabled and an application requests transmit Xon/Xoff handshaking the device driver will disable both the transmit and receive buffers. There is one other adjustment Automatic Protocol Override can cause the device driver to make to the hardware buffers of a device. When DSR input sensitivity is enabled, and APO is enabled, the receive buffer will be disabled by the device driver. DSR input sensitivity is designed to handle devices that may transmit garbage whenever DSR is in the inactive state. In this case it would be necessary to ignore any bytes received while DSR is inactive. It may be possible for the far-end to transmit a character at the same time it activates DSR. This could cause the near-end to miss a valid byte if its receive buffer is enabled. What does all this mean to you? Probably nothing. There are not many "far-end" devices around these days that do not have some level of buffering capability. We recommend that you leave APO off, and FIFOs enabled, unless, and until, you determine that you are communicating with some archaic equipment that requires it. ═══ ═══ IBM, OS/2, PS/2, Micro Channel, and AT are all trade marks of International Business Machines, Incorporated. ═══ ═══ Windows is a trade mark of Microsoft Corporation. ═══ ═══ Micro Channel Architecture The IBM PS/2 and compatables use a Micro Channel Architecture system bus. IBM and PS/2 are trade marks of International Business Machines, Incorporated. ═══ ═══ Industry Standard Architecture The IBM AT and compatables use an Industry Standard Architecture system bus. IBM and AT are trade marks of International Business Machines, Incorporated.