COMPort

(Engine-Level Function)

Description:	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. Note that the SerialStream function is generally preferred in many situations.
Returns:	Numeric
Usage:	Steady State only.
Function Groups:	Serial Port
Related to:	ActiveX \| SerCheck \| SerialStream \| SerIn \| StrLen \| SerOut \| SerRcv \| SerRTS \| SerSend \| SerString \| SerStrEsc \| SerWait
Format:	ComPort(Port, ReceiveLen, TransmitLen, Baud, DataBits, StopBits, Parity, RTS, XOnXOff, Obsolete, Obsolete, Control, 0, 0, 0, 0, 0, 0, 0, 0, 0)
Parameters:

Port

Required. 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 9.1, this is 4096).

ReceiveLen

Required. 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

Required. 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

Required. 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

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

StopBits

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

Parity

Required. 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

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.

XOnXOff

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

Obsolete

No longer used, but is maintained for backward compatibility with previous versions of VTScada. Set to 0.

Obsolete

No longer used, but is maintained for backward compatibility with previous versions of VTScada. Set to 0.

Control

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:

(See: Bitwise Parameters & Operations)

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 VTScada. Set to 0.

Obsolete x 9

Required. Nine parameters following Control are obsolete, but must be included for the function to compile. Normally set to 0's.

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 deactivated upon leaving the state. Standard VTScada 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 or not available
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 VTScada'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 VTScada, 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 use. It is a good idea to understand how fixed modules may be used to provide semaphores and queues (so that modules 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.