Technical Reference > CtAPI Functions > Function Reference > ctOpen

ctOpen

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