Q(uick)BASIC Statement: OPEN COM

Quick View

OPEN COM

A device I/O statement that opens and initializes a communications channel for I/O

Worth knowing

Useful and cross-version information about the programming environments of QBasic and QuickBasic.

Syntax

OPEN "COMn: optlist1 optlist2" [FOR mode] AS [#]filenum% [LEN=reclen%]

Description/Parameter(s)

Opens and initializes a communications channel for input or output (I/O). The OPEN COM statement must be executed before a device can be used for communication using an RS232 interface.

The communications port to open (1 = COM1, 2 = COM2).

optlist1

The most-often-used communications parameters:

[baud] [,[parity] [,[data] [,[stop]]]]

baud is the baud rate of the device to be opened:

75, 110, 150, 300, 600, 1200, 2400, 4800, 9600

parity is the method of parity checking:

n (none)	e (even)	o (odd)
s (space)	m (mark)	pe (enable error checking)

data is the number of data bits per byte:

5, 6, 7, 8

stop is the number of stop bits:

1, 1.5, 2

Defaults: 300 baud, even parity, 7 data bits, 1 stop bit.

optlist2

A list of less-often-used parameters, separated by commas:

Option	Description
ASC	Opens the device in ASCII mode.
BIN	Opens the device in binary mode.
CD[m]	Sets the timeout period (in milliseconds) on the Data Carrier Detect (DCD) line.
CS[m]	Sets the timeout period (in milliseconds) on the Clear to Send (CTS) line.
DS[m]	Sets the timeout period (in milliseconds) on the Data Set Ready (DS) line.
LF	Sends a line-feed character after a carriage return.
OP[m]	Specifies how long (in milliseconds) OPEN COM waits for all communications lines to become open.
RB[n]	Sets the size (in bytes) of the receive buffer.
RS	Suppresses detection of Request to Send (RTS).
TB[n]	Sets the size (in bytes) of the transmit buffer.

mode

INPUT, OUTPUT, or RANDOM (the default). See ⮜ OPEN Statement File Modes ⮞.

filenum%

A number in the range 1 through 255 that identifies the communications channel as long as it is open.

reclen%

Random-access-mode buffer size (default is 128 bytes).

Example

'Use this example for trouble shooting serial communications problems.
'Slow baud, hardware handshaking is ignored and buffers are enlarged.
OPEN "COM1:300,N,8,1,CD0,CS0,DS0,OP0,RS,TB2048,RB2048" FOR RANDOM AS #1

Syntax

OPEN "COMn: optlist1 optlist2" [FOR mode] AS [#]filenum [LEN=reclen]

Description/Parameter(s)

COMn: is the name of the device to be opened. The n argument is the number of a legal communications device, such as COM1: or COM2:. The first list of options, optlist1, has the following form:

[speed][,[parity] [,[data][,[stop]]]]

The following list describes the possible options:

Option	Description
speed	The "baud" rate (baud means "bits per second") of the device to be opened. Valid speeds are 75, 110, 150, 300, 600, 1200, 1800, 2400 and 9600.
parity	The parity of the device to be opened. Valid entries for parity are: N (none), E (even), O (odd), S (space), or M (mark).
data	The number of data bits per byte. Valid entries are 5, 6, 7, or 8.
stop	The number of stop bits. Valid entries are 1, 1.5, or 2.

Options from this list must be entered in the order shown; moreover, if any options from optlist2 are chosen, comma placeholders must still be used even if none of the options from optlist1 are chosen. For example:

OPEN "COM1: ,,,,CD1500" FOR INPUT AS #1

If you set the data bits per byte to eight, you must specify no parity (N). Because QuickBASIC uses complete bytes (eight bits) for numbers, you must specify eight data bits when transmitting or receiving numeric data.

The choices for optlist2 are described in the following list. The argument m is given in milliseconds; the default value for m is 1000.

Option	Description
ASC	Opens the device in ASCII mode. In ASCII mode, tabs are expanded to spaces, carriage returns are forced at the end-of-line, and CTRL+Z is treated as end-of-file. When the channel is closed, CTRL+Z is sent over the RS-232 line.
BIN	Opens the device in binary mode. This option supersedes the LF option. BIN is selected by default unless ASC is specified. In the BIN mode, tabs are not expanded to spaces, a carriage return is not forced at the end-of-line, and CTRL+Z is not treated as end-of-file. When the channel is closed, CTRL+Z will not be sent over the RS-232 line.
CD[m]	Controls the timeout on the Data Carrier Detect line (DCD). If DCD is low for more than m milliseconds, a device timeout occurs.
CS[m]	Controls the timeout on the Clear To Send line (CTS). If CTS is low (there is no signal) for more than m milliseconds, a device timeout occurs.
DS[m]	Controls the timeout on the Data Set Ready line (DSR). If DSR is low for more than m milliseconds, a device timeout occurs.
LF	Allows communication files to be printed on a serial line printer. When LF is specified, a line-feed character (0AH) is automatically sent after each carriage-return character (0DH). This includes the carriage return sent as a result of the width setting. Note that INPUT and LINE INPUT, when used to read from a COM file that was opened with the LF option, stop when they see a carriage return, ignoring the line feed.
OP[m]	Controls how long the statement waits for the open to be successful. The parameter m is a value in the range 0 to 65,535 representing the number of milliseconds to wait for the communications lines to become active. If OP is specified without a value, the statement waits for ten seconds. If OP is omitted, OPEN COM waits for ten times the maximum value of the CD or DS timeout values.
RB[n]	Sets the size of the receive buffer to n bytes. If n is omitted, or the option is omitted, the current value is used. The current value can be set by the /C option on the QuickBASIC or BC command line. The default is 512 bytes. The maximum size is 32,767 bytes.
RS	Suppresses detection of Request To Send (RTS).
TB[n]	Sets the size of the transmit buffer to n bytes. If n is omitted, or the option is omitted, the current value is used. The default size is 512 bytes.

The options from the list above can be entered in any order, but they must be separated from one another by commas. For CS[m], DS[m], and CD[m], if there is no signal within m milliseconds, a timeout occurs. The value for m may range from 0 to 65,535, with 1000 as the default value. The CD default is 0.) If m is equal to 0 for any of these options the option is ignored. The CTS line is checked whenever there is data in the transmit buffer if the CS option is specified. The DSR and DCD lines are continuously checked for timeouts if the corresponding options (DS, CD) are specified.

The mode argument is one of the following string expressions:

Mode	Description
OUTPUT	Specifies sequential output mode
INPUT	Specifies sequential input mode
RANDOM	Specifies random-access mode

If the mode expression is omitted, it is assumed to be random-access input/output. The filenum is the number used to open the file. The OPEN COM statement must be executed before a device can be used for communication using an RS-232 interface.

If the device is opened in RANDOM mode, the LEN option specifies the length of an associated random-access buffer. The default value for length is 128. You can use any of the random-access I/O statements, such as GET and PUT, to treat the device as if it were a random- access file.

The OPEN COM statement performs the following steps in opening a communications device:

The communications buffers are allocated and interrupts are enabled.
The Data Terminal Ready line (DTR) is set high.
If either of the OP or DS options is nonzero, the statement waits up to the indicated time for the Data Set Ready line (DSR) to be high. If a timeout occurs, the process goes to step 6.
he Request To Send line (RTS) is set high if the RS option is not specified.
If either of the OP or CD options is nonzero, OPEN COM waits up to the indicated time for the Data Carrier Detect line (DCD) to be high. If a timeout occurs, the process goes to step 6. Otherwise, OPEN COM has succeeded.
The open has failed due to a timeout. The process deallocates the buffers, disables interrupts, and clears all of the control lines.

Note:

Use a relatively large value for the OP option compared to the CS, DS, or CD options. If two programs are attempting to establish a communications link, they both need to attempt an OPEN during at least half of the time they are executing.

Any syntax errors in the OPEN COM statement produce an error message that reads "Bad file name."

Example

The following program fragment opens communications channel 1 in random-access mode at a speed of 9600 baud, no parity bit, eight data bits, and one stop bit. Input/output will be in the binary mode. Other lines in the program can now access channel 1 as file number 2.

OPEN "COM1:9600,N,8,1,BIN" AS 2

Syntax

OPEN "COMn: optlist1 optlist2" [FOR mode] AS [#]filenum% [LEN=reclen%]

Description/Parameter(s)

Opens and initializes a communications channel for I/O. The OPEN COM statement must be executed before a device can be used for communication using an RS232 interface.

Optimization Note

If there is not an OPEN COM statement in your program, you can reduce the size of the .EXE file by linking with the stub file NOCOM.OBJ.

If there are syntax errors in the OPEN COM statement, BASIC generates the error message, "Bad file name."
The argument filenum% is the number used to open the file.
The OPEN COM statement has many options, which can be separated into two option lists:
- optlist1 contains the most general and often-used parameters;
- optlist2 contains options used in special situations.
optlist1 specifies the communication line parameters and has the following syntax:

[speed] [,[parity] [,[data] [,[stop]]]]

Following are the valid values for optlist1 options:

Option	Description	Range (default in bold)
speed	Baud rate (bits per second)	75, 110, 150, 300, 600, 1200, 1800, 2400, 9600
parity	Method of parity checking (none, even, odd, space, mark, error checking)	N, E, O, S, M, PE
data	Number of data bits per byte	5, 6, 7, or 8
stop	Number of stop bits	1, 1.5, or 2¹
¹ The default value is 1 for baud rates greater than 110. For baud rates less than or equal to 110, the default value is 1.5 when data is 5; otherwise, the value is 2.

Options in this list must be entered in the order shown. Use comma placeholders for defaults. For example,

OPEN "COM1: ,N,8," FOR INPUT AS #1

Only the baud rates shown are supported. Any other value for speed is invalid.
The PE parity value turns on error checking for parity errors.
If you set data to eight bits per byte, you must specify no parity (N).

Important

Because BASIC uses complete bytes (8 bits) for numbers, you must specify 8 data bits when transmitting or receiving numeric data.
If any options from optlist2 are chosen, comma placeholders must still be used even if all of the optlist1 options are defaults. For example:

OPEN "COM1: ,,,,CD1500" FOR INPUT AS #1OPEN "COM1: ,,,,CD1500" FOR INPUT AS #1

The optlist2 options can be specified in any order, and must be separated from one another by commas. There are three types of options: data mode, buffer size, and handshaking.
The data-mode options (ASC, BIN, and LF):

Option

Description

Default

ASC or BIN

Specifies treatment of tabs, carriage returns, and Ctrl+Z in the data stream:

	ASC	BIN
Tabs expanded to blanks	Yes	No
CR forced at end of line	Yes	No
Ctrl+Z means end-of-file	Yes	No
Ctrl+Z sent when device closed	Yes	No

BIN

Effective only with the ASC option. Used to enable communication files to be printed on a serial line printer. Causes a LF character (0AH) to be automatically sent after each CR (0DH).

Ignored (as part of BIN default)

Note that the carriage return may be sent as a result of the width setting for the device.

Note also that INPUT and LINE INPUT, when used from a COM file that was opened with the LF option, ignore the line feed.

The buffer-size options for sequential modes (RB and TB):

Option	Description
RB[n]	Receive buffer size (in bytes)
RB[n]	If the RB option is not used or n is omitted, the default is 512 bytes, unless overridden by the /C option in the BC or QBX command line. Maximum receive buffer size is 32,767 bytes.
TB[n]	Transmit buffer size (in bytes)
TB[n]	If the TB option is not used or n is omitted, the default is 512 bytes.

Handshake and timing options (RS, CD, CS, DS, and OP):

Option

Description

Suppresses detection of Request To Send (RTS).

CD[m]

Specifies the timeout period on the Data Carrier Detect line (DCD). If no signal appears on the DCD line (the DCD line remains low) for more than m milliseconds, a device timeout occurs. If a CD timeout occurs, ERDEV contains 130 (82H).

Default if CD option not used, m is omitted, or m = 0	Range, if m specified
m = 0, which means ignore the state of the DCD line.	0 - 65,535 milliseconds

CS[m]

Specifies the timeout period on the Clear To Send line (CTS). If no signal appears on the CTS line (the CTS line remains low) for more than m milliseconds, a device timeout occurs. If a CS timeout occurs, ERDEV contains 128 (80H).

Default if CS option not used or m is omitted	Range, if m specified
m = 1000 milliseconds	0 - 65,535 milliseconds (m = 0 means ignore the state of the CTS line)

DS[m]

Specifies the timeout period on the Data Set Ready line (DSR). If no signal appears on the DSR line (the DSR line remains low) for more than m milliseconds, a device timeout occurs. If a DS timeout occurs, ERDEV contains 129 (81H).

Default if DS option not used or m is omitted	Range, if m specified
m = 1000 milliseconds	0 - 65,535 milliseconds (m = 0 means ignore the state of the DSR line)

OP[m]

Specifies how long the OPEN statement waits for all communications lines to become active:

Default if OP not used	Default if OP used, but m omitted	Range, if m specified
10 times the CD or DS timeout value, whichever is greater	10 seconds	0 - 65,535 milliseconds

Usage Notes
Specifying the argument reclen% is effective only in random-access mode. You can use any of the random-access I/O statements, such as GET and PUT, to treat the device as if it were a random-access file.
Use a relatively large value for the OP option compared to the CS, DS, or CD options.
The argument mode is one of the following string expressions:
Mode Description
OUTPUT Specifies sequential output mode.
INPUT Specifies sequential input mode.
RANDOM Specifies random-access mode.
If mode is omitted, it is assumed to be random-access input/output.
The OPEN COM statement performs the following steps in opening a communications device:
1. The communications buffers are allocated and interrupts are enabled.
2. The Data Terminal Ready line (DTR) is set high.
3. If either of the OP or DS options is nonzero, the statement waits for the timeout period for the Data Set Ready line (DSR) to go high. If a timeout occurs, the process goes to step 6.
4. If the RS option is not specified, the Request To Send line (RTS) is set high.
5. If either of the OP or CD options is nonzero, the statement waits for the timeout period for the Data Carrier Detect line (DCD) to go high. If a timeout occurs, the process goes to step 6. Otherwise, the RS232 device has been successfully opened.
6. If there is a timeout, the open fails. The process deallocates the buffers, disables interrupts, clears all of the control lines, and generates the message, "Device timeout." In addition, for DOS, the process sets the value of ERDEV$ to COM and sets ERDEV to a value that indicates the signal line that timed out, according to the following table:
  ERDEV value Signal line
  128 (80H) Clear to Send (CTS) timeout
  129 (81H) Data Set Ready (DSR) timeout
  130 (82H) Data Carrier Detect (DCD) timeout

Example

This example uses the OPEN COM statement to open the COM1 port for input and the COM statement to enable event trapping. The ON COM statement passes control to a subroutine when there is activity on a terminal.
Note: To run this program, you must have a terminal connected to the COM1 port.

CLS
'Set up error handling in case COM1 doesn't exist.
ON ERROR GOTO ErrHandler
'Open the COM port.
OPEN "COM1:9600,N,8,1,BIN" FOR INPUT AS #1
 
'Turn on COM event processing.
COM(1) ON
'Set up COM event handling.
ON COM(1) GOSUB Com1Handler
'Wait for a COM event to occur or a key to be pressed.
DO
LOOP WHILE INKEY$ = ""
'Turn off COM event handling.
COM(1) OFF
CLS
END
 
Com1Handler:
    PRINT A$; "Something was typed on the terminal attached to COM1."
    RETURN
 
ErrHandler:
    SELECT CASE ERR
  CASE 68: PRINT "COM1 is unavailable on this computer.": END
  CASE ELSE: END
    END SELECT

ERDEV value	Signal line
128 (80H)	Clear to Send (CTS) timeout
129 (81H)	Data Set Ready (DSR) timeout
130 (82H)	Data Carrier Detect (DCD) timeout