Opens a connection to the Citect SCADA API. The CTAPI.DLL is initialized and a connection is made to Citect SCADA. If Citect SCADA is not running when this function is called, the function will exit and report an error. This function needs to be called before any other CTAPI function to initialize the connection to Citect SCADA.
If you use the CT_OPEN_RECONNECT mode, and the connection is lost, the CTAPI will attempt to reconnect to Citect SCADA. When the connection has been re-established, you can continue to use the CTAPI. However, while the connection is down, every function will return errors. If a connection cannot be created the first time ctOpen() is called, a valid handle is still returned; however GetLastError() will indicate an error.
If you do not use the CT_OPEN_RECONNECT mode, and the connection to Citect SCADA is lost, you need to free handles returned from the CTAPI and call ctClose() to free the connection. You need to then call ctOpen() to re-establish the connection and re-create any handles.
Note: To use the CTAPI on a remote computer without installing Citect SCADA, you will need to copy the following files from the [bin]
directory to your remote computer: CTAPI.dll, CT_IPC.dll, CTENG32.dll, CTRES32.dll, CTUTIL32.dll, CIDEBUGHELP.dll, CTUTILMANAGEDHELPER.dll.
If calling this function from a remote computer, a valid username and a non-blank password needs to be used.
Syntax
ctOpen(sComputer, sUser, sPassword, nMode)
sComputer
Type: LPCSTR
Input/output: Input
Description: The computer you want to communicate with
via CTAPI. For a local connection, specify NULL as the
computer name. The Windows Computer Name is the name
as specified in the Identification tab, under the Network
section of the Windows Control Panel.
sUser
Type: LPCSTR
Input/output: Input
Description: Your username as defined in the
Citect SCADA project running on the computer
you want to connect to. This argument is only necessary if you
are calling this function from a remote computer. On a local
computer, it is optional.
sPassword
Type: LPCSTR
Input/output: Input
Description: Your password as defined in the
Citect SCADA project running on the computer
you want to connect to. This argument is only necessary if you
are calling this function from a remote computer. You need to
use a non-blank password. On a local computer, it is
optional.
nMode
Type: DWORD
Input/output: Input
Description: The mode of the Cicode call. Set this to 0 (zero).
The following modes are supported:
CT_OPEN_RECONNECT - Reopen connection on error or communication interruption. If the connection to Citect SCADA is lost CTAPI will continue to retry to connect to Citect SCADA.
CT_OPEN_READ_ONLY - Open the CTAPI in read only mode. This allows read only access to data - you cannot write to any variable in Citect SCADA or call any Cicode function.
CT_OPEN_BATCH - Disables the display of message boxes when an error occurs.
Return Value
If the function succeeds, the return value specifies a handle. If the function does not succeed, the return value is NULL. Use GetLastError() to get extended error information.
Related Functions
ctCiCode, ctClose, ctEngToRaw, ctGetOverlappedResult, ctHasOverlappedIoCompleted, ctRawToEng, ctTagRead, ctTagWrite, ctTagWrite
Example
HANDLE hCTAPI;
ctClose(hCTAPI);
hCTAPI = ctOpen(NULL, NULL, NULL, 0);
if (hCTAPI == NULL) {
dwStatus = GetLastError(); // get error
} else {
ctTagWrite(hCTAPI, "SP123", "1.23");
}
// example of open for remote TCP/IP connection.
hCTAPI = ctOpen("203.19.130.2", "ENGINEER", "CITECT", 0);
Published June 2018