Technical Reference > CtAPI Functions > Function Reference > ctCiCode


Executes a Cicode function on the connected CitectSCADA computer. This allows you to control CitectSCADA 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 CitectSCADA 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 CitectSCADA 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.


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


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


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


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


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


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 need the result of the function.


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.


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



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