ComOpen

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

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. If you need high speed communication (for communicating with PLCs, etc.), you should write a protocol driver. Refer to the CitectSCADA "Driver Development Kit".

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

Syntax

ComOpen(sPort, iMode)

sPort:

The port name as specified in the Ports database.

iMode:

The mode of the open:

0 - Take control of the port from CitectSCADA. In this non-shared mode, you have complete access to the port - CitectSCADA cannot use the port. Communication will be restored when the port is closed.

1 - Share the port with CitectSCADA. In this mode, you can write to the port, and CitectSCADA can also use it. Please be aware that ComRead will be unreliable if the communication port is opened as shared.

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;

	WHILE 1 DO

		! put data into buffer and set length

		.

		.

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

		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, 2); 

		IF SerialReadError THEN

			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