ctCiCode

Executes a Cicode function on the connected Citect SCADA computer. This allows you to control Citect SCADA or to get information returned from Cicode functions. You may call either built in or user defined Cicode functions. Cancels a pending overlapped I/O operation.

The function name and arguments to that function are passed as a single string. Standard Citect SCADA conversion is applied to convert the data from string type into the type expected by the function. When passing strings put the strings between the Citect SCADA string delimiters.

Functions which expect pointers or arrays are not supported. Functions which expect pointers are functions which update the arguments. This includes functions DspGetMouse(), DspAnGetPos(), StrWord(), and so on. Functions which expect arrays to be passed or returned are not supported, for example TableMath(), TrnSetTable(), TrnGetTable(). You may work around these limitations by calling a Cicode wrapper function which in turn calls the function you require.

If the Cicode function you are calling takes a long time to execute, is pre-empt or blocks, then the result of the function cannot be returned in the sResult argument. The Cicode function will, however, execute correctly.

Syntax

ctCiCode(hCTAPI, sCmd, hWin, nMode, sResult, dwLength, pctOverlapped)

hCTAPI

Type: Handle
Input/output: Input
Description: The handle to the CTAPI as returned from ctOpen().

sCmd

Type: String
Input/output: Input
Description: The command to execute.

vhWin

Type: Dword
Input/output: Input
Description: The Citect SCADA window to execute the function. This is a logical Citect SCADA window (0, 1, 2, 3 etc.) not a Windows Handle.

nMode

Type: Dword
Input/output: Input
Description: The mode of the Cicode call. Set this to 0 (zero).

sResult

Type: LPSTR
Input/output: Output
Description: The buffer to put the result of the function call, which is returned as a string. This may be NULL if you do not require the result of the function.

dwLength

Type: Dword
Input/output: Input
Description: The length of the sResult buffer. If the result of the Cicode function is longer than the this number, then the result is not returned and the function call does not succeed, however the Cicode function is still executed. If the sResult is NULL then this length needs to be 0.

pctOverlapped

Type: CTOVERLAPPED*
Input/output: Input
Description: CTOVERLAPPED structure. This structure is used to control the overlapped notification. Set to NULL if you want a synchronous function call.

Return Value

Type: Dword. TRUE if successful, otherwise FALSE. Use GetLastError() to get extended error information.

Related Functions

ctOpen

Example

char    sName[32];
ctCicode(hCTAPI, "AlarmAck(0,)", 0, 0, NULL, 0, NULL);
ctCicode(hCTAPI, "PageInfo(0)", 0, 0, sName, sizeof(sName), NULL);
/* to call the Prompt function with the string "Hello Citect", the
C code would be:
*/

ctCicode(hCTAPI, "Prompt(\"Hello Citect\")", 0, 0, NULL, 0, NULL);
/* If the string does not contain any delimiters (for example spaces or commas) you may omit the string delimiters. For example to display a page called "Menu" the C code would be: 
*/
ctCicode(hCTAPI, "PageDisplay(Menu)", 0, 0, NULL, 0, NULL);

Published June 2018