Opening a communications port

Before we can actually open a communications port, we must first obtain a PowerBASIC file number so we may manage input and output to the communications port. The best method of obtaining a file number is to use the FREEFILE function:

DIM hComm AS LONG

hComm = FREEFILE

The general way of opening a communications port in a PowerBASIC program is with a COMM OPEN statement. The syntax is similar to a simple random-access file OPEN, where n is the communications port number

COMM OPEN "COMn" AS #hComm

Note the trailing colon typical in DOS communications is not permitted with COMM OPEN.

If you are familiar with serial communications with DOS compilers (where all of the communications parameters are configured within a single OPEN statement), you will realize that we must instead configure these parameters individually. For this purpose, PowerBASIC offers the COMM SET statement:

COMM SET #hComm, Comfunc = value

Although configuring a serial port for communications can mean using quite a few COMM SET statements, PowerBASIC offers a greater control of the serial port than was possible before, plus a completely new method of querying existing settings and status. Retrieving a setting is performed with the COMM function, which returns a Long-integer value:

x& = COMM(#hComm, Comfunc)

Comfunc must be one of the following keywords:

*Comfunc*	Return values (TRUE <> 0, FALSE = 0)
BAUD	Port Baud Rate (9600, 14400, 19200, etc). See notes below.
BREAK	TRUE/FALSE Break is asserted. Break is generally used to "get the attention" of the connected modem, terminal or system.
BYTE	Number of bits per byte (4, 5, 6, 7, or 8).
CD	TRUE/FALSE Carrier Detect state. Synonym for RLSD (READ-ONLY). When CD is TRUE, the DCE (modem) has a suitable connection on the communications channel present. When CD is FALSE, there is no suitable connection.
CTSFLOW	TRUE/FALSE Enable CTS output flow control (Input signal). When CTSFLOW is enabled, it causes the DTE (computer) to stop sending data whenever the CTS signal is set to logic low by the DCE (modem). Transmission continues when the DCE (modem) sets the CTS signal back to logic high. The CTS signal is usually used in response to an RTS signal.
DSRFLOW	TRUE/FALSE Enable DSR output flow control (Input signal). When DSRFLOW is enabled, it causes the DTE (computer) to stop sending data whenever the DSR signal is set to logic low by the DCE (modem). Transmission is enabled when the DSR signal returns to logic high. The DSR signal is often used in conjunction with CTS in response to a RTS signal.
DSRSENS	TRUE/FALSE Enable DSR sensitivity. When DSRSENS is enabled, data received by the DTE (computer) is placed into the receive buffer only if DSR is set to logic high. If DSR is set low, received data is discarded. Enabling DSRSENS allows DSR to enable or disable the DTE (the computer) to receive data from the DTE (the modem). DSRSENS is rarely used in practical communications situations.
DTRFLOW	TRUE/FALSE Enable DTR handshaking flow control (Output signal). When DTRFLOW is enabled, it signals that the DCE (modem) should prepare to connect to the communications channel. DTR is usually used for modem on-hook/off-hook control, but can also be used in conjunction with DSR for handshaking.
DTRLINE	TRUE/FALSE Enable DTR line. When enabled, DTRLINE leaves the DTR line active when the port is closed by the DTE (computer). This ensures that the DCE (modem) does not close the communications channel when the port is closed.
NULL	TRUE/FALSE Null ($NUL) bytes are discarded when read.
PARITY	TRUE/FALSE Enable parity checking. This mode must be enabled for the other Parity options to be selected.
PARITYCHAR	Character to use for parity error replacement. PARITY must be enabled.
PARITYREPL	TRUE/FALSE Enable character replacement on parity error. PARITY must be enabled.
PARITYTYPE	0 = None, 1 = Odd, 2 = Even, 3 = Mark, 4 = Space. PARITY must be enabled. Default = 0.
RING	TRUE/FALSE Ring indicator is on (READ-ONLY). When RING returns TRUE, a ringing signal is being received on the communications channel (by the modem). RING approximates the state of the ringing signal; however, it may not report accurately in all Windows platforms.
RLSD	Receive-line-signal-detect (READ-ONLY). See CD/Carrier Detect above.
RTSFLOW	Ready To Send (Output signal). 0 = Disable, 1 = Enable, 2 = Handshake, 3 = Toggle. Toggle is used for half-duplex (2-wire) operations to "reverse" the line. While the DTE (computer) is busy sending data, it raises the RTS signal, and the DCE (modem) blocks its data receive channel. When RTS signal reverts to logic low, the DCE (modem) reverts to transmit mode and the DTE (computer) switches to receive mode.
Handshake	mode causes the DTE (computer) to check the receive buffer (RXQUE) after each character is placed into the buffer. When the buffer is 5/6th full, the RTS signal is dropped. When the receive buffer drops to below 1/6th full, RTS is raised again.
RXBUFFER	Size of the receive buffer in bytes.
RXQUE	Bytes currently in the receive buffer (READ-ONLY).
STOP	0 = 1 stop bits, 1 = 1.5 stop bits, 2 = 2 stop bits.
TXBUFFER	Size of the transmit buffer in bytes. In some cases, Windows may not be able to report the transmit size.
TXQUE	Bytes currently in the transmit buffer (READ-ONLY).
XINPFLOW	TRUE/FALSE Enable XON/XOFF input flow control. When the DTE (computer) receive buffer is full, an XOFF character is sent to the DCE (modem) to instruct it to halt transmission. When the DCE is ready to resume transmission, an XON character is sent to the DCE. Typically, XOFF is sent when the receive buffer has less than 1/16th remaining, and XON is sent when the receive buffer drops to less than 1/16th of its maximum size. Default = FALSE.
XOUTFLOW	TRUE/FALSE Enable XON/XOFF out flow control. When enabled, the DCE (modem) sends an XOFF to the DTE (computer) to halt data transmission to the DCE. When the DCE is ready to receive more data, an XON character is sent. XOUTFLOW typically uses the same 1/16th rules as XINPFLOW. Default = FALSE.

Common baud rates range from 110 to 256000. There are equates defined in the WIN32API.INC file, prefixed with %CBR_ to assist you with specifying a common baud rate, but you are not restricted to a limited set of rates.

To open a communication port and initialize it for use, you will need to set the following parameters. The values are for demonstration purposes, you may choose your own settings as necessary.

' Minimum recommended settings

COMM SET #hComm, BAUD = 9600 ' 9600 baud

COMM SET #hComm, BYTE = 8 ' 8 bits

COMM SET #hComm, PARITY = %FALSE ' No parity

COMM SET #hComm, STOP = 0 ' 1 stop bit

COMM SET #hComm, TXBUFFER = 2048 ' 2 Kb transmit buffer

COMM SET #hComm, RXBUFFER = 4096 ' 4 Kb receive buffer

' Optional settings for flow control

COMM SET #hComm, CTSFLOW = 1 ' Enable CTS flow control

COMM SET #hComm, RTSFLOW = 1 ' Enable RTS flow control

COMM SET #hComm, XINPFLOW = 0 ' Disable XON/OFF Input

' flow control

COMM SET #hComm, XOUTFLOW = 0 ' Disable XON/XOFF output

' flow

When we have finished using our communication channel, we can terminate it using the COMM CLOSE function:

COMM CLOSE #hComm

If any errors occur when attempting to open the communications port, or as a result of an invalid Comfunc value, PowerBASIC will set the ERR system variable.