The MSComm control provides serial communications for your application by allowing the transmission

and reception of data through a serial port.

Syntax
MSComm
Remarks
The MSComm control provides the following two ways for handling communications:
!vent"driven communications is a very powerful method for handling serial port interactions. #n
many situations you want to be notified the moment an event takes place$ such as when a character arrives
or a change occurs in the Carrier %etect &C%' or Re(uest To Send &RTS' lines. #n such cases$ use the
MSComm control)s *nComm event to trap and handle these communications events. The *nComm event
also detects and handles communications errors. +or a list of all possible events and communications errors$
see the Comm!vent property.
,ou can also poll for events and errors by checking the value of the Comm!vent property after
each critical function of your program. This may be preferable if your application is small and self"
contained. +or example$ if you are writing a simple phone dialer$ it may not make sense to generate an
event after receiving every character$ because the only characters you plan to receive are the *- response
from the modem.
!ach MSComm control you use corresponds to one serial port. #f you need to access more than one serial
port in your application$ you must use more than one MSComm control. The port address and interrupt
address can be changed from the .indows Control /anel.
0lthough the MSComm control has many important properties$ there are a few that you should be familiar
with first.
/roperties %escription
Comm/ort Sets and returns the communications port number.
Settings Sets and returns the baud rate$ parity$ data bits$ and stop bits as a string.
/ort*pen Sets and returns the state of a communications port. 0lso opens and closes a port.
#nput Returns and removes characters from the receive buffer.
*utput .rites a string of characters to the transmit buffer
The following simple example shows basic serial communications using a modem:
/rivate Sub +orm12oad &'
) 3uffer to hold input string
%im #nstring 0s String
) 4se C*M5.
MSComm5.Comm/ort 6 5
) 7899 baud$ no parity$ : data$ and 5 stop bit.
MSComm5.Settings 6 ;7899$<$:$5;
) Tell the control to read entire buffer when #nput
) is used.
MSComm5.#nput2en 6 9
) *pen the port.
MSComm5./ort*pen 6 True
) Send the attention command to the modem.
MSComm5.*utput 6 ;0T; = Chr>&5?'
) .ait for data to come back to the serial port.
%o
%o!vents
2oop 4ntil MSComm5.#n3ufferCount @6 A
) Read the ;*-; response data in the serial port.
#nstring 6 MSComm5.#nput
) Close the serial port.
MSComm5./ort*pen 6 +alse
!nd Sub
<ote The MSComm control can use polling or an event"driven method to retrieve data from the port. This
simple example uses the polling method. +or an example of the event"driven method$ see help for the
*nComm event.
The Communications control allows you to add both simple serial port communication
functionality to your application and advanced functionality to create a full-featured, event-
driven communications tool.
Figure 2.1 The Communications control
The Communications control provides an interface to a standard set of communications
commands. It allows you to establish a connection to a serial port, connect to another
communication device (a modem, for instance), issue commands, exchange data, and
monitor and respond to various events and errors that may be encountered during a serial
connection.
Possible Uses
ial a phone number.
!onitor a serial port for incoming data.
Create a full-featured terminal program.
Sample Applications: Dialer.vbp and !Term.vbp
The ialer.vbp and "#Term.vbp sample applications, located in the Tools$%amples directory
of the "isual #asic C-&'!, demonstrate simple and complex (respectively) programming
techni(ues of the Communications control.
!asics o" Serial Communications
)very computer comes with one or more serial ports. They are named successively* C'!+,
C'!,, etc. 'n a standard -C, the mouse is usually connected to the C'!+ port. . modem
may be connected to C'!,, a scanner to C'!/, etc. %erial ports provide a channel for the
transmission of data from these external serial devices.
The essential function of the serial port is to act as an interpreter between the C-0 and the
serial device. .s data is sent through the serial port from the C-0, #yte values are converted
to serial bits. 1hen data is received, serial bits are converted to #yte values.
. further layer of interpretation is needed to complete the transmission of data. 'n the
operating system side, 1indows uses a communications driver, Comm.drv, to send and
receive data using standard 1indows .-I functions. The serial device manufacturer provides
a driver that connects its hardware to 1indows. 1hen you use the Communications control,
you are issuing .-I functions, which are then interpreted by Comm.drv and passed to the
device driver.
.s a programmer, you need only concern yourself with the 1indows side of this interaction.
.s a "isual #asic programmer, you need only concern yourself with the interface that the
Communications control provides to .-I functions of the 1indows communications driver. In
other words, you set and monitor properties and events of the Communications control.
#stablishing the Serial Connection
The first step in using the Communications control is establishing the connection to the serial
port. The following table lists the properties that are used to establish the serial connection*
Properties Description
Comm-ort %ets and returns the communications port number.
%ettings %ets and returns the baud rate, parity, data bits, and stop bits as a string.
-ort'pen %ets and returns the state of a communications port. .lso opens and closes a
port.
$pening the Serial Port
To open a serial port, use the Comm-ort, -ort'pen, and %ettings properties. 2or example*
' Open the serial port
MSComm1.CommPort = 2
MSComm1.Settings = "9600,N,8,1"
MSComm1.PortOpen = r!e
The Comm-ort property sets which serial port to open. .ssuming that a modem is connected
to C'!,, the above example sets the value to , (C'!,) and connects to the modem. 3ou
can set the Comm-ort property value to any number between + and +4 (the default is +). If,
however, you set this value to a C'! port that does not exist for the system on which your
application is run, an error will be generated.
The %ettings property allows you to specify the baud rate, parity, and the number of data bits
and stop bits. #y default, the baud rate is set at 5466. The parity setting is for data validation.
It is commonly not used, and set to 787. The data bits setting specifies the number of bits that
represent a chun9 of data. The stop bit indicates when a chun9 of data has been received.
'nce you:ve specified which port to open and how data communication is to be handled, you
use the -ort'pen property to establish the connection. It is a #oolean value, True or 2alse. If,
however, the port is not functional, if the Comm-ort property is set incorrectly, or if the device
does not support the settings you:ve specified, an error will be generated or the external
device may not wor9 correctly. %etting the value of the -ort'pen property to 2alse closes the
port.
%or&ing 'ith a (odem
In most cases, you will use the Communications control to program your application to wor9
with a modem. 1ith the Communications control, you can use the standard ;ayes-
compatible command set to dial a phone number, or connect to and interact with another
modem.
'nce the serial port connection has been established using the Comm-ort, %ettings, and
-ort'pen properties, you use the 'utput property to activate and interact with the modem.
The 'utput property is used to issue commands which control the interaction between one
modem and another. 2or example*
' "#ti$ate the mo%em an% %ial a phone n!m&er.
MSComm1.O!tp!t = ""' ((()((((" * $&Cr
In the example above, the command 7.T7 initiates the connection, 77 dials the number, and
7T7 specifies touch tone (rather than pulse). . carriage return character (vbCr) must be
specified when an .T command is used.
1hen a command is successfully processed, an 7'<7 result code will be returned. 3ou can
test for this result code to determine if a command was processed successfully.
For (ore )n"ormation 2or a complete list of ;ayes-compatible commands, chec9 your
modem documentation.
Setting *eceive and Transmit !u""er Properties at Design Time
1hen a port is opened, receive and transmit buffers are created. To manage these buffers,
the Communications control provides you with a number of properties that can be set at
design time using the control:s -roperty -ages.
!u""er (emor+ Allocation
The In#uffer%i=e and 'ut#uffer%i=e properties specify how much memory is allocated to the
receive and transmit buffers. )ach are set by default to the values shown above. The larger
you ma9e the number, the less memory you have available to your application. If, however,
your buffer is too small, you run the ris9 of overflowing the buffer unless you use
handsha9ing.
For (ore )n"ormation %ee 7;andsha9ing7 later in this topic for more information.
The *Threshold and SThreshold Properties
The &Threshold and %Threshold properties set or return the number of characters that are
received into the receive and transmit buffers before the 'nComm event is fired. The
'nComm event is used to monitor and respond to changes in communications states. %etting
the value for each property to =ero (6) prevents the 'nComm event from firing. %etting the
value to something other than 6 (+, for instance) causes the 'nComm event to be fired every
time a single character is received into either buffer.
For (ore )n"ormation %ee 7The 'nComm )vent and the Comm)vent -roperty7 in this
topic for more information on these properties.
The )nput,en and #$F#nable Properties
%etting the Input>en property to 6 causes the Communications control to read the entire
contents of the receive buffer when the Input property is used. 1hen reading data from a
machine whose output is formatted in fixed-length bloc9s of data, the value of this property
can be set appropriately.
The )'2)nable property is used to indicate when an )nd of 2ile ()'2) character is found
during data input. %etting this to True causes data input to stop and the 'nComm event to fire
to inform you that this condition has occurred.
For (ore )n"ormation %ee 7!anaging the &eceive and Transmit #uffers7 and 7The
'nComm )vent and the Comm)vent -roperty7 in this topic for more information.
(anaging the *eceive and Transmit !u""ers
.s mentioned above, receive and transmit buffers are created whenever a port is opened.
The receive and transmit buffers are used to store incoming data and to transmit outgoing
data. The Communications control allows you to manage these buffers by providing you with
a number of properties that are used to place and retrieve data, return the si=e of each buffer,
and handle both text and binary data. -roperly managing these buffers is an important part of
using the Communications control.
The *eceive !u""er
The Input property is used to store and retrieve data from the receive buffer. 2or example, if
you wanted to retrieve data from the receive buffer and display it in a text box, you might use
the following code*
+t'ispla,.e+t = MSComm1.-np!t
To retrieve the entire contents of the receive buffer, however, you must first set the Input>en
property to 6. This can be done at design or run time.
3ou can also receive incoming data as either text or binary data by setting the Input!ode
property to one of the following "isual #asic constants* comInput!odeText or
comInput!ode#inary. The data will either be retrieved as string or as binary data in a #yte
array. 0se comInput!odeText for data that uses the .8%I character set and
comInput!ode#inary for all other data, such as data that has embedded control characters,
8ulls, etc.
.s each byte of data is received, it is moved into the receive buffer and the In#ufferCount
property is incremented by one. The In#ufferCount property, then, can be used to retrieve the
number of bytes in the receive buffer. 3ou can also clear the receive buffer by setting the
value of this property to 6.
The Transmit !u""er
The 'utput property is used to send commands and data to the transmit buffer.
>i9e the Input property, data can be transmitted as either text or binary data. The 'utput
property, however, must transmit either text or binary data by specifying either a string or #yte
array variant.
3ou can send commands, text strings, or #yte array data with the 'utput property. 2or
example*
' Sen% an " #omman%
MSComm1.O!tp!t = ""' ((()((((" * $&Cr
' Sen% a te+t string
MsComm1.O!tp!t = "his is a te+t string" * $&Cr
' Sen% .,te arra, %ata
MSComm1.O!tp!t = O!t
.s previously mentioned, transmit lines must end with a carriage return character (vbCr). In
the last example, O!t is a variant defined as a #yte array* 'im O!t/0 "s .,te. If it were a
string variant, it would be defined as* 'im O!t/0 "s String.
3ou can monitor the number of bytes in the transmit buffer by using the 'ut#ufferCount
property. 3ou can clear the transmit buffer by setting this value to 6.
-ote The Communications control cannot send or receive double byte character set (#C%)
binary data.
.andsha&ing
.n integral part of managing the receive and transmit buffers is ensuring that the bac9-and-
forth transmission of data is successful ? that the speed at which the data is being received
does not overflow the buffer limits, for example.
Handshaking refers to the internal communications protocol by which data is transferred from
the hardware port to the receive buffer. 1hen a character of data arrives at the serial port, the
communications device has to move it into the receive buffer so that your program can read
it. . handsha9ing protocol ensures that data is not lost due to a buffer overrun, where data
arrives at the port too (uic9ly for the communications device to move the data into the receive
buffer.
3ou set the ;andsha9ing property to specify the handsha9ing protocol to be used by your
application. #y default, this value is set to none (com8one). 3ou can, however, specify one of
the other following protocols*
Setting alue Description
com8one 6 8o handsha9ing (efault).
com@'n@'ff + @'8A@'22 handsha9ing.
com&T% , &T%ACT% (&e(uest To %endAClear To %end) handsha9ing.
com&T%@'n@'ff / #oth &e(uest To %end and @'8A@'22 handsha9ing.
The protocol that you choose depends upon the device to which you:re connecting. %etting
this value to com&T%@'n@'ff supports both of the protocols.
-ote If you do set this value to either com&T% or com&T%@'n@'ff, you need to set the
&T%)nabled property to True. 'therwise, you will be able to connect and send, but not
receive, data.
The $nComm #vent and the Comm#vent Propert+
epending upon the scope and functionality of your application, you may need to monitor and
respond to any number of events or errors which may occur during the connection to another
device or in the receipt or transmission of data.
The 'nComm event and the Comm)vent property allow you to trap and chec9 the value of
communication events and errors.
1hen a communication event or error occurs, the 'nComm event is fired and the value of
the Comm)vent property is changed. Therefore, if necessary, you can chec9 the value of the
Comm)vent property each time the 'nComm event is fired. #ecause communications
(especially over telephone lines) can be unpredictable, trapping these events and errors
allows you to respond to them appropriately.
The following table lists the communication events that will trigger the 'nComm event. The
values will then be written to the Comm)vent property.
Constant alue Description
com)v%end + There are fewer than %Threshold number of characters in the transmit
buffer.
com)v&eceive , &eceived &Threshold number of characters. This event is generated
continuously until you use the Input property to remove the data from the receive buffer.
com)vCT% / Change in Clear To %end line.
com)v%& B Change in ata %et &eady line. This event is only fired when %&
changes from + to 6.
com)vC C Change in Carrier etect line.
com)v&ing 4 &ing detected. %ome 0.&Ts (universal asynchronous receiver-
transmitters) may not support this event.
com)v)'2 D )nd 'f 2ile (.%CII character ,4) character received.
The 'nComm event is also triggered, and a value is written to the Comm)vent property,
when the following errors are encountered.
Setting alue Description
com)vent#rea9+66+ . #rea9 signal was received.
com)ventCT%T' +66, Clear To %end Timeout. The Clear To %end line was low for
CT%Timeout number of milliseconds while trying to transmit a character.
com)vent%&T' +66/ ata %et &eady Timeout. The ata %et &eady line was low for
%&Timeout number of milliseconds while trying to transmit a character.
com)vent2rame +66B 2raming )rror. The hardware detected a framing error.
com)vent'verrun +664 -ort 'verrun. . character was not read from the hardware before
the next character arrived and was lost.
com)ventCT' +66D Carrier etect Timeout. The Carrier etect line was low for
CTimeout number of milliseconds while trying to transmit a character. Carrier etect is also
9nown as the &eceive >ine %ignal etect (&>%).
com)vent&x'ver +66E &eceive #uffer 'verflow. There is no room in the receive buffer.
com)vent&x-arity +665 -arity )rror. The hardware detected a parity error.
com)ventTx2ull+6+6 Transmit #uffer 2ull. The transmit buffer was full while trying to (ueue a
character.
Com)ventC# +6++ 0nexpected error retrieving evice Control #loc9 (C#) for the port.