DOCUMENT:Q101419 12-NOV-1999 [win16sdk] TITLE :The DCB Structure in Windows 3.1 PRODUCT :Microsoft Windows Software Development Kit PROD/VER:WINDOWS:3.1 OPER/SYS: KEYWORDS:kb16bitonly ====================================================================== ------------------------------------------------------------------------------- The information in this article applies to: - Microsoft Windows Software Development Kit (SDK) 3.1 ------------------------------------------------------------------------------- SUMMARY ======= The data control block (DCB) structure defines the control setting for a serial communications device. OpenComm() and BuildCommDCB() both initialize a DCB structure. However, there are many fields in the DCB that cannot be changed using these procedures. These fields can be updated directly, and these changes can be applied to the communications port using SetCommState(). MORE INFORMATION ================ OpenComm() uses BuildCommDCB() with "COM1:9600, E, 7, 1" as the lpszDef parameter to build a default DCB. OpenComm() internally calls SetCommState() with this default DCB to set the initial state of the communications port. BuildCommDCB() can be used to initialize a DCB with certain settings. This procedure takes a string in the same format as the MS-DOS mode command for its lpszDef parameter. For example, BuildCommDCB("COM1:9600, n, 8, 1", &myDCB) sets myDCB to have a baud rate of 9600, no parity, 8-bit byte size, and 1 stop bit. This string needs to contain only the COM port and baud rate; if the other values are absent, they will default. The default settings are even parity, byte size of 7, and 1 stop bit. SetCommState() must be called to put the new DCB settings into effect. SetCommState() takes a DCB as a parameter, and sets the port according to all the parameters. A DCB can be initialized by calling BuildCommDCB() or the current settings can be returned by calling GetCommState(). In addition, the fields in the DCB can be modified directly. After a DCB is changed, SetCommState() must be used to apply the setting to the port. Below is a summary of all the DCB fields. Each field has a description of what happens in BuildCommDCB(). The information that follows SetCommState() indicates how the DCB can be manipulated manually. That DCB can then be used in the lpDCB parameter to SetCommState(). Id - The ID of the port. This is set by BuildCommDCB(), and is the same as the OpenComm() return value. BaudRate - BuildCommDCB() - The baud rate is based on the first two characters in the baud rate position in the MS-DOS mode string. For example, "COM1:96,n,8,1" will set the baud rate to 9600. The only baud rates that can be set are 110, 150, 300, 600,1200, 2400, 4800, 9600, and 19200. If none of these baud rates are used, BuildCommDCB() returns an error. SetCommState() - The BaudRate field can set any baud rate up to 57,600 by either setting the BaudRate field in the DCB to one of the CBR_baudrate constants, or to any number greater than 2 and less than CBR_110. Numbers outside this range result in SetCommState() returning an IE_BAUDRATE error. ByteSize - BuildCommDCB() - Specifying any number other than 7 or 8 results in an error. SetCommState() - The byteSize field can be set to any number between 4 and 8. Numbers outside this range result in SetCommState() returning an IE_BYTESIZE error. Parity - BuildCommDCB - The parity can be set to "E" (even), "O" (odd), "N" (none), "M" (mark) or "S" (space). SetCommState() - The Parity field in the DCB can be set to NOPARITY, ODDPARITY, EVENPARITY, MARKPARITY, or SPACEPARITY. Other settings result in SetCommState() returning and IE_DEFAULT error. StopBits - BuildCommDCB - Stop bits of 1 or 2 are accepted. Any other value (including 1.5) returns an error. SetCommDCB() - The StopBits field can be set to ONESTOPBIT, ONE5STOPBITS, or TWOSTOPBITS. Other settings result in SetCommState() returning an IE_DEFAULT error. The time-out field, RlsTimeout, CtsTimeout, or DsrTimeout, enables time-out checking if its value is anything other than zero. This time-out checking occurs during WriteComm() regardless of any other values in the DCB, including fOutxCtsFlow and fOutxDsrFlow. Specifying INFINITE does not really enable infinite time-out. The value is set to -1 (which is 65536), which makes the time-out approximately 65 seconds. If a time-out occurs, WriteComm() returns 0 (zero), and GetCommError() returns a time-out error (CE_CTSTO, CE_DSRTO, or CE_RLSDTO). RlsTimeout - BuildCommDCB() - If the 6th parameter of the MS-DOS mode string is specified as P, then this time-out is infinite (set to -1). Any other value returns an error. If it is not specified, it defaults to (zero). SetCommDCB() - RlsTimeout can be set to IGNORE, INFINITE, or any number. This field is the amount of time, in milliseconds, to wait for RLSD (same as Carrier Detect) to become high, before copying any data to the transmit queue during WriteComm(). CtsTimeout - BuildCommDCB() - MS-DOS mode string translated exactly like RlsTimeout. SetCommDCB() - CtsTimeout can be set to IGNORE, INFINITE, or any number. This field is the amount of time, in milliseconds, to wait for CTS (Clear to Send) to become high before copying any data to the transmit queue during WriteComm(). DsrTimeout - BuildCommDCB() - MS-DOS mode string translated exactly like RlsTimeout. SetCommDCB() - DsrTimeout can be set to IGNORE, INFINITE, or any number. This field is the amount of time, in milliseconds, to wait for DSR (Data Set Ready) to become high before copying any data to the transmit queue during WriteComm(). All of the following flags are set to 0 in BuildCommDCB(), except for fBinary, which is set to 1. Any of these can be set to 0 or 1 before calling SetCommState(). fBinary - If fBinary is set to zero, reception of the EofChar character indicates the end of the input stream. ReadComm() will not return any characters past EofChar. If any characters are received after EofChar, it will be treated as overflowing the receive queue (CE_RXOVER). The reception of EofChar is indicated in the COMSTAT status flag CSTF_EOF. If fBinary is set to one, the EofChar character has no special meaning. fRtsDisable - RTS flow control is used ONLY if fRtsDisable is set to 0, and fRtsFlow is set to one. Any other combination will disable RTS flow control. OpenComm() will set RTS high, and it will remain high unless RTS flow control is enabled or fRtsDisable is set. fRtsDisable fRtsFlow RTS state --------------------------------------------- 0 0 Set High 0 1 RTS flow control enabled 1 0 Set low 1 1 Set low CloseComm() does not change the state of RTS or DTR, regardless of the state of the disable settings, but it drops them momentarily while closing the port. If RTS or DTR are not being used for flow control, they can be manipulated using EscapeCommFuntion(). fDtrDisable - Used with fDtrFlow. Functions similar to fRtsDisable/fRtsFlow. fRtsflow - See fRtsDisable. fDtrflow - See fDtrDisable and fRtsDisable. fParity - Specifies whether parity checking is enabled. If this flag is set, parity checking is performed, and CE_RXPARITY errors are reported. ReadComm() will return a negative value if it encounters an error (such as a parity error). GetCommError()is used to retrieve and clear that error. To receive notification of a parity error, SetCommEventMask() can be used to enable EV_ERR events. GetCommEventMask() should be used to clear the event, however, GetCommError() must still be used to clear the error. fOutxCtsFlow - Specifies that CTS signal is to be monitored for output flow control. If this flag is set and CTS is turned off, output is suspended until CTS is again set. If the CtsTimeout field contains any value other than zero, WriteComm() will wait for CTS, regardless of the value of fOutxCtsFlow. fOutxDsrFlow - Specifies that DSR signal is to be monitored for output flow control. If this flag is set and DSR is turned off, output is suspended until DSR is again set. If the DsrTimeout field contains any value other than zero, WriteComm() will wait for DSR, regardless of the value of fOutxDsrFlow. fDummy - Reserved. fOutX - Specifies that X-on/X-off flow control is used during transmission. If this flag is set, transmission stops when the XoffChar is received and starts again when the XonChar is received. If transmission is waiting as a result of the X-off character being received, the CSTF_XOFFHOLD flag in the COMSTAT structure will be set. fInX - Specifies that X-on/X-off flow control is used during reception. If this flag is set, the XoffChar character is sent when the reception queue comes within XoffLim characters of being full and the XonChar character is sent when the reception queue comes within XonLim characters of being empty. If transmission is waiting as a result of the X-off character being transmitted, the CSTF_XOFFSENT flag is set in the COMSTAT structure. fPeChar - Specifies that characters received with parity errors are to be replaced with the character specified by PeChar. fNull - Specifies that received null character are to be discarded. fChEvt - Not actually used. fDummy2 - Reserved. XonChar - BuildCommDCB() - Set to 0x11 (CTRL+Q) SetCommState() - Can be set to any character. This field is the X-on character for both transmit and receive. See fInX and fOutX. XoffChar - BuildCommDCB() - Set to 0x13 (CTRL+S) SetCommState() - Can be set to any character. This field is the X-off character for both transmit and receive. See fInX and fOutX. XonLim - BuildCommSCB() - Set to 10. SetCommState() - Can be set to any value. When the number of characters in the receive queue drops below this value, the X-on character is sent, if enabled, and DTR is set, if enabled. See fInX and fOutX. XoffLim - BuildCommDCB() - Set to 10. SetCommState() - can be set to any value. When the number of characters in the receive queue exceeds this value, the X-off character is sent, if enabled, and DTR is dropped, if enabled. See fInX and fOutX. PeChar - BuildCommDCB() - Set to 0. SetCommState() - Can be set to any character. Parity error replacement character. See fPeChar and fParity. EofChar - BuildCommDCB() - Set to 0. SetCommState() - Can be set to any character. Character which specifies end of input. See fBinary. EvtChar - BuildCommDCB() - Set to 0. SetCommState() - Can be set to any character. Specifies the value of the character to be used to signal an event. When this value is received, an EV_RXFLAG event will be generated. The fChEvt flag is not actually used. Use SetCommEventMask() to enable these events. TxDelay - Not actually used. Additional query words: 3.10 ====================================================================== Keywords : kb16bitonly Technology : kbAudDeveloper kbWin3xSearch kbSDKSearch kbWinSDKSearch kbWinSDK310 Version : WINDOWS:3.1 ============================================================================= THE INFORMATION PROVIDED IN THE MICROSOFT KNOWLEDGE BASE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. MICROSOFT DISCLAIMS ALL WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING THE WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL MICROSOFT CORPORATION OR ITS SUPPLIERS BE LIABLE FOR ANY DAMAGES WHATSOEVER INCLUDING DIRECT, INDIRECT, INCIDENTAL, CONSEQUENTIAL, LOSS OF BUSINESS PROFITS OR SPECIAL DAMAGES, EVEN IF MICROSOFT CORPORATION OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. SOME STATES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES SO THE FOREGOING LIMITATION MAY NOT APPLY. Copyright Microsoft Corporation 1999.