Searches for the first object in the specified table, device, trend, or alarm data which satisfies the filter string. A handle to the found object is returned via pObjHnd. The object handle is used to retrieve the object properties. To find the next object, call the ctFindNext function with the returned search handle.
If you experience server performance problems when using ctFindFirst() refer to CPULoadCount and CpuLoadSleepMS.
Syntax
ctFindFirst(hCTAPI, szTableName, szFilter, pObjHnd,dwFlags)
hCTAPI
Type: Handle
Input/output: Input
Description: The handle to the CTAPI as returned from ctOpen().
szTableName
Type: LPCTSTR
Input/output: Input
Description: The table, device, trend, or alarm data to be
searched. The following tables and fields can be searched:
CLUSTER, NAME/TAG, RAW_ZERO, RAW_FULL, ENG_ZERO, ENG_FULL, ENG_UNITS, COMMENT, SAMPLEPER, TYPE
CLUSTER, TAG, NAME, DESC, HELP, CATEGORY, STATE, TIME, DATE, AREA, ALMCOMMENT
CLUSTER, TAG, NAME, DESC, HELP, CATEGORY, STATE, TIME, DATE, AREA, VALUE, HIGH, LOW, HIGHHIGH, LOWLOW, DEADBAND, RATE, DEVIATION, ALMCOMMENT
CLUSTER, TAG, NAME, DESC, HELP, CATEGORY, STATE, TIME, DATE, AREA, ALMCOMMENT
CLUSTER, TAG, NAME, DESC, HELP, CATEGORY, STATE, TIME, MILLISEC, DATE, AREA, ALMCOMMENT
CLUSTER, TAG, NAME, DESC, HELP, CATEGORY, STATE, TIME, DATE, AREA, ALMCOMMENT, PRIORITY, STATE_DESC, OLD_DESC
CLUSTER, TAG, NAME, HELP, ALMCOMMENT, CATEGORY, STATE, TIME, DATE, AREA, VALUE, PRIORITY, HIGH, LOW, HIGHHIGH, LOWLOW, DEADBAND, RATE, DEVIATION
CLUSTER, TAG, NAME, DESC, CATEGORY, AREA, ALMCOMMENT
CLUSTER, TAG, NAME, DESC, CATEGORY, AREA, ALMCOMMENT
CLUSTER, TAG, STATE_DESC0, STATE_DESC1, STATE_DESC2, STATE_DESC3, STATE_DESC4, STATE_DESC5, STATE_DESC6, STATE_DESC7
CLUSTER, TAG, NAME, DESC, HELP, CATEGORY, STATE, TIME, DATE, AREA, ALMCOMMENT, VALUE, HIGH, LOW, HIGHHIGH, LOWLOW, DEADBAND, RATE, DEVIATION, PRIORITY, STATE_DESC, OLD_DESC, ALARMTYPE
CLUSTER, TAG, NAME, DESC, HELP, CATEGORY, TIME, DATE, AREA, VALUE, HIGH, LOW, HIGHHIGH, LOWLOW, DEADBAND, RATE, DEVIATION, PRIORITY, STATE_DESC, OLD_DESC, ALARMTYPE, ONDATE, ONDATEEXT, ONTIME, ONMILLI, OFFDATE, OFFDATEEXT, OFFTIME, OFFMILLI, DELTATIME, ACKDATE, ACKDATEEXT, ACKTIME, ALMCOMMENT, USERNAME, FULLNAME, USERDESC, SUMSTATE, SUMDESC, NATIVE_SUMDESC, COMMENT, NATIVE_COMMENT
PRIV, AREA, CLUSTER, NAME, TRIGGER, VALUE, RUNNING, STARTS, TOTALISER
For information on fields, see the Browse Function Field Reference in the Cicode Reference Guide.
Note: The migration tool in CitectSCADAv7.20 converts memory PLC variables to local variable tags which are in a separate table to the variable tags. Calling ctFindFirst with szTableName "Tag" will not return the local variable tags. In order to return the local variable tags you need to call ctFindFirst with the szTableName of "LocalTag". Local variables do not have clusters and have only one pair of zero/full scales (as opposed to raw and engineering scales for variable tags).
The field names for local variable tags are:
NAME, TYPE, ASIZE (array size), ZERO, FULL, UNITS, COMMENT.
The array size field is available only for local tags.
szFilter
Type: LPCTSTR
Input/output: Input
Description: Filter criteria. This is a string based on the
following format:
"PropertyName1=FilterCriteria1;PropertyName2=FilterCriteria2"
The wildcard * may be used as part of the filter criteria to match multiple entries. Use an empty string, or "*" as the filter string to match every entry.
pObjHnd
Type: HANDLE
Input/output: Output
Description: The pointer to the found object handle. This is used
to retrieve the properties.
dwFlags
This argument is no longer used, pass in a value of 0 for this argument.
To search a table:
In szTableName specify the name of the table.
To search a device:
In szTableName specify the name as defined in the CitectSCADA Devices form, for example "RECIPES" for the Example project.
To search trend data:
In szTableName specify the trend using the following format (including the quotation marks):
`TRNQUERY,Endtime,EndtimeMs,Period,NumSamples,Tagname,Displaymode,Datamode'
See TrnQuery for syntax details.
To search alarm data:
In szTableName specifythe alarm data using the following format (including the quotation marks):
`ALMQUERY,Database,TagName,Starttime,StarttimeMs,Endtime,EndtimeMs,Period'
See AlmQuery for syntax details.
Return Value
If the function succeeds, the return value is a search handle used in a subsequent call to ctFindNext() or ctFindClose(). If the function does not succeed, the return value is NULL. To get extended error information, call GetLastError()
Related Functions
ctOpen, ctFindNext, ctFindClose, ctGetProperty, ctFindFirstEx
Example
HANDLE hSearch;
HANDLE hObject;
HANDLE hFind;
// Search the Tag table
hSearch = ctFindFirst(hCTAPI, "Tag", NULL, &hObject, 0);
if (hSearch == NULL) {
// no tags found
} else {
do {
char sName[32];
// Get the tag name
ctGetProperty(hObject, "Tag", sName, sizeof(sName), NULL,
DBTYPE_STR);
} while (ctFindNext(hSearch, &hObject));
ctFindClose(hSearch);
}
// Get Historical Trend data via CTAPI
// Get 100 samples of the CPU trend at 2 second
hFind = ctFindFirst(hCTAPI, "CTAPITrend(\"10:15:00 \", \"11/8/1998\", 2, 100, 0,
\"CPU\")", &hObject, 0);
while (hFind) {
char sTime[32], sDate[32], sValue[32];
ctGetProperty(hObject, "TIME", sTime, sizeof(sTime), NULL, DBTYPE_STR);
ctGetProperty(hObject, "DATE", sDate, sizeof(sDate), NULL, DBTYPE_STR);
ctGetProperty(hObject, "CPU", sValue, sizeof(sValue), NULL, DBTYPE_STR);
// do something with the trend data.
if (!ctFindNext(hFind, &hObject)) {
ctFindClose(hFind);
hFind = NULL;
break;
}
}