ComOpen

Opens a communication port for access. The board and port need to both be defined in the database (using the Boards and Ports settings).

If you try to open the same COM port twice with ComOpen, the second open will not succeed and return -1. If this is passed without checking other Com functions, the COM port may not do anything. For this reason, do not open COM ports twice, and always check the return value from ComOpen.

The communication system should be used for low speed communications only. You should not use the communication functions to communicate with high speed PLCs - the performance may not be adequate.

It is highly recommended that you only use ComOpen in the context where no existing driver is using the same port.

For slower connections where latency might exist, it is recommended that a sleep is configured after ComOpen(). This delay will ensure that ComRead or ComWrite do not execute before the device is connected. The sleep should be twice as long as the time it takes for communication to reach its destination and return (for example, ping time for TCPIP ports). For local serial ports, a sleep will not be needed.

This function can only be called from an I/O server.

Syntax

ComOpen(sPort, nMode)

sPort:

The port name as specified in the Ports database.

nMode:

The mode of the open:

0 - Take control of the port from Plant SCADA. In this non-shared mode, you have complete access to the port - Plant SCADA cannot use the port. Communication will be restored when the port is closed. In this mode, fresh port opens will occur each call.

1 - Share the port with Plant SCADA. In this mode, you can write to the port, and Plant SCADA can also use it. Please be aware that ComRead will be unreliable if the communication port is opened as shared. In this mode, if the port is found to be connected, a reconnect does not occur. If not connected, then the port is connected.

It is recommended that mode 1 be used where possible.

Return Value

A communication port handle if the communication system is opened successfully, otherwise -1 is returned. The handle identifies the table where all data on the associated port is stored. You can use the handle in the other communication functions, to send and receive characters from the port.

Related Functions

ComClose, ComRead, ComWrite

Example

INT

FUNCTION

StartSerial(STRING sPort)

INT hPort;

hPort = ComOpen(sPort, 0);

IF hPort < 0 THEN

Prompt("Cannot open port " + sPort);

RETURN -1;

END

TaskNew("SerialRead", hPort, 0);

TaskNew("SerialWrite", hPort, 0);

ComClose(hPort);

RETURN 0;
END

INT

FUNCTION

SerialWrite(INT hPort)

STRING buffer;

INT SerialWriteError;

INT length;

INT error;

WHILE 1 DO

! put data into buffer and set length
.
.

ErrSet(1);

SerialWriteError = ComWrite(hPort, buffer, length, 1);

error = IsError() // if 7 then a timeout occurred

IF SerialWriteError THEN

Prompt("Error Writing port");

ComReset(hPort);

END

END

RETURN 0;

END

INT

FUNCTION

SerialRead(INT hPort)

STRING buffer;

INT length;

INT total;

INT SerialReadError;

total = 0;

WHILE 1 DO

length = 128; ! need to set length as read modifies

SerialReadError = ComRead(hPort, buffer, length, 1);

IF SerialReadError THEN

// Only flag error if data expected

Prompt("Error from port " + SerialReadError : ####);

ComReset(hPort);

ELSE

! get data from buffer, length is set to number read
.
.

END

END

RETURN 0;

END

See Also

Communication Functions