Statement

Syntax

OPEN "C",portID,baud ¬
   [,[parity][,[stopbit][,[wordLength][,buffer]]]]

Revised

March 2, 2001 (Release 5)

Description

This statement opens a serial communications port (the modem port or the printer port) so that your program can write to or read from a serial device. The optimal values for the various parameters depend on the device and the desired communications protocol; see the device's manual for more information. The parameters are interpreted as follows:

¥ portID
Set this either to _modemPort or to _printerPort or to any port sepcified to a maximum -8. (Ports are numbered from -1 for the printer port to -8.) The _modemPort value also usually works to communicate with a built-in modem. Some Macintosh computers provide different values. A Powerbook generally uses _modemPort as the infra red port. and _printerPort as the internal modem. USB adapters such as the Keyspan adapter will provide different values if the device is connected before booting as opposed to plugging it in after the computer is running.

¥ baud
Set this to one of the following values: 110; 300; 1200; 1800; 2400; 3600; 4800; 7200; 9600; 19200; 38400; 57600, 115200, 230400.

¥ parity
Set this to one of the following values: _noParity; _oddParity; _evenParity. The default value is _noParity.

¥ stopbit
Set this to one of the following values: _oneStopBit; _twoStopBits; _halfStopBit (1.5 stop bits). The default value is _oneStopBit.

¥ wordLength
Set this to one of the following values: _fiveBits; _sixBits; _sevenBits; _eightBits. The default value is _sevenBits. Note: do not set this parameter to the values 5, 6, 7 or 8: these are different from the values of the symbolic constants.

¥ buffer
Set this to a number in the range 1 through 32,768. This parameter indicates how many bytes to allocate for an input buffer. The input buffer stores data that is being received, even when the program is not reading it, allowing the program to process data while data is being received in the background. The default value for buffer is 4096 bytes. To determine the number of unread characters currently in the buffer, use LOF(portID,1).

Reading Data
To read incoming data from an open serial port, use the same commands that you would use to read data from a file; e.g., INPUT#, READ#, etc. Since it's difficult to predict when (if ever) the data will come in, it's best to design your program so that it won't get "stuck" on a single statement waiting for incoming data. Instead, you should execute a loop that periodically checks whether there is any data to read. This will allow your program to proceed with other activities while it's waiting; or to quit waiting if too much time has elapsed.

There are basically three ways to check whether there is any data available in the buffer:

• You can check the value of LOF(portID,1). This will return zero if no data is available to read; otherwise, it returns the number of bytes waiting to be read.
• You can use the READ# portID,stringVar$;0 statement. By specifying ";0", you instruct the READ# statement to return immediately if there is no data available; if there is data, the statement reads all the characters currently in the input buffer (up to the maximum allowable length of stringVar$), and puts them into stringVar$. You can use LEN(stringVar$) after the READ# statement to determine how many (if any) characters were read.
• You can use the INKEY$(portID) function. It will either return one character from the buffer, or a null string if the buffer was empty.

Writing Data
To write data out to an open serial port, use the same commands that you would use to write data to a file; e.g., PRINT#, WRITE#, etc.

FB Runtime Globals
FB has several reserved global variables. (See Subs Files.Incl in Header folder)

gFBHasComTB%<spacer type="horizontal" size="105">//true if comm toolbox is used...
gFBSerialPortCount%<spacer type="horizontal" size="36">//number of com port
gFBSerialName$(n)<spacer type="horizontal" size="55">//serial port name
gFBSerialInName$(n)<spacer type="horizontal" size="36">//input buffer name
gFBSerialOutName$(n)<spacer type="horizontal" size="28">//output buffe name
gOSXSerialInited<spacer type="horizontal" size="66">//[!]0 if serial inited under OS X

After any communications port has been opened or after you make your own call to the runtime FN FBInitSerialPorts, you may refer to gFBSerialPortCount% for the total number of devices (maximum 8). gFBSerialOutName$(n) contains the name of the device. With this in mind, the serial ports can best be referred to by name rather than number when multiple ports are present or when USB devices are in use for the purpose of emulating serial ports.

To search all available communication ports use the folling lines. This is especially important if a USB/serial port adapter is inserted after the program has started.

<code>gFBSerialportCount% = 0<br>
//<spacer type="horizontal" size="58">This is for OS X<br>
<b>LONG IF</b> SYSTEM(_sysVers) => 1000<br>
  gOSXSerialInited = _false<br>
<b>END IF</b></code>

Example:
<img src="res/cd.gif" alt="" width="20" height="19" border="0"> CD Example: CTB demo

See Also

CLOSE; HANDSHAKE; LOC; LOF; INPUT#; READ#; READ FILE; READ FIELD; INKEY$; PRINT#; WRITE#; WRITE FILE; WRITE FIELD