COMPort

Description: This function opens a serial port and handles all interrupts and asynchronous events for that serial port, including transmission, reception, and control. It returns its own error code. Please note that the SerialStream function is generally preferred in many situations; however, ComPort continues to be supported.

Returns: Numeric

Usage: Steady State

Format: ComPort(Port, ReceiveLen, TransmitLen, Baud, DataBits, StopBits, Parity, RTS, XOnXOff, Obsolete, Obsolete, Control)

Parameters: Port { numeric } { required } { no default: }

Any numeric expression giving the serial port number to be used. For COM1: Port = 1; for COM2: Port = 2. The valid range for Port is 1 to MaxComPorts (a variable storing the maximum number of Windows serial ports available. As of the release date of VTS 8.0, this is 4096).

ReceiveLen { numeric } { required } { no default: }

Any numeric expression giving the size of the receive buffer in bytes. ReceiveLen must be in the range 2 to 32 766. If more bytes are received than can fit in the receive buffer before your application removes them using SerRcv or a similar WEB function, the additional data will be lost.

TransmitLen { numeric } { required } { no default: }

Any numeric expression giving the size of the transmit buffer in bytes. TransmitLen must be in the range 2 to 32 766; the buffer must be large enough to hold the maximum number of bytes pending transmission at any instance.

Baud { numeric } { required } { no default: }

Any numeric expression giving the baud rate. Baud must be in the range 10 to 115 200, and must divide evenly into 115 200 with no more than 2.5% error.

DataBits { numeric } { required } { no default: }

Any numeric expression giving the number of data bits per character. DataBits must be 5, 6, 7, or 8.

StopBits { numeric } { required } { no default: }

Any numeric expression giving the number of stop bits per character. StopBits must be 1 or 2.

Parity { numeric } { required } { no default: }

Any numeric expression giving the parity checking to use (as follows):

Value	Parity
0	No parity
1	Odd parity
2	Even parity
3	0 Stick (space parity)
4	1 Stick (mark parity)

RTS { numeric } { required } { no default: }

Any numeric expression that gives the RTS buffer control method. RTS is on while transmitting; when a transmission is complete, RTS is off. This is usually used to control the transmitters on RS-422/485 ports. This parameter has no effect if the automatic RTS control is selected in the Control parameter.

Acceptable values of the RTS parameter are as follows:

Value	RTS Method
0	Force RTS off
1	Force RTS on
2	Half-duplex operation (Windows NT only)
3	Controlled by SerRTS function

If this parameter is 2, the SerRTS function can set its value, however, regardless of SerRTS, the RTS control line will be asserted when data is sent. If the SerRTS is called to change the RTS line while data is being transmitted, the RTS line will not change when the last byte is sent. If SerRTS is not executed while the data is transmitted, the RTS line will be cleared after the last byte is transmitted.

Under Windows 95, a value of 2 will behave the same as a value of 1.

XOnXOff { Boolean } { required } { no default: }

Any logical expression. If true (non-0), software flow control is to be used; if false (0), flow control software is not used.

Obsolete { numeric } { required } { no default: }

No longer used, but is maintained for backward compatibility with previous versions of VTS; set to 0.

Obsolete { numeric } { required } { no default: }

No longer used, but is maintained for backward compatibility with previous versions of VTS; set to 0.

Control { numeric } { required } { no default: }

Any numeric expression that specifies the handling procedure for the clear to send (CTS), carrier detect (CD), and data set ready (DSR) input lines, and the data terminal ready (DTR) output line on the serial port. The value must be in the range 0 to 63. The desired action is the sum of the following values:

Value	Bit No.	Control
1	0	DTR on (otherwise DTR is off)
2	1	Enable CTS control
4	2	Enable CD control
8	3	Enable DSR control
16	4	Enable RTS/CTS control
32	5	Enable DTR/DSR control

If bit 1, CTS control, is set data will only be transmitted if the CTS signal is on. If CTS control is disabled, the CTS line is ignored.

If bit 2, CD control, is set data will only be transmitted when the CD signal is on. If CD control is disabled, the CD line is ignored.

If bit 3, DSR control, is set data will only be transmitted when the DSR signal is on. If DSR control is disabled, the DSR line is ignored.

If bit 4, RTS/CTS control, is set the CTS control behaves as described above, and the RTS line will be held high until the receive buffer reaches 75% full. It will then go low, indicating to the other device to stop transmitting data. The RTS line will go high again when the receive data buffer drops below 25% full. This is known as hardware flow control. RTS/CTS control enabled overrides the RTS parameter.

If bit 5, DTR/DSR control, is set the DSR control behaves as described above, and the DTR line will be held high until the receive buffer reaches 75% full. It will then go low, indicating to the other device to stop transmitting data. The DTR line will go high again when the receive data buffer drops below 25% full. This is known as hardware flow control. DTR/DSR control enabled overrides bit 0, DTR on option.

bits 6 through 14: Obsolete. No longer used, but maintained for backward compatibility with previous versions of VTS; set to 0.

Comments: This statement has been superseded by the SerialStream function and is maintained for backwards compatibility only.

This function is part of the driver toolkit and must be active to control its serial port; the ComPort is activated upon entering the state, and de-activated upon leaving the state. Standard VTS drivers that use the serial port use this statement. Typically, all parameters are public member variables of I/O driver modules which are set to default values in a script, and may be altered using the scope resolution operator, (a backslash ( \ )) (see the section on the driver in question).

The return value is an error code having one of the following meanings:

Value	Meaning
0	No error
1	Out-of-range error in one of the parameters
2	Port already in use
5	Access denied
31	General failure
87	Invalid parameter

A ComPort function must be active for serial port communications. None of the driver toolkit functions (anything beginning with Ser... , such as SerSend) will work without a ComPort function.

Make sure that VTS's mouse (if it is serial) is on a different port, because the mouse and ComPort can interfere. Also make sure that no other hardware or software is interfering with the serial port hardware interrupts (IRQ4 for COM1:, IRQ3 for COM2:). Network cards often use IRQ4, which will cause a problem with a mouse or ComPort on COM1.

Before writing a communications driver for VTS, it is important to understand some general data communications concepts (such as headers, checksums, packets, etc.) as well as the particular protocol you wish to implement. Although there are enough VTS statements to implement I/O drivers, you must design the modules that use these statements. It is a good idea to understand how fixed modules may be used to implement semaphores and queues (so that module designed to read packets can queue up for their turns to use the serial port, and prevent collisions).

Example:

ComPort(2 { COM2: },

1024 { Buffer 1024 bytes of received data },

1024 { Buffer 1024 bytes of transmitted data },

9600 { Baud rate },

8 { Data bits per byte },

1 { Stop bit per byte },

0 { No parity bit },

1 { Force RTS on },

0, 0, 0 { Obsolete parameters },

3 { Control: DTR On, CTS control enabled },

0, 0, 0, 0, 0, 0, 0, 0, 0 { Obsolete parameters });

This example opens COM2: for use with serial port functions. These functions should use 2 as their Port parameter.