Microsoft KB Archive/101419

{|
 * width="100%"|

The DCB Structure in Windows 3.1

 * }

Q101419

-

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). GetCommErroris 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

Issue type :

Technology : kbAudDeveloper kbWin3xSearch kbSDKSearch kbWinSDKSearch kbWinSDK310