Error Codes returned from CtAPI Functions

The error codes returns from the CtAPI functions are the Microsoft WIN 32 error codes. These error codes are documented in the Microsoft SDKs. Where the error code is a Citect SCADA special error code, the error code is added to the value -ERROR_USER_DEFINED_BASE.

Note: If a CtAPI function returns the error 233, it typically means the connection to the client is not established. However, it may also mean the client has not logged in correctly. confirm both scenarios.

int bRet = ctTagWrite(hCTAPI, "SP123", "12.34");
if (bRet == 0) {
	dwStatus = GetLastError();
	if (dwStatus < ERROR_USER_DEFINED_BASE) {
		// Microsoft error codes see ERROR.H
	} else {
		short    status;
		// status is theCitect SCADA error codes, see Citect SCADA help
		status = dwStatus - ERROR_USER_DEFINE_BASE;
	}
}

IsCitectError(dwStatus)             // test if Citect SCADA 
error
WIN32_TO_CT_ERROR(dwStatus)          // Convert to Citect SCADA 
status

if (IsCitectError(dwStatus)) {
	short    status;
	// status is the Citect SCADA error codes, see Citect SCADA help
	status = WIN32_TO_CT_ERROR(dwStatus);
}

If the connection is lost between your application and Citect SCADA, you need to close the connection and reopen. An inoperative connection will be shown by the returning of a Microsoft error code. If a Citect SCADA status error is returned, the connection has not been lost. The command requested is invalid and the connection does not have to be closed and reopened.

int bRet = ctTagWrite(hCTAPI, "SP123", "12.34");
if (bRet == 0) {
	dwStatus = GetLastError();
	if (dwStatus < ERROR_USER_DEFINED_BASE) {
		ctClose(hCTAPI);
		hCTAPI = ctOpen(NULL, NULL, NULL, 0);
		while (hCTAPI == NULL) {
			Sleep(2000); // wait a while
			hCTAPI = ctOpen(NULL, NULL, NULL, 0);
		}
	}
}

When the connection between your application and Citect SCADA is lost, any pending overlapped commands will time out and be canceled by CtAPI. You need to destroy handles which are associated with the connection.

In Version 5.10, the CT_OPEN_RECONNECT mode was added to ctOpen(). When this mode is enabled, CtAPI will attempt to re-establish the connection to Citect SCADA if a communication interruption occurs. Handles created with the connection will remain valid when the connection is re-created. While the connection is down, functions will be ineffective and will report errors.