ctFindFirstEx

Performs the same as ctFindFirst, but with an additional new argument. 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.

If ctFindFirst is called instead of ctFindFirstEx, the szCluster defaults to NULL.

Syntax

ctFindFirstEx(hCTAPI, szTableName, szFilter, szCluster, 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:

• Trend - Trend Tags

• CLUSTER, NAME/TAG, RAW_ZERO, RAW_FULL, ENG_ZERO, ENG_FULL, ENG_UNITS, COMMENT, SAMPLEPER, TYPE

• DigAlm - Digital Alarm Tags

• CLUSTER, TAG, NAME, DESC, HELP, CATEGORY, STATE, TIME, DATE, AREA, ALMCOMMENT

• AnaAlm - Analog Alarm Tags

• CLUSTER, TAG, NAME, DESC, HELP, CATEGORY, STATE, TIME, DATE, AREA, VALUE, HIGH, LOW, HIGHHIGH, LOWLOW, DEADBAND, RATE, DEVIATION, ALMCOMMENT

• AdvAlm - Advanced Alarm Tags

• CLUSTER, TAG, NAME, DESC, HELP, CATEGORY, STATE, TIME, DATE, AREA, ALMCOMMENT

• HResAlm - Time-Stamped Alarm Tags

• CLUSTER, TAG, NAME, DESC, HELP, CATEGORY, STATE, TIME, MILLISEC, DATE, AREA, ALMCOMMENT

• ArgDigAlm - Argyle Digital Alarm Tags

• CLUSTER, TAG, NAME, DESC, HELP, CATEGORY, STATE, TIME, DATE, AREA, ALMCOMMENT, PRIORITY, STATE_DESC, OLD_DESC

• ArgAnaAlm - Argyle Analog Alarm Tags

• CLUSTER, TAG, NAME, HELP, ALMCOMMENT, CATEGORY, STATE, TIME, DATE, AREA, VALUE, PRIORITY, HIGH, LOW, HIGHHIGH, LOWLOW, DEADBAND, RATE, DEVIATION

• TsDigAlm - Time-Stamped Digital Alarm Tags

• CLUSTER, TAG, NAME, DESC, CATEGORY, AREA, ALMCOMMENT

• TsAnaAlm - Time-Stamped Analog Alarm Tags

• CLUSTER, TAG, NAME, DESC, CATEGORY, AREA, ALMCOMMENT

• ArgDigAlmStateDesc - Argyle Digital Alarm Tag State Descriptions

• CLUSTER, TAG, STATE_DESC0, STATE_DESC1, STATE_DESC2, STATE_DESC3, STATE_DESC4, STATE_DESC5, STATE_DESC6, STATE_DESC7

• Alarm - Alarm Tags

• 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

• AlarmSummary - Alarm Summary

• 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

• Accum - Accumulators

• PRIV, AREA, CLUSTER, NAME, TRIGGER, VALUE, RUNNING, STARTS, TOTALISER

• Tag - Variable Tags
• LocalTag - Local Tags
• Cluster - Clusters

For information on fields, see the Browse Function Field Reference in the Cicode Reference Guide.

szFilter

Type: LPCTSTR
Input/output: Input
Description: Filter criteria. This is a string based on the following format:

"PropertyName1=FilterCriteria1;PropertyName2=FilterCriteria2"\.

"*" as the filter to achieve the same result.

szCluster

Type: LPCTSTR
Input/output: Input
Description: Specifies on which cluster the ctFindFirst function will be performed. If left NULL or empty string then the ctFindFirst will be performed on the active cluster if there is only one.

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.

In szTableName specify the name of the table.

In szTableName specify the name as defined in the CitectSCADA Devices form, for example "RECIPES" for the Example project.

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.

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, ctFindFirst