Extensibility > CtAPI > Function Reference > ctOpen

ctOpen

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;
hCTAPI = ctOpen(NULL, NULL, NULL, 0);
if (hCTAPI == NULL) {
dwStatus = GetLastError(); // get error
} else {
ctTagWrite(hCTAPI, "SP123", "1.23");
ctClose(hCTAPI);
}
// example of open for remote TCP/IP connection.
hCTAPI = ctOpen("203.19.130.2", "ENGINEER", "CITECT", 0);

Published June 2018