ctOpen

Opens a connection to the Plant SCADA API. The CTAPI.DLL is initialized and a connection is made to Plant SCADA. If Plant 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 Plant SCADA.

If you use the CT_OPEN_RECONNECT mode, and the connection is lost, the CTAPI will attempt to reconnect to Plant 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 Plant 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 CtAPI on a remote computer without installing Plant SCADA, you will need several CtAPI binaries. These binaries are packaged in the files CtApi.Win32.Redist.zip and CtApi.x64.Redist.zip, which can be found in the <Plant SCADA_Disk>\Plant SCADA <VersionNumber>\Extras\CtAPI directory of the Plant SCADA installation media. See Running CtAPI Applications in the topic CtAPI.

If calling this function from a remote computer, a valid username and a non-blank password needs to be used.

To establish encrypted communications for a remote connection, see Secure the Connection from a Remote CtAPI Application.

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.

Note: To use a local connection when the CtAPI process is running as a Windows service, you need to add the user account as a member to the Runtime Users security role in Configurator (see Security Roles). You also need to check that the Enable Encryption option is selected on Configurator's Encryption page.

Note: Using a hostname to connect to a CTAPI server running Plant SCADA 8.20 or earlier will not work if Windows is configured to return an IPv6 address for that hostname, as 8.20 and earlier do not support IPv6 network addresses. To avoid this, use an IPv4 address directly, or if encryption is enabled, configure Windows to return an IPv4 address in preference to an IPv6 address.

sUser

Type: LPCSTR
Input/output: Input
Description: A user name as defined in the Plant SCADA project running on the computer to which you want to connect, or a Windows user name if nMode is set to CT_OPEN_WINDOWSUSER.

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: The sUser password defined in the Plant SCADA project running on the computer to which you want to connect, or the password for the Windows user name if nMode is set to CT_OPEN_WINDOWSUSER.

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 CtAPI call. Set this to 0 (zero). The following modes are supported:

CT_OPEN_RECONNECT (0x00000002) — Reopen connection on error or communication interruption. If the connection to Plant SCADA is lost CTAPI will continue to retry to connect to Plant SCADA.

CT_OPEN_READ_ONLY (0x00000004) — Open the CTAPI in read only mode. This allows read only access to data - you cannot write to any variable in Plant SCADA or call any Cicode function.

CT_OPEN_BATCH (0x00000008) — Disables the display of message boxes when an error occurs.

CT_OPEN_EXTENDED (0x00000010) — Allows for encrypted communication. This parameter is implicitly set when encryption is enabled (with the Accept encrypted and non-encrypted connections option not selected) via the Configurator.

CT_OPEN_WINDOWSUSER (0x00000020) — Indicates that sUser and sPassword are Windows user credentials. If sUser and sPassword are blank, then the credentials of the Windows user that is launching the application will be used.

To use Windows credentials to run CtAPI operations, you need to confirm the following:

1) Your server needs to be running Plant SCADA 2020 R2 (or later).

2) You need to use the CT_OPEN_WINDOWSUSER mode, and either:

CT_OPEN_EXTENDED mode is used in the CtOpen call.

Or:

The encryption mode on the CtAPI client is set to “Encrypted”.

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

Examples

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", "PASSWORD", 0);

.

.

STRING sComputer, sUser, sPassword;

HANDLE hCTAPI;

// get input for sComputer, sUser, sPassword variables from UI, or 3rd party APIs

hCTAPI = ctOpen(sComputer, sUser, sPassword, CT_OPEN_WINDOWSUSER);