Opens a connection to the CitectSCADA API. The CTAPI.DLL is initialized and a connection is made to CitectSCADA. If CitectSCADA 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 CitectSCADA.
If you use the CT_OPEN_RECONNECT mode, and the connection is lost, the CTAPI will attempt to reconnect to CitectSCADA. 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 CitectSCADA 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 CitectSCADA, 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, and CIDEBUGHELP.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 CitectSCADA 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 CitectSCADA 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 CitectSCADA is lost CTAPI will continue to retry to connect to CitectSCADA.
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 CitectSCADA 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);